Target contractVerified 2026-07-23Not yet executable

Acceptance tutorial for v4 navigation; not executable yet.

Your First Target Script

warning

This tutorial demonstrates the planned API. Use it as an acceptance example, not as a script for the current v3 runtime.

This script asks Hexis to navigate, waits for the result, and handles expected failure. Lua chooses the goal; the engine owns pathfinding, movement, recovery, and cleanup.

hexis.script({
    api = "4.0",
    name = "Walk to a Point",
    version = "0.1.0",
    capabilities = {
        "navigation.go",
        "hud",
    },
})

local config = hexis.config({
    arrive_within = hexis.config.number({
        label = "Arrival distance",
        default = 2,
        min = 1,
        max = 5,
    }),
})

function hexis.main()
    local trip = hexis.navigation.go({
        destination = {x = 100, y = 64, z = 200},
        arrive_within = config.arrive_within,
    })

    local result = hexis.await(trip, {timeout = 45})

    if result.ok then
        hexis.notify("Destination reached")
        return
    end

    if result.code == "NAVIGATION_NO_PATH" then
        hexis.notify("No safe route was found")
        return
    end

    if result.code ~= "CANCELED" then
        hexis.log.warn(result.code .. ": " .. result.message)
    end
end

What the script owns

• the destination;
• acceptable arrival distance;
• how long the user is willing to wait;
• which failures deserve a notification;
• whether another action should follow.

What Hexis owns

• reading the current world safely;
• selecting and executing a route;
• movement and camera coordination;
• reacting to changing blocks;
• action progress and cancellation;
• releasing inputs after every terminal outcome.

Why there is no loop

The navigation action is itself long-running. hexis.await suspends this Lua task without blocking the Minecraft thread. The engine completes ticks at game speed and returns one result.

Extending the plan

Composition stays readable:

local trip = hexis.await(hexis.navigation.go({destination = target}))

if trip.ok then
    local harvest = hexis.await(hexis.mining.harvest({
        region = work_area,
        target = resource,
    }))

    if not harvest.ok and harvest.retryable then
        -- Lua decides whether retrying still serves the user's goal.
    end
end

Do not replace the mining action with a large Lua implementation of scanning, vantage selection, aiming, and break timing. Use hexis.raw only when the custom mechanic truly requires it.

Acceptance checklist

Before this tutorial becomes Implemented, the shipped binding must prove:

• reachable, blocked, timeout, cancel, and world-change outcomes;
• no leaked movement/camera input;
• stable error codes and serializable diagnostics;
• correct AI generation from a plain-language request;
• parity between the documented example and a focused runtime test.