sdk.path

A* on Data.map.walkable / game.map.find_path. Cross-floor uses stairs and teleports from world.bin. Does not walk or attack. 8-way; diagonal is illegal if either adjacent cardinal is blocked. Live creatures do not block. Default Chebyshev cap is 128. Spec: docs/superpowers/specs/2026-08-21-sdk-path-design.md

local M = require("sdk.path")

Constants

Lua 5.4 has no enums — these are integer (or string) fields on the module.

Name	Value	Summary
range	128	—

to

function · to(from, dest, opts)

Returns table|nil: hit { target, goal, path, steps, partial }

Parameters

Name	Type	Summary
from	Pos	—
dest	Pos	—
opts	table|nil	range, partial, blocked/occupied, walkable, prefer_dir, turn_penalty, clearance, avoid_unpass, opened

Returns

Type	Summary
table|nil	hit { target, goal, path, steps, partial }
string|nil	err one of: unknown, too far, no path, map miss

find

function · find(q, opts)

Live creature with that name wins over Data.npc / town / waypoint.

Parameters

Name	Type	Summary
q	string|Pos	name or tile
opts	table|nil	from, range, ...Path.to opts

Returns

Type	Summary
table|nil	hit Path.to row plus kind/target
string|nil	err one of: unknown, no session, too far, no path, map miss

near

function · near(here, kind, opts)

Live only: kind is "npc" | "monster" | "creature".

Parameters

Name	Type	Summary
here	Pos	—
kind	string	—
opts	table|nil	—

Returns

Type	Summary
table|nil	hit
string|nil	err

recorded

function · recorded(from, route, opts)

Replay a recorded route as authoritative movement rather than feeding a future waypoint back into A*. A recorded tile was physically reached by the player, so it is better evidence than the static walk map (especially around roofs and doors). This function never skips corners or advances progress before the caller observes the new position.

follow

function · follow(from, route, opts)

Follow a recorded route without re-anchoring backwards on every tick. Returns a normal Path.to hit decorated with route_index/goal_index/direction.