Refine Princess Lima for v2 presentation

docs/princess-lima-map-authoring.md

@@ -1,58 +1,87 @@
-# Princess Lima map authoring
+# Princess Lima v2 map authoring
 
-## Framework
+## Runtime contract
 
-Use [Tiled](https://www.mapeditor.org/) as the visual authoring tool and Phaser
-as the runtime. Every region is a 720×720 orthogonal map whose locked image
-layer is the corresponding frame from `regional-style-atlas.png`.
+Princess Lima uses committed Tiled JSON maps rendered by Phaser 4.1.0. The
+regional style atlas is reference art only and must never be used as runtime
+terrain or collision geometry. Maps use orthogonal 32-pixel tiles and may vary
+in width and height.
 
-The runtime contract mirrors Tiled object groups in
-`PrincessLimaData.MAP_LAYERS`. Every map has these named layers:
+The current source maps live in `assets/maps/princess-lima/`. Rebuild them with:
 
-1. `Collision`
-2. `Dynamic Collision`
-3. `Exits`
-4. `NPCs`
-5. `Enemies`
-6. `Puzzles`
-7. `Items`
+```sh
+node tools/generate-princess-lima-maps.mjs
+```
 
-Do not paint collision or interaction geometry into the finished artwork.
-Production collision objects are invisible.
+The generator is deterministic so authored content can be reviewed as ordinary
+JSON. It creates the nine production regions and a Tiled tileset reference.
+Hand editing in Tiled is supported as long as the schema below is preserved.
 
-## Collision rules
+Every map has these uniquely named layers:
 
-- Trace only terrain that is visibly solid: buildings, walls, cliff faces,
-  deep water, fences, furniture, and the four outer edges.
+1. Base terrain
+2. Terrain variation
+3. Paths
+4. Water
+5. Cliffs and buildings
+6. Props
+7. Objects behind actors
+8. Actor layer
+9. Objects above actors
+10. Shadows
+11. Lighting
+12. Collision
+13. Interaction zones
+14. Dialogue triggers
+15. Quest triggers
+16. Enemy zones
+17. Camera zones
+18. Scene transitions
+19. Named safe spawns
+20. Audio zones
+21. Optional secrets
+
+Object IDs must be unique. Scene transitions require valid `target` and `spawn`
+properties. Enemy objects require a validated `enemy` ID. Dialogue objects use
+a validated `dialogue` ID. Safe spawns are named points and may not overlap
+collision.
+
+## Collision and navigation
+
+- Trace only visibly solid buildings, walls, cliffs, water, fences, furniture,
+  and map edges.
 - Keep paths, doors, bridges, stairs, and floor tiles walkable.
-- Use rectangles while the game uses Phaser Arcade Physics. A future switch to
-  Matter Physics can use Tiled polygon objects without approximating them.
-- Every dynamic blocker needs an `opensWith` property matching a validated
-  route ID.
-- Never put a puzzle control, item, actor, or safe spawn inside collision.
-- Keep enemies away from puzzle controls and safe spawns.
+- Use rectangles while the runtime uses Arcade Physics.
+- Never place a required objective, transition, actor, or safe spawn inside
+  collision.
+- Keep encounter zones away from chapter-safe spawns.
+- Preserve a collision-free route between each required spawn and objective in
+  every reachable state variant.
+- Route blockers must name the flag or quest consequence that opens them.
 
-## Interaction rules
+EasyStar receives a navigation grid derived from the collision layer at runtime.
+It is pathfinding only; Phaser remains responsible for movement and physics.
 
-- Exits, NPCs, enemies, puzzles, and items belong on their named object layer.
-- Puzzle and item labels appear only within 92 pixels of the player.
-- The interaction radius is 54 pixels; exit portals use 70 pixels.
-- Every mechanism must be reachable before the state change it triggers.
-- Interaction labels must use the object name rather than an unexplained shape.
+## Interactions and state variants
+
+Interaction objects declare a short `action` or `observation`. Reusable actions
+include `puzzle`, `chest`, `free-prisoner`, `disable-defence`,
+`route-choice`, and `boss-mechanic`. Secrets use the Optional secrets layer.
+Resolved variants are driven by `<region>_resolved` story flags and must leave
+all required routes reachable.
 
 ## Verification
 
-On localhost, use:
+The Node map tests validate layers, IDs, transitions, safe spawns, navigation
+reachability, and content references. During manual authoring, also:
 
-```text
-/play/rpg.html?region=mountain&spawn=bridgeControls
-/play/rpg.html?region=mountain&spawn=bridgeControls&collisionDebug=1
-```
+1. Inspect the clean render and collision-debug render.
+2. Walk every boundary and transition in both directions.
+3. Exercise locked and resolved routes.
+4. Check all named spawns after save/reload.
+5. Repeat transitions while watching the browser console and memory.
+6. Confirm production URLs never expose debug geometry.
 
-Before publishing:
-
-1. Compare the clean rendered map with its locked source image.
-2. Enable collision debugging and check every visible boundary.
-3. Walk each route in both its locked and unlocked states.
-4. Confirm all object-layer points pass the collision-safety tests.
-5. Confirm ordinary production URLs show no collision geometry.
+Use `?collisionDebug=1` on localhost for Arcade Physics bounds. The v2 save
+always restores at a named chapter-safe spawn rather than trusting legacy
+coordinates.