formatVersion
SourceVersion of the description, dump, and trace formats.
Runtime
Debug
Opt-in runtime introspection for tools, tests, and coding agents.
A runtime made with debug: true carries a debug handle. Runtimes made without it have no handle at all, so production code cannot reach into internals by accident and pays nothing for them.
The handle is read-only: it describes the schema and schedules, dumps the current world as plain data, reports stream retention, and streams trace events while schedules run. Nothing it returns can change the world.
- describe() is static: every component, resource, event, relation, machine, and service, each named schedule's steps, each system's declared access, who reads and writes what, and lints over that graph.
- dump(filter?) is the current world: entities with component values and relation targets, resources, machine values, and pending commands. It works even when snapshot() is gated, because a dump is never restored.
- observe(listener) delivers one TraceEvent per frame start, schedule boundary, system run or skip, applied marker, and machine transition. System runs carry every component, resource, event, and next-state write with before/after values; applied markers carry every command with the system that queued it and its structural effects.
- streams() reports each event, transition-event, and relation-failure stream: its size, and each reader's unread count and loss.
Values in descriptions, dumps, and traces are shared with the world, not copied. World values are immutable by contract, so they stay valid as a history, but serialize them before sending them elsewhere.
@typeonce/bevy-ts-devtools builds sessions, histories, formatting, and invariants on top of this handle.
Examples
const runtime = Game.Runtime.make({ services, resources, debug: true })
runtime.debug.nameSchedules({ setup: setupSchedule, update: updateSchedule })
const stop = runtime.debug.observe((event) => {
if (event.type === "system" && event.outcome !== "ok") console.log(event)
})
runtime.tick(setupSchedule)
console.log(runtime.debug.dump({ with: [Player] }))
stop()