@aura3d/scene 1.4.0 → 1.4.1

package/src/SceneSerializer.ts

@@ -1,177 +0,0 @@
-import { ValidationError } from "@aura3d/core";
-import { DirectionalLight } from "./DirectionalLight.js";
-import { OrthographicCamera } from "./OrthographicCamera.js";
-import { PerspectiveCamera } from "./PerspectiveCamera.js";
-import { PointLight } from "./PointLight.js";
-import { Renderable } from "./Renderable.js";
-import { Scene } from "./Scene.js";
-import type { SerializedSceneMetadata } from "./SceneMetadata.js";
-import { SceneNode } from "./SceneNode.js";
-import { SpotLight } from "./SpotLight.js";
-
-export interface SerializedSceneNode {
-  id: string;
-  name: string;
-  visible: boolean;
-  layerMask: number;
-  kind: "node" | "perspectiveCamera" | "orthographicCamera" | "directionalLight" | "pointLight" | "spotLight";
-  transform: {
-    position: [number, number, number];
-    rotation: [number, number, number, number];
-    scale: [number, number, number];
-  };
-  renderable?: {
-    geometry: string;
-    material: string;
-    layerMask: number;
-    castShadow: boolean;
-    receiveShadow: boolean;
-    morphWeights?: readonly number[];
-    instanceTransforms?: readonly number[];
-    instanceColors?: readonly number[];
-  };
-  camera?: {
-    fovYRadians?: number;
-    aspect?: number;
-    left?: number;
-    right?: number;
-    bottom?: number;
-    top?: number;
-    near: number;
-    far: number;
-    zoom?: number;
-    resizeMode?: "fit-vertical" | "fit-horizontal" | "preserve-frustum";
-    viewport: { x: number; y: number; width: number; height: number };
-  };
-  light?: {
-    color: [number, number, number];
-    intensity: number;
-    castsShadow: boolean;
-    range?: number;
-    angle?: number;
-    penumbra?: number;
-  };
-  children: SerializedSceneNode[];
-}
-
-export interface SerializedScene {
-  version: 1;
-  metadata?: SerializedSceneMetadata;
-  root: SerializedSceneNode;
-}
-
-export function serializeScene(scene: Scene): SerializedScene {
-  return {
-    version: 1,
-    ...(scene.metadata.isEmpty ? {} : { metadata: scene.metadata.toJSON() }),
-    root: serializeNode(scene.root)
-  };
-}
-
-export function deserializeScene(serialized: SerializedScene): Scene {
-  if (serialized.version !== 1) throw new ValidationError("SCENE_VERSION", `Unsupported scene version: ${serialized.version}`);
-  const scene = new Scene();
-  if (serialized.metadata) scene.metadata.replace(serialized.metadata);
-  for (const child of serialized.root.children) {
-    const node = deserializeNode(child);
-    scene.root.addChild(node);
-    scene.registerSubtree(node);
-  }
-  return scene;
-}
-
-function serializeNode(node: SceneNode): SerializedSceneNode {
-  const renderable = node.renderable;
-  return {
-    id: node.id,
-    name: node.name,
-    visible: node.visible,
-    layerMask: node.layerMask,
-    kind: node instanceof PerspectiveCamera ? "perspectiveCamera" : node instanceof OrthographicCamera ? "orthographicCamera" : node instanceof DirectionalLight ? "directionalLight" : node instanceof PointLight ? "pointLight" : node instanceof SpotLight ? "spotLight" : "node",
-    transform: {
-      position: [...node.transform.position],
-      rotation: [...node.transform.rotation],
-      scale: [...node.transform.scale]
-    },
-    renderable: renderable ? {
-      geometry: renderable.geometry,
-      material: renderable.material,
-      layerMask: renderable.layerMask,
-      castShadow: renderable.castShadow,
-      receiveShadow: renderable.receiveShadow,
-      ...(renderable.morphWeights.length > 0 ? { morphWeights: [...renderable.morphWeights] } : {}),
-      ...(renderable.instanceTransforms ? { instanceTransforms: [...renderable.instanceTransforms] } : {}),
-      ...(renderable.instanceColors ? { instanceColors: [...renderable.instanceColors] } : {})
-    } : undefined,
-    camera: serializeCamera(node),
-    light: serializeLight(node),
-    children: node.children.map(serializeNode)
-  };
-}
-
-function deserializeNode(data: SerializedSceneNode): SceneNode {
-  const node =
-    data.kind === "perspectiveCamera" ? new PerspectiveCamera({ id: data.id, name: data.name, fovYRadians: data.camera?.fovYRadians, aspect: data.camera?.aspect, near: data.camera?.near, far: data.camera?.far }) :
-    data.kind === "orthographicCamera" ? new OrthographicCamera({ id: data.id, name: data.name, left: data.camera?.left, right: data.camera?.right, bottom: data.camera?.bottom, top: data.camera?.top, near: data.camera?.near, far: data.camera?.far, zoom: data.camera?.zoom, resizeMode: data.camera?.resizeMode }) :
-    data.kind === "directionalLight" ? new DirectionalLight(data.name, data.id) :
-    data.kind === "pointLight" ? new PointLight(data.name, data.id) :
-    data.kind === "spotLight" ? new SpotLight(data.name, data.id) :
-    new SceneNode({ id: data.id, name: data.name });
-  node.visible = data.visible;
-  node.layerMask = data.layerMask;
-  node.transform.setPosition(...data.transform.position);
-  node.transform.setRotation(...data.transform.rotation);
-  node.transform.setScale(...data.transform.scale);
-  if (data.camera && (node instanceof PerspectiveCamera || node instanceof OrthographicCamera)) node.setViewport(data.camera.viewport);
-  if (data.light && (node instanceof DirectionalLight || node instanceof PointLight || node instanceof SpotLight)) {
-    node.color = [...data.light!.color];
-    node.intensity = data.light!.intensity;
-    node.castsShadow = data.light!.castsShadow;
-  }
-  if (data.light?.range !== undefined && (node instanceof PointLight || node instanceof SpotLight)) node.range = data.light.range;
-  if (data.light?.angle !== undefined && node instanceof SpotLight) node.angle = data.light.angle;
-  if (data.light?.penumbra !== undefined && node instanceof SpotLight) node.penumbra = data.light.penumbra;
-  if (data.renderable) node.renderable = new Renderable(data.renderable);
-  for (const child of data.children) node.addChild(deserializeNode(child));
-  return node;
-}
-
-function serializeCamera(node: SceneNode): SerializedSceneNode["camera"] {
-  if (node instanceof PerspectiveCamera) {
-    return {
-      fovYRadians: node.fovYRadians,
-      aspect: node.aspect,
-      near: node.near,
-      far: node.far,
-      viewport: { ...node.viewport }
-    };
-  }
-  if (node instanceof OrthographicCamera) {
-    return {
-      left: node.left,
-      right: node.right,
-      bottom: node.bottom,
-      top: node.top,
-      near: node.near,
-      far: node.far,
-      zoom: node.zoom,
-      resizeMode: node.resizeMode,
-      viewport: { ...node.viewport }
-    };
-  }
-  return undefined;
-}
-
-function serializeLight(node: SceneNode): SerializedSceneNode["light"] {
-  if (node instanceof DirectionalLight || node instanceof PointLight || node instanceof SpotLight) {
-    const color = Array.isArray(node.color) ? [...node.color] as [number, number, number] : [node.color.x, node.color.y, node.color.z] as [number, number, number];
-    return {
-      color,
-      intensity: node.intensity,
-      castsShadow: node.castsShadow,
-      ...(node instanceof PointLight || node instanceof SpotLight ? { range: node.range } : {}),
-      ...(node instanceof SpotLight ? { angle: node.angle, penumbra: node.penumbra } : {})
-    };
-  }
-  return undefined;
-}

package/src/SpotLight.ts

@@ -1,39 +0,0 @@
-import { ValidationError } from "@aura3d/core";
-import { Light } from "./Light.js";
-
-export class SpotLight extends Light {
-  private currentAngle = Math.PI / 4;
-  private currentPenumbra = 0;
-  private currentRange = 10;
-
-  constructor(name = "SpotLight", id?: string) {
-    super("spot", name, id);
-  }
-
-  get angle(): number {
-    return this.currentAngle;
-  }
-
-  set angle(value: number) {
-    if (!(value > 0 && value < Math.PI / 2)) throw new ValidationError("SPOT_LIGHT_ANGLE", "Spot light angle must be within (0, PI / 2).");
-    this.currentAngle = value;
-  }
-
-  get penumbra(): number {
-    return this.currentPenumbra;
-  }
-
-  set penumbra(value: number) {
-    if (!(value >= 0 && value <= 1)) throw new ValidationError("SPOT_LIGHT_PENUMBRA", "Spot light penumbra must be within [0, 1].");
-    this.currentPenumbra = value;
-  }
-
-  get range(): number {
-    return this.currentRange;
-  }
-
-  set range(value: number) {
-    if (!(value > 0) || !Number.isFinite(value)) throw new ValidationError("SPOT_LIGHT_RANGE", "Spot light range must be positive.");
-    this.currentRange = value;
-  }
-}

package/src/TransformNode.ts

@@ -1,116 +0,0 @@
-import {
-  cloneMat4,
-  composeMat4,
-  decomposeMat4,
-  identityMat4,
-  invertMat4,
-  multiplyMat4,
-  normalizeQuat,
-  type Mat4,
-  type Quat,
-  type Vec3
-} from "./MathTypes.js";
-
-export class TransformNode {
-  private dirty = true;
-  private readonly dirtyListeners = new Set<() => void>();
-  matrixAutoUpdate = true;
-  readonly position: Vec3 = [0, 0, 0];
-  readonly rotation: Quat = [0, 0, 0, 1];
-  readonly scale: Vec3 = [1, 1, 1];
-  localMatrix: Mat4 = identityMat4();
-  worldMatrix: Mat4 = identityMat4();
-  inverseWorldMatrix: Mat4 = identityMat4();
-
-  setPosition(x: number, y: number, z: number): this {
-    this.position[0] = x;
-    this.position[1] = y;
-    this.position[2] = z;
-    return this.markDirty();
-  }
-
-  setRotation(x: number, y: number, z: number, w: number): this {
-    const normalized = normalizeQuat([x, y, z, w]);
-    this.rotation[0] = normalized[0];
-    this.rotation[1] = normalized[1];
-    this.rotation[2] = normalized[2];
-    this.rotation[3] = normalized[3];
-    return this.markDirty();
-  }
-
-  setScale(x: number, y: number, z: number): this {
-    this.scale[0] = x;
-    this.scale[1] = y;
-    this.scale[2] = z;
-    return this.markDirty();
-  }
-
-  setFromLocalMatrix(matrix: Mat4): this {
-    const decomposed = decomposeMat4(matrix);
-    this.position[0] = decomposed.position[0];
-    this.position[1] = decomposed.position[1];
-    this.position[2] = decomposed.position[2];
-    this.rotation[0] = decomposed.rotation[0];
-    this.rotation[1] = decomposed.rotation[1];
-    this.rotation[2] = decomposed.rotation[2];
-    this.rotation[3] = decomposed.rotation[3];
-    this.scale[0] = decomposed.scale[0];
-    this.scale[1] = decomposed.scale[1];
-    this.scale[2] = decomposed.scale[2];
-    return this.markDirty();
-  }
-
-  setLocalMatrix(matrix: Mat4, options: { readonly decompose?: boolean; readonly matrixAutoUpdate?: boolean } = {}): this {
-    if (!matrix.every(Number.isFinite)) throw new Error("Transform local matrix must contain finite values.");
-    this.localMatrix = cloneMat4(matrix);
-    this.matrixAutoUpdate = options.matrixAutoUpdate ?? false;
-    if (options.decompose ?? true) {
-      const decomposed = decomposeMat4(matrix);
-      this.position[0] = decomposed.position[0];
-      this.position[1] = decomposed.position[1];
-      this.position[2] = decomposed.position[2];
-      this.rotation[0] = decomposed.rotation[0];
-      this.rotation[1] = decomposed.rotation[1];
-      this.rotation[2] = decomposed.rotation[2];
-      this.rotation[3] = decomposed.rotation[3];
-      this.scale[0] = decomposed.scale[0];
-      this.scale[1] = decomposed.scale[1];
-      this.scale[2] = decomposed.scale[2];
-    }
-    return this.markDirty();
-  }
-
-  setMatrixAutoUpdate(enabled: boolean): this {
-    this.matrixAutoUpdate = enabled;
-    return this.markDirty();
-  }
-
-  markDirty(): this {
-    if (!this.dirty) {
-      this.dirty = true;
-      for (const listener of [...this.dirtyListeners]) listener();
-    }
-    return this;
-  }
-
-  onDirty(listener: () => void): () => void {
-    this.dirtyListeners.add(listener);
-    return () => this.dirtyListeners.delete(listener);
-  }
-
-  isDirty(): boolean {
-    return this.dirty;
-  }
-
-  updateWorld(parentWorld?: Mat4, force = false): boolean {
-    const shouldUpdate = force || this.dirty;
-    if (!shouldUpdate) return false;
-    if (this.matrixAutoUpdate) {
-      this.localMatrix = composeMat4(this.position, this.rotation, this.scale);
-    }
-    this.worldMatrix = parentWorld ? multiplyMat4(parentWorld, this.localMatrix) : cloneMat4(this.localMatrix);
-    this.inverseWorldMatrix = invertMat4(this.worldMatrix);
-    this.dirty = false;
-    return true;
-  }
-}

package/src/index.ts

@@ -1,20 +0,0 @@
-export * from "./MathTypes.js";
-export * from "./TransformNode.js";
-export * from "./Bounds.js";
-export * from "./SceneNode.js";
-export * from "./Object3D.js";
-export * from "./Hierarchy.js";
-export * from "./Camera.js";
-export * from "./PerspectiveCamera.js";
-export * from "./OrthographicCamera.js";
-export * from "./Light.js";
-export * from "./DirectionalLight.js";
-export * from "./PointLight.js";
-export * from "./SpotLight.js";
-export * from "./Layers.js";
-export * from "./Lights.js";
-export * from "./Renderable.js";
-export * from "./SceneQuery.js";
-export * from "./SceneMetadata.js";
-export * from "./Scene.js";
-export * from "./SceneSerializer.js";

package/tests/scene.test.ts

@@ -1,117 +0,0 @@
-import assert from "node:assert/strict";
-import { test } from "node:test";
-import {
-  Bounds3,
-  PerspectiveCamera,
-  Renderable,
-  Scene,
-  SceneNode,
-  deserializeScene,
-  quatFromEuler,
-  serializeScene
-} from "../src/index.js";
-
-test("scene hierarchy propagates nested transforms deterministically", () => {
-  const scene = new Scene();
-  const parent = scene.createNode("parent");
-  const child = scene.createNode("child");
-  parent.transform.setPosition(2, 0, 0);
-  child.transform.setPosition(0, 3, 0);
-  scene.root.addChild(parent);
-  parent.addChild(child);
-
-  scene.updateWorldTransforms();
-
-  assert.equal(child.transform.worldMatrix[12], 2);
-  assert.equal(child.transform.worldMatrix[13], 3);
-  assert.equal(child.transform.worldMatrix[14], 0);
-});
-
-test("scene hierarchy rejects self-parenting and cycles", () => {
-  const parent = new SceneNode({ name: "parent" });
-  const child = new SceneNode({ name: "child" });
-  parent.addChild(child);
-
-  assert.throws(() => parent.addChild(parent), /cannot be parented to itself/);
-  assert.throws(() => child.addChild(parent), /cycle rejected/);
-});
-
-test("scene traversal snapshots children when nodes are removed during traversal", () => {
-  const scene = new Scene();
-  const a = scene.createNode("a");
-  const b = scene.createNode("b");
-  scene.root.addChild(a);
-  scene.root.addChild(b);
-  const visited: string[] = [];
-
-  scene.traverse((node) => {
-    visited.push(node.name);
-    if (node === a) scene.root.removeChild(b);
-  });
-
-  assert.deepEqual(visited, ["root", "a", "b"]);
-});
-
-test("bounds transform handles negative scale", () => {
-  const node = new SceneNode();
-  node.transform.setPosition(5, 0, 0).setScale(-2, 3, 1);
-  node.updateWorldTransform();
-
-  const world = Bounds3.fromCenterSize([0, 0, 0], [2, 2, 2]).transform(node.transform.worldMatrix);
-
-  assert.deepEqual(world.min, [3, -3, -1]);
-  assert.deepEqual(world.max, [7, 3, 1]);
-});
-
-test("perspective camera produces view projection and frustum planes", () => {
-  const camera = new PerspectiveCamera({ fovYRadians: Math.PI / 2, aspect: 1, near: 1, far: 100 });
-  camera.transform.setPosition(0, 0, 10);
-  camera.updateCameraMatrices();
-
-  assert.equal(camera.frustumPlanes.length, 6);
-  assert.equal(camera.viewMatrix[14], -10);
-  assert.ok(Math.abs(camera.projectionMatrix[0] - 1) < 1e-8);
-  assert.throws(() => new PerspectiveCamera({ fovYRadians: 0 }).computeProjectionMatrix(), /fov/);
-});
-
-test("directional camera-space contracts are independent from controls", () => {
-  const camera = new PerspectiveCamera();
-  camera.transform.setRotation(...quatFromEuler(0, Math.PI / 4, 0));
-  camera.updateCameraMatrices();
-
-  assert.equal(camera.viewport.width, 1);
-  assert.equal(camera.viewport.height, 1);
-  assert.throws(() => camera.setViewport({ x: 0, y: 0, width: 0, height: 1 }), /positive/);
-});
-
-test("scene collects renderables, cameras, and lights without mutation", () => {
-  const scene = new Scene();
-  const node = scene.createNode("mesh");
-  const camera = scene.createPerspectiveCamera();
-  const light = scene.createLight("directional");
-  scene.root.addChild(node);
-  scene.root.addChild(camera);
-  scene.root.addChild(light);
-  scene.addRenderable(node, new Renderable({ geometry: "geometry:cube", material: "material:unlit" }));
-
-  const before = node.transform.worldMatrix.slice();
-  const renderables = scene.collectRenderables();
-
-  assert.equal(renderables.length, 1);
-  assert.equal(scene.collectCameras().length, 1);
-  assert.equal(scene.collectLights().length, 1);
-  assert.deepEqual(node.transform.worldMatrix, before);
-});
-
-test("scene serialization roundtrips a simple hierarchy", () => {
-  const scene = new Scene();
-  const parent = scene.createNode("parent");
-  const child = scene.createNode("child");
-  parent.addChild(child);
-  scene.root.addChild(parent);
-
-  const restored = deserializeScene(serializeScene(scene));
-
-  assert.deepEqual(restored.findByName("child").map((node) => node.name), ["child"]);
-  assert.equal(restored.root.children[0].children[0].name, "child");
-});

package/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "declaration": true,
-    "outDir": "dist",
-    "emitDeclarationOnly": true
-  },
-  "include": ["src/**/*.ts"]
-}