Mining Contract
Lua owns resource goals, region choice, competition policy, inventory policy, and stop rules. The engine owns scanning, connected-block analysis, vantage selection, navigation, camera alignment, ray verification, break timing, recovery, and cleanup.
Candidate surface
| Capability | Purpose |
|---|---|
mining.harvest | Complete resource-harvesting job |
mining.break_block | Break one validated block target |
mining.inspect | Bounded immutable mining observation |
These names become final only after the Galatea parity slice.
Harvest request
local job = hexis.mining.harvest({
region = pack.regions.galatea_grove,
resource = pack.resources.fig_logs,
policy = {
avoid_players_within = 8,
stop_when_inventory_full = true,
max_consecutive_failures = 5,
},
tool = {
prefer_tags = {"axe"},
allow_swap = true,
},
})
Regions and semantic resources come from packs. Core also accepts engine-neutral block selectors for local-world use. Every search has explicit spatial and work budgets.
Mechanism boundary
The engine is responsible for:
- spatial candidate discovery and cache invalidation;
- connected-block and reach analysis;
- stable scoring and bounded target blacklisting;
- vantage and navigation coordination;
- camera/resource arbitration;
- live ray verification before interaction;
- tool selection and synchronized hotbar use;
- break progress, retries, and stuck classification;
- cleanup of held inputs, highlights, workers, and leases.
Lua may branch on structured outcomes, change policy, select another region, or start an inventory workflow. It does not reimplement the mechanism loop.
Progress and result
Progress phases are searching, approaching, aligning, breaking,
recovering, and stopping. Data may include candidate count, redacted target
position, harvested count, inventory pressure, and failure streak.
Success or policy-stop data contains:
{
harvested = 42,
elapsed = 118.4,
stop_reason = "INVENTORY_FULL",
failures = {unreachable = 2, obstructed = 1},
}
Policy stops can be successful outcomes. Mining adds NO_TARGET,
TARGET_UNREACHABLE, TARGET_CHANGED, TOOL_UNAVAILABLE,
BREAK_REJECTED, INVENTORY_FULL, and COMPETITION_LIMIT.
Resources
Harvesting can atomically require movement, camera, interaction, and
hotbar. Inventory transactions are requested only through the inventory
domain. A single-block action may require fewer resources, but raw input never
bypasses the lease model.
Pack boundary
Packs provide resource identities, region geometry, item semantics, server restrictions, and optional route/topology hints. Core contains no Hypixel island, Treecapitator, lobby, menu, resource, or sell-policy assumptions.
Acceptance tasks
- Break a reachable block with verified aim and cleanup.
- Reject a changed or obstructed target without attacking the wrong block.
- Bound an empty-region search by time and scanned volume.
- Cancel during navigation, aiming, and breaking without held input.
- Stop on full inventory with a structured policy result.
- Recover from a rejected tool swap and report the reason.
- Match Galatea’s trusted target selection and behavior in replay and live use.
- Run an engine-neutral harvesting fixture without a server pack.
- Prove world unload invalidates caches and workers.
- Show that AI-generated policy uses the job action instead of recreating its mechanism with raw calls.