org_web/docs/princess-lima-map-authoring.md

Princess Lima v2 map authoring

Runtime contract

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 current source maps live in assets/maps/princess-lima/. Rebuild them with:

node tools/generate-princess-lima-maps.mjs

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.

Every map has these uniquely named layers:

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 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.

EasyStar receives a navigation grid derived from the collision layer at runtime. It is pathfinding only; Phaser remains responsible for movement and physics.

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

The Node map tests validate layers, IDs, transitions, safe spawns, navigation reachability, and content references. During manual authoring, also:

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.

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.