sdk.destinations

@type library Semantic destination and multi-hop NPC travel resolver. It converts the generated town/NPC/travel catalog into a small graph; local walking remains the responsibility of sdk.path / sdk.navigator.

local M = require("sdk.destinations")

area

function · area(q)

Resolve the exact official Cyclopedia area selected by the planner. Area IDs are JSON numbers but plans intentionally store them as strings.

area_position

function · area_position(q)

Area catalog row plus a walkable position. Plans store area ids as strings. Common: use this, not M.area alone, when Path.to needs a coordinate.

nearest_town

function · nearest_town(where)

Closest official town by Chebyshev to its temple, with a heavy floor penalty. Different-z temples (rooftops, boats) must not beat a same-floor neighbour.

in_settlement

function · in_settlement(here, opts)

True when here is within SETTLEMENT_RADIUS of an official temple (1 floor slack). Streets around a temple are not PZ; this is "in town", not "in protection zone". Common: override opts.towns in tests; reject temples with x/y < 1000 as junk.

graph

function · graph(npc_rules)

Town-to-town travel graph from Data.travel(), skipping avoid/depot-only NPCs. Each edge is one boat/carpet hop; local walking between NPC and temple is Path.

travel_route

function · travel_route(from, destination, npc_rules)

Cheapest multi-hop NPC travel from from town to destination town. Dijkstra on M.graph; empty route means already in that city. Common: pass planner npc_rules so "priority" boats beat a longer walk-equivalent cost.

npc_for_action

function · npc_for_action(npc_rules, action, from)

Per-NPC planner actions can nominate a concrete depot/service waypoint. Returning a catalog position makes the rule operational even when the NPC is not currently in the creature list.

resolve

function · resolve(destination, from)

Normalize a planner destination (position/city/npc/area/hunt/depot) to a walk target. City resolution also returns travel legs. Common: from is the player tile so multi-stand NPCs pick the nearest catalog position.