# 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:

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