Build map-derived playerbot navigation and transitions

[adrunkhuman]

Goal

Build destination-driven, map-derived navigation that selects efficient cross-floor routes and performs transitions through normal game mechanics. Callers provide a destination, not a hand-authored sequence of stairs, ladders, tools, or portals.

Current Baseline

• Shared directed topology covers the loaded map and supports exact, range, and alternative destination goals.
• Capability-aware routing indexes walk-on floor changes, ladders, rope and shovel transitions, ordinary map teleports, and declared ordinary/level/house doors. Door access follows the resolved action and live restrictions; windows expose no passage (Derive traversable doors from registered action semantics #200).
• Dynamic same-floor segments use normal creature pathfinding. Static topology narrows global search before bounded tile planning.
• Detailed planning uses a 1,024-tile endpoint margin and a 100000-node cap.
• Known shovel passages retain a stable topology identity across open/closed states. Travel and hunt routes walk through open passages without a shovel or use and verify a shovel on closed passages (Resolve shovel passages from their live open or closed state #203).
• Complete approved hunt routes are retained for execution. Displacement, blocked steps, failed transitions, or a replan request discard approval and require complete revalidation.
• Registered NPC travel competes with static routes. Eligible non-opaque offers retain loaded dialogue, fare, level/premium requirements, destination verification, and protected future fares/recovery funds. Local approach routing resolves the moving provider’s interaction range.
• Merged Let stuck bots fight adjacent attackers without chasing #193 replaces timed transit defense/breakout with shared movement-failure state. After failed movement, the bot may fight one adjacent attacker without chasing or requiring proof that killing it opens a route. It prefers the intended-step attacker, otherwise the easiest survivable fight, and retains that target until passage opens, the target dies/leaves reach, safety changes, or the workflow is interrupted. Passive blockers and genuinely unreachable destinations remain distinct.
• Movement, item use, use-with, doors, and transitions execute through normal game APIs and action delays.

Delivered Work

• Index walk-on stairs and holes from floor-change metadata and actual destinations.
• Index and execute ladders.
• Index and execute rope spots and rope holes when the bot has a rope.
• Index and execute shovel holes when the bot has a shovel, including closed/open dynamic state.
• Index and execute ordinary teleports whose destination is available from loaded map state.
• Traverse ordinary unlocked doors through normal movement/use behavior.
• Cost walking segments and transitions so a cross-floor route can beat a longer same-floor route.
• Cache static navigation topology and bound per-decision planning work.
• Verify transition outcomes and provide bounded retry, replan, and terminal behavior.
• Replace hardcoded Rookgaard transition checkpoints with destination-driven planning and retain the route as regression coverage.

Remaining Work

• Define encounter-aware movement using visible threats and permitted memory (Define playerbot perception and memory beyond visible targets #84), coordinated with combat tactics (Build reusable playerbot combat targeting and tactics #54) and retreat (Playerbot survival: healing, retreat, and recovery #38). Cover travel, patrol, target approach, and corpse collection. Deferred; do not implement static spawn exclusion zones as the final solution. See evidence and agreed scope.

• Recheck the historical Folda narrow-corridor/respawn failure against the shared movement fallback merged in Let stuck bots fight adjacent attackers without chasing #193. The original incident used the superseded timed breakout; do not restore or extend that mechanism. Preserve runtime evidence, related tactics Build reusable playerbot combat targeting and tactics #54. Focused movement-fallback evidence does not establish all passive-blocker cases.

• Demonstrate ordinary dynamic-blocker reliability beyond the deterministic Svargrond fixture. Merged Fix playerbot routing around blocked approaches #198 excludes blocked approaches, rejects forbidden exact goals early, distinguishes search-budget exhaustion from unreachability for paid fallback, and bounds fare/safety rejection recovery. The fixture reaches its destination on foot without NPC travel.

• Reuse or expose authoritative datapack transition semantics instead of copying rope, hole, ladder, and tool item-ID lists into playerbot navigation.

• Support locked doors and key matching, vocation/premium gates, and quest/storage-backed access.

• Integrate eligible registered, non-opaque NPC travel with hunt/depot routing, normal dialogue/payment, and arrival verification.

• Extend transport to unsupported NPC-mediated gates, schedules, opaque/custom conditions or actions, and remaining boat/carpet/steamship/mine-cart semantics. Registered-offer support does not imply complete transport coverage.

• Support stateful and consumable transitions, including scarab-coin, carried/equipped-item, one-way, timed, and mutable-world requirements.

• Support additional elevation and obstacle mechanics such as levitate, parcel stacks, pickaxes, and machetes where loaded semantics can be exposed safely.

• Represent satisfiable missing requirements as sub-objectives without retrying unsupported transitions.

• Complete focused transition fixtures for the remaining supported classes.

Door passage contract

Delivered by #200:

• Door actions publish per-item closed/open pairs and supported access behavior from authoritative Lua tables. Navigation preserves unique-ID → action-ID → item-ID override precedence; unannotated overrides inherit no passage permission.
• Validate opening targets against loaded metadata, preserve live level/house checks, execute normal actions, and verify that the whole tile becomes enterable.
• Windows expose no passage. Unknown transitions remain unsupported; planning does not guess from names or adjacent IDs, parse Lua source, or execute unknown actions speculatively.
• Passage descriptions follow action registration/reload lifetime and topology invalidation.
• Cover ordinary/level doors, locked/quest/house restrictions, overrides, windows, reloads, and a real route that rejects a window shortcut.

Entry points: server/data/scripts/actions/others/{doors,windows}.lua, server/src/actions.{h,cpp}, luascript.cpp, and playerbotnavigation.cpp / playerbottopology.cpp. Locked/key, quest/storage, vocation, and premium access remain outside the supported passage contract.

Route Contract

Derive static walkable regions and transition candidates from loaded map and shared datapack semantics. Search a capability-aware graph globally, then execute local segments and transitions through normal Game, movement, item-use, spell, and interaction APIs. Verify every transition and replan after obstruction, map-state change, displacement, or failed requirement.

A mapped transition is not necessarily usable. Inventory, level, vocation, storage, combat/PZ state, keys, money, and other requirements can change availability or cost.

Every long-term edge must report source, expected destination, directionality, cost, current availability and reason, ordered activation protocol, required state, consumed resources, changed state, success verification, partial-activation recovery, and whether a missing requirement is impossible, temporary, or satisfiable through another objective.

Regression Contract

• Route to supplied hunting and service destinations and back with map-derived transitions.
• Prefer a cross-floor route when its estimated cost is lower.
• Report missing tools and requirements instead of retrying blindly.
• Replan in bounds from the actual position after a blocked segment or failed transition.
• On restart, discard transient paths and reconstruct navigation from persisted objective and player state.
• Cover same-floor travel, cheaper cross-floor travel, rope, ladder, shovel, mutable portal, teleport, unlocked door, missing-tool failure, blockage recovery, and patrol recovery.
• Emit JSONL destinations, plans, replans, requirements, failures, timing, and terminal reasons without logging every successful tile.

Constraints

• Treat loaded map and shared game/datapack semantics as authoritative; do not maintain a hand-curated world-route database.
• Coordinates are valid destinations and regression fixtures, never production transition checkpoints.
• Do not parse Lua source at runtime for semantics.
• Do not run unbounded whole-map tile search per bot decision.
• Preserve protocol 8.60 gameplay rules and normal server validation.
• Keep work on the dispatcher/scheduler model; do not add one thread or blocking loop per bot.
• Fail unsupported transitions explicitly and never bypass them.

Related: #22, #51, #148, #160.

[adrunkhuman]

PRs #161, #162, and #170 are merged. The body now records the map-wide topology, mutable-portal, retained-route, and complete-revalidation baseline. Authoritative transition descriptors, access gates, mediated transport, stateful transitions, and remaining fixtures stay open.

[adrunkhuman]

Merged #186 (af562324dade073590fc6edd349cbac83f9df108). Hunt planning now considers registered NPC transport, validates a depot exit near the selected hunt and required supplier routes, and protects later fares/recovery funds. Nearby approach changes retain blocker/failure evidence; exhausted blocked transit has a bounded no-chase breakout. Focused navigation/transit and corpse regressions passed. Unsupported opaque/scripted transport and the remaining transition classes stay open.

[adrunkhuman]

Folda return blocked after a successful Frost Troll hunt

Observed during ordinary autonomous play on 2026-09-13, not a fixture. The hunt finished with 91 kills, 2,791 XP and 120 gold, but Bot One exhausted return-navigation recovery and stopped.

• At 19:16:20.823Z, terminal reason navigation_route_unavailable, position (32001,31560,8), goal return_to_depot. Still had 303/305 HP, 20 potions and 227 total gold.
• Depot planning repeatedly found a mainland route, while runtime approach to the Folda captain area (32045,31578,7) returned Unreachable with zero movement. No boat refusal or fare failure occurred.
• Repeated defensive_path_blocker events identified adjacent Frost Trolls. Some were killed, but the approach remained blocked. The leading hypothesis, also strongly suspected by the operator, is trolls repeatedly occupying a narrow corridor. The exact obstructed tile/transition is not yet confirmed.
• The bounded 30-second transit_breakout expired. Investigate the disagreement between depot route validation and live NPC-approach execution, including whether blocker combat permits useful forward progress before respawns close the corridor again. Related tactics: Build reusable playerbot combat targeting and tactics #54.

Start with PlayerBotController navigation recovery/NPC approach in server/src/playerbotcontroller.cpp and route-critical defensive targeting in server/src/playerbotcombat.cpp. Reproduce the narrow-corridor/respawn case and preserve bounded dispatcher work and normal movement/combat APIs; do not merely raise retry limits without identifying the failure.

Evidence: run 65b5a621a09a1; hunt completion sequences 28899687–28899692; route failures 28900280 and 28900476; breakout 28900507. Local-only captured log: /tmp/bot-return-route-20260913T194848Z.log (not uploaded; may be removed). User saved the server before requesting a server-only restart as a recovery attempt; outcome not yet verified.

[adrunkhuman]

Reproduced the Svargrond blocked-approach failure from (32251,31136,7) toward Robert at (32232,31076,6). Suppressing (32250,31136,7) left topology selecting that same approach: it checked the transition target/arrival but not the approach. Local search exhausted 100,000 nodes; direct local search avoiding that square reached Robert in 88 steps / 6,171 nodes.

The fallback was Svargrond → Thais (110 gp, Captain Breezelda) → Svargrond (180 gp, Captain Bluebear). The original service incident recorded 1,152 fare/reserve rejections over about 25 minutes. Each rejection reset fixed-goal failure history. An idle pushable Husky did not reproduce the full movement failure; the deterministic reproduction starts from the blocked-position entry, not a claim that every nearby Husky stalls the bot.

Implemented locally on fix/playerbot-local-route-recovery, based on f99680f; uncommitted, unpushed, unmerged. The correction selects an alternate local transition, rejects explicitly blocked exact goals early, prevents local NodeLimit from automatically selecting paid fallback, and counts fare/risk rejection toward bounded recovery.

The real-map regression reaches Robert on foot and forbids paid plans/successful NPC travel. Fare and risk fixtures reach failure counts 1–20, emit one terminal event, and remain silent afterward. Focused navigation/looting checks passed; independent review found no remaining material findings. This is not proof of sustained ordinary progression or every dynamic blocker.

Reproduction and validation evidence is machine-local under ~/venore-8-20-20260921T211126Z/repro/ (not uploaded). real_depot and carlin_local_service assertions failed identically on detached master; those were not changed to make this work pass.

[adrunkhuman]

Mammoth encounters during ordinary hunting exposed a potential gap between route safety and encounter avoidance. The earlier fights were not retained, so their exact approach paths remain unverified.

Code inspection confirms that route danger estimates brief exposure around spawn locations, with distance falloff. It does not model provoking pursuit. Rejecting a mammoth hunting region therefore does not guarantee that movement through a nearby easy region avoids encountering one. Relevant entry points are PlayerBotHuntRegionAdapter::travelDanger() and corridorDanger() in server/src/playerbothuntregionadapter.cpp, and PlayerBotNavigationCostPolicy::dangerCost() in server/src/playerbotnavigation.cpp.

Defer implementation. Future behavior should use visible creature positions and permitted remembered observations (#84), with spawn data as advance warning—not assume monsters remain at their spawns or read hidden creatures' live positions. It must remain useful with multiple bots moving creatures around. Cover travel, patrol, target approach, and corpse collection; coordinate engagement decisions with #54 and retreat with #38. Keep bounded retreat and hunt abandonment as the current fallback.

Split out a focused child issue when the perception and movement contract is concrete enough to implement. Do not implement static spawn exclusion zones as the final solution.

[adrunkhuman]

Merged #200 and #203: action-declared door passages exclude windows; shovel passages use live open/closed state. #198 is also merged. Encounter avoidance, broader access/transition support, and ordinary dynamic-blocker reliability remain open.