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.

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

The streaming namespace: 21 functions.

globals/streaming/cells

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 }.

local s = streaming.cells()

globals/streaming/levels

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 }.

local l = streaming.levels()

globals/streaming/observe

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 }.

local r = streaming.observe()

globals/streaming/reasons

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.

local r = streaming.reasons()

globals/streaming/terrain

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.

local t = streaming.terrain()

globals/streaming/voxel

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.

local v = streaming.voxel()

globals/streaming/whyNotDrawn

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 }.

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

modules/streaming/cells

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.

local s = streaming.cells()

modules/streaming/levels

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.

local l = streaming.levels()

modules/streaming/observe

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.

local r = streaming.observe()

modules/streaming/reasons

reasons(): { string }

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

local r = streaming.reasons()

modules/streaming/terrain

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.

local t = streaming.terrain()

modules/streaming/voxel

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.

local v = streaming.voxel()

modules/streaming/whyNotDrawn

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.

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

typed/builtin//modules/api/engine/streaming/streaming/cells

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 }.

local s = streaming.cells()

typed/builtin//modules/api/engine/streaming/streaming/levels

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 }.

local l = streaming.levels()

typed/builtin//modules/api/engine/streaming/streaming/observe

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 }.

local r = streaming.observe()

typed/builtin//modules/api/engine/streaming/streaming/reasons

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.

local r = streaming.reasons()

typed/builtin//modules/api/engine/streaming/streaming/terrain

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.

local t = streaming.terrain()

typed/builtin//modules/api/engine/streaming/streaming/voxel

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.

local v = streaming.voxel()

typed/builtin//modules/api/engine/streaming/streaming/whyNotDrawn

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 }.

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