88 lines
3.0 KiB
Markdown
Executable File
88 lines
3.0 KiB
Markdown
Executable File
# 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.
|