---
title: "streaming"
description: "What the engine has resident of a world's detail right now, and why a piece of it is not on screen."
section: "API Reference"
slug: "api-streaming"
canonical: "https://origozero.ai/docs/api-streaming"
updated: "2026-10-20T13:15:37.043666422+00:00"
tags: ["api", "reference"]
---

# streaming

What the engine has resident of a world's detail right now, and why a piece of it is not on screen. Covers the four systems that decide how much of a world stands at any moment: terrain's LOD cut, a voxel world's chunk meshes, spatial streaming's cell store, and mesh LOD's level selection. Reading a `Terrain`, `VoxelWorld`, `StreamingSource` or `MeshLod` component's fields back tells you what was asked for. `streaming.observe()` answers the other question: what is standing, what it costs, and for a chunk that is not drawn, which of a closed set of reasons it is not drawn for. The same reading is served at `/zero/runtime/observations/streaming`. It is built by the call and published as its last act, so both transports carry the document one pass produced.

```lua
require("@builtin::modules.api.engine.streaming") -- streaming (also available as global 'streaming')
```

The `streaming` namespace: 21 functions.

## globals/streaming/cells {#globals-streaming-cells}

```lua
streaming.cells() -> { [string]: any }
```

What the spatial-streaming store has resident: the configured radii and
budget, the counters the store keeps, and one row per cell with how many of
its groups are standing, what it costs, and whether a release wrote it to a
file it now reads back from.

**Returns** `{ [string]: any }` — `{ config, stats, sources, cells, proxies }`.

```lua
local s = streaming.cells()
```

## globals/streaming/levels {#globals-streaming-levels}

```lua
streaming.levels(scene: any?) -> { [string]: any }
```

Which level every mesh-LOD receiver is drawing at, and the screen
fraction that selection was measured from.
A receiver whose entity the scene no longer holds is reported as
`standing = false`: the chain is registered and there is nothing left for
it to draw.

**Parameters**

- `scene` `any` _(optional)_ — The scene walk to read against. Omitted, the call takes its own.

**Returns** `{ [string]: any }` — `{ count, receivers }`.

```lua
local l = streaming.levels()
```

## globals/streaming/observe {#globals-streaming-observe}

```lua
streaming.observe() -> { [string]: any }
```

The whole reading in one document: terrain, voxel, streaming cells and
mesh LOD, plus the totals those rows sum to.

Built by this call and published as its last act, so
`/zero/runtime/observations/streaming` serves the same document rather
than a second derivation of it.

**Returns** `{ [string]: any }` — `{ terrain, voxel, cells, levels, totals }`.

```lua
local r = streaming.observe()
```

## globals/streaming/reasons {#globals-streaming-reasons}

```lua
streaming.reasons() -> { string }
```

Every reason `whyNotDrawn` can answer with, so a caller can enumerate
the set rather than meeting it one failure at a time.

**Returns** `{ string }` — Sorted array of reason names.

```lua
local r = streaming.reasons()
```

## globals/streaming/terrain {#globals-streaming-terrain}

```lua
streaming.terrain(scene: any?) -> { [string]: any }
```

What each terrain entity is drawing: whether a heightfield is bound to
it, the LOD cut it settled on, what that cut costs in indices and in the
vertex pool, and the eye the cut was refined under.

**Parameters**

- `scene` `any` _(optional)_ — The scene walk to read against. Omitted, the call takes its own,
which is what makes a whole reading one walk rather than four.

**Returns** `{ [string]: any }` — `{ count, entities }` — one row per entity carrying a `Terrain`.

```lua
local t = streaming.terrain()
```

## globals/streaming/voxel {#globals-streaming-voxel}

```lua
streaming.voxel(scene: any?) -> { [string]: any }
```

What became of every chunk of every voxel world: how many are meshed,
queued, failed or empty, and one row per chunk carrying the state, the
engine's reason when a build failed, and what the build reserved on the
device.

**Parameters**

- `scene` `any` _(optional)_ — The scene walk to read against. Omitted, the call takes its own.

**Returns** `{ [string]: any }` — `{ count, worlds }` — one entry per entity carrying a `VoxelWorld`.

```lua
local v = streaming.voxel()
```

## globals/streaming/whyNotDrawn {#globals-streaming-whynotdrawn}

```lua
streaming.whyNotDrawn(subject: any?) -> { [string]: any }
```

Why a piece of a world's detail is not on screen, as one reason from
the closed set `streaming.reasons()` enumerates, with a detail line naming
what that reason is about.

The subject picks which system answers:
* an entity ref, id or name — whichever of the four systems holds it
* `{ entity = ..., chunk = "cx_cy_cz" }` — one chunk of a voxel world
* `{ entity = ..., level = n }` — one level of a mesh-LOD chain
* `{ cell = "x_z" }` — one cell of the spatial-streaming store

**Parameters**

- `subject` `any` _(optional)_ — The entity, chunk, level or cell to answer about.

**Returns** `{ [string]: any }` — `{ kind, reason, detail }`.

```lua
local w = streaming.whyNotDrawn({ entity = "Vox", chunk = "0_0_0" })
```

## modules/streaming/cells {#modules-streaming-cells}

```lua
cells(): { [string]: any }
```

What the spatial-streaming store has resident: the configured radii and
budget, the counters the store keeps, and one row per cell with how many of
its groups are standing, what it costs, and whether a release wrote it to a
file it now reads back from.

```lua
local s = streaming.cells()
```

## modules/streaming/levels {#modules-streaming-levels}

```lua
levels(scene: any?): { [string]: any }
```

Which level every mesh-LOD receiver is drawing at, and the screen
fraction that selection was measured from.
A receiver whose entity the scene no longer holds is reported as
`standing = false`: the chain is registered and there is nothing left for
it to draw.

**Parameters**

- `scene` `any?` _(optional)_ — The scene walk to read against. Omitted, the call takes its own.

```lua
local l = streaming.levels()
```

## modules/streaming/observe {#modules-streaming-observe}

```lua
observe(): { [string]: any }
```

The whole reading in one document: terrain, voxel, streaming cells and
mesh LOD, plus the totals those rows sum to.

Built by this call and published as its last act, so
`/zero/runtime/observations/streaming` serves the same document rather
than a second derivation of it.

```lua
local r = streaming.observe()
```

## modules/streaming/reasons {#modules-streaming-reasons}

```lua
reasons(): { string }
```

Every reason `whyNotDrawn` can answer with, so a caller can enumerate
the set rather than meeting it one failure at a time.

```lua
local r = streaming.reasons()
```

## modules/streaming/terrain {#modules-streaming-terrain}

```lua
terrain(scene: any?): { [string]: any }
```

What each terrain entity is drawing: whether a heightfield is bound to
it, the LOD cut it settled on, what that cut costs in indices and in the
vertex pool, and the eye the cut was refined under.

**Parameters**

- `scene` `any?` _(optional)_ — The scene walk to read against. Omitted, the call takes its own,
which is what makes a whole reading one walk rather than four.

```lua
local t = streaming.terrain()
```

## modules/streaming/voxel {#modules-streaming-voxel}

```lua
voxel(scene: any?): { [string]: any }
```

What became of every chunk of every voxel world: how many are meshed,
queued, failed or empty, and one row per chunk carrying the state, the
engine's reason when a build failed, and what the build reserved on the
device.

**Parameters**

- `scene` `any?` _(optional)_ — The scene walk to read against. Omitted, the call takes its own.

```lua
local v = streaming.voxel()
```

## modules/streaming/whyNotDrawn {#modules-streaming-whynotdrawn}

```lua
whyNotDrawn(subject: any): { [string]: any }
```

Why a piece of a world's detail is not on screen, as one reason from
the closed set `streaming.reasons()` enumerates, with a detail line naming
what that reason is about.

The subject picks which system answers:
* an entity ref, id or name — whichever of the four systems holds it
* `{ entity = ..., chunk = "cx_cy_cz" }` — one chunk of a voxel world
* `{ entity = ..., level = n }` — one level of a mesh-LOD chain
* `{ cell = "x_z" }` — one cell of the spatial-streaming store

**Parameters**

- `subject` `any` _(optional)_ — The entity, chunk, level or cell to answer about.

```lua
local w = streaming.whyNotDrawn({ entity = "Vox", chunk = "0_0_0" })
```

## typed/builtin//modules/api/engine/streaming/streaming/cells {#typed-builtin-modules-api-engine-streaming-streaming-cells}

```lua
streaming.cells() -> { [string]: any }
```

What the spatial-streaming store has resident: the configured radii and
budget, the counters the store keeps, and one row per cell with how many of
its groups are standing, what it costs, and whether a release wrote it to a
file it now reads back from.

**Returns** `{ [string]: any }` — `{ config, stats, sources, cells, proxies }`.

```lua
local s = streaming.cells()
```

## typed/builtin//modules/api/engine/streaming/streaming/levels {#typed-builtin-modules-api-engine-streaming-streaming-levels}

```lua
streaming.levels(scene: any?) -> { [string]: any }
```

Which level every mesh-LOD receiver is drawing at, and the screen
fraction that selection was measured from.
A receiver whose entity the scene no longer holds is reported as
`standing = false`: the chain is registered and there is nothing left for
it to draw.

**Parameters**

- `scene` `any` _(optional)_ — The scene walk to read against. Omitted, the call takes its own.

**Returns** `{ [string]: any }` — `{ count, receivers }`.

```lua
local l = streaming.levels()
```

## typed/builtin//modules/api/engine/streaming/streaming/observe {#typed-builtin-modules-api-engine-streaming-streaming-observe}

```lua
streaming.observe() -> { [string]: any }
```

The whole reading in one document: terrain, voxel, streaming cells and
mesh LOD, plus the totals those rows sum to.

Built by this call and published as its last act, so
`/zero/runtime/observations/streaming` serves the same document rather
than a second derivation of it.

**Returns** `{ [string]: any }` — `{ terrain, voxel, cells, levels, totals }`.

```lua
local r = streaming.observe()
```

## typed/builtin//modules/api/engine/streaming/streaming/reasons {#typed-builtin-modules-api-engine-streaming-streaming-reasons}

```lua
streaming.reasons() -> { string }
```

Every reason `whyNotDrawn` can answer with, so a caller can enumerate
the set rather than meeting it one failure at a time.

**Returns** `{ string }` — Sorted array of reason names.

```lua
local r = streaming.reasons()
```

## typed/builtin//modules/api/engine/streaming/streaming/terrain {#typed-builtin-modules-api-engine-streaming-streaming-terrain}

```lua
streaming.terrain(scene: any?) -> { [string]: any }
```

What each terrain entity is drawing: whether a heightfield is bound to
it, the LOD cut it settled on, what that cut costs in indices and in the
vertex pool, and the eye the cut was refined under.

**Parameters**

- `scene` `any` _(optional)_ — The scene walk to read against. Omitted, the call takes its own,
which is what makes a whole reading one walk rather than four.

**Returns** `{ [string]: any }` — `{ count, entities }` — one row per entity carrying a `Terrain`.

```lua
local t = streaming.terrain()
```

## typed/builtin//modules/api/engine/streaming/streaming/voxel {#typed-builtin-modules-api-engine-streaming-streaming-voxel}

```lua
streaming.voxel(scene: any?) -> { [string]: any }
```

What became of every chunk of every voxel world: how many are meshed,
queued, failed or empty, and one row per chunk carrying the state, the
engine's reason when a build failed, and what the build reserved on the
device.

**Parameters**

- `scene` `any` _(optional)_ — The scene walk to read against. Omitted, the call takes its own.

**Returns** `{ [string]: any }` — `{ count, worlds }` — one entry per entity carrying a `VoxelWorld`.

```lua
local v = streaming.voxel()
```

## typed/builtin//modules/api/engine/streaming/streaming/whyNotDrawn {#typed-builtin-modules-api-engine-streaming-streaming-whynotdrawn}

```lua
streaming.whyNotDrawn(subject: any?) -> { [string]: any }
```

Why a piece of a world's detail is not on screen, as one reason from
the closed set `streaming.reasons()` enumerates, with a detail line naming
what that reason is about.

The subject picks which system answers:
* an entity ref, id or name — whichever of the four systems holds it
* `{ entity = ..., chunk = "cx_cy_cz" }` — one chunk of a voxel world
* `{ entity = ..., level = n }` — one level of a mesh-LOD chain
* `{ cell = "x_z" }` — one cell of the spatial-streaming store

**Parameters**

- `subject` `any` _(optional)_ — The entity, chunk, level or cell to answer about.

**Returns** `{ [string]: any }` — `{ kind, reason, detail }`.

```lua
local w = streaming.whyNotDrawn({ entity = "Vox", chunk = "0_0_0" })
```