Documentation / scene / Scene

Class: Scene

Defined in: libs/scene/src/scene/scene.ts:38

Represents a renderable world that manages scene graph, spatial indexing, and environment.

Core responsibilities:

• Owns the root SceneNode and maintains a spatial Octree for culling/raycasting.
• Manages environment/lighting via Environment.
• Provides per-frame update queues (global and per-camera) for scene nodes.
• Offers utilities like ray construction and raycasting.
• Emits observable events: update, startrender, endrender.

Performance notes:

• Octree placement is lazily synchronized on demand before reads (e.g., octree, boundingBox) and during per-frame updates.
• Update queues use weak references to avoid retaining disposed nodes.

Extends

• object & Disposable<this>

Implements

• IRenderable

Constructors

Constructor

new Scene(name?): Scene

Defined in: libs/scene/src/scene/scene.ts:91

Creates an instance of Scene.

Initializes:

• Unique ID
• Empty environment
• Octree with default depth/leaf capacities
• Root scene node named "Root"

Parameters

name?

string

Optional scene name for diagnostics/UI.

Returns

Scene

Overrides

makeObservable(Disposable)<{ /** Dispatched once per frame before render-related work. */ update: [Scene]; /** Dispatched immediately before rendering begins for a camera. */ startrender: [Scene, Camera, Compositor]; /** Dispatched immediately after rendering finishes for a camera. */ endrender: [Scene, Camera, Compositor]; }>().constructor

Accessors

disposed

Get Signature

get disposed(): boolean

Defined in: libs/base/dist/index.d.ts:6065

Returns

boolean

Implementation of

IRenderable.disposed

Inherited from

makeObservable(Disposable)<{ /** Dispatched once per frame before render-related work. */ update: [Scene]; /** Dispatched immediately before rendering begins for a camera. */ startrender: [Scene, Camera, Compositor]; /** Dispatched immediately after rendering finishes for a camera. */ endrender: [Scene, Camera, Compositor]; }>().disposed

---

id

Get Signature

get id(): number

Defined in: libs/scene/src/scene/scene.ts:112

Gets the unique identifier of the scene.

Returns

number

---

name

Get Signature

get name(): string

Defined in: libs/scene/src/scene/scene.ts:118

Name of the scene

Returns

string

Set Signature

set name(val): void

Defined in: libs/scene/src/scene/scene.ts:121

Parameters

val

string

Returns

void

---

mainCamera

Get Signature

get mainCamera(): Camera

Defined in: libs/scene/src/scene/scene.ts:127

Main camera used to render the scene by default.

Returns

Camera

Set Signature

set mainCamera(camera): void

Defined in: libs/scene/src/scene/scene.ts:130

Parameters

camera

Camera

Returns

void

---

rootNode

Get Signature

get rootNode(): SceneNode

Defined in: libs/scene/src/scene/scene.ts:136

Gets the root scene node of the scene

Returns

SceneNode

---

octree

Get Signature

get octree(): Octree

Defined in: libs/scene/src/scene/scene.ts:144

Gets the octree used for spatial organization and queries.

Ensures pending node placements are synchronized before returning.

Returns

Octree

---

boundingBox

Get Signature

get boundingBox(): AABB

Defined in: libs/scene/src/scene/scene.ts:154

Gets the world-axis-aligned bounding box of the scene.

Ensures pending node placements are synchronized before computing.

Returns

AABB

---

env

Get Signature

get env(): Environment

Defined in: libs/scene/src/scene/scene.ts:162

The environment (sky, lights, IBL) of the scene.

Returns

Environment

---

metaData

Get Signature

get metaData(): Metadata

Defined in: libs/scene/src/scene/scene.ts:168

Arbitrary metadata associated with the scene (e.g., imported asset info).

Returns

Metadata

Set Signature

set metaData(val): void

Defined in: libs/scene/src/scene/scene.ts:171

Parameters

val

Metadata

Returns

void

---

script

Get Signature

get script(): string

Defined in: libs/scene/src/scene/scene.ts:180

Attached script filename or identifier (engine-specific).

Remarks

Integrates with the engine’s scripting system if available.

Returns

string

Set Signature

set script(fileName): void

Defined in: libs/scene/src/scene/scene.ts:183

Parameters

fileName

string

Returns

void

---

scriptConfig

Get Signature

get scriptConfig(): object | unknown[]

Defined in: libs/scene/src/scene/scene.ts:196

Script component configuration payload used by editor/runtime script components.

Returns

object | unknown[]

Set Signature

set scriptConfig(value): void

Defined in: libs/scene/src/scene/scene.ts:199

Parameters

value

object | unknown[]

Returns

void

---

scripts

Get Signature

get scripts(): ScriptAttachment[]

Defined in: libs/scene/src/scene/scene.ts:213

All script attachments on this scene.

Returns

ScriptAttachment[]

Set Signature

set scripts(value): void

Defined in: libs/scene/src/scene/scene.ts:216

Parameters

value

ScriptAttachment[]

Returns

void

---

scriptConfigs

Get Signature

get scriptConfigs(): unknown[]

Defined in: libs/scene/src/scene/scene.ts:222

Script configs for all script attachments.

Returns

unknown[]

Set Signature

set scriptConfigs(value): void

Defined in: libs/scene/src/scene/scene.ts:225

Parameters

value

unknown[]

Returns

void

Methods

on()

Call Signature

on<K>(type, listener, context?): void

Defined in: libs/base/dist/index.d.ts:635

IEventTarget.on

Type Parameters

K

K extends "dispose" | "update" | "startrender" | "endrender"

Parameters

type

K

listener

EventListener<object & object, K>

context?

unknown

Returns

void

Implementation of

IRenderable.on

Inherited from

makeObservable(Disposable)<{ /** Dispatched once per frame before render-related work. */ update: [Scene]; /** Dispatched immediately before rendering begins for a camera. */ startrender: [Scene, Camera, Compositor]; /** Dispatched immediately after rendering finishes for a camera. */ endrender: [Scene, Camera, Compositor]; }>().on

Call Signature

on<K>(type, listener, context?): void

Defined in: libs/base/dist/index.d.ts:594

IEventTarget.on

Type Parameters

K

K extends "dispose"

Parameters

type

K

listener

EventListener<{ dispose: []; }, K>

context?

unknown

Returns

void

Implementation of

IRenderable.on

Inherited from

makeObservable(Disposable)<{ /** Dispatched once per frame before render-related work. */ update: [Scene]; /** Dispatched immediately before rendering begins for a camera. */ startrender: [Scene, Camera, Compositor]; /** Dispatched immediately after rendering finishes for a camera. */ endrender: [Scene, Camera, Compositor]; }>().on

---

once()

Call Signature

once<K>(type, listener, context?): void

Defined in: libs/base/dist/index.d.ts:639

IEventTarget.once

Type Parameters

K

K extends "dispose" | "update" | "startrender" | "endrender"

Parameters

type

K

listener

EventListener<object & object, K>

context?

unknown

Returns

void

Implementation of

IRenderable.once

Inherited from

makeObservable(Disposable)<{ /** Dispatched once per frame before render-related work. */ update: [Scene]; /** Dispatched immediately before rendering begins for a camera. */ startrender: [Scene, Camera, Compositor]; /** Dispatched immediately after rendering finishes for a camera. */ endrender: [Scene, Camera, Compositor]; }>().once

Call Signature

once<K>(type, listener, context?): void

Defined in: libs/base/dist/index.d.ts:598

IEventTarget.once

Type Parameters

K

K extends "dispose"

Parameters

type

K

listener

EventListener<{ dispose: []; }, K>

context?

unknown

Returns

void

Implementation of

IRenderable.once

Inherited from

makeObservable(Disposable)<{ /** Dispatched once per frame before render-related work. */ update: [Scene]; /** Dispatched immediately before rendering begins for a camera. */ startrender: [Scene, Camera, Compositor]; /** Dispatched immediately after rendering finishes for a camera. */ endrender: [Scene, Camera, Compositor]; }>().once

---

off()

Call Signature

off<K>(type, listener, context?): void

Defined in: libs/base/dist/index.d.ts:643

IEventTarget.off

Type Parameters

K

K extends "dispose" | "update" | "startrender" | "endrender"

Parameters

type

K

listener

EventListener<object & object, K>

context?

unknown

Returns

void

Implementation of

IRenderable.off

Inherited from

makeObservable(Disposable)<{ /** Dispatched once per frame before render-related work. */ update: [Scene]; /** Dispatched immediately before rendering begins for a camera. */ startrender: [Scene, Camera, Compositor]; /** Dispatched immediately after rendering finishes for a camera. */ endrender: [Scene, Camera, Compositor]; }>().off

Call Signature

off<K>(type, listener?, context?): void

Defined in: libs/base/dist/index.d.ts:602

IEventTarget.off

Type Parameters

K

K extends "dispose"

Parameters

type

K

listener?

EventListener<{ dispose: []; }>

context?

unknown

Returns

void

Implementation of

IRenderable.off

Inherited from

makeObservable(Disposable)<{ /** Dispatched once per frame before render-related work. */ update: [Scene]; /** Dispatched immediately before rendering begins for a camera. */ startrender: [Scene, Camera, Compositor]; /** Dispatched immediately after rendering finishes for a camera. */ endrender: [Scene, Camera, Compositor]; }>().off

---

dispatchEvent()

Call Signature

dispatchEvent<K>(type, ...args): void

Defined in: libs/base/dist/index.d.ts:647

IEventTarget.dispatchEvent

Type Parameters

K

K extends "dispose" | "update" | "startrender" | "endrender"

Parameters

type

K

args

...object & object[K]

Returns

void

Implementation of

IRenderable.dispatchEvent

Inherited from

makeObservable(Disposable)<{ /** Dispatched once per frame before render-related work. */ update: [Scene]; /** Dispatched immediately before rendering begins for a camera. */ startrender: [Scene, Camera, Compositor]; /** Dispatched immediately after rendering finishes for a camera. */ endrender: [Scene, Camera, Compositor]; }>().dispatchEvent

Call Signature

dispatchEvent<K>(type, ...args): void

Defined in: libs/base/dist/index.d.ts:606

IEventTarget.dispatchEvent

Type Parameters

K

K extends "dispose"

Parameters

type

K

args

...object[K]

Returns

void

Implementation of

IRenderable.dispatchEvent

Inherited from

makeObservable(Disposable)<{ /** Dispatched once per frame before render-related work. */ update: [Scene]; /** Dispatched immediately before rendering begins for a camera. */ startrender: [Scene, Camera, Compositor]; /** Dispatched immediately after rendering finishes for a camera. */ endrender: [Scene, Camera, Compositor]; }>().dispatchEvent

---

dispose()

dispose(): void

Defined in: libs/base/dist/index.d.ts:6066

Returns

void

Implementation of

IRenderable.dispose

Inherited from

makeObservable(Disposable)<{ /** Dispatched once per frame before render-related work. */ update: [Scene]; /** Dispatched immediately before rendering begins for a camera. */ startrender: [Scene, Camera, Compositor]; /** Dispatched immediately after rendering finishes for a camera. */ endrender: [Scene, Camera, Compositor]; }>().dispose

---

findNodeById()

findNodeById<T>(id): T

Defined in: libs/scene/src/scene/scene.ts:244

Finds a scene node by its persistent ID.

Type Parameters

T

T extends SceneNode

Expected node type.

Parameters

id

string

Persistent identifier to match against SceneNode.persistentId.

Returns

T

The first matching node, or null if not found.

---

findNodeByName()

findNodeByName<T>(name): T

Defined in: libs/scene/src/scene/scene.ts:260

Finds a scene node by name.

If multiple nodes share the same name, returns the first match encountered during traversal.

Type Parameters

T

T extends SceneNode

Expected node type.

Parameters

name

string

Node name to match.

Returns

T

The first matching node, or null if not found.

Remarks

Names are not guaranteed unique. Prefer IDs for stable references.

---

raycast()

raycast(ray, length?): object

Defined in: libs/scene/src/scene/scene.ts:271

Casts a ray into the scene and returns the closest intersection, if any.

Parameters

ray

Ray

The ray in world space.

length?

number = Infinity

Maximum ray length. Defaults to Infinity.

Returns

object

Intersection info { target, dist, point }, or null if no hit.

target

target: PickTarget = raycastVisitor.intersected

dist

dist: number = raycastVisitor.intersectedDist

point

point: Vector3 = raycastVisitor.intersectedPoint

---

constructRay()

constructRay(camera, viewportWidth, viewportHeight, screenX, screenY, invModelMatrix?): Ray

Defined in: libs/scene/src/scene/scene.ts:298

Constructs a world-space ray from a camera and a screen position.

Parameters

camera

Camera

Camera whose projection/view defines the ray.

viewportWidth

number

Current viewport width in pixels.

viewportHeight

number

Current viewport height in pixels.

screenX

number

Screen-space x (pixels).

screenY

number

Screen-space y (pixels).

invModelMatrix?

Matrix4x4

Optional inverse model matrix to transform the ray into local space.

Returns

Ray

The constructed Ray.

Remarks

Computes NDC from screen coordinates, unprojects using invViewProjectionMatrix, then forms a ray from the camera world position to the unprojected point. If invModelMatrix is provided, both origin and direction are transformed.

---

queueUpdateNode()

queueUpdateNode(node): void

Defined in: libs/scene/src/scene/scene.ts:329

Queues a node for a one-shot update before the next render.

The node's update(frame, elapsedSeconds, deltaSeconds) will be called during Scene.frameUpdate and then the node is removed from the queue.

Parameters

node

SceneNode

Node to schedule.

Returns

void

Remarks

• To update continuously each frame, call queueUpdateNode(this) from within the node's update method.
• Duplicate scheduling within the same frame is prevented.

---

queueUpdateDrawable()

queueUpdateDrawable(drawable): void

Defined in: libs/scene/src/scene/scene.ts:344

Queues a drawable for a one-shot state update before the next render.

The drawable's updateState() will be called during Scene.frameUpdate and then the drawable is removed from the queue.

Parameters

drawable

Drawable

Drawable to schedule.

Returns

void

Remarks

• To update continuously each frame, call queueUpdateDrawable(this) from within the drawable's updateState method.
• Duplicate scheduling within the same frame is prevented.

---

queuePerCameraUpdateNode()

queuePerCameraUpdateNode(node): void

Defined in: libs/scene/src/scene/scene.ts:361

Queues a node for a one-shot per-camera update before render.

The node's updatePerCamera(camera, elapsedSeconds, deltaSeconds) will be called once for each camera during Scene.frameUpdatePerCamera, then removed.

Parameters

node

SceneNode

Node to schedule.

Returns

void

Remarks

• To run per-camera work continuously, re-queue from updatePerCamera.
• Duplicate scheduling within the same frame is prevented.

---

render()

render(): void

Defined in: libs/scene/src/scene/scene.ts:371

Renders this scene using the mainCamera, if present.

Equivalent to mainCamera.render(this) when mainCamera is set.

Returns

void

Implementation of

IRenderable.render

---

frameUpdate()

frameUpdate(): void

Defined in: libs/scene/src/scene/scene.ts:425

Performs per-frame scene updates, once per device frame.

Steps:

• Ensure this runs only once per frame (via frameInfo.frameCounter).
• Update environment light synchronization.
• Dispatch update event.
• Drain the one-shot node update queue and call node.update(...).
• Apply pending octree placement updates.

Returns

void

---

frameUpdatePerCamera()

frameUpdatePerCamera(camera): void

Defined in: libs/scene/src/scene/scene.ts:464

Performs per-camera scene updates for the current frame.

Steps:

• Drain the per-camera update queue and call node.updatePerCamera(camera, ...).
• Apply pending octree placement updates.

Parameters

camera

Camera

The camera being updated for.

Returns

void

---

updateNodePlacement()

updateNodePlacement(octree, list): void

Defined in: libs/scene/src/scene/scene.ts:490

Applies placement changes for nodes in list to the given octree.

Rules:

• If node is not disposed, attached, not hidden, and placeToOctree is true, it is placed; otherwise removed.
• Drains list until empty.

Parameters

octree

Octree

Target spatial index.

list

Set<GraphNode>

Set of nodes awaiting placement evaluation.

Returns

void

---

onDispose()

protected onDispose(): void

Defined in: libs/scene/src/scene/scene.ts:519

Disposes the scene and its owned resources.

Disposes:

• Environment
• Root node (and, by extension, its hierarchy)
• Main camera reference wrapper

Returns

void

Overrides

makeObservable(Disposable)<{ /** Dispatched once per frame before render-related work. */ update: [Scene]; /** Dispatched immediately before rendering begins for a camera. */ startrender: [Scene, Camera, Compositor]; /** Dispatched immediately after rendering finishes for a camera. */ endrender: [Scene, Camera, Compositor]; }>().onDispose