@aura3d/scene 1.0.6

package/src/SceneMetadata.ts

@@ -0,0 +1,225 @@
+import { ValidationError } from "@aura3d/core";
+
+export type SceneMetadataSeed = string | number;
+export type SceneMetadataPlanKind =
+  | "animation"
+  | "camera"
+  | "environment"
+  | "interaction"
+  | "lighting"
+  | "physics"
+  | "postprocess"
+  | "rendering";
+export type SceneMetadataCapabilityStatus = "supported" | "unsupported" | "approximation" | "route-local";
+
+export interface SceneAssetProvenance {
+  readonly id: string;
+  readonly uri?: string;
+  readonly source?: string;
+  readonly loader?: string;
+  readonly version?: string;
+  readonly digest?: string;
+  readonly license?: string;
+  readonly nodeIds?: readonly string[];
+  readonly materialIds?: readonly string[];
+  readonly notes?: string;
+}
+
+export interface SceneMaterialAssignment {
+  readonly nodeId: string;
+  readonly materialId: string;
+  readonly slot?: string | number;
+  readonly sourceMaterialId?: string;
+  readonly fallback?: boolean;
+  readonly unsupportedFeatures?: readonly string[];
+}
+
+export interface ScenePlanMetadata {
+  readonly id: string;
+  readonly kind: SceneMetadataPlanKind;
+  readonly description: string;
+  readonly owner?: string;
+  readonly nodeIds?: readonly string[];
+  readonly deterministicSeed?: SceneMetadataSeed;
+  readonly unsupportedFeatures?: readonly string[];
+  readonly evidence?: readonly string[];
+}
+
+export interface SceneCapabilityDisclosure {
+  readonly feature: string;
+  readonly status: SceneMetadataCapabilityStatus;
+  readonly reason?: string;
+  readonly owner?: string;
+  readonly evidence?: readonly string[];
+}
+
+export interface SceneRevisionMetadata {
+  readonly id?: string;
+  readonly parentRevisionId?: string;
+  readonly summary: string;
+  readonly author?: string;
+  readonly timestamp?: string;
+  readonly deterministicSeed?: SceneMetadataSeed;
+}
+
+export type SceneRevisionRecord = Required<Pick<SceneRevisionMetadata, "id" | "summary">> & SceneRevisionMetadata;
+
+export interface SceneMetadataOptions {
+  readonly deterministicSeed?: SceneMetadataSeed;
+  readonly assets?: readonly SceneAssetProvenance[];
+  readonly materialAssignments?: readonly SceneMaterialAssignment[];
+  readonly plans?: readonly ScenePlanMetadata[];
+  readonly capabilities?: readonly SceneCapabilityDisclosure[];
+  readonly revisions?: readonly SceneRevisionMetadata[];
+}
+
+export type SerializedSceneMetadata = SceneMetadataOptions;
+
+export class SceneMetadata {
+  deterministicSeed?: SceneMetadataSeed;
+  readonly assets: SceneAssetProvenance[] = [];
+  readonly materialAssignments: SceneMaterialAssignment[] = [];
+  readonly plans: ScenePlanMetadata[] = [];
+  readonly capabilities: SceneCapabilityDisclosure[] = [];
+  readonly revisions: SceneRevisionRecord[] = [];
+
+  constructor(options: SceneMetadataOptions = {}) {
+    this.replace(options);
+  }
+
+  replace(options: SceneMetadataOptions | SceneMetadata): this {
+    this.deterministicSeed = options.deterministicSeed;
+    this.assets.length = 0;
+    this.materialAssignments.length = 0;
+    this.plans.length = 0;
+    this.capabilities.length = 0;
+    this.revisions.length = 0;
+    for (const asset of options.assets ?? []) this.registerAsset(asset);
+    for (const assignment of options.materialAssignments ?? []) this.assignMaterial(assignment);
+    for (const plan of options.plans ?? []) this.addPlan(plan);
+    for (const capability of options.capabilities ?? []) this.discloseCapability(capability);
+    for (const revision of options.revisions ?? []) this.recordRevision(revision);
+    return this;
+  }
+
+  clone(): SceneMetadata {
+    return new SceneMetadata(this.toJSON());
+  }
+
+  get isEmpty(): boolean {
+    return this.deterministicSeed === undefined
+      && this.assets.length === 0
+      && this.materialAssignments.length === 0
+      && this.plans.length === 0
+      && this.capabilities.length === 0
+      && this.revisions.length === 0;
+  }
+
+  registerAsset(asset: SceneAssetProvenance): this {
+    requireNonEmpty(asset.id, "asset id");
+    upsertByKey(this.assets, cloneAsset(asset), (candidate) => candidate.id === asset.id);
+    return this;
+  }
+
+  assignMaterial(assignment: SceneMaterialAssignment): this {
+    requireNonEmpty(assignment.nodeId, "material assignment nodeId");
+    requireNonEmpty(assignment.materialId, "material assignment materialId");
+    const cloned = cloneMaterialAssignment(assignment);
+    upsertByKey(
+      this.materialAssignments,
+      cloned,
+      (candidate) => candidate.nodeId === cloned.nodeId && candidate.slot === cloned.slot
+    );
+    return this;
+  }
+
+  addPlan(plan: ScenePlanMetadata): this {
+    requireNonEmpty(plan.id, "plan id");
+    requireNonEmpty(plan.description, "plan description");
+    upsertByKey(this.plans, clonePlan(plan), (candidate) => candidate.id === plan.id);
+    return this;
+  }
+
+  discloseCapability(disclosure: SceneCapabilityDisclosure): this {
+    requireNonEmpty(disclosure.feature, "capability feature");
+    upsertByKey(this.capabilities, cloneCapability(disclosure), (candidate) => candidate.feature === disclosure.feature);
+    return this;
+  }
+
+  discloseUnsupportedFeature(
+    feature: string,
+    reason: string,
+    options: Omit<SceneCapabilityDisclosure, "feature" | "reason" | "status"> = {}
+  ): this {
+    return this.discloseCapability({ ...options, feature, reason, status: "unsupported" });
+  }
+
+  recordRevision(revision: SceneRevisionMetadata): this {
+    requireNonEmpty(revision.summary, "revision summary");
+    const id = revision.id ?? `revision-${this.revisions.length + 1}`;
+    upsertByKey(this.revisions, cloneRevision({ ...revision, id }), (candidate) => candidate.id === id);
+    return this;
+  }
+
+  unsupportedFeatures(): readonly SceneCapabilityDisclosure[] {
+    return this.capabilities.filter((capability) => capability.status === "unsupported");
+  }
+
+  toJSON(): SerializedSceneMetadata {
+    return {
+      ...(this.deterministicSeed !== undefined ? { deterministicSeed: this.deterministicSeed } : {}),
+      ...(this.assets.length > 0 ? { assets: this.assets.map(cloneAsset) } : {}),
+      ...(this.materialAssignments.length > 0 ? { materialAssignments: this.materialAssignments.map(cloneMaterialAssignment) } : {}),
+      ...(this.plans.length > 0 ? { plans: this.plans.map(clonePlan) } : {}),
+      ...(this.capabilities.length > 0 ? { capabilities: this.capabilities.map(cloneCapability) } : {}),
+      ...(this.revisions.length > 0 ? { revisions: this.revisions.map(cloneRevision) } : {})
+    };
+  }
+}
+
+function requireNonEmpty(value: string | undefined, label: string): void {
+  if (!value || value.trim().length === 0) {
+    throw new ValidationError("SCENE_METADATA", `Scene metadata ${label} must be a non-empty string.`);
+  }
+}
+
+function upsertByKey<T>(items: T[], value: T, matches: (candidate: T) => boolean): void {
+  const index = items.findIndex(matches);
+  if (index >= 0) items[index] = value;
+  else items.push(value);
+}
+
+function cloneAsset(asset: SceneAssetProvenance): SceneAssetProvenance {
+  return {
+    ...asset,
+    ...(asset.nodeIds ? { nodeIds: [...asset.nodeIds] } : {}),
+    ...(asset.materialIds ? { materialIds: [...asset.materialIds] } : {})
+  };
+}
+
+function cloneMaterialAssignment(assignment: SceneMaterialAssignment): SceneMaterialAssignment {
+  return {
+    ...assignment,
+    ...(assignment.unsupportedFeatures ? { unsupportedFeatures: [...assignment.unsupportedFeatures] } : {})
+  };
+}
+
+function clonePlan(plan: ScenePlanMetadata): ScenePlanMetadata {
+  return {
+    ...plan,
+    ...(plan.nodeIds ? { nodeIds: [...plan.nodeIds] } : {}),
+    ...(plan.unsupportedFeatures ? { unsupportedFeatures: [...plan.unsupportedFeatures] } : {}),
+    ...(plan.evidence ? { evidence: [...plan.evidence] } : {})
+  };
+}
+
+function cloneCapability(capability: SceneCapabilityDisclosure): SceneCapabilityDisclosure {
+  return {
+    ...capability,
+    ...(capability.evidence ? { evidence: [...capability.evidence] } : {})
+  };
+}
+
+function cloneRevision(revision: SceneRevisionMetadata): SceneRevisionRecord {
+  return { ...revision, id: revision.id ?? "revision-1" };
+}

package/src/SceneNode.ts

@@ -0,0 +1,139 @@
+import { ValidationError } from "@aura3d/core";
+import { Bounds3 } from "./Bounds.js";
+import { cloneMat4, invertMat4, multiplyMat4 } from "./MathTypes.js";
+import type { Renderable } from "./Renderable.js";
+import { TransformNode } from "./TransformNode.js";
+
+let nextSceneNodeId = 1;
+
+export interface SceneNodeOptions {
+  id?: string;
+  name?: string;
+}
+
+export interface AddChildOptions {
+  preserveWorldTransform?: boolean;
+}
+
+export interface DisposeNodeOptions {
+  recursive?: boolean;
+}
+
+export class SceneNode {
+  readonly id: string;
+  name: string;
+  visible = true;
+  layerMask = 1;
+  renderOrder = 0;
+  disposed = false;
+  userData: Record<string, unknown> = {};
+  renderable?: Renderable;
+  readonly transform = new TransformNode();
+  localBounds: Bounds3 | null = null;
+  worldBounds = new Bounds3();
+  readonly children: SceneNode[] = [];
+  parent: SceneNode | null = null;
+
+  constructor(options: SceneNodeOptions = {}) {
+    this.id = options.id ?? `node-${nextSceneNodeId++}`;
+    this.name = options.name ?? this.id;
+    this.transform.onDirty(() => this.markWorldDirty());
+  }
+
+  addChild(child: SceneNode, options: AddChildOptions = {}): this {
+    this.assertAlive();
+    child.assertAlive();
+    assertCanParent(this, child);
+    if (child.parent === this) return this;
+    const preservedWorld = options.preserveWorldTransform ? cloneMat4(child.transform.worldMatrix) : undefined;
+    if (preservedWorld) this.updateWorldTransform();
+    child.parent?.removeChild(child);
+    this.children.push(child);
+    child.parent = this;
+    if (preservedWorld) child.transform.setFromLocalMatrix(multiplyMat4(invertMat4(this.transform.worldMatrix), preservedWorld));
+    child.markWorldDirty();
+    return this;
+  }
+
+  removeChild(child: SceneNode): boolean {
+    this.assertAlive();
+    const index = this.children.indexOf(child);
+    if (index < 0) return false;
+    this.children.splice(index, 1);
+    child.parent = null;
+    child.markWorldDirty();
+    return true;
+  }
+
+  removeFromParent(): boolean {
+    return this.parent?.removeChild(this) ?? false;
+  }
+
+  isAncestorOf(candidate: SceneNode): boolean {
+    let current = candidate.parent;
+    while (current) {
+      if (current === this) return true;
+      current = current.parent;
+    }
+    return false;
+  }
+
+  traverse(visitor: (node: SceneNode) => void): void {
+    visitor(this);
+    for (const child of [...this.children]) child.traverse(visitor);
+  }
+
+  updateWorldTransform(force = false): void {
+    const changed = this.transform.updateWorld(this.parent?.transform.worldMatrix, force);
+    for (const child of this.children) child.updateWorldTransform(force || changed);
+  }
+
+  updateWorldBounds(): Bounds3 {
+    let bounds = this.localBounds ? this.localBounds.transform(this.transform.worldMatrix) : new Bounds3();
+    for (const child of this.children) bounds = bounds.union(child.updateWorldBounds());
+    this.worldBounds = bounds;
+    return this.worldBounds;
+  }
+
+  setLocalBounds(bounds: Bounds3 | null): this {
+    this.assertAlive();
+    this.localBounds = bounds?.clone() ?? null;
+    this.worldBounds = this.localBounds ? this.localBounds.transform(this.transform.worldMatrix) : new Bounds3();
+    return this;
+  }
+
+  dispose(options: DisposeNodeOptions = {}): void {
+    if (this.disposed) return;
+    const recursive = options.recursive ?? true;
+    const children = [...this.children];
+    if (recursive) {
+      for (const child of children) child.dispose(options);
+    } else {
+      for (const child of children) child.parent = null;
+    }
+    this.children.length = 0;
+    this.parent?.removeChild(this);
+    this.parent = null;
+    this.renderable = undefined;
+    this.localBounds = null;
+    this.userData = {};
+    this.visible = false;
+    this.disposed = true;
+  }
+
+  markWorldDirty(): void {
+    for (const child of this.children) {
+      child.transform.markDirty();
+      child.markWorldDirty();
+    }
+  }
+
+  protected assertAlive(): void {
+    if (this.disposed) throw new ValidationError("DISPOSED_SCENE_NODE", `Scene node ${this.name} is disposed.`);
+  }
+}
+
+export function assertCanParent(parent: SceneNode, child: SceneNode): void {
+  if (parent === child) throw new ValidationError("SCENE_SELF_PARENT", "A scene node cannot be parented to itself.");
+  if (child.isAncestorOf(parent)) throw new ValidationError("SCENE_HIERARCHY_CYCLE", "Scene hierarchy cycle rejected.");
+}

package/src/SceneQuery.ts

@@ -0,0 +1,39 @@
+import { Bounds3 } from "./Bounds.js";
+import { Camera } from "./Camera.js";
+import { Light } from "./Light.js";
+import { Renderable } from "./Renderable.js";
+import { SceneNode } from "./SceneNode.js";
+
+export interface SceneQueryOptions {
+  name?: string | RegExp;
+  visible?: boolean;
+  layerMask?: number;
+  type?: "camera" | "light" | "node";
+  bounds?: Bounds3;
+}
+
+export function queryScene(root: SceneNode, options: SceneQueryOptions): SceneNode[] {
+  const result: SceneNode[] = [];
+  root.traverse((node) => {
+    if (options.visible !== undefined && node.visible !== options.visible) return;
+    if (options.layerMask !== undefined && (node.layerMask & options.layerMask) === 0) return;
+    if (options.name !== undefined) {
+      const matches = typeof options.name === "string" ? node.name === options.name : options.name.test(node.name);
+      if (!matches) return;
+    }
+    if (options.type === "camera" && !(node instanceof Camera)) return;
+    if (options.type === "light" && !(node instanceof Light)) return;
+    if (options.bounds && !node.worldBounds.intersects(options.bounds)) return;
+    result.push(node);
+  });
+  return result;
+}
+
+export function collectRenderables(root: SceneNode): { node: SceneNode; renderable: Renderable }[] {
+  const result: { node: SceneNode; renderable: Renderable }[] = [];
+  root.traverse((node) => {
+    const maybe = node.renderable;
+    if (maybe && node.visible) result.push({ node, renderable: maybe });
+  });
+  return result;
+}

package/src/SceneSerializer.ts

@@ -0,0 +1,177 @@
+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

@@ -0,0 +1,39 @@
+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;
+  }
+}