Public API contractVerified 2026-08-13Not yet executable

hexis.area.enter is implemented in the source foundation; it is not AI-runnable until distributed-build acceptance.

Lua v4 Area Transitions

hexis.area.enter is the implemented-foundation boundary for moving an official script into a known game area. Lua names a semantic destination. The host owns transfer, arrival proof, retries, control cleanup, and the intentional world-generation change.

This page remains non-executable until a named distributed build passes controlled live acceptance.

Request

The bundle must declare area.travel.

local arrival = hexis.await(hexis.area.enter({
    destination = "hypixel.skyblock.galatea",
}), {timeout = 30})

The request contains exactly one field: the nonblank semantic destination string. It has no command, warp slug, server address, arrival text, retry count, or timeout field. Unknown request fields and a missing capability are catchable Lua errors before dispatch.

The action owns movement, camera, attack/use, hotbar, and inventory/screen for the transition. It can start only when it is the run's sole action and no other area transition is active. Contention returns a retryable busy result instead of sharing old-world controls.

Successful results

Success returns the shared action result with this exact data shape:

{
    status = "succeeded",
    ok = true,
    code = "ok",
    message = "",
    retryable = false,
    data = {
        destination = "hypixel.skyblock.galatea",
        outcome = "arrived", -- or "already_present"
        attempts = 1,
        world_generation = 8,
    },
}

already_present means current server evidence already proved the destination, so the host sent no transfer. Its attempts value is 0. arrived means a transfer was sent and later proved; attempts starts at 1.

Expected failure results

The stable area-specific result codes are:

Code	Retryable	Meaning	Data
invalid_argument	No	Destination is blank or absent from this bundle's official catalog	Empty
busy	Yes	Required controls, another action, or another transition prevents an exclusive transfer	Empty
denied	No	The connected server is outside the destination's allowlisted host	destination, attempts, command_dispatched
arrival_unconfirmed	Yes	Bounded attempts completed without stable destination evidence	destination, attempts, command_dispatched
internal_error	No	The mechanism or safe-stop boundary failed	Empty

For denied, attempts is 0 and command_dispatched is false. For arrival_unconfirmed, command_dispatched is true. User cancellation, hexis.await timeout, authority loss, runtime invalidation, and an unauthorized world change use the shared cancelled, timeout, authority_lost, or world_changed lifecycle results.

Messages are human context, not branching keys. Lua should branch on code, retryable, and the typed data fields. retryable means the script may consider requesting the same semantic destination again after observing fresh state. The action never redirects to the Park, chooses an alternate destination, or runs a fallback route.

Generation adoption

Ordinarily, a world-generation change invalidates the old run. An active area.enter is the one narrow exception:

1. The host makes the transition action exclusive, so no old-world action can survive it.
2. It dispatches only the official catalog's validated transfer.
3. After a transfer, arrival must match on two observations from the same new world generation at different observed ticks.
4. The runtime adopts only that proven world-generation component, closes the run's old event subscriptions, and completes the action.
5. Lua continues in the same run and may create new-world subscriptions and actions after the successful result.

Run, authority, and runtime generations are never adopted. If any of those change, if the observed generation does not match the one being adopted, or if the world changes without destination evidence, the host safe-stops the run with the applicable lifecycle result. Galatea therefore subscribes to its chat event only after area.enter succeeds.

Hidden official catalog

Destination evidence and transfer mechanics live in one integrity-bound hexis.area_catalog pack inside an official embedded bundle. That pack is validated before Lua but is intentionally hidden:

• hexis.content.pack cannot return it;
• Lua cannot inspect host allowlists, arrival evidence, or transfer values;
• marketplace and development bundles cannot define an area catalog;
• a bundle cannot fall back to a global catalog; and
• Lua cannot provide raw warp commands or arbitrary destination mechanics.

The public contract is the semantic destination ID and typed action result. Adding another destination is an official catalog and acceptance change, not a new raw-command API.