sdk.transitions

Automatic entrances for pathing. Interactive blockers are discovered from Tibia's live map stack and approached by the caller; request() performs one brokered use and verifies the resulting teleport/open state.

local M = require("sdk.transitions")

key

function · key(door)

Stable identity for one stack object: xyz + id + stackpos. Failed-entrance maps and broker keys must not collapse two stacked items.

should_discover

function · should_discover(reason, away, talk_range, phase)

Discover only while walking and still outside talk range. planned/blocked/stuck are the only walk failures that justify a door scan.

is_entrance

function · is_entrance(door, item)

Fail-closed entrance test: usable, not furniture, door words or minimap 186. Open doors (unpass ~= true) must not be used -- that toggles them shut. New official ids with no legacy row rely on the fixed-blocker + color signature.

live_entrance

function · live_entrance(door)

Return the exact live stack object that discovery selected. This is the fail-closed boundary before an entrance can be used: catalog heuristics by themselves never authorize an interaction after the map stack changed.

validate_activation

function · validate_activation(candidate, here)

Player must stand adjacent on the same floor as the live stack object. Catalog heuristics never authorize use; live_entrance is the fail-closed gate.

choose

function · choose(candidates, here, dest, anchor, failed)

Lowest-score unused candidate; id tie-break keeps the choice stable. failed[] is a key set from M.key so a bad door is not retried this walk.

approach

function · approach(here, door, opts)

Shortest Path.to an adjacent walkable tile that A* actually reached. Goal snapping can pick the enclosed side of a door; require hit.goal == asked tile.

discover

function · discover(here, dest, anchor, opts)

Scan Tiles.around for usable entrances near dest/anchor and pick one. Only candidates with a proven adjacent approach are eligible.

check_effect

function · check_effect(door, origin, here, opts)

Classify the use: teleported, opened, or unchanged. Refresh is opt-in; an unconditional memory reread can race a newer door packet.

activate

function · activate(candidate)

Broker send body: Tools.door on the frozen stack identity. validate_activation must have already confirmed the live object.

request

function · request(owner, candidate, origin, opts)

Returns a broker ticket. Call result(ticket) for nil/pending, true/effect, or false/error. The caller remains responsible for re-planning after true.

result

function · result(ticket)

Poll helper: pending / confirmed effect / failed status for a request ticket. Evidence is weak-keyed on the ticket so a coalesced retry keeps the original.