Target API Overview

Proposed syntax

The examples on this page define acceptance targets. Do not assume these functions exist in the current runtime until the page is marked Implemented.

The target API is organized around capabilities, not around every internal Java method. High-level actions do useful work, observations return immutable data, events report change, and hexis.raw provides deliberate low-level control.

Candidate surface

Namespace	Role	Typical ownership
`hexis.navigation`	Reach a destination under constraints	Engine action
`hexis.mining`	Select and harvest blocks/resources	Engine action
`hexis.combat`	Hunt, engage, or disengage targets	Engine action
`hexis.camera`	Track or frame a subject	Engine action
`hexis.inventory`	Observe and transact inventory state	Engine action/query
`hexis.world`	Immutable block/entity/spatial observations	Query/event
`hexis.gui`	Synchronized screen transactions	Engine action
`hexis.hud`	Script-scoped presentation	Resource
`hexis.events`	Typed bounded subscriptions	Event
Side-effect capabilities	Chat, commands, HTTP, notifications, storage	Gated action/resource
`hexis.packs`	Server-specific semantic knowledge	Pack adapter
`hexis.raw`	Safe low-level game capabilities	Raw action/query

Namespace and function names remain candidate vocabulary until a vertical slice passes its acceptance gates. The rules below are stable design constraints.

One obvious long-running pattern

local action = hexis.navigation.go({
    destination = {x = 100, y = 64, z = 200},
    arrive_within = 2,
})

local result = hexis.await(action, {timeout = 30})

if not result.ok then
    hexis.log.warn(result.code .. ": " .. result.message)
end

Avoid parallel families such as to, start_async, is_navigating, arrived, and last_error. One action handle owns state, progress, cancellation, and its terminal result.

Contract shapes

Requests

Requests use one named table when a capability has options. Unknown keys fail validation. Units, coordinate frames, defaults, and ranges are explicit.

Results

Every terminal result has:

{
    ok = true,
    code = "OK",
    message = "Destination reached",
    retryable = false,
    data = {},
}

Failures are values for expected game outcomes. Invalid calls and violated invariants are validation/runtime errors with structured diagnostics.

Observations

Observations are serializable snapshots tagged with world identity and tick/time. They do not expose mutable Java objects.

Handles

Action, subscription, HUD, and scope handles are opaque. They expose only their documented lifecycle operations and become invalid when their owning scope ends.

Composition rules

Lua can await, time out, cancel, sequence, branch, and race actions.
Engine actions may contain sophisticated internal coordination.
Resource conflicts are explicit, never last-writer-wins.
Every loop has a stop condition, event wait, or bounded delay.
Every server-specific selector comes from a pack.
Raw is chosen intentionally and asks for narrower capabilities.

What should not cross the boundary

The public API does not expose arbitrary Java classes, reflection, threads, packets, mutable Minecraft objects, engine implementation classes, or internal algorithm state. Diagnostics explain decisions without revealing protected behavior-quality internals.

How names become final

A candidate capability is named only after representative tasks and production scripts establish its semantic center. AI evaluations then test whether models select it correctly without inventing adjacent calls. If not, revise the contract before adding more domains.

Contract map

Concern	Normative page
Types, requests, results, errors, and resources	Contract conventions
Manifests, scopes, scheduling, and composition	Core runtime
Movement and path execution	Navigation
Scanning and harvesting	Mining
Targeting, engagement, and view control	Combat and camera
Slots, containers, and screens	Inventory and GUI
Blocks, entities, events, and world identity	World and events
User presentation and generated configuration	HUD and config
Chat, commands, network, and persistence	Side effects and external I/O
Low-level controls and observations	`hexis.raw`
Compatibility and migration	Versioning
Evidence required to ship	Acceptance matrix

Candidate surface​

One obvious long-running pattern​

Contract shapes​

Requests​

Results​

Observations​

Handles​

Composition rules​

What should not cross the boundary​

How names become final​

Contract map​