@aura3d/scene 1.0.6

package/src/MathTypes.ts

@@ -0,0 +1,157 @@
+import { Frustum, Matrix4, Quaternion, Vector3 } from "@aura3d/math";
+
+export type Vec3 = [number, number, number];
+export type Quat = [number, number, number, number];
+export type Mat4 = [
+  number, number, number, number,
+  number, number, number, number,
+  number, number, number, number,
+  number, number, number, number
+];
+export type PlaneTuple = [number, number, number, number];
+
+export const EPSILON = 1e-8;
+
+export function vec3(x = 0, y = 0, z = 0): Vec3 {
+  return [x, y, z];
+}
+
+export function quat(x = 0, y = 0, z = 0, w = 1): Quat {
+  return fromMathQuat(new Quaternion(x, y, z, w).normalize());
+}
+
+export function identityMat4(): Mat4 {
+  return fromMathMat4(Matrix4.identity());
+}
+
+export function cloneMat4(value: Mat4): Mat4 {
+  return [...value] as Mat4;
+}
+
+export function addVec3(a: Vec3, b: Vec3): Vec3 {
+  return toMathVec3(a).add(toMathVec3(b)).toArray();
+}
+
+export function subVec3(a: Vec3, b: Vec3): Vec3 {
+  return toMathVec3(a).subtract(toMathVec3(b)).toArray();
+}
+
+export function scaleVec3(a: Vec3, scalar: number): Vec3 {
+  return toMathVec3(a).multiplyScalar(scalar).toArray();
+}
+
+export function lengthVec3(a: Vec3): number {
+  return toMathVec3(a).length();
+}
+
+export function normalizeVec3(a: Vec3): Vec3 {
+  return toMathVec3(a).normalize().toArray();
+}
+
+export function normalizeQuat(value: Quat): Quat {
+  return fromMathQuat(toMathQuat(value).normalize());
+}
+
+export function quatFromEuler(x: number, y: number, z: number): Quat {
+  const sx = Math.sin(x / 2);
+  const cx = Math.cos(x / 2);
+  const sy = Math.sin(y / 2);
+  const cy = Math.cos(y / 2);
+  const sz = Math.sin(z / 2);
+  const cz = Math.cos(z / 2);
+  return quat(
+    sx * cy * cz + cx * sy * sz,
+    cx * sy * cz - sx * cy * sz,
+    cx * cy * sz + sx * sy * cz,
+    cx * cy * cz - sx * sy * sz
+  );
+}
+
+export function multiplyMat4(a: Mat4, b: Mat4): Mat4 {
+  return fromMathMat4(toMathMat4(a).multiply(toMathMat4(b)));
+}
+
+export function composeMat4(position: Vec3, rotation: Quat, scale: Vec3): Mat4 {
+  return fromMathMat4(Matrix4.compose(toMathVec3(position), toMathQuat(rotation), toMathVec3(scale)));
+}
+
+export function transformPoint(matrix: Mat4, point: Vec3): Vec3 {
+  return toMathMat4(matrix).transformPoint(toMathVec3(point)).toArray();
+}
+
+export function invertMat4(matrix: Mat4): Mat4 {
+  return fromMathMat4(toMathMat4(matrix).inverse());
+}
+
+export function perspectiveMat4(fovYRadians: number, aspect: number, near: number, far: number): Mat4 {
+  return fromMathMat4(Matrix4.perspective(fovYRadians, aspect, near, far));
+}
+
+export function orthographicMat4(left: number, right: number, bottom: number, top: number, near: number, far: number): Mat4 {
+  return fromMathMat4(Matrix4.orthographic(left, right, bottom, top, near, far));
+}
+
+export function extractFrustumPlanes(viewProjection: Mat4): PlaneTuple[] {
+  return Frustum.fromMatrix(toMathMat4(viewProjection)).planes.map((plane) => [
+    plane.normal.x,
+    plane.normal.y,
+    plane.normal.z,
+    plane.constant
+  ]);
+}
+
+export function toMathVec3(value: Vec3): Vector3 {
+  return new Vector3(value[0], value[1], value[2]);
+}
+
+export function toMathQuat(value: Quat): Quaternion {
+  return new Quaternion(value[0], value[1], value[2], value[3]);
+}
+
+export function toMathMat4(value: Mat4): Matrix4 {
+  return new Matrix4(value);
+}
+
+export function fromMathMat4(value: Matrix4): Mat4 {
+  return [...value.elements] as Mat4;
+}
+
+export function fromMathQuat(value: Quaternion): Quat {
+  return [value.x, value.y, value.z, value.w];
+}
+
+export function decomposeMat4(matrix: Mat4): { position: Vec3; rotation: Quat; scale: Vec3 } {
+  const position: Vec3 = [matrix[12], matrix[13], matrix[14]];
+  const sx = Math.hypot(matrix[0], matrix[1], matrix[2]);
+  const sy = Math.hypot(matrix[4], matrix[5], matrix[6]);
+  const sz = Math.hypot(matrix[8], matrix[9], matrix[10]);
+  if (sx <= EPSILON || sy <= EPSILON || sz <= EPSILON) throw new Error("Cannot decompose transform matrix with zero scale.");
+
+  const m00 = matrix[0] / sx;
+  const m01 = matrix[4] / sy;
+  const m02 = matrix[8] / sz;
+  const m10 = matrix[1] / sx;
+  const m11 = matrix[5] / sy;
+  const m12 = matrix[9] / sz;
+  const m20 = matrix[2] / sx;
+  const m21 = matrix[6] / sy;
+  const m22 = matrix[10] / sz;
+  const trace = m00 + m11 + m22;
+  let rotation: Quat;
+
+  if (trace > 0) {
+    const s = Math.sqrt(trace + 1) * 2;
+    rotation = [(m21 - m12) / s, (m02 - m20) / s, (m10 - m01) / s, 0.25 * s];
+  } else if (m00 > m11 && m00 > m22) {
+    const s = Math.sqrt(1 + m00 - m11 - m22) * 2;
+    rotation = [0.25 * s, (m01 + m10) / s, (m02 + m20) / s, (m21 - m12) / s];
+  } else if (m11 > m22) {
+    const s = Math.sqrt(1 + m11 - m00 - m22) * 2;
+    rotation = [(m01 + m10) / s, 0.25 * s, (m12 + m21) / s, (m02 - m20) / s];
+  } else {
+    const s = Math.sqrt(1 + m22 - m00 - m11) * 2;
+    rotation = [(m02 + m20) / s, (m12 + m21) / s, 0.25 * s, (m10 - m01) / s];
+  }
+
+  return { position, rotation: normalizeQuat(rotation), scale: [sx, sy, sz] };
+}

package/src/Object3D.ts

@@ -0,0 +1,149 @@
+import { SceneNode, type SceneNodeOptions } from "./SceneNode.js";
+import { Renderable, type RenderableDescriptor } from "./Renderable.js";
+import type { Mat4, Quat, Vec3 } from "./MathTypes.js";
+
+export interface Object3DOptions extends SceneNodeOptions {
+  readonly visible?: boolean;
+  readonly layerMask?: number;
+  readonly renderOrder?: number;
+  readonly userData?: Record<string, unknown>;
+}
+
+export class Object3D extends SceneNode {
+  readonly isObject3D = true;
+
+  constructor(options: Object3DOptions = {}) {
+    super(options);
+    applyObject3DOptions(this, options);
+  }
+
+  get position(): Vec3 {
+    return this.transform.position;
+  }
+
+  get quaternion(): Quat {
+    return this.transform.rotation;
+  }
+
+  get scale(): Vec3 {
+    return this.transform.scale;
+  }
+
+  get matrix(): Mat4 {
+    return this.transform.localMatrix;
+  }
+
+  get matrixWorld(): Mat4 {
+    return this.transform.worldMatrix;
+  }
+
+  get matrixAutoUpdate(): boolean {
+    return this.transform.matrixAutoUpdate;
+  }
+
+  set matrixAutoUpdate(enabled: boolean) {
+    this.transform.setMatrixAutoUpdate(enabled);
+  }
+
+  setLocalMatrix(matrix: Mat4, options: { readonly decompose?: boolean; readonly matrixAutoUpdate?: boolean } = {}): this {
+    this.transform.setLocalMatrix(matrix, options);
+    return this;
+  }
+}
+
+export class Group extends Object3D {
+  readonly isGroup = true;
+}
+
+export interface MeshOptions extends Object3DOptions {
+  readonly renderable?: Renderable | RenderableDescriptor;
+}
+
+export class Mesh extends Object3D {
+  readonly isMesh = true;
+
+  constructor(options: MeshOptions = {}) {
+    super(options);
+    if (options.renderable) this.renderable = toRenderable(options.renderable);
+  }
+
+  setRenderable(renderable: Renderable | RenderableDescriptor): this {
+    this.renderable = toRenderable(renderable);
+    return this;
+  }
+}
+
+export class SkinnedMesh extends Mesh {
+  readonly isSkinnedMesh = true;
+
+  get skinning(): Renderable["skinning"] | undefined {
+    return this.renderable?.skinning;
+  }
+
+  setSkinning(skinning: NonNullable<Renderable["skinning"]>): this {
+    if (!this.renderable) throw new Error("SkinnedMesh requires a renderable before skinning can be assigned.");
+    this.renderable.skinning = {
+      jointCount: skinning.jointCount,
+      matrices: new Float32Array(skinning.matrices)
+    };
+    return this;
+  }
+}
+
+export class InstancedMesh extends Mesh {
+  readonly isInstancedMesh = true;
+
+  get instanceTransforms(): Float32Array | undefined {
+    return this.renderable?.instanceTransforms;
+  }
+
+  get instanceColors(): Float32Array | undefined {
+    return this.renderable?.instanceColors;
+  }
+
+  setInstanceTransforms(transforms: Float32Array | readonly number[]): this {
+    if (!this.renderable) throw new Error("InstancedMesh requires a renderable before instance transforms can be assigned.");
+    this.renderable.instanceTransforms = new Renderable({
+      geometry: this.renderable.geometry,
+      material: this.renderable.material,
+      layerMask: this.renderable.layerMask,
+      castShadow: this.renderable.castShadow,
+      receiveShadow: this.renderable.receiveShadow,
+      skinning: this.renderable.skinning,
+      morphWeights: this.renderable.morphWeights,
+      instanceTransforms: transforms,
+      instanceColors: this.renderable.instanceColors
+    }).instanceTransforms;
+    return this;
+  }
+
+  setInstanceColors(colors: Float32Array | readonly number[]): this {
+    if (!this.renderable) throw new Error("InstancedMesh requires a renderable before instance colors can be assigned.");
+    this.renderable.instanceColors = new Renderable({
+      geometry: this.renderable.geometry,
+      material: this.renderable.material,
+      layerMask: this.renderable.layerMask,
+      castShadow: this.renderable.castShadow,
+      receiveShadow: this.renderable.receiveShadow,
+      skinning: this.renderable.skinning,
+      morphWeights: this.renderable.morphWeights,
+      instanceTransforms: this.renderable.instanceTransforms,
+      instanceColors: colors
+    }).instanceColors;
+    return this;
+  }
+}
+
+function applyObject3DOptions(node: SceneNode, options: Object3DOptions): void {
+  if (options.visible !== undefined) node.visible = options.visible;
+  if (options.layerMask !== undefined) node.layerMask = options.layerMask;
+  if (options.renderOrder !== undefined) {
+    if (!Number.isFinite(options.renderOrder)) throw new Error("Object3D renderOrder must be finite.");
+    node.renderOrder = options.renderOrder;
+  }
+  if (options.userData) node.userData = { ...options.userData };
+}
+
+function toRenderable(renderable: Renderable | RenderableDescriptor): Renderable {
+  return renderable instanceof Renderable ? renderable : new Renderable(renderable);
+}

package/src/OrthographicCamera.ts

@@ -0,0 +1,73 @@
+import { ValidationError } from "@aura3d/core";
+import { orthographicMat4, type Mat4 } from "./MathTypes.js";
+import { Camera } from "./Camera.js";
+
+export interface OrthographicCameraOptions {
+  id?: string;
+  name?: string;
+  left?: number;
+  right?: number;
+  bottom?: number;
+  top?: number;
+  near?: number;
+  far?: number;
+  zoom?: number;
+  resizeMode?: OrthographicResizeMode;
+}
+
+export type OrthographicResizeMode = "fit-vertical" | "fit-horizontal" | "preserve-frustum";
+
+export class OrthographicCamera extends Camera {
+  left: number;
+  right: number;
+  bottom: number;
+  top: number;
+  near: number;
+  far: number;
+  zoom: number;
+  resizeMode: OrthographicResizeMode;
+
+  constructor(options: OrthographicCameraOptions = {}) {
+    super(options.name ?? "OrthographicCamera", options.id);
+    this.left = options.left ?? -1;
+    this.right = options.right ?? 1;
+    this.bottom = options.bottom ?? -1;
+    this.top = options.top ?? 1;
+    this.near = options.near ?? 0.1;
+    this.far = options.far ?? 1000;
+    this.zoom = options.zoom ?? 1;
+    this.resizeMode = options.resizeMode ?? "fit-vertical";
+    this.projectionMatrix = this.computeProjectionMatrix();
+  }
+
+  computeProjectionMatrix(): Mat4 {
+    if (!(this.zoom > 0)) throw new ValidationError("CAMERA_ZOOM", "Orthographic zoom must be positive.");
+    return orthographicMat4(this.left / this.zoom, this.right / this.zoom, this.bottom / this.zoom, this.top / this.zoom, this.near, this.far);
+  }
+
+  resize(width: number, height: number): void {
+    if (width <= 0 || height <= 0) throw new ValidationError("CAMERA_RESIZE", "Orthographic resize dimensions must be positive.");
+    const aspect = width / height;
+    const centerX = (this.left + this.right) / 2;
+    const centerY = (this.bottom + this.top) / 2;
+    const halfWidth = (this.right - this.left) / 2;
+    const halfHeight = (this.top - this.bottom) / 2;
+    if (this.resizeMode === "fit-horizontal") {
+      const resizedHalfHeight = halfWidth / aspect;
+      this.bottom = centerY - resizedHalfHeight;
+      this.top = centerY + resizedHalfHeight;
+    } else if (this.resizeMode === "preserve-frustum") {
+      const resizedHalfWidth = Math.max(halfWidth, halfHeight * aspect);
+      const resizedHalfHeight = Math.max(halfHeight, halfWidth / aspect);
+      this.left = centerX - resizedHalfWidth;
+      this.right = centerX + resizedHalfWidth;
+      this.bottom = centerY - resizedHalfHeight;
+      this.top = centerY + resizedHalfHeight;
+    } else {
+      const resizedHalfWidth = halfHeight * aspect;
+      this.left = centerX - resizedHalfWidth;
+      this.right = centerX + resizedHalfWidth;
+    }
+    this.updateCameraMatrices();
+  }
+}

package/src/PerspectiveCamera.ts

@@ -0,0 +1,54 @@
+import { ValidationError } from "@aura3d/core";
+import { perspectiveMat4, type Mat4 } from "./MathTypes.js";
+import { Camera } from "./Camera.js";
+
+export interface PerspectiveCameraOptions {
+  id?: string;
+  name?: string;
+  fovYRadians?: number;
+  aspect?: number;
+  near?: number;
+  far?: number;
+}
+
+export class PerspectiveCamera extends Camera {
+  fovYRadians: number;
+  aspect: number;
+  near: number;
+  far: number;
+
+  constructor(options: PerspectiveCameraOptions = {}) {
+    super(options.name ?? "PerspectiveCamera", options.id);
+    this.fovYRadians = options.fovYRadians ?? Math.PI / 3;
+    this.aspect = options.aspect ?? 1;
+    this.near = options.near ?? 0.1;
+    this.far = options.far ?? 1000;
+    this.projectionMatrix = this.computeProjectionMatrix();
+  }
+
+  computeProjectionMatrix(): Mat4 {
+    validatePerspectiveProjection(this.fovYRadians, this.aspect, this.near, this.far);
+    return perspectiveMat4(this.fovYRadians, this.aspect, this.near, this.far);
+  }
+
+  resize(width: number, height: number): void {
+    if (width <= 0 || height <= 0) throw new ValidationError("CAMERA_RESIZE", "Perspective resize dimensions must be positive.");
+    this.aspect = width / height;
+    this.updateCameraMatrices();
+  }
+}
+
+function validatePerspectiveProjection(fovYRadians: number, aspect: number, near: number, far: number): void {
+  if (!Number.isFinite(fovYRadians) || fovYRadians <= 0 || fovYRadians >= Math.PI) {
+    throw new ValidationError("CAMERA_FOV", "Perspective fovYRadians must be finite and greater than 0 and less than PI.");
+  }
+  if (!Number.isFinite(aspect) || aspect <= 0) {
+    throw new ValidationError("CAMERA_ASPECT", "Perspective aspect must be finite and positive.");
+  }
+  if (!Number.isFinite(near) || near <= 0) {
+    throw new ValidationError("CAMERA_NEAR", "Perspective near plane must be finite and positive.");
+  }
+  if (!Number.isFinite(far) || far <= near) {
+    throw new ValidationError("CAMERA_FAR", "Perspective far plane must be finite and greater than near.");
+  }
+}

package/src/PointLight.ts

@@ -0,0 +1,25 @@
+import { ValidationError } from "@aura3d/core";
+import { Bounds3 } from "./Bounds.js";
+import { Light } from "./Light.js";
+
+export class PointLight extends Light {
+  private currentRange = 10;
+
+  constructor(name = "PointLight", id?: string) {
+    super("point", name, id);
+  }
+
+  get range(): number {
+    return this.currentRange;
+  }
+
+  set range(value: number) {
+    if (!(value > 0) || !Number.isFinite(value)) throw new ValidationError("POINT_LIGHT_RANGE", "Point light range must be positive.");
+    this.currentRange = value;
+  }
+
+  getWorldBounds(): Bounds3 {
+    const p = this.transform.worldMatrix;
+    return Bounds3.fromCenterSize([p[12], p[13], p[14]], [this.range * 2, this.range * 2, this.range * 2]);
+  }
+}

package/src/Renderable.ts

@@ -0,0 +1,71 @@
+import { ValidationError } from "@aura3d/core";
+
+export interface RenderableDescriptor {
+  geometry: string;
+  material: string;
+  layerMask?: number;
+  castShadow?: boolean;
+  receiveShadow?: boolean;
+  skinning?: {
+    readonly jointCount: number;
+    readonly matrices: Float32Array;
+  };
+  morphWeights?: readonly number[];
+  instanceTransforms?: Float32Array | readonly number[];
+  instanceColors?: Float32Array | readonly number[];
+}
+
+export class Renderable {
+  readonly geometry: string;
+  readonly material: string;
+  layerMask: number;
+  castShadow: boolean;
+  receiveShadow: boolean;
+  skinning?: {
+    readonly jointCount: number;
+    readonly matrices: Float32Array;
+  };
+  morphWeights: number[];
+  instanceTransforms?: Float32Array;
+  instanceColors?: Float32Array;
+
+  constructor(descriptor: RenderableDescriptor) {
+    if (!descriptor.geometry) throw new ValidationError("RENDERABLE_GEOMETRY", "Renderable geometry handle is required.");
+    if (!descriptor.material) throw new ValidationError("RENDERABLE_MATERIAL", "Renderable material handle is required.");
+    this.geometry = descriptor.geometry;
+    this.material = descriptor.material;
+    this.layerMask = descriptor.layerMask ?? 1;
+    this.castShadow = descriptor.castShadow ?? true;
+    this.receiveShadow = descriptor.receiveShadow ?? true;
+    if (descriptor.skinning !== undefined) {
+      if (!Number.isInteger(descriptor.skinning.jointCount) || descriptor.skinning.jointCount <= 0 || descriptor.skinning.jointCount > 96) {
+        throw new ValidationError("RENDERABLE_SKINNING", "Renderable skinning jointCount must be an integer in [1, 96].");
+      }
+      if (descriptor.skinning.matrices.length !== descriptor.skinning.jointCount * 16 || !Array.from(descriptor.skinning.matrices).every(Number.isFinite)) {
+        throw new ValidationError("RENDERABLE_SKINNING", "Renderable skinning matrices must contain one finite mat4 per joint.");
+      }
+      this.skinning = {
+        jointCount: descriptor.skinning.jointCount,
+        matrices: new Float32Array(descriptor.skinning.matrices)
+      };
+    }
+    this.morphWeights = [...(descriptor.morphWeights ?? [])];
+    if (descriptor.instanceTransforms !== undefined) {
+      const values = Array.from(descriptor.instanceTransforms);
+      if (values.length === 0 || values.length % 16 !== 0 || !values.every(Number.isFinite)) {
+        throw new ValidationError("RENDERABLE_INSTANCES", "Renderable instanceTransforms must contain one or more finite mat4 values.");
+      }
+      this.instanceTransforms = new Float32Array(values);
+    }
+    if (descriptor.instanceColors !== undefined) {
+      const values = Array.from(descriptor.instanceColors);
+      if (values.length === 0 || values.length % 4 !== 0 || !values.every(Number.isFinite)) {
+        throw new ValidationError("RENDERABLE_INSTANCE_COLORS", "Renderable instanceColors must contain one or more finite vec4 values.");
+      }
+      if (this.instanceTransforms && values.length / 4 !== this.instanceTransforms.length / 16) {
+        throw new ValidationError("RENDERABLE_INSTANCE_COLORS", "Renderable instanceColors count must match instanceTransforms count.");
+      }
+      this.instanceColors = new Float32Array(values);
+    }
+  }
+}

package/src/Scene.ts

@@ -0,0 +1,134 @@
+import { ValidationError } from "@aura3d/core";
+import { Camera } from "./Camera.js";
+import { DirectionalLight } from "./DirectionalLight.js";
+import { Light } from "./Light.js";
+import { Group, InstancedMesh, Mesh, Object3D, SkinnedMesh, type MeshOptions, type Object3DOptions } from "./Object3D.js";
+import { OrthographicCamera } from "./OrthographicCamera.js";
+import { PerspectiveCamera } from "./PerspectiveCamera.js";
+import { PointLight } from "./PointLight.js";
+import { Renderable } from "./Renderable.js";
+import { collectRenderables, queryScene, type SceneQueryOptions } from "./SceneQuery.js";
+import { SceneMetadata } from "./SceneMetadata.js";
+import { SceneNode } from "./SceneNode.js";
+import { SpotLight } from "./SpotLight.js";
+
+export class Scene {
+  readonly root = new SceneNode({ id: "root", name: "root" });
+  readonly metadata = new SceneMetadata();
+  private readonly nodesById = new Map<string, SceneNode>([[this.root.id, this.root]]);
+
+  createNode(name?: string): SceneNode {
+    return this.register(new SceneNode({ name }));
+  }
+
+  createObject3D(options: Object3DOptions = {}): Object3D {
+    return this.register(new Object3D(options));
+  }
+
+  createGroup(options: Object3DOptions = {}): Group {
+    return this.register(new Group(options));
+  }
+
+  createMesh(options: MeshOptions = {}): Mesh {
+    return this.register(new Mesh(options));
+  }
+
+  createSkinnedMesh(options: MeshOptions = {}): SkinnedMesh {
+    return this.register(new SkinnedMesh(options));
+  }
+
+  createInstancedMesh(options: MeshOptions = {}): InstancedMesh {
+    return this.register(new InstancedMesh(options));
+  }
+
+  createPerspectiveCamera(options: ConstructorParameters<typeof PerspectiveCamera>[0] = {}): PerspectiveCamera {
+    return this.register(new PerspectiveCamera(options));
+  }
+
+  createOrthographicCamera(options: ConstructorParameters<typeof OrthographicCamera>[0] = {}): OrthographicCamera {
+    return this.register(new OrthographicCamera(options));
+  }
+
+  createLight(kind: "directional" | "point" | "spot", name?: string): DirectionalLight | PointLight | SpotLight {
+    const light = kind === "directional" ? new DirectionalLight(name) : kind === "point" ? new PointLight(name) : new SpotLight(name);
+    return this.register(light);
+  }
+
+  addRenderable(node: SceneNode, renderable: Renderable): void {
+    node.renderable = renderable;
+  }
+
+  getNodeById(id: string): SceneNode | undefined {
+    return this.nodesById.get(id);
+  }
+
+  findByName(name: string): SceneNode[] {
+    return this.query({ name });
+  }
+
+  query(options: SceneQueryOptions): SceneNode[] {
+    if (options.bounds) this.updateWorldBounds();
+    return queryScene(this.root, options);
+  }
+
+  updateWorldTransforms(): void {
+    this.root.updateWorldTransform();
+  }
+
+  updateWorldBounds(): void {
+    this.updateWorldTransforms();
+    this.root.updateWorldBounds();
+  }
+
+  update(): void {
+    this.updateWorldBounds();
+  }
+
+  traverse(visitor: (node: SceneNode) => void): void {
+    this.root.traverse(visitor);
+  }
+
+  collectRenderables(): { node: SceneNode; renderable: Renderable }[] {
+    return collectRenderables(this.root);
+  }
+
+  collectCameras(): Camera[] {
+    return this.query({ type: "camera" }).filter((node): node is Camera => node instanceof Camera);
+  }
+
+  collectLights(): Light[] {
+    return this.query({ type: "light" }).filter((node): node is Light => node instanceof Light);
+  }
+
+  removeNode(node: SceneNode): boolean {
+    if (node === this.root) return false;
+    const descendants: SceneNode[] = [];
+    node.traverse((descendant) => descendants.push(descendant));
+    const removed = node.removeFromParent();
+    for (const descendant of descendants) this.nodesById.delete(descendant.id);
+    return removed;
+  }
+
+  dispose(): void {
+    const descendants: SceneNode[] = [];
+    for (const child of [...this.root.children]) child.traverse((descendant) => descendants.push(descendant));
+    for (const child of [...this.root.children]) child.dispose();
+    for (const descendant of descendants) this.nodesById.delete(descendant.id);
+    this.root.children.length = 0;
+  }
+
+  registerSubtree(node: SceneNode): void {
+    node.traverse((descendant) => {
+      if (this.nodesById.has(descendant.id)) {
+        throw new ValidationError("DUPLICATE_SCENE_NODE", `Duplicate scene node id: ${descendant.id}`);
+      }
+      this.nodesById.set(descendant.id, descendant);
+    });
+  }
+
+  private register<T extends SceneNode>(node: T): T {
+    if (this.nodesById.has(node.id)) throw new ValidationError("DUPLICATE_SCENE_NODE", `Duplicate scene node id: ${node.id}`);
+    this.nodesById.set(node.id, node);
+    return node;
+  }
+}