Inventory and GUI Contract
Inventory and GUI work is transactional. Lua describes desired state or a semantic menu operation; Java owns screen revision checks, click ordering, acknowledgement, retries, and recovery.
Candidate surface
| Capability | Purpose |
|---|---|
inventory.snapshot | Immutable player/container inventory observation |
inventory.ensure | Reach a desired loadout or item state |
inventory.transact | Execute validated inventory operations |
gui.transact | Execute semantic menu operations |
Simple bounded snapshots may return synchronously after the client-thread gateway. Transactions always return action handles.
Observations
Every snapshot contains world_generation, screen_revision, container type,
slot records, cursor state, and selected hotbar slot. Item records use stable
Minecraft identifiers, count, damage, and sanitized component data. Pack
annotations may add semantic tags but never replace the base identity.
Snapshots are immutable. A transaction submitted against an old revision fails instead of clicking a newly changed screen.
Transaction request
local action = hexis.inventory.transact({
expected_revision = snapshot.screen_revision,
operations = {
{kind = "select_hotbar", slot = 2},
{kind = "move", from = 18, to = 5, count = 1},
},
atomic = true,
})
Operations are validated as a complete plan before the first mutation. atomic
means Hexis will not start if preconditions fail; Minecraft cannot guarantee
rollback after a server accepts a partial sequence, so results always describe
which operations were acknowledged.
Semantic GUI
local sell = hexis.gui.transact({
menu = pack.menus.resource_vendor,
operation = pack.operations.sell_inventory,
constraints = {keep = pack.items.protected},
})
Packs own menu titles, layout relations, item lore interpretation, and semantic operations. Core owns synchronized interaction, revision checks, close/open transitions, and bounded acknowledgement.
Resources and results
Transactions hold inventory and, when a container is open, screen.
Hotbar-only actions may hold hotbar. Combat, mining, and raw interaction
cannot mutate the same resources concurrently.
Progress phases are validating, waiting_screen, executing, confirming,
and recovering. Result data includes acknowledged operations, final revision,
and a sanitized final snapshot.
Domain codes include SCREEN_REQUIRED, SCREEN_CHANGED, SLOT_CHANGED,
ITEM_NOT_FOUND, CURSOR_NOT_EMPTY, TRANSACTION_REJECTED,
ACK_TIMEOUT, PARTIAL_APPLY, and MENU_UNRECOGNIZED.
Acceptance tasks
- Snapshot player and container inventories with stable revisions.
- Reject a stale transaction before any click.
- Confirm each operation against server-observed state.
- Report partial application without claiming rollback.
- Cancel between operations and leave no held cursor/input state.
- Handle screen close, replacement, lag, and world unload.
- Resolve inventory contention with mining/combat explicitly.
- Execute one generic container fixture without a pack.
- Execute one pack-provided semantic menu transaction.
- Ensure AI uses semantic operations instead of guessed slot numbers when a pack contract exists.