Runtime and Actions
Long-running game behavior is represented by an action, not by a blocking Java call plus unrelated status functions.
local trip = hexis.navigation.go({
destination = {x = 100, y = 64, z = 200},
arrive_within = 2,
})
local result = hexis.await(trip)
The exact names are provisional. The lifecycle semantics are not.
Action state machine
Every action must support:
- a stable identity and capability name;
- validated immutable input;
- progress snapshots when meaningful;
- cooperative cancellation with a deadline;
- exactly one terminal result;
- engine-enforced resource cleanup;
- structured telemetry that can explain failure.
Result contract
{
ok = false,
code = "NAVIGATION_NO_PATH",
message = "No traversable route reached the destination",
retryable = true,
data = {
last_position = {x = 91.5, y = 64.0, z = 182.0},
},
}
Codes are stable and machine-readable. Messages are diagnostic. Optional data uses documented serializable values. Java exceptions and live Java objects never cross the public boundary.
Scheduling model
Lua policy runs on one deterministic script lane. Minecraft access and time-sensitive work run through the client-thread scheduler or protected native workers. Workers return immutable data; they do not mutate Minecraft directly.
Resource ownership
Actions lease named resources such as:
- movement;
- camera;
- attack/use input;
- hotbar selection;
- inventory GUI;
- HUD/world overlays.
Conflicts are rejected, queued, or resolved by an explicit parent composition policy. Scripts do not silently fight over controls. Releasing the action releases its leases even after error, cancellation, script stop, disconnect, or world unload.
Waiting and concurrency
hexis.await(action) suspends the Lua task without blocking the Minecraft client
thread. Target composition primitives are:
- await one action;
- wait for the first of several actions;
- set a timeout;
- cancel a scope;
- subscribe to typed progress/events.
Parallelism is explicit. An AI should not create hidden background work merely by calling an “async” variant of every function.
World lifecycle
World identity is attached to observations and actions. Disconnect, dimension
change, respawn, or server transfer invalidates world-scoped handles. The runtime
cancels affected actions before new-world work begins and returns a structured
reason such as WORLD_CHANGED.
Cleanup guarantee
“Automatic cleanup” is a contract only when the engine can prove ownership of every acquired resource. Each implemented action must have tests for normal completion, failure, cancellation, timeout, script stop, and world unload.