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

Princess Lima map authoring

Framework

Use Tiled 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:

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