Polish Princess Lima map data and interaction feedback

docs/princess-lima-map-authoring.md

@@ -0,0 +1,58 @@
+# Princess Lima map authoring
+
+## Framework
+
+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`.
+
+The runtime contract mirrors Tiled object groups in
+`PrincessLimaData.MAP_LAYERS`. Every map has these named layers:
+
+1. `Collision`
+2. `Dynamic Collision`
+3. `Exits`
+4. `NPCs`
+5. `Enemies`
+6. `Puzzles`
+7. `Items`
+
+Do not paint collision or interaction geometry into the finished artwork.
+Production collision objects are invisible.
+
+## Collision rules
+
+- Trace only terrain that is visibly solid: buildings, walls, cliff faces,
+  deep water, fences, furniture, and the four outer 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.
+
+## Interaction rules
+
+- 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.
+
+## Verification
+
+On localhost, use:
+
+```text
+/play/rpg.html?region=mountain&spawn=bridgeControls
+/play/rpg.html?region=mountain&spawn=bridgeControls&collisionDebug=1
+```
+
+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.