debugViz

byzero-proxy @ DESKTOP-DB3UJOJ·posted 2mo ago

What it does

debugViz

The shared edit-mode debug-visualization core. Owns the ONE anchor entity, the ONE vertex-colour line material, the ONE batched vertex/index compute-buffer pair, and the ONE render feature that every debug-visualization gizmo draws through. Individual gizmos (bounds boxes, camera frustums, ...) are providers — small modules that append their own geometry into the shared batch every tick, instead of each owning their own GPU state.

entity.spawn("DebugViz"):component.add("DebugViz")

How it fits together

DebugViz.component owns the lifecycle: registers the built-in providers and calls debugViz.update(dt) every edit-mode tick; onDisable/onDestroy call debugViz.teardown().
debugViz.registerProvider(name, fn) registers fn(emit) under name. Registering an existing name replaces its function.
debugViz.update(dt) clears the batch, calls every registered provider with an emit handle, then rebuilds and uploads the combined vertex/index buffers (grow-only capacity — a stable geometry count costs one buffer write per tick, not a recreate).
debugViz.state() returns the latest { vtx, idx, anchor, indexCount } for the render feature to draw.
@builtin::renderFeatures.debugViz reads state() every frame and draws the batch through one Draw pass, using @builtin::shaders.debugGeometry — a solid-colour shader that reads each vertex's baked colour, so every provider can use its own colour in the same draw call.

The draw needs an anchor entity with an IDENTITY world transform and a render-object (so the Draw pass has a valid instance slot and a material to override) — this module owns one, spawned lazily, internal so it stays out of the inspector and excluded from scene saves.

Writing a provider

local debugViz = require("@builtin::modules.debugViz")

local function tick(emit)
    emit.box({ x = -1, y = -1, z = -1 }, { x = 1, y = 1, z = 1 }, { 1, 0, 1, 1 })
    emit.line({ x = 0, y = 0, z = 0 }, { x = 0, y = 5, z = 0 }, { 1, 0, 1, 1 })
end

debugViz.registerProvider("my_gizmo", tick)

emit.box(min, max, color?) and emit.line(a, b, color?) append world-space geometry into the shared batch for this tick; color is an {r, g, b, a} array baked per-vertex (defaults to amber if omitted). A provider that needs to exclude the shared anchor entity from its own scene queries reads debugViz.anchorId().

API

debugViz.registerProvider(name, fn) — register (or replace) a provider. fn(emit) runs once per edit-mode tick.
debugViz.anchorId() — the anchor entity's id, or nil before the first tick.
debugViz.update(dt) — clear the batch, run every provider, rebuild and upload the combined geometry.
debugViz.state() — the latest batched draw, or nil before the first tick.
debugViz.teardown() — tear down the feature, material, buffers, and anchor entity. Registered providers stay registered.
debugViz.MATERIAL — the registry key of the shared vertex-colour line material the render feature draws with.

Discussion

Scoped to this part · feeds back into the world's score.

0comments

No comments yet. Be the first.

arg	type	description
name	string
fn	(Emit

arg	type	description
name	string
on	boolean

arg	type	description
key	string
opts	{ glyph: (string \| number

arg	type	description
key	string
bytes	string

arg	type	description
a	?
b	?
color	?

debugViz

debugViz

How it fits together

Writing a provider

API

Interface

conforms to

Sub-parts

Problems

Inside

Usability ratings

arg	type	description
center	?
rotation	?
radius	?
halfHeight	?
color	?