Core Runtime API
The core API is deliberately small. Domain capabilities plug into the same manifest, scope, action, and result model.
Script manifest
hexis.script({
api = "4.0",
name = "Resource Collector",
version = "1.0.0",
capabilities = {
"navigation.go",
"mining.harvest",
"inventory.observe",
"hud",
},
packs = {
["hypixel.skyblock"] = "^2.1",
},
})
The manifest is evaluated before ordinary script code. It declares the maximum authority the script may use; runtime code cannot add capabilities. Unknown or unavailable requirements prevent start with a structured diagnostic.
Root and child scopes
Every run has a root scope. Actions, subscriptions, HUD elements, highlights, and child scopes belong to it. Stopping the script closes the root.
local raw_scope = hexis.scope({
name = "Custom interaction",
capabilities = {"raw.camera", "raw.interaction"},
deadline = 10,
})
A child capability list may only narrow its parent. Actions attach to the root
unless their request explicitly contains scope = raw_scope. Closing a scope:
- prevents new children;
- requests cancellation;
- waits through a bounded cleanup grace period;
- force-releases engine-owned resources;
- invalidates its handles.
scope:close(reason) is idempotent.
Action handles
Domain actions return opaque handles:
local action = hexis.navigation.go({
destination = {x = 100, y = 64, z = 200},
arrive_within = 2,
})
The stable handle surface is:
| Member | Meaning |
|---|---|
action:id() | Stable operation ID for logs and telemetry |
action:state() | Current action state |
action:cancel(reason) | Idempotent cancellation request |
action:on_progress(callback) | Scoped, serial progress subscription |
Polling state is for diagnostics, not control loops.
Await
local result = hexis.await(action, {
timeout = 30,
cancel_on_timeout = true,
})
hexis.await yields only the current Lua coroutine. It never blocks the client
thread. Timeout defaults to cancelling the child action and returns TIMEOUT.
Cancellation of the caller propagates to the awaited child unless
detach = true was explicitly permitted by policy.
Select
local selected = hexis.select({navigation, danger_event}, {
timeout = 30,
cancel_remaining = true,
})
hexis.select returns {index, handle, result} for the first terminal child.
Ordering breaks same-lane ties deterministically. It does not discard the
terminal result or silently cancel losers.
Cleanup helper
hexis.defer(callback) registers lightweight Lua cleanup on the current scope.
Callbacks run once in reverse registration order with a bounded budget. They
cannot start new actions. Engine cleanup never depends on Lua cleanup
successfully completing.
Validation and failures
Calls validate against the registry before dispatch. Invalid syntax, missing capabilities, and unknown fields produce structured errors. Queueing, world-state, resource, and gameplay failures produce normal results.
No public operation exposes threads, futures, Java objects, reflection, packet construction, or arbitrary filesystem/network access.
Scheduler guarantee
Each script has one Lua execution lane. Top-level code, event callbacks, progress callbacks, deferred cleanup, and resumed coroutines are serialized on that lane. The client-thread gateway owns Minecraft access; worker pools return immutable messages to the lane.