Inspector
Defined in: Inspector.ts:744
Programmatic runtime control and state queries for testing and debugging.
The engine does not create one: DebugPlugin or InspectorPlugin installs
it under InspectorKey, and debug: true exposes it as
window.__yage__.inspector.
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new Inspector(
engine):Inspector
Defined in: Inspector.ts:1196
Parameters
Section titled “Parameters”engine
Section titled “engine”EngineRef
Returns
Section titled “Returns”Inspector
Properties
Section titled “Properties”capture
Section titled “capture”
readonlycapture:object
Defined in: Inspector.ts:1174
dataURL
Section titled “dataURL”dataURL: () =>
Promise<string>
Returns
Section titled “Returns”Promise<string>
png: () =>
Promise<Uint8Array<ArrayBufferLike>>
Returns
Section titled “Returns”Promise<Uint8Array<ArrayBufferLike>>
pngBase64
Section titled “pngBase64”pngBase64: () =>
Promise<string>
Returns
Section titled “Returns”Promise<string>
events
Section titled “events”
readonlyevents:object
Defined in: Inspector.ts:1093
clearLog
Section titled “clearLog”clearLog: () =>
void
Returns
Section titled “Returns”void
getLog
Section titled “getLog”getLog: () =>
EventLogEntry[]
Returns
Section titled “Returns”isEnabled
Section titled “isEnabled”isEnabled: () =>
boolean
Returns
Section titled “Returns”boolean
setCapacity
Section titled “setCapacity”setCapacity: (
n) =>void
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”void
setEnabled
Section titled “setEnabled”setEnabled: (
enabled) =>void
Turn event-log recording on/off at runtime. Off means zero per-event
allocation: the EventBus tap detaches and recordBusEvent is never
called. DebugConfig.eventLog controls the startup default; this is
the runtime switch for toggling mid-session.
Parameters
Section titled “Parameters”enabled
Section titled “enabled”boolean
Returns
Section titled “Returns”void
waitFor
Section titled “waitFor”waitFor: (
pattern,options?) =>Promise<EventLogEntry>
Resolve the earliest retained match without consuming it, or wait for a
future match. Clear the log before an action to require a new event.
withinFrames expires after that many completed engine frames; events
on the deadline frame match first. Zero searches retained history only.
Disposing the Inspector or disabling the log rejects pending waits.
Parameters
Section titled “Parameters”pattern
Section titled “pattern”string | RegExp
options?
Section titled “options?”source?
Section titled “source?”"scene" | "entity" | "bus"
withinFrames?
Section titled “withinFrames?”number
Returns
Section titled “Returns”Promise<EventLogEntry>
readonlyinput:object
Defined in: Inspector.ts:949
clearAll
Section titled “clearAll”clearAll: () =>
void
Returns
Section titled “Returns”void
fireAction
Section titled “fireAction”fireAction: (
name,frames) =>void
Parameters
Section titled “Parameters”string
frames?
Section titled “frames?”number = 1
Returns
Section titled “Returns”void
gamepadAxis
Section titled “gamepadAxis”gamepadAxis: (
side,value) =>void
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”void
gamepadButton
Section titled “gamepadButton”gamepadButton: (
code,pressed) =>void
Parameters
Section titled “Parameters”string
pressed
Section titled “pressed”boolean
Returns
Section titled “Returns”void
hold: (
code,frames) =>void
Parameters
Section titled “Parameters”string
frames
Section titled “frames”number
Returns
Section titled “Returns”void
keyDown
Section titled “keyDown”keyDown: (
code) =>void
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”void
keyUp: (
code) =>void
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”void
mouseDown
Section titled “mouseDown”mouseDown: (
button) =>void
Parameters
Section titled “Parameters”button?
Section titled “button?”0 | 1 | 2
Returns
Section titled “Returns”void
mouseMove
Section titled “mouseMove”mouseMove: (
x,y) =>void
Parameters
Section titled “Parameters”number
number
Returns
Section titled “Returns”void
mouseUp
Section titled “mouseUp”mouseUp: (
button) =>void
Parameters
Section titled “Parameters”button?
Section titled “button?”0 | 1 | 2
Returns
Section titled “Returns”void
pointerDown
Section titled “pointerDown”pointerDown: (
button,opts?) =>void
Inject a synthetic pointer-down. With opts.id and opts.type: "touch"
this drives a multi-touch contact, exercising getPointers(),
per-pointer event hooks, and the any-pointer aggregate for MouseLeft.
Parameters
Section titled “Parameters”button?
Section titled “button?”0 | 1 | 2
Returns
Section titled “Returns”void
pointerMove
Section titled “pointerMove”pointerMove: (
x,y,opts?) =>void
Inject a synthetic pointer-move with full pointer addressing. Pass opts
with id / type: "touch" to drive a specific finger; defaults match
the primary mouse pointer (same as mouseMove).
Parameters
Section titled “Parameters”number
number
Returns
Section titled “Returns”void
pointerUp
Section titled “pointerUp”pointerUp: (
button,opts?) =>void
Parameters
Section titled “Parameters”button?
Section titled “button?”0 | 1 | 2
number
Returns
Section titled “Returns”void
tap: (
code,frames) =>void
Parameters
Section titled “Parameters”string
frames?
Section titled “frames?”number = 1
Returns
Section titled “Returns”void
pointer
Section titled “pointer”
readonlypointer:object
Defined in: Inspector.ts:1053
Pointer input that reaches @yagejs/ui primitives, by asking the
renderer to deliver real pointer events. The renderer’s own event system
hit-tests and delivers them, so stacking order, a disabled button’s
pointer mode and clipping all apply exactly as they do for a person
clicking.
Distinct from Inspector.input, which writes InputManager state
and never reaches a user-interface element. The two also differ in
timing: a button’s onClick has already run when a verb here returns,
because delivery is synchronous, while engine input state reflects the
press at the next frame’s drain. Step one frame before asserting on
action state.
Requires RendererPlugin. The four verbs that dispatch also require at
least one rendered frame; hitTest does not.
These verbs drive one primary mouse pointer. A second finger, a touch or a pen pointer is only reachable through Inspector.input, whose verbs take a pointer id and type and write engine state without going near the user interface.
const hit = inspector.pointer.click("entity-7:UISurface:0/2");expect(hit.path.some((node) => node.type === "UIButton")).toBe(true);click: (
target,opts?) =>InspectorPointerHit
Presses and releases at one point, which is what a UIButton requires
to run its onClick.
Parameters
Section titled “Parameters”target
Section titled “target”Returns
Section titled “Returns”down: (
target,opts?) =>InspectorPointerHit
Presses a mouse button, left unless opts says otherwise.
Parameters
Section titled “Parameters”target
Section titled “target”Returns
Section titled “Returns”hitTest
Section titled “hitTest”hitTest: (
target) =>InspectorPointerHit
Resolves target and reports what is under it, dispatching nothing.
Parameters
Section titled “Parameters”target
Section titled “target”Returns
Section titled “Returns”move: (
target) =>InspectorPointerHit
Moves the pointer, which drives hover state. Takes no button: a move presses and releases nothing, and carries whichever buttons an earlier down left held.
Parameters
Section titled “Parameters”target
Section titled “target”Returns
Section titled “Returns”up: (
target,opts?) =>InspectorPointerHit
Releases a mouse button, left unless opts says otherwise.
Parameters
Section titled “Parameters”target
Section titled “target”Returns
Section titled “Returns”
readonlytime:InspectorTime
Defined in: Inspector.ts:775
Methods
Section titled “Methods”_completeFrame()
Section titled “_completeFrame()”_completeFrame():
void
Defined in: Inspector.ts:1804
Internal
Expire unmatched waiters after the frame’s events and destruction.
Returns
Section titled “Returns”void
addExtension()
Section titled “addExtension()”addExtension<
T>(namespace,api):T
Defined in: Inspector.ts:1441
Register a namespaced extension API for plugin-specific debug helpers.
Type Parameters
Section titled “Type Parameters”T extends object
Parameters
Section titled “Parameters”namespace
Section titled “namespace”string
T
Returns
Section titled “Returns”T
attachSceneEventObserver()
Section titled “attachSceneEventObserver()”attachSceneEventObserver(
scene):void
Defined in: Inspector.ts:1704
Internal
Install token-event observation for one scene. No-op if disabled.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”void
attachTimeController()
Section titled “attachTimeController()”attachTimeController(
controller):void
Defined in: Inspector.ts:1666
Internal
DebugPlugin attaches the frozen-time controller through this hook.
Parameters
Section titled “Parameters”controller
Section titled “controller”Returns
Section titled “Returns”void
detachSceneEventObserver()
Section titled “detachSceneEventObserver()”detachSceneEventObserver(
scene):void
Defined in: Inspector.ts:1712
Internal
Clear token-event observation for one scene.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”void
detachTimeController()
Section titled “detachTimeController()”detachTimeController(
controller?):void
Defined in: Inspector.ts:1671
Internal
Clear a previously attached time controller.
Parameters
Section titled “Parameters”controller?
Section titled “controller?”Returns
Section titled “Returns”void
dispose()
Section titled “dispose()”dispose():
void
Defined in: Inspector.ts:1741
Internal
The installer’s teardown releases the event-bus tap through this hook.
Returns
Section titled “Returns”void
drive()
Section titled “drive()”drive<
T>(fn,opts?):Promise<InspectorDriveResult<T>>
Defined in: Inspector.ts:1223
Run fn against the running game with the clock held still and every
frame-advancing verb awaitable, then report what happened. The clock is
frozen for the duration and returned to the state it was in, and every
synthetic input is released afterwards. If a release hook throws, cleanup
stops with the clock frozen and its lease held, and the drive rejects.
Nothing thrown by fn escapes: a throw is the result’s error. Missing
DebugPlugin throws from the call itself, before anything runs.
const run = await inspector.drive(async ({ input, until }) => { input.keyDown("KeyD"); const frames = await until( () => (inspector.getEntityPosition("player")?.x ?? 0) > 950, ); return { frames };});The same callback body works as a @yagejs-tools/lab scenario drive,
which adds scene, controls and expect on top of these verbs.
Type Parameters
Section titled “Type Parameters”T = void
Parameters
Section titled “Parameters”(ctx) => T | Promise<T>
Returns
Section titled “Returns”Promise<InspectorDriveResult<T>>
getComponentData()
Section titled “getComponentData()”getComponentData(
nameOrId,componentClass):unknown
Defined in: Inspector.ts:1601
Get inspectable component data by class name string. The entity is
addressed by name or by entity.id, so several same-named entities are
individually readable.
Parameters
Section titled “Parameters”nameOrId
Section titled “nameOrId”string | number
componentClass
Section titled “componentClass”string
Returns
Section titled “Returns”unknown
getComponentFacet()
Section titled “getComponentFacet()”getComponentFacet<
K>(component,namespace):unknown
Defined in: Inspector.ts:1494
Read one plugin-owned facet without reflecting component state or taking a scene snapshot. Missing contributors and unavailable facets return undefined. Uses the same contributor and failure policy as snapshot().
Type Parameters
Section titled “Type Parameters”K extends string
Parameters
Section titled “Parameters”component
Section titled “component”namespace
Section titled “namespace”K
Returns
Section titled “Returns”unknown
getEntities()
Section titled “getEntities()”getEntities():
EntitySnapshot[]
Defined in: Inspector.ts:1608
Get all entities in the active scene as lightweight snapshots.
Returns
Section titled “Returns”getEntity()
Section titled “getEntity()”getEntity(
nameOrId):EntitySnapshot|undefined
Defined in: Inspector.ts:1568
Find one entity by name or by entity.id. A name matches the first
active entity of the active scene. An id (a number, or the string form
snapshot() and the event log use) reaches any entity on the scene
stack, dormant and inactive included, destroyed excluded. A string is
tried as a name first, so a name wins over an id with the same spelling.
Parameters
Section titled “Parameters”nameOrId
Section titled “nameOrId”string | number
Returns
Section titled “Returns”EntitySnapshot | undefined
getEntityCount()
Section titled “getEntityCount()”getEntityCount():
number
Defined in: Inspector.ts:2506
Live entities across every scene on the stack, dormant ones included.
Returns
Section titled “Returns”number
getEntityPosition()
Section titled “getEntityPosition()”getEntityPosition(
nameOrId): {x:number;y:number; } |undefined
Defined in: Inspector.ts:1578
Get entity position (from Transform component), addressing the entity by
name or by entity.id.
Parameters
Section titled “Parameters”nameOrId
Section titled “nameOrId”string | number
Returns
Section titled “Returns”{ x: number; y: number; } | undefined
getErrors()
Section titled “getErrors()”getErrors():
ErrorSnapshot
Defined in: Inspector.ts:1650
Get recorded failures from the error boundary.
Returns
Section titled “Returns”getExtension()
Section titled “getExtension()”getExtension<
T>(namespace):T|undefined
Defined in: Inspector.ts:1456
Look up a previously registered extension API by namespace.
Type Parameters
Section titled “Type Parameters”T extends object
Parameters
Section titled “Parameters”namespace
Section titled “namespace”string
Returns
Section titled “Returns”T | undefined
getInputState()
Section titled “getInputState()”getInputState():
InputStateSnapshot
Defined in: Inspector.ts:1621
Get current input state (keys, pointers, gamepad).
Returns
Section titled “Returns”getSceneStack()
Section titled “getSceneStack()”getSceneStack():
SceneSnapshot[]
Defined in: Inspector.ts:1626
Get scene stack info.
Returns
Section titled “Returns”getSystems()
Section titled “getSystems()”getSystems():
SystemSnapshot[]
Defined in: Inspector.ts:1638
Get active system info.
Returns
Section titled “Returns”hasComponent()
Section titled “hasComponent()”hasComponent(
nameOrId,componentClass):boolean
Defined in: Inspector.ts:1592
Check if an entity has a component by class name string. The entity is
addressed by name or by entity.id.
Parameters
Section titled “Parameters”nameOrId
Section titled “nameOrId”string | number
componentClass
Section titled “componentClass”string
Returns
Section titled “Returns”boolean
recordTokenEvent()
Section titled “recordTokenEvent()”recordTokenEvent(
scene,eventName,data,entity):void
Defined in: Inspector.ts:1721
Internal
Scene observers forward token events through this method:
entity is the emitting entity for a bubbled entity.emit, undefined
for a scene.emit.
Parameters
Section titled “Parameters”eventName
Section titled “eventName”string
unknown
entity
Section titled “entity”Entity | undefined
Returns
Section titled “Returns”void
registerFacetContributor()
Section titled “registerFacetContributor()”registerFacetContributor(
contributor): () =>void
Defined in: Inspector.ts:1476
Register an InspectorFacetContributor so a plugin can augment
component/entity snapshots with a namespaced facet (e.g. the renderer’s
render geometry). Returns an unregister function; call it on plugin
teardown. Re-registering a namespace replaces the prior contributor.
Parameters
Section titled “Parameters”contributor
Section titled “contributor”Returns
Section titled “Returns”() => void
removeExtension()
Section titled “removeExtension()”removeExtension(
namespace):void
Defined in: Inspector.ts:1462
Remove a previously registered extension namespace.
Parameters
Section titled “Parameters”namespace
Section titled “namespace”string
Returns
Section titled “Returns”void
setEventLogEnabled()
Section titled “setEventLogEnabled()”setEventLogEnabled(
enabled):void
Defined in: Inspector.ts:1678
Internal
Enable or disable event log recording.
Parameters
Section titled “Parameters”enabled
Section titled “enabled”boolean
Returns
Section titled “Returns”void
setSeed()
Section titled “setSeed()”setSeed(
seed):void
Defined in: Inspector.ts:1661
Reseed every scene RNG on the stack and every one created later. Same as
engine.sceneRandom.setSeed(seed), which game code calls without going
through the Inspector.
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”void
snapshot()
Section titled “snapshot()”snapshot():
EngineSnapshot
Defined in: Inspector.ts:1507
Full deterministic state snapshot (stable ordering, serializable).
Returns
Section titled “Returns”snapshotJSON()
Section titled “snapshotJSON()”snapshotJSON():
string
Defined in: Inspector.ts:1528
Stable JSON form of snapshot.
Returns
Section titled “Returns”string
snapshotScene()
Section titled “snapshotScene()”snapshotScene(
nameOrId):WorldSceneSnapshot
Defined in: Inspector.ts:1538
Snapshot one scene by its public scene.name or its inspector-assigned
id (snapshot().scenes[].id). Name is tried first. If more than one
active scene shares that name, throws rather than guessing — pass the id
instead. Falls back to an id match when no scene has that name.
Parameters
Section titled “Parameters”nameOrId
Section titled “nameOrId”string
Returns
Section titled “Returns”Coding agents: fetch https://yage.dev/llms.txt first and prefer the Markdown references it links over these HTML pages. This page's Markdown counterpart is /llms/packages/core.md.