Worldshaper/docs/kb/systems/layers-tile-editing.md

Layers And Tile Editing

What It Does

This subsystem handles normal tile painting, erasing, selection, visible layer management, sparse height layers, and the mapping between visible document edits and stored chunk data.

Key Files

• src/worldshaperStudio/interactionController.ts
• src/worldshaperStudio/runtime.ts
• src/worldshaperStudio/sidebarController.ts
• src/worldshaperStudio/mapDocumentController.ts
• src/worldshaperStudio/popupSessionStore.ts
• src/worldshaperStudio/dom.ts

Endpoints It Uses

• primarily saved through POST /api/world/:worldId/chunks/batch-save

Important Data And Rules

• room layer 0 is the base layer
• non-base layers use sparse or transparent-style fill semantics
• height layers are separate structures from room layers
• visibility is tracked in popup session state
• painting in world mode must mark affected chunks dirty

Invariants And Constraints

• layer ordering matters to rendering and selection behavior
• layer visibility must not destroy layer data
• tile edits in world mode must map local viewport coordinates back to world chunk coordinates
• height layers are not the same thing as standard room layers

Common Request Themes

• better layer reordering
• more precise tiling tools
• height/elevation features
• snapping or unsnapped placement
• erase or selection behavior

Triage Questions

• Is this about normal room layers or height layers?
• Does the request affect paint semantics, visibility, ordering, or storage?
• Does it apply to map mode, world mode, or both?