Public API contractVerified 2026-08-13Not yet executable

Some v4 members exist in the source foundation; no v4 call is AI-runnable until a distributed build records acceptance evidence.

Lua v4 Contract

Lua v4 is a hard break from the v3 source inventory. A v3 function is not part of v4 unless it appears in the generated v4 registry. Some members are implemented in the source foundation, but nothing on this page is an accepted public or AI-runnable call yet.

Lua chooses goals, priorities, fallbacks, and how completed actions compose. Hexis owns timing-sensitive movement, targeting, aiming, mining, interaction, resource ownership, and cleanup.

Static script bundles

The script catalog reads a bundle manifest without executing Lua. Each manifest has a stable script ID and version, entrypoint, display metadata, configuration schema, requested capabilities, runtime compatibility, exact dependencies, and exact content files. Manifest schema 2 adds strict bundle-local pack descriptors for server-specific workload data. This exists in the source foundation but remains non-public until distributed-build acceptance; see Lua v4 Script Content Packs. The implemented content-source boundary lists metadata and prepares one exact selected bundle. Embedded official and local development sources use that same replaceable boundary, so a future marketplace source does not require a second runtime path.

Catalog listings identify their source, compatibility, configuration schema, and descriptive install state. A listing is metadata, not executable code. The runtime starts only a prepared bundle from a content source. Marketplace download, install, update, removal, publisher verification, and remote trust policy are not implemented by this source foundation and remain separate from the public Lua contract.

Actions and results

Long-running operations return action handles. Only the host waits on them:

local handle = hexis.navigate.to({
    destination = {x = 100, y = 64, z = 200},
    arrive_within = 2.0,
    allow_ether_transmission = true,
})

local result = hexis.await(handle, {timeout = 45})
if not result.ok and result.code == "unreachable" then
    return try_another_destination()
end

This syntax exists in the source foundation and is not executable in an accepted distributed build yet.

Every terminal result contains:

• status: succeeded, failed, or cancelled;
• ok: whether the action reached its requested outcome;
• code: a stable machine-readable result code;
• message: user-facing context that may improve without breaking scripts;
• retryable: whether retry can be considered after observing fresh state;
• data: bounded action-specific output.

The shared result-code vocabulary is ok, cancelled, timeout, arrival_unconfirmed, unreachable, navigation_failed, target_lost, player_dead, player_low_health, component_too_large, item_not_found, aim_failed, screen_closed, screen_changed, gui_precondition_failed, world_changed, authority_lost, denied, busy, invalid_argument, and internal_error. Each concrete action emits only the subset it can prove. The initial navigator uses unreachable only when a complete path-search frontier is exhausted. Node-limit, incomplete-terrain, follower, and engine failures are retryable navigation_failed. When an await deadline expires, the host cancels that action, waits for cleanup, then returns timeout. A malformed request or missing declared capability is a catchable Lua error before dispatch, rather than an action result. See Lua v4 Navigation Action for the exact search mapping and request-local arrival tolerance.

Registry status

The generated v4 registry separates members with concrete runtime bindings from members that remain design targets. An implemented registry member exists in the v4 foundation. It is still not a public runnable promise until a named distributed build passes focused and controlled live acceptance. A planned member is documentation-only and is not placed in the Lua global.

Action surface

Domain	Registry members	Source status	Lua keeps
Area travel	hexis.area.enter	Implemented foundation	Semantic destination and result handling
Navigation	hexis.navigate.to	Implemented foundation	Destination, arrival tolerance, Ether Transmission opt-in, and typed fallback
Combat	hexis.combat.fire; hexis.combat.engage	Implemented foundation	Target selection, action choice, retries, and stop policy
GUI	hexis.gui.transact	Implemented foundation	Which observed slot matters and whether to stop or resnapshot
Foraging	hexis.foraging.catch_tadpole	Implemented foundation	Candidate selection and whether to continue
Mining	hexis.mining.mine_block; hexis.mining.mine_connected; hexis.mining.mine_area	Implemented foundation	Exact block-ID priorities, target set, tool, handoff request, navigation opt-in, and recovery policy
Inventory	hexis.inventory.ensure_held	Implemented foundation	Ordered acceptable tools and the fallback when none is present
Interaction	hexis.interact.use	Implemented foundation	Exact air, block, or entity target and fallback

The implemented-foundation observation surface is hexis.world.blocks.observe, hexis.world.blocks.find, hexis.world.entities.find, and hexis.world.crosshair.observe. The implemented-foundation GUI observation is hexis.gui.snapshot. The implemented-foundation content-pack surface is hexis.content.pack, and the implemented-foundation configuration read surface is hexis.config.snapshot.

Intentional server-area transfer uses hexis.area.enter({destination = ...}). Lua never supplies a warp command or arrival evidence. See Lua v4 Area Transitions for its typed outcomes, hidden official catalog, exclusivity, and world-generation adoption contract.

Combat has two distinct implemented-foundation actions. hexis.combat.fire sends one stationary ranged shot and never claims a hit or defeat. hexis.combat.engage pursues and fights one exact target with bounded melee_kite behavior and reports defeat separately from target loss and player_dead. Its optional finite stop_below_health_percent field accepts 1 through 100; omission preserves the existing behavior with no implicit threshold. A threshold crossing is the non-retryable player_low_health result, after mechanism-owned control cleanup. The official Sven workload maps its required flee_health setting, default 10 and bounded 5 through 20 in steps of 5, into that optional action field. Hunting remains Lua target-selection and sequencing policy, so v4 does not define hexis.combat.hunt. See Lua v4 Combat Actions for the strict requests, results, resource boundary, and live gates. Interaction likewise has one implemented target union, hexis.interact.use; v4 does not split block and entity use into parallel public calls.

Synchronous observations remain separate from actions. They return detached, bounded snapshots and never take control of movement, camera, attack, use, inventory, screens, or overlays.

Policy and mechanism boundary

Domain	Lua policy	Hexis mechanism
Area travel	Semantic destination and result handling	Validated transfer, arrival evidence, bounded same-destination attempts, and generation adoption
Navigation	Where to go, arrival tolerance, the parked Ether Transmission opt-in, and what typed fallback to try	Typed search outcome evidence, current ground-route execution and following, stuck recovery, and cleanup
Combat	Which observed target to choose, fire versus engage, retries after fresh evidence, and when to stop	Exact-identity tracking, stationary fire, aim and attack cadence, pursuit, guarded retreat, held-item validation, and cleanup
GUI	Which immutable screen evidence identifies a meaningful target and when to resnapshot or stop	Screen generations, revision journal, slot fingerprints, one guarded click or exact-revision close, event backpressure, and cleanup
Mining	Exact block-ID priorities, coordinate, connected seeds or bounded area, held selector, handoff request, navigation opt-in, and recovery	Resident target discovery, connected or disconnected selection, multi-target vantage navigation, exact aim, server-packet-confirmed breaking, bounded retry, and cleanup
Interaction	Desired entity, block, item, or menu outcome	Reach, look, target assertion, use timing, screen revision checks, and cleanup

That navigation row does not claim accepted v4 water traversal, flight, or Ether Transmission. Flight has no v4 action contract, water behavior has no recorded v4 acceptance evidence, and the Ether Transmission request field is currently parked as described below.

hexis.inventory.ensure_held chooses the first matching hotbar item from an ordered, bounded selector and leaves it selected after success. Actions that use that item must still own the hotbar and revalidate the held selector. A completed equip action is not permanent ownership.

local equipped = hexis.await(hexis.inventory.ensure_held({
    selector = {
        name_patterns = {"Treecapitator", "Figstone Splitter", "Fig Hew"},
    },
}), {timeout = 5})

hexis.interact.use is one strict target union rather than three overlapping calls. Its target is exactly one of air, a block position, or an entity identity. Block and entity variants aim and assert the live crosshair before sending one vanilla use. The air variant never means "use whatever happens to be under the crosshair."

local used = hexis.await(hexis.interact.use({
    target = {
        kind = "block",
        position = {x = -464, y = 119, z = -81},
    },
    held = {
        name_patterns = {"Superboom TNT"},
    },
}), {timeout = 5})

The entity form uses {kind = "entity", ref = {id = entity_uuid, world_generation = generation}} from a bounded observation. The engine resolves it again while aiming. A stale generation returns world_changed before acquiring controls; an entity absent from the current generation returns target_lost. It never falls back to a different entity. The air form succeeds only while the live crosshair is a miss.

If behavior coordinates several controls, runs repeatedly during an action, or must always clean up, it belongs in Hexis. Lua retains the decision around that action. Server-specific names, regions, routes, and selectors belong in pack data rather than the general API.

Waiting, events, and selection

Each running script has one owner lane. hexis.await(handle) waits without blocking the game client. hexis.select(candidates, options) waits for the first action, filtered-chat event, subscription closure, or timeout using argument order as its deterministic tie-breaker. It accepts at most 64 action handles or reusable subscription handles and rejects duplicates. An action winner is consumed; an event consumes one record but leaves the subscription open. Losers continue, and a timeout consumes or cancels nothing. Scripts cannot create runtime coroutines or call one Lua state concurrently.

The implemented event sources are filtered chat and revisioned GUI mutations. A bundle declares the matching events.chat.filtered or events.gui.filtered capability, then uses the same hexis.events.subscribe, hexis.events.next, hexis.select, and hexis.events.unsubscribe model. Filters and queues are bounded, producers never block the Minecraft client, and overflow is observable through dropped_before. See Lua v4 Filtered Chat Events and Lua v4 GUI Evidence and Actions for the exact source contracts. Neither source invokes Lua callbacks.

hexis.cancel(handle) explicitly stops one same-script action, waits up to five seconds for cleanup, consumes the handle, and returns its typed terminal result. A foreign, already-consumed, or otherwise unknown handle is a Lua error.

Both waits default to one hour and accept a bounded timeout from 0 through 3,600 seconds. An await timeout cancels and consumes that action handle. A select timeout consumes nothing.

A run generation owns every action, wait, event subscription, timer, HUD, and highlight created during that enablement. Stopping the script, changing worlds, or invalidating the run cancels old work and closes subscriptions before run completion. Terminal results are delivered only after owned controls have been released.

The generation tracks the run, world, execution authority, and runtime. A mismatch invalidates the whole old run. When more than one boundary changes, the result priority is authority_lost, then world_changed, then cancelled.

An irreversible GUI transaction adds one explicit commit boundary. Cancellation wins before the claim and prevents submission; after the claim, the GUI result wins. A mechanism exception after that claim returns non-retryable internal_error with application_uncertain = true and quarantines GUI resources. See Lua v4 GUI Evidence and Actions.

Capabilities and coexistence

Bundles request coarse capabilities such as navigation, mining, combat, interaction, inventory, GUI, HUD, overlay, or network access. Each action also acquires its concrete resources atomically. Conflicting actions receive busy; controls are never silently shared.

Request variants can require an additional declared capability. For example, setting allow_ether_transmission = true requires the bundle and the current execution authority to both allow etherwarp. The registry records this conditional rule so runtime validation, documentation, and future AI tools do not drift apart.

The current Pathfinder build has Ether Transmission parked. The v4 field is therefore contract syntax, not evidence that teleport movement is live. The official Galatea acceptance bundle keeps it false until the Pathfinder gate is unparked and tested.

The concrete control resources are movement, camera, attack/use, hotbar, inventory/screen, and overlay ownership.

There is no trusted controller or observer label. Observation and overlay scripts coexist with controlling workflows because they request non-conflicting capabilities, use isolated bounded queues, and do not acquire game controls.

Configuration and HUD status

Bundle manifests carry a strict flat configuration schema, and the source foundation now validates it, persists complete per-script values, captures one immutable snapshot when a run starts, and exposes fresh Lua copies through hexis.config.snapshot(). The call has no setter and requires no capability. A successful settings update applies only to the next run.

The current Galatea UI adapter does not yet render a customer settings editor, so the backend's write path is not exposed from that module panel. See Lua v4 Script Configuration for the exact schema keywords and bounds, stable-ID storage path, default behavior, atomic write caveat, configured official fields, and remaining live gate. Mechanism tuning such as aim deadlines and path-search budgets does not become customer configuration.

The target HUD is also schema-owned. A bundle declares a small fixed set of status fields; Lua publishes typed values only. It cannot create arbitrary coordinates, colors, fonts, images, or world overlays. HUD panels are keyed by run identity and disappear during run cleanup. These calls remain planned until their concrete registry rows and runtime services exist.

Minimal Galatea policy

hexis.mining.mine_connected is the high-level connected-block action used by Galatea. It owns live exact-ID discovery from route seed hints, valid vantage selection, multi-target navigation, exact aim, target validation, server-packet-confirmed breaking, bounded retry, and cleanup. Its public request contains the route result's world_generation, 1 through 128 seeds, an exact blocks.priorities map plus connectivity, a held selector, and optional handoff and navigation policy. Selection budgets, component limits, aiming, breaking, vantage search, jumping, navigation timeouts, and retry counts are engine policy, not Lua request fields. Galatea Lua keeps only area entry, route choice, config-controlled tree and azalea scheduling, Tadpole target choice, tool selectors, and recovery from typed results. competition_mode is only a manual switch for azalea and Tadpole detours, while max_azaleas caps successful azalea actions between trees. The current bundle has no tree_mode, stop_at_max_contest, automatic contest detection, or selling workflow. See Lua v4 Mining Actions for all three requests and the confirmed-versus-predictive truth.

local arrival = hexis.await(hexis.area.enter({
    destination = "hypixel.skyblock.galatea",
}), {timeout = 30})
if not arrival.ok then
    return arrival
end

local regeneration = hexis.events.subscribe({
    type = "chat.received",
    filter = {
        contains_any = {
            "You cannot damage a tree while it is regenerating",
        },
        case_sensitive = false,
    },
})

local harvest = hexis.mining.mine_connected({
    world_generation = route.world_generation,
    seeds = eligible_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", "Fig Hew"},
    },
    handoff = "confirmed",
    navigation = {allow_ether_transmission = false},
})

local selected = hexis.select({harvest, regeneration}, {timeout = 600})
if selected.kind == "event" then
    local cancelled = hexis.cancel(harvest)
    return wait_for_tree_regeneration(cancelled)
elseif selected.kind == "action" then
    return choose_after_harvest(selected.result)
end

local cancelled = hexis.cancel(harvest)
return stop_or_recover(selected, cancelled)

This acceptance example deliberately contains no Lua implementation of scanning, path following, camera timing, ray checks, mining retries, or control cleanup. The three named helpers are local Galatea policy, not Hexis API members. The regeneration subscription is intentionally created after area entry because a proven transition adopts the new world generation and closes old-world subscriptions. An explicit false is authoritative and does not require the etherwarp capability. Omitting the field also uses the safe false default; only explicit true opts into Ether Transmission and requires that capability.

The maintained Galatea bundle also schedules bounded route-backed Flowering Azalea harvests and composes successful azaleas with hexis.foraging.catch_tadpole. The catch action is one guarded atomic net use, not a chase. See Lua v4 Galatea Workload for the exact action and current workload boundaries. Config schema version 2 has exactly route, competition_mode, and max_azaleas. Workload schema 5 supplies tree and azalea route filters and exact block-ID priority maps without duplicating the route or azalea cap.

World evidence

Lua v4's source foundation provides bounded exact-block observations, resident-only block search, bounded entity search, and the client's actual crosshair hit. They remain non-public until distributed-build acceptance. See Lua v4 World Evidence for the frozen request, result, capability, identity, freshness, and interaction-handoff contracts.

Generated contract

The runtime-owned v4 action registry drives Lua bindings, action and observation request validation, and deterministic exports. Docusaurus consumes a recorded export to produce the human reference page, Lua annotations, and machine-readable JSON. Its build checks that those generated artifacts and every website-catalog bundle's file hashes have not drifted. An explicit cross-repository check compares the complete website catalog with every embedded official bundle, including each manifest, declared Lua file, and pack byte for byte.

Nested action schemas are not fully represented yet. Table-valued fields are therefore documented as tables instead of pretending their internal shape is machine-validated by the registry. Host request fields describe positional arguments rather than table validation. Planned calls remain non-executable until their concrete adapters exist. Implemented calls remain non-public until a named distributed build has focused and controlled live acceptance evidence.