# 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?