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.