Zephyr3d

Appearance

Documentation / scene / Scene

Class: Scene ​

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

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 ​

Constructors ​

Constructor ​

new Scene(name?): Scene

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

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:6107

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:119

Gets the unique identifier of the scene.

Returns ​

number

name ​

Get Signature ​

get name(): string

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

Name of the scene

Returns ​

string

Set Signature ​

set name(val): void

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

Parameters ​
val ​

string

Returns ​

void

mainCamera ​

Get Signature ​

get mainCamera(): Camera

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

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:137

Parameters ​
camera ​

Camera

Returns ​

void

rootNode ​

Get Signature ​

get rootNode(): SceneNode

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

Gets the root scene node of the scene

Returns ​

SceneNode

octree ​

Get Signature ​

get octree(): Octree

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

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:161

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:169

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

Returns ​

Environment

lightingMode ​

Get Signature ​

get lightingMode(): LightingMode

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

Lighting unit model. Legacy remains the default for backward compatibility.

Returns ​

LightingMode

Set Signature ​

set lightingMode(val): void

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

Parameters ​
val ​

LightingMode

Returns ​

void

metersPerUnit ​

Get Signature ​

get metersPerUnit(): number

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

Number of physical meters represented by one scene-space unit.

Returns ​

number

Set Signature ​

set metersPerUnit(val): void

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

Parameters ​
val ​

number

Returns ​

void

metaData ​

Get Signature ​

get metaData(): Metadata

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

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:208

Parameters ​
val ​

Metadata

Returns ​

void

script ​

Get Signature ​

get script(): string

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

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:220

Parameters ​
fileName ​

string

Returns ​

void

scriptConfig ​

Get Signature ​

get scriptConfig(): object | unknown[]

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

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:236

Parameters ​
value ​

object | unknown[]

Returns ​

void

scripts ​

Get Signature ​

get scripts(): ScriptAttachment[]

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

All script attachments on this scene.

Returns ​

ScriptAttachment[]

Set Signature ​

set scripts(value): void

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

Parameters ​
value ​

ScriptAttachment[]

Returns ​

void

scriptConfigs ​

Get Signature ​

get scriptConfigs(): unknown[]

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

Script configs for all script attachments.

Returns ​

unknown[]

Set Signature ​

set scriptConfigs(value): void

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

Parameters ​
value ​

unknown[]

Returns ​

void

Methods ​

on() ​

Call Signature ​

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

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

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:630

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:675

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:634

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:679

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:638

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:683

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:642

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:6108

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:281

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:297

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:308

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:335

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:366

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:381

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:398

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:408

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:462

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:501

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:527

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:556

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

Released under the MIT License.

Copyright © Zephyr3d