Target contractVerified 2026-07-23Not yet executable

Normative raw-security boundary; operation names remain provisional.

hexis.raw

hexis.raw keeps Lua capable when a high-level action does not fit. It exposes small, safe Minecraft operations through the same scheduler and security model as the rest of Hexis.

Raw means lower abstraction, not unrestricted Java access.

Candidate capability groups

Group	Purpose
hexis.raw.input	Lease and control movement, attack, use, and hotbar input
hexis.raw.camera	Look toward a point or orientation under explicit timing
hexis.raw.interaction	Interact with a validated block/entity hit result
hexis.raw.raycast	Request engine-executed ray observations
hexis.raw.inventory	Low-level synchronized slot operations
hexis.raw.world	Narrow block/entity snapshot queries

Exact names are provisional. Each operation must still be typed, capability gated, cancellable where long-running, client-thread safe, rate limited, and bound to a resource scope.

Example custom sequence

hexis.script({
    api = "4.0",
    name = "Custom Interaction",
    version = "0.1.0",
    capabilities = {
        "raw.camera",
        "raw.interaction",
        "raw.raycast",
    },
})

local scope = hexis.scope({
    name = "Custom interaction",
    capabilities = {
        "raw.camera",
        "raw.interaction",
        "raw.raycast",
    },
})

local hit = hexis.raw.raycast.block({
    origin = "eyes",
    direction = {x = 0.2, y = -0.6, z = 0.7},
    max_distance = 5,
    scope = scope,
})

if hit then
    local aimed = hexis.await(hexis.raw.camera.look_at({
        target = hit.position,
        duration = 0.18,
        scope = scope,
    }))

    if aimed.ok then
        hexis.await(hexis.raw.interaction.use_block({
            hit = hit,
            hand = "main",
            scope = scope,
        }))
    end
end

scope:close()

The child scope can only narrow the manifest's capabilities; it cannot grant authority. The target runtime closes it automatically on failure, cancellation, script stop, or world change.

Responsibilities at raw level

When Lua chooses raw capabilities, it owns more policy:

• sequencing and retry decisions;
• validating that observations still match its goal;
• selecting timeouts and stop conditions;
• handling resource conflicts and expected failures;
• composing actions into a coherent workflow.

The engine still owns:

• client-thread dispatch;
• input and camera resource leases;
• rate and instruction budgets;
• cancellation and forced cleanup;
• safe serialization;
• capability enforcement;
• supported Minecraft interaction paths.

What raw never exposes

• luajava, reflection, or arbitrary class construction;
• direct network sockets, filesystem, processes, or native loading;
• unrestricted packet creation or sending;
• mutable Minecraft client/world/entity objects;
• unmanaged threads or callbacks;
• a way to bypass a denied high-level capability.

AI policy

AI generation should prefer the highest-level capability that preserves the user’s intent. Raw is appropriate when:

• no high-level contract represents the mechanic;
• the user explicitly requests a custom mechanism;
• the script is an experiment used to discover a future reusable action.

Raw-overuse is an API quality signal. Repeated raw recipes should be evaluated as candidates for a protected engine action, not copied into every generated script.