Lua v4 Navigation Action
hexis.navigate.to asks Hexis to reach one exact world position. Lua chooses
the destination, arrival tolerance, whether Ether Transmission may be used,
and what to do with the typed result. Hexis owns path search, route execution,
following, reroutes, safe stop, and control cleanup.
The typed implementation corresponds to loader 0.9.715, module 0.1.236,
module API protocol 3, and minimum loader 0.9.715. An older loader cannot
safely activate this module. This is source and compatibility evidence, not a
claim that the Lua call has completed controlled live acceptance.
Exact request
The request accepts only destination, optional arrive_within, and optional
allow_ether_transmission:
local navigation = hexis.navigate.to({
destination = {x = 100.5, y = 64, z = 200.5},
arrive_within = 2.0,
allow_ether_transmission = false,
})
local result = hexis.await(navigation, {timeout = 45})
destination contains exactly finite numeric x, y, and z coordinates.
arrive_within is a request-local Euclidean distance in blocks. It defaults to
2.0 and accepts any finite number from 0.5 through 8.0, inclusive. It does
not read or change a global Pathfinder arrival setting.
allow_ether_transmission is an optional boolean that defaults to false.
Explicit true requires the bundle and current execution authority to allow
the conditional etherwarp capability. The current Pathfinder release still
has Ether Transmission parked, so this field is contract syntax rather than
live Ether Transmission evidence.
The action requires navigation and pathfinding. It owns MOVEMENT and
CAMERA; an explicit Ether Transmission opt-in can also require ATTACK_USE
and HOTBAR. Malformed tables, unknown fields, non-finite coordinates, an
out-of-range arrival tolerance, or missing capabilities are catchable Lua
errors before navigation begins.
Exact terminal data
A terminal outcome produced by the navigation mechanism carries:
{
destination = {x = 100.5, y = 64, z = 200.5},
arrive_within = 2.0,
distance_remaining = 1.37,
}
destination and arrive_within repeat the accepted request. The finite
distance_remaining is the player's three-dimensional distance from that
destination when Hexis records the outcome. Preflight failure, lifecycle
invalidation, or an exception before typed terminal evidence exists can carry
empty action data.
Why unreachable is narrow
The path search now preserves four distinct termination reasons across the native and Java boundary:
| Search termination | Meaning | Lua action result |
|---|---|---|
REACHED | Search found route evidence to the requested arrival region | Continue following; return ok only after the player finishes within arrive_within |
NODE_LIMIT | The bounded search budget ended before a complete answer | Retryable navigation_failed |
FRONTIER_EXHAUSTED | Every reachable node in a complete known frontier was explored without reaching the goal | Non-retryable unreachable |
TERRAIN_INCOMPLETE | Resident terrain evidence was insufficient for a complete answer | Retryable navigation_failed |
These search terminations are engine evidence, not extra Lua result codes. Only
complete FRONTIER_EXHAUSTED evidence may become unreachable. Node-budget
exhaustion and missing terrain must never be mislabeled as proof that the
destination cannot be reached. The same rule applies to an initial search and
a later reroute.
Follower stalls, route-commit rejection, stopping outside the requested
tolerance, unavailable player or world state, and pathfinder or engine
failures also map to retryable navigation_failed. Lua should observe current
state before retrying. It should treat non-retryable unreachable as evidence
to choose a different destination or policy, not as a reason to repeat the
identical request immediately.
Action results
| Code | Retryable | Meaning |
|---|---|---|
ok | No | The player finished within the accepted arrive_within distance |
unreachable | No | A complete search frontier was exhausted without reaching the arrival region |
navigation_failed | Yes | Search was bounded or terrain-incomplete, or route execution/following failed without proof of unreachability |
busy | Yes | Required navigation controls were unavailable |
cancelled | No | The action was cancelled and synchronously safe-stopped |
internal_error | No | Navigation construction or safe-stop cleanup failed; failed safe stop quarantines the shared controls |
An await deadline cancels and consumes the action, waits for safe stop, and
returns timeout. World, authority, or runtime invalidation uses the shared
typed lifecycle result. No terminal result becomes visible until navigation is
stopped and its controls are released.
Acceptance gate
Before the call becomes public and AI-runnable, the named compatible build must
verify arrival at several tolerances, already-inside-tolerance completion,
complete frontier exhaustion, node limits, missing chunks, follower stalls,
reroute failures, cancellation, contention, world change, and failed safe stop
on a real client. In particular, a test must prove that incomplete terrain and
budget exhaustion remain retryable while only a complete frontier becomes
unreachable.