Lua v4 Mining Actions

Lua chooses a target set and recovery policy. Hexis discovers matching blocks, selects reachable mining vantages, navigates, aims, holds attack, waits for server block-update evidence, and releases every owned control before publishing a result.

The implemented source-foundation actions are:

Action	Selection meaning
`hexis.mining.mine_block`	Mine one exact coordinate if its current exact block ID is allowed.
`hexis.mining.mine_connected`	Starting from one of 1 through 128 seed hints, mine one matching connected component.
`hexis.mining.mine_area`	Scan one bounded radius or box in resident client terrain and mine matching blocks even when they are disconnected.

These are v4 actions. The similarly named calls under the v3 source inventory are historical bindings with different requests and completion semantics.

Shared request policy

All three actions require the current observation or route result's world_generation, a blocks.priorities map, and a held selector:

local policy = {
    blocks = {
        priorities = {
            ["minecraft:deepslate_diamond_ore"] = 100,
            ["minecraft:diamond_ore"] = 80,
        },
    },
    held = {
        name_patterns = {"Drill", "Pickaxe"},
    },
    handoff = "confirmed",
    navigation = {
        allow_ether_transmission = false,
    },
}

blocks.priorities accepts 1 through 16 exact namespaced block IDs and normalizes them to lowercase. Each key is at most 120 characters and each integer priority is from 1 through 1,000. Larger numbers are preferred. This is an exact ID map, not substring or display-name matching. Map iteration order does not define priority.

held contains only name_patterns: 1 through 16 nonblank item-name patterns, each at most 128 characters. The mining action validates the currently held main-hand item against that selector before discovery and before each break. It does not silently choose another hotbar item. Use hexis.inventory.ensure_held first when the script should select a tool.

handoff is optional and is exactly confirmed or predictive; omission defaults to confirmed. The runtime accepts predictive, but this foundation does not perform Tick Glide yet. It honestly returns handoff_effective = "confirmed" and prediction_fallback = true. A confirmed request returns prediction_fallback = false.

navigation is optional and contains only the required boolean allow_ether_transmission; omission means false. Setting it to true also requires the bundle's etherwarp capability. The three actions always require mining, navigation, and pathfinding.

Mine one exact block

local result = hexis.await(hexis.mining.mine_block({
    world_generation = observed.world_generation,
    target = {
        position = {x = 12, y = 64, z = -8},
    },
    blocks = {
        priorities = {["minecraft:iron_ore"] = 100},
    },
    held = {name_patterns = {"Pickaxe"}},
}), {timeout = 30})

target contains only position, whose x, y, and z are exact integers. The action does not substitute a nearby block. An unloaded target reports retryable terrain_incomplete; a loaded coordinate that no longer has an allowed ID reports retryable target_lost.

Mine one connected component

local route = hexis.routes.seeds({
    route = config.route,
    kind = "mineable_blocks",
    entry_block_types = {"Stripped Spruce Wood"},
})

local result = hexis.await(hexis.mining.mine_connected({
    world_generation = route.world_generation,
    seeds = route.seeds,
    blocks = {
        priorities = {
            ["minecraft:stripped_spruce_wood"] = 100,
            ["minecraft:stripped_spruce_log"] = 95,
            ["minecraft:stripped_oak_wood"] = 90,
            ["minecraft:stripped_oak_log"] = 85,
        },
        connectivity = "faces_edges_corners",
    },
    held = {name_patterns = {"Treecapitator", "Figstone Splitter"}},
    handoff = "confirmed",
}), {timeout = 600})

seeds contains 1 through 128 exact integer positions. Duplicate positions are removed. blocks.connectivity is required and is exactly faces or faces_edges_corners. The engine selects a live matching seed and performs a bounded resident-terrain flood fill from that seed. It does not merge separate components merely because multiple seed hints were supplied. The current hard limit is 400 accepted blocks; a larger discovered component returns non-retryable component_too_large instead of silently claiming completion.

Route seeds are worksite hints, not proof that blocks still exist. For a distant or server-specific vein, put the recorded route or coordinates in official content or route data, then let the engine validate the live exact block IDs and scan the resident connected component. Do not bake Hypixel coordinates into the general mining API.

Mine a resident area

Radius areas are spherical and accept integer radius 1 through 15:

local result = hexis.await(hexis.mining.mine_area({
    world_generation = observed.world_generation,
    area = {
        kind = "radius",
        center = {x = 20, y = 72, z = 20},
        radius = 4,
    },
    blocks = {
        priorities = {
            ["minecraft:gold_ore"] = 100,
            ["minecraft:iron_ore"] = 60,
        },
    },
    held = {name_patterns = {"Drill", "Pickaxe"}},
}), {timeout = 120})

A box area uses {kind = "box", minimum = {x,y,z}, maximum = {x,y,z}}. Bounds are inclusive, ordered, at most 32 blocks on each axis, and at most 32,768 positions total. The scanner reads resident chunks only and never causes a chunk load. It retains at most 256 matching area candidates. The action can still return success with complete = false when the scan encountered nonresident terrain or truncated more matches, so callers must inspect result data before treating an area as exhausted.

Unlike mine_connected, mine_area does not require adjacency. It is the default high-level action for a bounded group of disconnected matching blocks.

Target choice and completion truth

The engine ranks exact matching candidates by the explicit block-ID priority, distance, view direction, continuity with the last mined block, and prior failed attempts. For non-reachable candidates it generates several stable standing vantages per shortlisted target, sends all distinct vantage goals to one bounded multi-target path search, and follows the selected verified route. Lua does not choose aim points, path nodes, search limits, or retry counts.

Immediately before breaking, Hexis rechecks the world generation, exact target ID, held selector, reach, line of sight, and live crosshair. It registers a bounded watcher for server block-update packets before submitting attack. A break counts as mined only after the target disappears and the watcher saw a server update for that exact position. A local air observation alone cannot produce success. Missing confirmation returns retryable break_unconfirmed.

Successful and failed results include bounded progress evidence such as blocks_mined, candidates_found, blocks_vanished, complete, remaining_count, remaining, world_data_incomplete, truncated, handoff_effective, prediction_fallback, path-search evidence, the selected seed, last target, last vantage, and whether physical input was submitted. Cancellation after physical submission is conservatively non-retryable.

Current validation boundary

Headless focused tests cover strict decoding, priority-map meaning, shared orchestration, typed path-search evidence, confirmed fallback, cancellation, and cleanup. Three development-only embedded labs exercise exact, connected, and disconnected-area requests. They are intentionally absent from the customer catalog and marketplace surface.

Controlled live testing still needs to prove tool matching against real item names, server block-update timing, vantage and navigation behavior at actual worksites, incomplete-chunk recovery, cancellation after attack submission, and both allowed states of Ether Transmission navigation. Tick Glide also needs live measurement before predictive can become its effective handoff.

V5 clean-room reference

V5 is useful only as behavioral evidence. Its nearby miner gathers matching blocks in a bounded box, cheaply ranks candidates, runs visibility and reach checks on a shortlist, and moves toward a matching target when none is currently reachable. Its Tunnels Miner starts from recorded vein coordinates, checks which recorded blocks still match the chosen ore, derives candidate standing positions around live vein edges, and pathfinds toward those vantages. That is a hard-coded distant worksite map plus live validation, not a global search for unknown distant veins.

V5 calls its predicted next-target handoff “Tick Gliding.” It estimates mining ticks from server-specific hardness, measured mining speed, boosts, and TPS compensation, then may begin the next target before ordinary air observation. Hexis deliberately keeps that timing mechanism in Java and keeps success tied to server packet evidence.

V5 and V5Loader are GPL-3.0 projects. Hexis does not copy or translate their source. These links pin the clean-room behavioral reference used for this design:

Shared request policy​

Mine one exact block​

Mine one connected component​

Mine a resident area​

Target choice and completion truth​

Current validation boundary​

V5 clean-room reference​