Worldshaper/docs/kb/systems/chunk-storage-streaming.md

# Chunk Storage And Streaming

## What It Owns

This system owns the world-mode chunk model: loading chunk neighborhoods, composing chunk data into the current editor session, and persisting chunk updates back to disk.

## Core Behaviors

- Load a neighborhood of chunks around a world position.
- Compose room layers from chunk-local rows into a temporary larger editing surface.
- Compose sparse height layers from chunk data.
- Compose placed instances and overlays from chunk payloads.
- Batch-save chunk changes back to the API.

## Important Data

Chunk payloads can contribute:

- `roomLayers`
- `heightLayers`
- `instances`
- `backgroundTileId`
- chunk coordinates and dimensions

## Important Files

- `server.js`
- `src/worldChunking.ts`
- `src/worldshaperStudio/bootstrap.ts`
- `src/worldshaperStudio/runtime.ts`

## Known Behavior Notes

- The bootstrap path currently loads a neighborhood around an initial bookmark or world center instead of streaming every chunk in the world.
- Exact chunk access is grid-based, so many performance requests should start with profiling the current neighborhood/cache path before proposing spatial trees.
- World mode is not editing one isolated chunk in a vacuum; it edits a composed surface backed by many chunk records.

## Relationships

- Feeds `Layers And Tile Editing`, which paints onto the composed chunk neighborhood.
- Feeds `World Overview`, which visualizes and transforms chunk-level records.
- Depends on `Persistence And Save Pipeline` to write chunk mutations.
- Feeds `Rendering And Viewport`, which only draws what the currently loaded chunk neighborhood exposes.

## Triage Hints

Requests about chunk loading, chunk transforms, chunk duplication, world streaming, chunk persistence, spatial indexing, and neighborhood performance should start here.