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

Layers And Tile Editing

What It Owns

This system owns the main world-canvas tile workflow: selecting a room layer, choosing a tile brush, painting, erasing, and editing sparse height layers in world mode.

Core Behaviors

• Freehand tile painting on the active layer.
• Shape strokes for the world canvas:
  • freehand
  • rectangle outline
  • circle outline
  • line with axis lock behavior
• Height-layer painting modes:
  • single or freehand paint
  • rectangle fill
  • circle fill
  • erase variants for the same shapes
• Background-cell editing modes:
  • explicit tile stamp
  • transparent hole
  • inherit world background

Important UI Surfaces

• Layers sidebar
• Height layer list
• Canvas brush interactions
• Background mode button and preview

Important Files

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

Known Tool Details

• Tile strokes register history entries with shape-specific labels such as rectangle stroke, circle stroke, brush stroke, and erase stroke.
• Height strokes register their own history labels and track the target Z layer.
• Layer editing is tightly coupled to the currently loaded chunk neighborhood in world mode.
• Brush behavior depends on catalog tile metadata resolved through runtime helpers.

Relationships

• Depends on Content Catalog And Records for tile definitions and brush metadata.
• Depends on Chunk Storage And Streaming for the currently editable chunk neighborhood.
• Depends on Persistence And Save Pipeline for actually writing edits back to storage.
• Feeds Rendering And Viewport, which visualizes the edited layers and sparse height patches.

Triage Hints

Requests about rectangle tools, brush behavior, height painting, active layer confusion, background stamping, and tile-placement modes should usually start here, even when they also touch rendering or chunk persistence.