---
title: "World detail — terrain, voxels, streaming, LOD"
description: "Four systems decide how much of a world stands at any one moment:"
section: "Topics"
slug: "topics-world-detail"
canonical: "https://origozero.ai/docs/topics-world-detail"
updated: "2026-10-15T11:08:40.374013079+00:00"
---

# World detail — terrain, voxels, streaming, LOD

- **terrain** — a heightfield drawn through a quadtree LOD cut that refines
  under the camera
- **voxels** — a `VoxelWorld` split into chunks, each meshed on the GPU into
  its own child entity
- **spatial streaming** — a cell store that stands and releases groups of
  entities as sources move
- **mesh LOD** — a level chosen per entity from how much of the viewport it
  spans

Reading a `Terrain`, `VoxelWorld`, `StreamingSource` or `MeshLod` component's
fields back tells you what was **asked for**. The `streaming` namespace answers
the other question: what is standing, what it costs, and for a piece that is
not on screen, which of a closed set of reasons it is not.

## What is resident right now

```lua
local reading = streaming.observe()
reading.totals        --> voxelChunks / voxelChunksMeshed / voxelChunksFailed /
                      --  voxelGpuBytes / terrainEntities / terrainBound /
                      --  terrainIndexCount / cellsTotal / cellsResident /
                      --  cellsPending / cellBytesResident / lodReceivers
reading.terrain       --> per Terrain entity: bound, nodeCount, indexCount,
                      --  vertexCapacity, meshGuid, and the eye the cut refined under
reading.voxel         --> per VoxelWorld: chunksTotal / meshed / queued / failed /
                      --  empty, gpuBytes, and one row per chunk
reading.cells         --> the store's config, its counters, and one row per cell
reading.levels        --> per LOD receiver: the level it draws at and the screen
                      --  fraction that selection was measured from
```

Each axis reads on its own too: `streaming.terrain()`, `streaming.voxel()`,
`streaming.cells()`, `streaming.levels()`.

The same document is served at `/zero/runtime/observations/streaming`. It is
built by the call and published as its last act, so the namespace and the VFS
node carry one reading rather than two derivations of it:

```lua
local served = require("@builtin::modules.json").decode(
    vfs.read("/zero/runtime/observations/streaming"))
served.reading.totals.voxelChunksFailed
```

Nothing is computed per frame. An engine nobody is observing pays nothing, and
`streaming.observe()` is the only thing that builds the reading.

### Which pool a number belongs to

`voxelGpuBytes` is what the voxel chunk builds reserved on the device — the
vertex pool at the renderer's own stride plus one `u32` per reserved index. It
is that pool alone. The terrain pool is reported as `vertexCapacity` per
terrain entity, the streaming store's bytes as `cellBytesResident`, and every
resource the device holds under any system is `renderer.gpuMemory()` and
`asset.observe()`.

## Why a piece is not on screen

```lua
streaming.whyNotDrawn(entityOrName)                     -- whichever system holds it
streaming.whyNotDrawn({ entity = "Vox", chunk = "0_0_0" })  -- one voxel chunk
streaming.whyNotDrawn({ entity = rock, level = 0 })         -- one mesh-LOD level
streaming.whyNotDrawn({ cell = "3_-2" })                    -- one streaming cell
```

The answer is `{ kind, reason, detail }`. `reason` is one of the set
`streaming.reasons()` enumerates, and `detail` names what it is about:

| reason | what it means |
|---|---|
| `drawn` | the engine holds this subject's geometry and is drawing it |
| `notManaged` | no terrain, voxel, streaming or mesh-LOD system holds it |
| `notBuilt` | nothing has built this subject's geometry |
| `buildQueued` | a build has been asked for and has not run yet |
| `buildFailed` | a build ran and the engine did not carry it through — `detail` is the engine's own message |
| `builtEmpty` | a build ran over a region holding nothing to draw |
| `emittedNothing` | the build ran and the shader wrote no geometry into the capacity it reserved |
| `outsideRadius` | no streaming source is close enough to want it resident |
| `evicted` | it was resident, the store released it, and its content now reads from the file the release wrote |
| `coarserLevel` | a coarser LOD level is the one selected, so this level is not the one drawn |
| `finerLevel` | a finer LOD level is the one selected, so this level is not the one drawn |
| `noSuchLevel` | the LOD chain holds no level with this number |
| `hidden` | the entity carrying the geometry is switched off |

## A voxel world that stands and draws nothing

A chunk's state is the **engine's** verdict on the build, not the component's
record of having asked for one. `VoxelWorld:dirtyChunks()` empties as soon as
each chunk has been *attempted*; `VoxelWorld:chunks()` says what became of the
attempt:

```lua
for _, chunk in ipairs(world:chunks()) do
    print(chunk.key, chunk.state, chunk.detail)
end
-- 0_0_0  buildFailed  the compute shader never compiled within 10000ms, so the dispatch was dropped
```

Each row carries `state`, `detail`, `dispatches` and `failures` from the
engine's dispatch record, the block count the build read (`solidVoxels`), what
it reserved (`reservedVertices`, `reservedIndices`, `gpuBytes`), and the entity
and mesh the chunk draws through.

The join is the buffer prefix: every buffer of a build is created under one, and
the engine's dispatch record names it — so `chunk.buildPrefix` is what holds a
chunk against `compute.program.status(shaderGuid)` directly.

### Reserved is not emitted, and the row carries both

`reservedVertices` / `reservedIndices` are the capacity the build asked the
device for, sized off an upper bound before the shader ran. `emittedVertices` /
`emittedIndices` are what the shader actually wrote, read back off the counters
it increments as it emits.

They are different numbers and the difference is a whole class of failure. A
dispatch the device carried through that wrote nothing leaves a chunk holding a
`MeshHandle`, a plausible `gpuBytes`, `failures = 0` — and no geometry. That
chunk reads `emittedNothing`, and **`meshed` is only ever reported for a chunk
whose counters say geometry is there**.

The read is issued once the engine has recorded the dispatch reaching the
device — a read issued before that returns the zeros the build wrote into the
counters, which is indistinguishable from a shader that emitted nothing. Until
it lands, the chunk reads `queued` with a detail saying the answer is not in
yet; `emittedVertices` and `emittedIndices` are absent from the row.

`Gpu.emitted(chunk.buildPrefix)` waits for that read rather than reporting the
absence, for a caller that wants the number and not the state.

## Publishing a reading of your own

`/zero/runtime/observations` is generic. Any Luau system can put a reading on
the engine's shelf and gain a VFS leaf without a change to the engine:

```lua
__observations.publish("mySystem", { resident = 12, pending = 3 })
-- served at /zero/runtime/observations/mySystem as
-- { name = "mySystem", publishedAtMs = ..., reading = { ... } }
__observations.names()   --> { "mySystem", "streaming" }
```

The document is serialised at the moment of the call, so the bytes the VFS
hands out are the bytes of the table the publishing call built.