### Create First Hexis Lua Script

Source: https://docs.usehexis.com/getting-started/installation

Provides a basic Lua script example for Hexis, demonstrating how to define script metadata and implement a simple logging loop. This serves as a starting point for creating custom scripts.

```lua
hexis.script({
		name = "My First Script",
		description = "Hello World!",
		author = "YourName",
		version = "1.0.0"
})
		
function hexis.main()
		hexis.log.info("Hello, Hexis!")
		
		while hexis.running() do
				hexis.log.info("Script is running...")
				hexis.wait(5)  -- Wait 5 seconds
		end
		
		hexis.log.info("Script stopped!")
end
```

--------------------------------

### Full Script Example - Hexis API

Source: https://docs.usehexis.com/script-lifecycle

A comprehensive example of a Hexis script, including metadata, configuration options (slider and toggle), and a main loop utilizing external libraries and Hexis functions.

```lua
hexis.script({
    name = "Galatea Forager",
    version = "2.1",
    author = "Hexis",
    category = "Foraging",
    description = "Automated foraging on Galatea Island",
    icon = "https://sky.coflnet.com/static/icon/TREECAPITATOR_AXE",
    type = "active",
    staff_detection = true,
})

local config = hexis.config({
    speed = hexis.config.slider("Aim Speed", 0.5, 3.0, 1.5),
    sell = hexis.config.toggle("Auto Sell", true),
})

local tree_mining = require("hypixel/lib/tree_mining")

while true do
    tree_mining.mine_nearest_tree({aim_speed = config.speed})

    if config.sell and hexis.inventory.is_full() then
        -- sell logic
    end

    hexis.wait(0.1)
end
```

--------------------------------

### Example: Simple HUD with Event Handling - hexis.hud

Source: https://docs.usehexis.com/api/hud

Demonstrates the creation of a simple HUD, showing it, starting a timer, and dynamically updating a 'kills' variable based on game events. It also calculates and displays a 'kills/hr' rate.

```lua
hexis.hud.create({
    title = "Enderman Slayer",
    elements = {
        {type = "stat", label = "Kills", value = "{kills}"},
        {type = "stat", label = "Time", value = "{elapsed_time}"},
        {type = "stat", label = "Kills/hr", value = "{rate}"},
    }
})

hexis.hud.show()
hexis.hud.start_timer()

local kills = 0

hexis.events.on("sound", "experience_orb", function()
    kills = kills + 1
    hexis.hud.set_var("kills", kills)
end)

while hexis.running() do
    local elapsed = hexis.timer.elapsed()
    if elapsed > 0 then
        hexis.hud.set_var("rate", hexis.format.number(kills / (elapsed / 3600)))
    end
    hexis.wait(1.0)
end
```

--------------------------------

### Custom Slayer Loop Example

Source: https://docs.usehexis.com/api/combat

An example demonstrating a custom slayer loop that finds a specific boss, pursues it, and engages in combat. It includes logic for pursuit, engagement, and logging combat results.

```Lua
function hexis.main()
    while hexis.script.is_running() do
        local boss = hexis.combat.find_boss({
            boss_name = "Sven Packmaster",
            entity_type = "wolf",
            radius = 64
        })

        if boss then
            -- Pursue until in range
            hexis.combat.pursue(boss)
            hexis.combat.set_camera_lock(boss)

            while hexis.combat.is_pursuing() and hexis.script.is_running() do
                hexis.combat.pursuit_tick()
                if hexis.combat.pursuit_distance() < 3.0 then
                    break
                end
                hexis.wait(0.05)
            end
            hexis.combat.pursue_stop()

            -- Fight
            local result = hexis.combat.engage({
                entity = boss,
                style = "engaged",
                timeout = 30
            })

            hexis.combat.clear_camera_lock()
            hexis.log.info("Combat result: " .. result)
        end

        hexis.wait(1.0)
    end
end
```

--------------------------------

### Tree Mining: Example with Regeneration Detection

Source: https://docs.usehexis.com/api/libraries

An example demonstrating how to use the `tree_mining.mine_all` function with an `on_abort` callback to detect and react to tree regeneration during the mining process. It also includes an `on_unreachable` callback for handling unreachable blocks.

```lua
local regen_detected = false  
hexis.events.on("chat", "regenerating", function()  
    regen_detected = true  
end)  
  
local result = tree_mining.mine_all(trunk, {  
    allow_jump = true,  
    on_abort = function() return regen_detected end,  
    on_unreachable = function(block)  
        hexis.player.look_at({x = block.x + 0.5, y = block.y + 0.5, z = block.z + 0.5, speed = 2.5})  
        hexis.player.use_item()  
        hexis.wait(1.0)  
    end  
})  
```

--------------------------------

### hexis.timer.start()

Source: https://docs.usehexis.com/utilities/timer

Starts the timer, beginning the tracking of elapsed time.

```APIDOC
## hexis.timer.start()

### Description
Starts the timer.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
None

### Request Example
```lua
hexis.timer.start()
```

### Response
#### Success Response (N/A)
N/A

#### Response Example
N/A
```

--------------------------------

### Example: Status Updates in Farming Script

Source: https://docs.usehexis.com/api/chat

Demonstrates how to use `hexis.chat.send` and `hexis.chat.send_as_hexis` within a main script loop to provide status updates. It shows sending a start message, periodic progress updates, and a final completion message.

```lua
function hexis.main()
    hexis.chat.send_as_hexis("Farming script started!")

    local crops_harvested = 0

    while hexis.running() do
        -- Farm logic here...
        crops_harvested = crops_harvested + 1

        -- Status update every 100 crops
        if crops_harvested % 100 == 0 then
            hexis.chat.send("Harvested " .. crops_harvested .. " crops")
        end

        hexis.wait(0.5)
    end

    hexis.chat.send_as_hexis("Farming complete! Total: " .. crops_harvested)
end
```

--------------------------------

### Start Hexis Timer

Source: https://docs.usehexis.com/utilities/timer

Initiates the timer. This function does not take any arguments and is the first step in tracking elapsed time.

```lua
hexis.timer.start()
```

--------------------------------

### Example Usage

Source: https://docs.usehexis.com/api/events

Demonstrates practical application of Hexis API functions for tracking game events and player status.

```APIDOC
## Example Usage

### Description
This section provides code examples illustrating how to use the Hexis API for common tasks like tracking player actions and updating the HUD.

### Code Examples

#### Tracking Kills via Sound Events
```lua
local kills = 0

hexis.events.on("sound", "experience_orb", function(event)
    kills = kills + 1
    hexis.hud.set_var("kills", kills)
    hexis.log.debug("XP at: " .. event.x .. ", " .. event.y .. ", " .. event.z)
end)
```

#### Tracking Rare Drops via Chat Events
```lua
hexis.events.on("chat", "RARE DROP", function(message)
    hexis.player.use_item() -- Celebration right-click
end)
```

#### Per-Tick Processing for Player Health
```lua
hexis.events.on("tick", nil, function()
    if hexis.player.health_percent < 20 then
        hexis.log.warn("Low health!")
    end
end)
```

#### Periodic Stats Update (Kills Per Hour)
```lua
hexis.events.every(60, function()
    local elapsed = hexis.timer.elapsed()
    local rate = kills / (elapsed / 3600)
    hexis.hud.set_var("kills_per_hour", hexis.format.number(rate))
end)
```
```

--------------------------------

### Equip Workflow Example

Source: https://docs.usehexis.com/api/inventory

Demonstrates a workflow for equipping an item. It first checks the hotbar, and if the item is not found, it opens the inventory, searches for the item, moves it to the hotbar, and then closes the inventory.

```lua
-- Check hotbar first
if hexis.inventory.contains("scythe") then
    hexis.player.equip({pattern = "scythe"})
else
    -- Need to get from inventory
    hexis.gui.safe_mode()
    hexis.inventory.open()
    hexis.wait(0.3)

    -- Scan slots to find the item
    local slots = hexis.gui.get_slots(0, 53)
    for _, slot in ipairs(slots) do
        if not slot.empty and slot.name and slot.name:find("Scythe") then
            hexis.gui.click(slot.id)
            hexis.wait(0.1)
            hexis.gui.switch_hotbar(0)
            hexis.gui.click(slot.id)
            break
        end
    end

    hexis.inventory.close()
end
```

--------------------------------

### Hexis Timer Example Usage

Source: https://docs.usehexis.com/utilities/timer

Demonstrates a common pattern for using the hexis timer within a game loop. It starts the timer, updates a HUD element with the formatted elapsed time periodically, and stops the timer upon loop completion, logging the total time.

```lua
hexis.timer.start()

while hexis.running() do
    -- Update HUD with elapsed time
    hexis.hud.set_var("time", hexis.timer.formatted())
    hexis.wait(1.0)
end

hexis.timer.stop()
hexis.log.info("Total time: " .. hexis.timer.formatted())
```

--------------------------------

### Ore Mining Script Example

Source: https://docs.usehexis.com/api/mining

A practical example demonstrating how to use various Hexis mining functions to scan for and mine ores.

```APIDOC
## Example: Ore Mining Script

### Description
This script demonstrates a basic ore mining operation using Hexis functions. It scans for diamond ores, selects a smart target, and mines it.

### Method
Lua Script

### Endpoint
N/A

### Parameters
N/A

### Request Example
```lua
local last_mined_pos = nil  
local blocks_mined = 0  
  
function hexis.main()  
    while hexis.running() do  
        -- Scan for ores  
        local ores = hexis.world.scan_blocks({  
            match_patterns = {"diamond_ore", "deepslate_diamond_ore"},
            radius = 20  
        })
  
        if #ores == 0 then  
            hexis.log.info("No ores found, waiting...")  
            hexis.wait(1.0)  
        else  
            -- Use smart target selection  
            local result = hexis.mining.select_target_smart({  
                candidates = ores,  
                last_mined = last_mined_pos,  
                cluster_radius = 4  
            })
  
            if result.success then  
                -- mine_block handles navigation + aiming + mining  
                local mine_result = hexis.mining.mine_block({  
                    x = result.target.x,  
                    y = result.target.y,  
                    z = result.target.z,  
                    timeout = 5.0  
                })
  
                if mine_result.success then  
                    last_mined_pos = result.target  
                    blocks_mined = blocks_mined + 1  
                    hexis.hud.set_var("mined", blocks_mined)
                else  
                    hexis.log.debug("Skipped: " .. mine_result.reason)
                end  
            end  
        end  
  
        hexis.wait(0.1)  
    end  
end  
```

### Response
N/A (This is a script example, not an API response)

### Success Response (200)
N/A

### Response Example
N/A
```

--------------------------------

### Timer Usage in Lua

Source: https://docs.usehexis.com/quick-reference

Demonstrates the use of a simple timer. It starts the timer, allows for some operations to be performed, and then logs the elapsed time in a formatted string before stopping the timer.

```lua
hexis.timer.start()
-- ... do stuff ...  
hexis.log.info("Elapsed: " .. hexis.timer.formatted())
hexis.timer.stop()  
```

--------------------------------

### Example Usage of hexis.format in Lua

Source: https://docs.usehexis.com/utilities/formatting

Demonstrates how to use the `hexis.format` functions to format numerical data (kills, coins, time) before setting them as variables in a HUD. This showcases practical application of the formatting methods.

```lua
local kills = 1523  
local coins = 1500000  
local time = 3661  
  
hexis.hud.set_var("kills", hexis.format.number(kills))    -- "1.5k"  
hexis.hud.set_var("coins", hexis.format.coins(coins))     -- "1.5M"  
hexis.hud.set_var("time", hexis.format.duration(time))    -- "1h 1m 1s"  
```

--------------------------------

### Start Asynchronous Navigation with Hexis

Source: https://docs.usehexis.com/api/navigation

Initiates A* pathfinding asynchronously, allowing for script execution during navigation. It returns immediately after starting the path computation. This function is ideal for scenarios requiring interruptible navigation or background tasks during movement.

```lua
-- Basic async navigation  
local started = hexis.navigate.start_async({  
    x = 100.5, y = 65, z = 200.5,  
    distance = 2.0  
})  
  
if started then  
    while hexis.navigate.is_navigating() do  
        if not hexis.script.is_running() then break end  
        -- Can do other things here (check events, update HUD, etc.)  
        hexis.wait(0.05)  
    end  
end  

```

```lua
hexis.navigate.start_async({  
    x = vantage.x, y = vantage.y, z = vantage.z,  
    distance = 1.5,  
    reach_target = {x = ore.x, y = ore.y, z = ore.z}  
})  

```

--------------------------------

### Example: Island Hopping Script Logic

Source: https://docs.usehexis.com/api/chat

Illustrates using `hexis.chat.command` to automate island hopping, including teleporting to the hub, selling items, and returning to the island. It incorporates `hexis.wait` to allow time for teleports.

```lua
function teleport_to_hub()
    hexis.chat.command("/hub")
    hexis.wait(3)  -- Wait for teleport
end

function teleport_to_island()
    hexis.chat.command("/is")
    hexis.wait(3)
end

function hexis.main()
    while hexis.running() do
        -- Farm on island
        farm_crops()

        -- When inventory full, go to hub
        if hexis.conditions.inventory_full() then
            hexis.chat.send("Inventory full, heading to hub...")
            teleport_to_hub()
            sell_items()
            teleport_to_island()
        end

        hexis.wait(1)
    end
end
```

--------------------------------

### Example: Combat Kill Notifications

Source: https://docs.usehexis.com/api/chat

Shows how to integrate `hexis.chat.send_as_hexis` with combat tracking using `hexis.combat.start` and `hexis.events.on`. It sends milestone notifications to the local chat based on the number of kills.

```lua
function hexis.main()
    hexis.combat.start({
        targets = {"Enderman"},
        style = "ranged"
    })

    local kills = 0

    while hexis.running() do
        -- Track kills via events
        hexis.events.on("chat", "You have slain", function()
            kills = kills + 1

            if kills % 50 == 0 then
                hexis.chat.send_as_hexis("Milestone: " .. kills .. " kills!")
            end
        end)

        hexis.wait(0.1)
    end
end
```

--------------------------------

### Create a Boolean Toggle Configuration

Source: https://docs.usehexis.com/script-lifecycle

This example illustrates how to create a boolean toggle (on/off switch) in the Hexis menu using `hexis.config.toggle()`. It shows how to define the label for the toggle and its default state (true for on, false for off).

```lua
enabled = hexis.config.toggle("Auto Sell", true)
debug = hexis.config.toggle("Debug Mode", false)

```

--------------------------------

### Script Lifecycle and Types

Source: https://docs.usehexis.com/script-lifecycle

Explains the two types of scripts: active and passive, and their behavioral differences. Provides examples of how to define each type.

```APIDOC
## Script Lifecycle

Every script is either **active** or **passive**. Set via the `type` field in `hexis.script()`.

| Behavior | Active (default) | Passive |
|---|---|---|
| Concurrent execution | Only **one** active script at a time | **Multiple** passive scripts simultaneously |
| Mod menu opens | Script **stops** | Script **keeps running** |
| Session persistence | Does **not** persist across sessions | **Persists** across Minecraft sessions |
| Typical pattern | Main loop with navigation/combat | Event-driven listeners, overlays, detectors |

### Active Scripts

Active scripts are the default. They control the player — pathfinding, mining, combat, etc. Only one can run at a time because they take control of movement and camera.

```lua
hexis.script({
    name = "Zealot Grinder",
    description = "Farms zealots in The End",
    -- type defaults to "active"
})

while true do
    hexis.combat.hunt("Zealot", {radius = 30})
    hexis.wait(0.5)
end
```

### Passive Scripts

Passive scripts run in the background alongside active scripts. They observe, display overlays, or react to events without controlling the player.

```lua
hexis.script({
    name = "Zone Overlay",
    type = "passive",
    description = "Shows player counts above zones",
})

while true do
    update_zone_labels()
    hexis.wait(10)
end
```

Use `type = "passive"` for scripts that:
* Display HUD overlays or world text labels
* Monitor chat or sound events
* Detect other players (e.g., macro detection)
* Don't need movement, combat, or camera control
```

--------------------------------

### HUD Setup in Lua

Source: https://docs.usehexis.com/quick-reference

Configures and displays a custom Heads-Up Display (HUD) for the script. It allows defining a title and elements like statistics, setting initial variable values, and making the HUD visible.

```lua
hexis.hud.create({  
    title = "My Script",  
    elements = {  
        {type = "stat", label = "Kills", value = "{kills}"},
        {type = "stat", label = "Time", value = "{elapsed_time}"},
    }
})
  
hexis.hud.set_var("kills", 0)
hexis.hud.show()  
```

--------------------------------

### Start Smart Mining

Source: https://docs.usehexis.com/api/mining

Initiates asynchronous mining with intelligent selection of the aim point. Requires position and optional aim speed parameters.

```lua
hexis.mining.start_mining_smart({
    x = 100,
    y = 65,
    z = 200,
    aim_speed = 2.5
})
```

--------------------------------

### Example: Strafe While Mining - hexis.movement

Source: https://docs.usehexis.com/api/movement

Demonstrates a practical application of the movement API, allowing a player to strafe towards a target while mining. It integrates `hexis.spatial.get_safe_strafe_direction` for intelligent strafing and `hexis.mining.aim_tick` for mining actions.

```lua
hexis.movement.take_control("fig_mode")  

while hexis.running() and mining_tree do  
    -- Strafe toward next tree while mining current one  
    local strafe = hexis.spatial.get_safe_strafe_direction(next_tree)  
    if strafe and strafe.is_safe then  
        hexis.movement.set_strafe_intensity(strafe.intensity)  
    end  

    hexis.mining.aim_tick()  
    hexis.movement.tick()  
    hexis.wait(0.05)  
end  

hexis.movement.release_control()  
```

--------------------------------

### Hexis Mod Folder Structure

Source: https://docs.usehexis.com/getting-started/installation

Illustrates the expected file structure within the Minecraft mods folder after installing Hexis and its dependencies. This structure is crucial for the game to recognize and load the mods correctly.

```plaintext
mods/
		├── fabric-api-x.x.x+1.21.11.jar
		└── hexis-x.x.x.jar
```

--------------------------------

### Hexis Configuration Folder Structure

Source: https://docs.usehexis.com/getting-started/installation

Details the directory structure created by Hexis for storing configuration files, scripts, and license information. This organization helps manage Hexis settings and custom scripts.

```plaintext
.minecraft/config/hexis/
		├── scripts/           # Your Lua scripts go here
		│   	└── lib/           # Shared libraries for scripts
		├── routes/            # Route files (.hxr)
		├── settings.json      # Hexis configuration
		└── license.key        # Your license information
```

--------------------------------

### Create a Basic 'Hello World' Script in Lua

Source: https://docs.usehexis.com/index

This script demonstrates the basic structure of a Hexis script, including registration, the main function, logging, and a simple loop with a wait. It's intended for beginners to understand the fundamental components of a Hexis script.

```lua
hexis.script({
    name = "Hello World",
    description = "My first script",
    author = "YourName",
    version = "1.0.0"
})

function hexis.main()
    hexis.log.info("Hello, Hexis!")

    while hexis.running() do
        -- Your automation logic here
        hexis.wait(1)
    end

    hexis.log.info("Goodbye!")
end

```

--------------------------------

### Define GUI Configuration Options

Source: https://docs.usehexis.com/script-lifecycle

This example shows how to define GUI configuration elements for a script using `hexis.config()`. It demonstrates creating a slider for 'Hunt Radius', a toggle for 'Auto Sell', and a dropdown for 'Weapon' selection.

```lua
local config = hexis.config({
    radius = hexis.config.slider("Hunt Radius", 10, 50, 30, 5),
    auto_sell = hexis.config.toggle("Auto Sell", true),
    weapon = hexis.config.dropdown("Weapon", {
        {"juju", "Juju Shortbow"},
        {"term", "Terminator"},
        {"hyp", "Hyperion"},
    }, "juju"),
})

```

--------------------------------

### Get Hexis Timer Elapsed Time in Seconds

Source: https://docs.usehexis.com/utilities/timer

Retrieves the total elapsed time in seconds since the timer was started or last reset. It returns a numerical value representing seconds and can be logged for analysis.

```lua
local seconds = hexis.timer.elapsed()
hexis.log.info("Elapsed: " .. seconds .. " seconds")
```

--------------------------------

### Create and Manage Multi-State HUDs with Hexis

Source: https://docs.usehexis.com/api/hud

This example demonstrates how to create a multi-state HUD using the hexis.hud module. It covers creating the HUD, adding different states with custom elements, setting the initial state, showing the HUD, and updating state variables. The HUD can dynamically switch between 'navigating' and 'mining' states based on script progression.

```lua
hexis.hud.create({position = "top-right", width = 260})

hexis.hud.add_state("navigating", {
    elements = {
        {type = "title", value = "Foraging Macro", subtitle = "Walking..."},
        {type = "stat", label = "Target", value = "{target}"},
        {type = "stat", label = "Mined", value = "{mined}"},
        {type = "stat", label = "Time", value = "{elapsed_time}"},
    }
})

hexis.hud.add_state("mining", {
    elements = {
        {type = "title", value = "Foraging Macro", subtitle = "Mining"},
        {type = "stat", label = "Tree", value = "{tree_type}"},
        {type = "stat", label = "Mined", value = "{mined}"},
        {type = "stat", label = "Time", value = "{elapsed_time}"},
    }
})

hexis.hud.set_state("navigating")
hexis.hud.show()
hexis.hud.start_timer()

-- Switch states as script progresses
hexis.hud.set_state("mining")
hexis.hud.set_var("tree_type", "Dark Oak")
hexis.hud.set_var("mined", 42)

```

--------------------------------

### Legacy Item Finding and Alternatives (Lua)

Source: https://docs.usehexis.com/api/gui

Demonstrates the legacy `gui.find` method and recommends preferred alternatives for Lua scripts. `click_item()` is advised for combined find-and-click actions, while `get_slots()` allows for manual scanning and custom logic.

```lua
-- Instead of gui.find, prefer these alternatives:

-- Option 1: Find and click in one step
hexis.gui.click_item({name = "Diamond", lore = "Click to buy"})

-- Option 2: Scan slots manually for custom logic
local slots = hexis.gui.get_slots(0, 53)
for _, slot in ipairs(slots) do
    if not slot.empty and slot.name:find("Diamond") then
        hexis.gui.click(slot.id)
        break
    end
end
```

--------------------------------

### Navigate Bazaar and Buy Item using Hexis GUI

Source: https://docs.usehexis.com/api/gui

This snippet demonstrates how to navigate the in-game Bazaar GUI to purchase an item. It includes steps for opening the Bazaar, waiting for it to load, clicking the 'Buy Instantly' button, confirming the purchase, and then closing the GUI. The code utilizes Hexis's GUI interaction functions with built-in delays for safe interaction.

```lua
-- Open bazaar and buy item (safe_mode optional, guard handles delays)  
hexis.chat.command("/bz")  
hexis.gui.wait_for("Bazaar", 5)  
  
hexis.gui.click_item({name = "Buy Instantly"})  -- First click: 200-500ms delay auto-applied  
hexis.wait(0.3)                                  -- Wait for server response  
hexis.gui.click_item({                           -- Second click: 100-150ms inter-click delay  
    name = "Confirm",  
    required = true  
})  
  
hexis.gui.close()  
```

--------------------------------

### Start HUD Timer - hexis.hud.start_timer

Source: https://docs.usehexis.com/api/hud

Starts the built-in session timer for the HUD. This timer automatically populates the `{elapsed_time}` variable, which can be displayed in HUD elements.

```lua
hexis.hud.start_timer()
```

--------------------------------

### Combined Safety Check Example

Source: https://docs.usehexis.com/api/conditions

An example demonstrating how to combine multiple conditions to create a comprehensive safety check. This function checks for nearby players, inventory status, and player health before allowing an action to proceed.

```lua
-- Combined safety check
local function is_safe()
    return hexis.conditions.no_players_nearby(30)
       and not hexis.inventory.is_full()
       and hexis.conditions.player_health("gt", 5)
end

while hexis.running() do
    if is_safe() then
        -- Continue farming
    else
        hexis.log.warn("Safety check failed, pausing...")
        hexis.wait(5.0)
    end
end
```

--------------------------------

### Start Continuous Mining Loop (Lua)

Source: https://docs.usehexis.com/api/mining

Starts an asynchronous mining loop that continuously searches for and breaks blocks based on a defined route. This function runs in the background and can be identified by a unique ID for pausing or resuming.

```Lua
hexis.mining.start_loop({
    id = "foraging_loop",        -- Unique identifier for pause/resume
    max_distance = 50,           -- Maximum block search distance (default 50)
    aim_speed = 2.5,             -- Aim speed multiplier (default 2.5)
    approach_distance = 2.0,     -- Distance to navigate to (default 2.0)
    use_zones = true,            -- Respect zone isolation (default true)
    chain_mining = true,         -- Enable chain mining (default false)
    chain_limit = 5,             -- Max blocks to chain mine (default 5)
    block_cooldown = 5,          -- Seconds before re-mining same block (default 5)
    mining_timeout = 5           -- Seconds before error if block not broken (default 5)
})

```

--------------------------------

### Load Libraries in Lua

Source: https://docs.usehexis.com/quick-reference

Demonstrates how to load external Lua libraries using the `require` function. This is essential for organizing code and using pre-built functionalities for tasks like tree mining or island navigation.

```lua
local tree_mining = require("hypixel/lib/tree_mining")  
local island_nav = require("hypixel/lib/island_nav")  
```

--------------------------------

### Start Underwater Navigation with Hexis

Source: https://docs.usehexis.com/api/navigation

Initiates underwater A* pathfinding using a native Rust implementation. This function starts swim following and returns immediately, allowing for concurrent script operations. It's suitable for navigating submerged environments.

```lua
local ok = hexis.navigate.swim_to({  
    x = 100, y = 30, z = 200,  
    max_nodes = 35000,  
    heuristic_weight = 1.2  
})  
  
if ok then  
    while hexis.navigate.is_swim_navigating() do  
        hexis.wait(0.05)  
    end  
end  

```

--------------------------------

### Route Loading in Lua

Source: https://docs.usehexis.com/quick-reference

Loads a predefined navigation route from a file. It then logs the route's name and the number of blocks it contains, useful for automated traversal scripts.

```lua
local route = hexis.routes.load("foraging/park/Park_Foraging")  
if route then  
    hexis.log.info("Loaded: " .. route.name)
    hexis.log.info("Blocks: " .. route.block_count)
end  
```

--------------------------------

### hexis.timer.elapsed_ms()

Source: https://docs.usehexis.com/utilities/timer

Retrieves the elapsed time in milliseconds since the timer was started or last reset.

```APIDOC
## hexis.timer.elapsed_ms()

### Description
Gets elapsed time in milliseconds.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
None

### Request Example
```lua
local ms = hexis.timer.elapsed_ms()
```

### Response
#### Success Response (N/A)
- **ms** (number) - The elapsed time in milliseconds.

#### Response Example
```lua
-- Assuming timer has run for 10.5 seconds (10500 milliseconds)
-- ms would be 10500
```
```

--------------------------------

### hexis.timer.elapsed()

Source: https://docs.usehexis.com/utilities/timer

Retrieves the elapsed time in seconds since the timer was started or last reset.

```APIDOC
## hexis.timer.elapsed()

### Description
Gets elapsed time in seconds.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
None

### Request Example
```lua
local seconds = hexis.timer.elapsed()
hexis.log.info("Elapsed: " .. seconds .. " seconds")
```

### Response
#### Success Response (N/A)
- **seconds** (number) - The elapsed time in seconds.

#### Response Example
```lua
-- Assuming timer has run for 10.5 seconds
-- seconds would be 10.5
```
```

--------------------------------

### Combat Loop API

Source: https://docs.usehexis.com/api/combat

Manages the background combat loop, including starting, stopping, and checking its status.

```APIDOC
## Combat Loop API

### `hexis.combat.start(options)`

Starts a background combat loop that automatically targets and attacks entities.

**Blocking:** No (runs in background, use `stop()` to end)

#### Parameters

- `targets` (string[]) - Required - Entity names to target
- `style` (string) - Optional - Defaults to `"melee"`. Can be `"ranged"` or `"melee"`
- `weapon` (string) - Optional - Weapon name to equip
- `radius` (number) - Optional - Defaults to `10`. Search radius for entities
- `aim_speed` (number) - Optional - Defaults to `1.0`. Camera aim speed multiplier
- `attack_cps` (number) - Optional - Defaults to `10`. Clicks per second

#### Request Example

```lua
hexis.combat.start({
    targets = {"Enderman", "Zealot"},
    style = "ranged",
    weapon = "Juju Shortbow",
    radius = 15,
    aim_speed = 1.0,
    attack_cps = 12,
})
```

### `hexis.combat.stop()`

Stops the combat loop and releases camera control.

#### Request Example

```lua
hexis.combat.stop()
```

### `hexis.combat.is_active()`

Returns `true` if combat loop is running.

#### Response Example

```json
{
  "isActive": true
}
```
```

--------------------------------

### Optimize multi-block mining with hexis.mining sessions

Source: https://docs.usehexis.com/guides/choosing-functions

This example demonstrates how to improve mining efficiency by using `hexis.mining.start_session()` and `hexis.mining.end_session()`. This approach keeps the attack action sustained between mining different blocks, leading to smoother transitions and potentially faster mining compared to individual `mine_block` calls.

```lua
-- SUBOPTIMAL: Camera stutters between blocks  
for _, block in ipairs(blocks) do  
    hexis.mining.mine_block({x = block.x, y = block.y, z = block.z})  
end  
  
-- BETTER: Session keeps attack held for smooth transitions  
hexis.mining.start_session()  
for _, block in ipairs(blocks) do  
    hexis.mining.mine_block({x = block.x, y = block.y, z = block.z})  
end  
hexis.mining.end_session()  

```

--------------------------------

### Navigate with start_async and handle interrupts

Source: https://docs.usehexis.com/guides/best-practices

Uses `hexis.navigate.start_async` for production scripts to allow handling interrupts during navigation. It includes a loop to check navigation status and script running status.

```lua
hexis.navigate.start_async({
    x = target.x, y = target.y, z = target.z,
    distance = 2.0
})

while hexis.navigate.is_navigating() do
    if not hexis.script.is_running() then return end
    -- Can check for competition events, danger, etc.
    hexis.wait(0.05)
end

```

--------------------------------

### Slot Information

Source: https://docs.usehexis.com/api/gui

Retrieve detailed information about a specific slot or a range of slots, and get the total container size.

```APIDOC
## GET /websites/usehexis/gui/slot_info

### Description
Gets detailed information about a single slot.

### Method
GET

### Endpoint
`/websites/usehexis/gui/slot_info?slot={slot}`

### Parameters
#### Query Parameters
- **slot** (number) - Required - The index of the slot to get information for.

### Response
#### Success Response (200)
- **id** (number) - Slot index.
- **name** (string) - Item display name.
- **type** (string) - Item type identifier.
- **row** (number) - Row in container (0-indexed).
- **col** (number) - Column in container (0-indexed).
- **color** (string) - Dyed color name ("red", "blue", etc. or "none").
- **empty** (boolean) - Whether slot is empty.
- **count** (number) - Stack size (0 if empty).
- **has_glint** (boolean) - Whether item has enchantment glint (foil effect).
- **lore** (table) - Array of lore line strings.

### Response Example
```json
{
  "id": 5,
  "name": "Diamond Sword",
  "type": "minecraft:diamond_sword",
  "row": 0,
  "col": 0,
  "color": "none",
  "empty": false,
  "count": 1,
  "has_glint": true,
  "lore": ["Sharpness V"]
}
```

## GET /websites/usehexis/gui/slots

### Description
Bulk-scans a range of slots and returns an array of slot info tables.

### Method
GET

### Endpoint
`/websites/usehexis/gui/slots?from={from}&to={to}`

### Parameters
#### Query Parameters
- **from** (number) - Required - The starting slot index (inclusive).
- **to** (number) - Required - The ending slot index (inclusive).

### Response
#### Success Response (200)
- Returns an array of slot info tables, each with the same fields as `get_slot_info`.

### Response Example
```json
[
  {
    "id": 0,
    "name": "Stone",
    "type": "minecraft:stone",
    "row": 0,
    "col": 0,
    "color": "none",
    "empty": false,
    "count": 64,
    "has_glint": false,
    "lore": []
  },
  {
    "id": 1,
    "name": "Air",
    "type": "minecraft:air",
    "row": 0,
    "col": 1,
    "color": "none",
    "empty": true,
    "count": 0,
    "has_glint": false,
    "lore": []
  }
]
```

## GET /websites/usehexis/gui/container_size

### Description
Returns the number of container slots (excluding player inventory).

### Method
GET

### Endpoint
`/websites/usehexis/gui/container_size`

### Response
#### Success Response (200)
- **size** (number) - The number of container slots.

### Response Example
```json
{
  "size": 54
}
```
```

--------------------------------

### Create a Numeric Slider Configuration

Source: https://docs.usehexis.com/script-lifecycle

This example demonstrates the use of `hexis.config.slider()` to create a numeric slider in the Hexis menu. It shows how to define the label, minimum value, maximum value, default value, and an optional step size for the slider.

```lua
speed = hexis.config.slider("Aim Speed", 0.1, 5.0, 1.0)
accuracy = hexis.config.slider("Detection Threshold (%)", 50, 95, 85, 5)

```

--------------------------------

### Select Hotbar Slot

Source: https://docs.usehexis.com/api/inventory

Select a specific hotbar slot by its index (0-8). Examples show selecting the first and last slots.

```lua
hexis.inventory.select_slot(0)  -- Select first slot
hexis.inventory.select_slot(8)  -- Select last slot
```

--------------------------------

### Use seconds for all timing with hexis.wait()

Source: https://docs.usehexis.com/guides/best-practices

Illustrates the correct usage of `hexis.wait()` for timing in seconds, warning against the common mistake of assuming milliseconds. It also shows how to achieve millisecond delays by dividing by 1000.

```lua
hexis.wait(1.5)           -- 1.5 seconds
hexis.wait(0.05)          -- 50 milliseconds
hexis.wait(500)           -- THIS IS 500 SECONDS, not 500ms!

-- For random delays, divide by 1000:
hexis.wait(math.random(200, 500) / 1000)  -- 200-500ms

```

--------------------------------

### Mining Loop Control

Source: https://docs.usehexis.com/api/mining

Functions to manage continuous mining operations, including starting, stopping, and checking the status of a mining loop.

```APIDOC
## Mining Loop Control

### Description
Manages the execution of a continuous mining loop.

### Functions

- `hexis.mining.start_loop(options)`: Starts a mining loop with specified options.
- `hexis.mining.stop_loop()`: Stops the active mining loop.
- `hexis.mining.is_loop_active()`: Returns a boolean indicating if the mining loop is currently active.
- `hexis.mining.get_blocks_mined()`: Returns the total number of blocks mined during the current loop session.
```

--------------------------------

### Configure Input Blocking Options

Source: https://docs.usehexis.com/script-lifecycle

This example demonstrates how to configure input blocking for active scripts using the `input_blocking` table within `hexis.script()`. It shows how to selectively block camera movement, player movement, item changes, and inventory access.

```lua
input_blocking = {
    block_camera = true,      -- Prevent player camera movement
    block_movement = true,    -- Prevent WASD movement
    block_item_change = true, -- Prevent hotbar slot changes
    block_inventory = false,  -- Prevent opening inventory
}

```

--------------------------------

### Route: Get Nearest Etherwarp

Source: https://docs.usehexis.com/api/routes

Retrieves the nearest etherwarp point for a given route. Returns nil if no etherwarp point is found.

```APIDOC
## Route: get_nearest_etherwarp()

### Description
Returns the nearest etherwarp point for the route, or `nil` if none is found.

### Method
`route:get_nearest_etherwarp()`

### Endpoint
N/A (This is a method call on a route object)

### Parameters
None

### Request Example
```lua
local route = hexis.routes.load("example_route")
local nearest_etherwarp = route:get_nearest_etherwarp()

if nearest_etherwarp then
    print("Nearest etherwarp found:", nearest_etherwarp.x, nearest_etherwarp.y, nearest_etherwarp.z)
else
    print("No etherwarp found for this route.")
end
```

### Response
#### Success Response
- **etherwarp_point** (table | nil) - A table containing the coordinates (x, y, z) of the nearest etherwarp point, or `nil` if none exists.
```

--------------------------------

### Check and Equip Item in Lua

Source: https://docs.usehexis.com/quick-reference

This snippet demonstrates how to check if an item exists in the player's inventory and then equip it if found. It's useful for ensuring specific tools or weapons are ready for use.

```lua
if hexis.inventory.contains("scythe") then  
    hexis.player.equip({name = "scythe"})
end  
```

--------------------------------

### GUI Interaction in Lua

Source: https://docs.usehexis.com/quick-reference

Provides a sequence for interacting with graphical user interfaces (GUIs). It includes enabling safe mode, opening a GUI, waiting, clicking a specific item (like a confirmation button), and closing the GUI.

```lua
hexis.gui.safe_mode()
hexis.gui.open()
hexis.wait(0.3)
hexis.gui.click_item({name = "Confirm"})
hexis.gui.close()
```

--------------------------------

### Toggle Sprint (Lua)

Source: https://docs.usehexis.com/api/player

Enables or disables the player's sprint ability. Calling with `enabled = true` starts sprinting, while `enabled = false` stops it.

```lua
hexis.player.sprint({enabled = true})   -- Start sprinting
hexis.player.sprint({enabled = false})  -- Stop sprinting
```

--------------------------------

### Get Precomputed Mining Target

Source: https://docs.usehexis.com/api/mining

Retrieves and clears the precomputed mining target. Returns nil if no target is ready. The returned target has the same format as the result from `select_target_smart`.

```lua
local precomputed = hexis.mining.get_precomputed_target()
if precomputed then
    -- Same format as select_target_smart result
end
```

--------------------------------

### Inventory Management in Lua

Source: https://docs.usehexis.com/quick-reference

Demonstrates common inventory operations: selecting a specific slot, finding an item by name and selecting its slot, and checking if the inventory is full. It uses `hexis.log.warn` to report if the inventory is full.

```lua
-- Select a slot  
hexis.inventory.select_slot(0)  
  
-- Find an item  
local slot = hexis.inventory.find_slot("aspect")  
if slot >= 0 then  
    hexis.inventory.select_slot(slot)
end  
  
-- Check if inventory is full  
if hexis.inventory.is_full() then  
    hexis.log.warn("Full!")
end  
```

--------------------------------

### Get Nearby Target Entities

Source: https://docs.usehexis.com/api/combat

Retrieves a list of entity names within a specified distance. This is useful for identifying potential targets for combat or other interactions.

```lua
local targets = hexis.combat.get_targets(20)
for _, name in ipairs(targets) do
    hexis.log.info("Target: " .. name)
end

```

--------------------------------

### require(name) - Load Sandboxed Libraries

Source: https://docs.usehexis.com/api/core

The `require(name)` function loads a library using the standard Lua `require()` mechanism. It features sandboxed resolution, with libraries being resolved from the `config/hexis/scripts/` directory. Libraries are loaded only once and then cached.

```APIDOC
## `require(name)`

### Description
Loads a library using standard Lua `require()` with sandboxed resolution. Libraries are resolved from `config/hexis/scripts/`. Libraries are loaded once and cached.

### Method
GET (conceptual, as it's a function call)

### Endpoint
N/A (Internal function)

### Parameters
- **name** (string) - Required - The name of the library to load.

### Request Example
```lua
local tree_mining = require("hypixel/lib/tree_mining")
local island_nav = require("hypixel/lib/island_nav")
local Competition = require("hypixel/lib/competition")
```

### Response
#### Success Response (table)
- **module table** (table) - The return value is the library's module table.

#### Response Example
```json
{
  "library_loaded": true,
  "module_data": { ... } 
}
```
```

--------------------------------

### Get Hexis Timer Elapsed Time in Milliseconds

Source: https://docs.usehexis.com/utilities/timer

Returns the elapsed time in milliseconds. This provides a more granular measurement than `elapsed()`. The function takes no arguments.

```lua
local ms = hexis.timer.elapsed_ms()
```

--------------------------------

### Define an Active Script with Metadata

Source: https://docs.usehexis.com/script-lifecycle

This example demonstrates how to define an active script using `hexis.script()`. Active scripts are the default and control player actions like movement and combat. This function call sets up essential metadata such as name, description, and input blocking.

```lua
hexis.script({
    name = "Zealot Grinder",
    description = "Farms zealots in The End",
    -- type defaults to "active"
})

while true do
    hexis.combat.hunt("Zealot", {radius = 30})
    hexis.wait(0.5)
end

```

--------------------------------

### Get Etherwarp Destinations from a Route (Lua)

Source: https://docs.usehexis.com/api/routes

Retrieves a list of etherwarp destinations available within the route. These are points that can be used for fast travel or teleportation.

```lua
route:get_etherwarp_points()
```

--------------------------------

### Get Ungrouped Zones (Lua)

Source: https://docs.usehexis.com/api/routes

Retrieves a list of all zone tables that have not been assigned to any zone group. This can be used to identify and manage zones that exist independently.

```lua
route:get_ungrouped_zones()
```

--------------------------------

### Get Crosshair Target Block

Source: https://docs.usehexis.com/api/mining

Retrieves information about the block currently targeted by the crosshair. Returns the block's coordinates (x, y, z) and the side of the block being targeted.

```lua
local target = hexis.mining.get_crosshair_target()
if target then
    -- target.x, target.y, target.z
    -- target.side = "up", "down", "north", "south", "east", "west"
end
```