API Contract Conventions
Every public capability follows this contract. A domain cannot invent its own timeout model, result shape, cancellation semantics, or unit conventions.
What is frozen
- one capability registry describes every AI-visible operation;
- long work returns an action handle;
- expected game failures are structured results;
- invalid calls fail before engine work starts;
- observations are immutable, serializable snapshots;
- scopes own handles and cancel children;
- resource conflicts are explicit;
- server semantics enter through versioned packs;
- public values never contain mutable Java or Minecraft objects.
Exact non-navigation operation names are provisional until their vertical slice passes the promotion gates.
Choose the highest useful abstraction
Repeated raw compositions are evidence that the engine is missing a reusable capability.
Types and units
| Type | Contract |
|---|---|
Vec3 | Decimal x, y, z in blocks |
BlockPos | Integer block-cell coordinates |
Rotation | Yaw and pitch in degrees |
| Duration | Decimal seconds; never ticks or milliseconds |
| Distance | Decimal blocks |
| Identifier | Stable lowercase dotted string |
| Timestamp | Monotonic seconds for durations; wall time only for display |
Player positions use feet coordinates. Every world value carries an internal
world generation; stale snapshots fail with WORLD_CHANGED.
Request rules
- Operations take one named table when they have options.
- Unknown keys, wrong types, non-finite numbers, and invalid ranges fail before resource acquisition.
- Defaults are defined in the capability registry and returned by discovery.
nilmeans omitted, not “use a hidden sentinel.”- Requests are copied at submission; later Lua mutations have no effect.
- Selectors are declarative data, not callbacks into Java loops.
Actions and progress
Long-running work transitions through:
CREATED → QUEUED → RUNNING → SUCCEEDED | FAILED | CANCELLED
Progress has phase, message, fraction when measurable, and typed domain
data. Progress is advisory and may be coalesced; terminal results are never
dropped. Callbacks execute serially on the owning Lua lane.
Terminal result
{
ok = false,
code = "NO_PATH",
message = "No reachable route satisfied the constraints",
retryable = true,
action_id = "01J...",
data = {},
diagnostics = {},
}
All domains share OK, CANCELLED, TIMEOUT, WORLD_CHANGED,
RESOURCE_BUSY, CAPABILITY_DENIED, PACK_UNAVAILABLE, INVALID_REQUEST,
and INTERNAL_ERROR. Domain pages define additional stable codes.
Expected Minecraft outcomes return results. Contract violations raise a
structured Lua error containing code, path, expected, and received.
Resources
The registry declares resources such as movement, camera, interaction,
hotbar, inventory, and screen. Acquisition is atomic and ordered by the
engine. Conflict policy is fail, wait, or permitted preemption. Scripts
cannot claim a higher trust priority than their manifest allows.
Every terminal path releases resources, held inputs, subscriptions, highlights, and HUD state before the result becomes visible.
Naming
- Names describe outcomes:
navigation.go, notstart_pathfinder. - One semantic action has one public name.
- Booleans read positively, such as
avoid_liquids. - Result codes are uppercase stable identifiers.
- Server brands, item aliases, and menu names do not appear in core contracts.
- Deprecation always names a replacement and removal version.
Discovery
The registry projection available to tools and AI contains descriptions, input and output schemas, defaults, permissions, resources, errors, pack requirements, examples, deprecations, and implementation status. If a capability is not marked Implemented, script-generation tools must not offer it as runnable.