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

Chunk Storage And Streaming

What It Does

World data is stored as per-chunk JSON files and loaded into the editor as chunk neighborhoods around a center chunk. The runtime caches chunk payloads, shifts neighborhoods as the viewport moves, and saves dirty chunks in batches.

Key Files

• server.js
• src/worldChunking.ts
• src/worldshaperStudio/bootstrap.ts
• src/worldshaperStudio/runtime.ts
• src/worldshaperStudio/persistenceController.ts

Endpoints It Uses

• GET /api/world/:worldId/chunk/:chunkX/:chunkY
• POST /api/world/:worldId/chunk/:chunkX/:chunkY
• GET /api/world/:worldId/chunks
• POST /api/world/:worldId/chunks/batch-save

Important Data And Rules

• chunks are stored as content/worlds/<worldId>/chunks/<x>_<y>.json
• world neighborhoods are requested as a square around a center chunk
• runtime keeps a chunk cache and tracks dirty chunk keys
• chunk payloads include roomLayers, heightLayers, instances, and optional backgroundTileId

Invariants And Constraints

• Exact chunk lookup is grid-based and direct.
• The editor does not load the entire world for normal editing.
• Small tile edits must sync back into the correct cached chunk.
• Save flow should preserve chunk-local edits without rebuilding unrelated chunks.

Common Request Themes

• chunk loading speed
• chunk streaming behavior
• per-chunk backgrounds
• chunk transforms, duplication, deletion
• performance questions around indexing and caching

Triage Questions

• Is the request about storage, fetch patterns, cache behavior, or save behavior?
• Does it affect only visible chunks or the full world?
• Is the user asking for chunk-local data, or freeform world overlays that break chunk assumptions?