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.