@caperjs/plugin-3d 0.0.0-stage → 0.8.0

package/lib/quality.d.ts

@@ -0,0 +1,9 @@
+export type Quality3D = 'auto' | 'low' | 'high';
+export declare function resolveQuality(quality: Quality3D, device: {
+    isMobile: boolean;
+    resolution: number;
+}): {
+    shadowQuality: 'low' | 'medium' | 'high';
+    resolution: number | 'inherit';
+};
+//# sourceMappingURL=quality.d.ts.map

package/lib/quality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality.d.ts","sourceRoot":"","sources":["../src/quality.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAEhD,wBAAgB,cAAc,CAC5B,OAAO,EAAE,SAAS,EAClB,MAAM,EAAE;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,aAAa,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAM9E"}

package/lib/renderer.d.ts

@@ -0,0 +1,2 @@
+export declare function assertRenderer3D(value: unknown): void;
+//# sourceMappingURL=renderer.d.ts.map

package/lib/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"AAOA,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAcrD"}

package/lib/version.d.ts

@@ -0,0 +1,2 @@
+export declare const version = "0.8.0";
+//# sourceMappingURL=version.d.ts.map

package/lib/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@caperjs/plugin-3d",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Experimental 3D for Caper, built on @pixi/3d",
+  "keywords": [
+    "3d",
+    "gltf",
+    "@pixi/3d",
+    "@caperjs/core",
+    "caper"
+  ],
+  "version": "0.8.0",
+  "files": [
+    "lib",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "main": "lib/caper-plugin-3d.mjs",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "default": "./lib/caper-plugin-3d.mjs",
+      "types": "./lib/index.d.ts"
+    }
+  },
+  "sideEffects": false,
+  "caper": {
+    "phase": "pre-renderer"
+  },
+  "scripts": {
+    "build": "pnpm run generate-version && vite build",
+    "test": "vitest run",
+    "generate-version": "node generateVersion.mjs"
+  },
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@caperjs/core": "^0.8.0",
+    "@pixi/3d": "0.1.0",
+    "happy-dom": "^15",
+    "vite": "^8.0.7",
+    "vite-plugin-dts": "^4.5.3",
+    "vitest": "^3"
+  },
+  "peerDependencies": {
+    "@caperjs/core": "^0.8.0",
+    "@pixi/3d": "0.1.0",
+    "pixi.js": "8.23.0"
+  }
 }

package/src/Entity3D.ts

@@ -0,0 +1,72 @@
+import { Container3D } from '@pixi/3d';
+import { bindAllMethods, WithLifecycle, WithSignals } from '@caperjs/core';
+import { createFactory3D } from './factory3d';
+import type { Factory3D } from './factory3d';
+import { ownedByView } from './owned';
+import type { Owned3D } from './owned';
+import type { View3D } from './View3D';
+
+type Listen<Self> = (event: string | symbol, fn: (...args: any[]) => void, context?: any) => Self;
+
+/**
+ * Base class for 3D entities: a `Container3D` with the Caper lifecycle (`added` / `removed` / `update`),
+ * signals, and its own 3D factory. Declare one like any entity (`defineEntity` + default export under
+ * `src/entities/`) and build it with `view.add.entity(id, props)`.
+ *
+ * Build parts in `added()`, not in the constructor: `this.add` / `this.make` belong to the view the entity is
+ * in, so they work once it has been added to one. Parts are parented to the entity; the resources they
+ * create are freed with the view, and model animations are driven by the view.
+ * Adding a pointer listener makes a passive entity interactive so it hears taps on its parts.
+ */
+export class Entity3D<Props = void> extends WithLifecycle(WithSignals(Container3D)) {
+  readonly props: Props;
+  private factories?: { owned: Owned3D; add: Factory3D; make: Factory3D };
+
+  constructor(props?: Props) {
+    super();
+    this.props = (props ?? {}) as Props;
+    bindAllMethods(this);
+    this._initLifecycle({ autoResize: false, autoUpdate: true });
+  }
+
+  // Fields, not methods, so `entity.on('pointertap', (e) => ...)` keeps upstream's per-event typing.
+  override on: Container3D['on'] & Listen<this> = ((event: string | symbol, fn: (...args: any[]) => void, context?: any) => {
+    this.enablePointerEvents(event);
+    return super.on(event, fn, context);
+  }) as Container3D['on'] & Listen<this>;
+
+  override once: Container3D['once'] & Listen<this> = ((event: string | symbol, fn: (...args: any[]) => void, context?: any) => {
+    this.enablePointerEvents(event);
+    return super.once(event, fn, context);
+  }) as Container3D['once'] & Listen<this>;
+
+  /** Listening is the opt-in: a passive ancestor is skipped when a part's event bubbles. */
+  private enablePointerEvents(event: string | symbol): void {
+    if (typeof event === 'string' && /^(global)?(pointer|mouse|touch)|^(click|tap|wheel|right|contextmenu)/.test(event) && this.eventMode === 'passive') {
+      this.eventMode = 'static';
+    }
+  }
+
+  get add(): Factory3D {
+    return this.resolveFactories().add;
+  }
+
+  get make(): Factory3D {
+    return this.resolveFactories().make;
+  }
+
+  private resolveFactories(): { add: Factory3D; make: Factory3D } {
+    const owned = this.view3d && ownedByView.get(this.view3d);
+    if (!owned) {
+      throw new Error(
+        'This Entity3D is not in a View3D yet. Build its parts in added(), after view.add.entity(...) or view.add.existing(entity).',
+      );
+    }
+    // Rebuilt only if the entity moved to another view.
+    if (this.factories?.owned !== owned) {
+      const view = this.view3d as View3D;
+      this.factories = { owned, add: createFactory3D(this, owned, true, view), make: createFactory3D(this, owned, false, view) };
+    }
+    return this.factories;
+  }
+}

package/src/Model.ts

@@ -0,0 +1,73 @@
+import { Model3D } from '@pixi/3d';
+import type { AnimationState } from '@pixi/3d';
+import type { Ticker } from 'pixi.js';
+
+export type PlayOptions = Partial<Pick<AnimationState, 'loop' | 'animationSpeed' | 'weight' | 'onComplete' | 'onLoop'>> & {
+  fade?: number;
+  layer?: boolean;
+};
+
+type Fade = { elapsed: number; duration: number; incoming: AnimationState; weight: number; outgoing: { state: AnimationState; weight: number }[] };
+
+export class Model extends Model3D {
+  private transition?: Fade;
+
+  play(name: string, options: PlayOptions = {}): AnimationState {
+    const player = this.player;
+    if (!player || !player.animationLabels.includes(name)) {
+      throw new Error(
+        `Animation '${name}' is unavailable; available clips: ${player?.animationLabels.join(', ') || '(none)'}.`,
+      );
+    }
+    const state = player.getState(name);
+    const running = this.transition;
+    if (options.layer) {
+      // A fade under way carries on; it just lets go of this clip if it was fading it out.
+      if (running) running.outgoing = running.outgoing.filter((old) => old.state !== state);
+    } else {
+      // A fade under way ends here: its outgoing clips stop at once.
+      for (const { state: old } of running?.outgoing ?? []) {
+        old.onComplete = old.onLoop = null;
+        old.stop();
+      }
+      this.transition = undefined;
+    }
+    const outgoing = options.layer ? [] : player.animationLabels
+      .map((label) => player.getState(label))
+      .filter((other) => other !== state && other.playing);
+    for (const other of outgoing) other.onComplete = other.onLoop = null;
+    const { fade = 0, layer: _layer, ...stateOptions } = options;
+    Object.assign(state, { loop: true, animationSpeed: 1, weight: 1, onComplete: null, onLoop: null }, stateOptions);
+    if (fade > 0 && outgoing.length) {
+      this.transition = {
+        elapsed: 0, duration: fade, incoming: state, weight: state.weight,
+        outgoing: outgoing.map((other) => ({ state: other, weight: other.weight })),
+      };
+      state.weight = 0;
+    } else {
+      for (const other of outgoing) other.stop();
+    }
+    state.gotoAndPlay(0);
+    return state;
+  }
+
+  stop(): void {
+    this.transition = undefined;
+    this.player?.stop();
+  }
+
+  update(ticker: Ticker): void {
+    const fade = this.transition;
+    if (fade) {
+      fade.elapsed = Math.min(fade.duration, fade.elapsed + ticker.deltaMS / 1000);
+      const progress = fade.elapsed / fade.duration;
+      fade.incoming.weight = fade.weight * progress;
+      for (const { state, weight } of fade.outgoing) {
+        state.weight = weight * (1 - progress);
+        if (progress === 1) state.stop();
+      }
+      if (progress === 1) this.transition = undefined;
+    }
+    this.player?.update(ticker);
+  }
+}

package/src/Plugin3D.ts

@@ -0,0 +1,35 @@
+import { Plugin, registerFactoryMethods } from '@caperjs/core';
+import type { IApplication, IPlugin } from '@caperjs/core';
+import { View3D } from './View3D';
+import type { View3DProps } from './View3D';
+import type { Quality3D } from './quality';
+import { assertRenderer3D } from './renderer';
+
+export interface Plugin3DOptions {
+  quality: Quality3D;
+}
+export interface IPlugin3D extends IPlugin<Plugin3DOptions> {}
+
+declare module '@caperjs/core' {
+  interface FactoryMethodOverrides {
+    view3d: (props?: View3DProps) => View3D;
+  }
+}
+
+// One stable function, so a re-run `initialize` registers the same method again (a no-op) instead of colliding.
+const view3d = (props?: View3DProps) => new View3D(props);
+
+export class Plugin3D extends Plugin<Plugin3DOptions> implements IPlugin3D {
+  id = '3d';
+
+  initialize(options: Partial<Plugin3DOptions> = {}): void {
+    this._options = { quality: 'auto', ...options };
+    this.addDisposer(registerFactoryMethods({ view3d }));
+  }
+
+  postInitialize(app: IApplication): void {
+    assertRenderer3D(app.renderer);
+  }
+}
+
+export default Plugin3D;

package/src/View3D.ts

@@ -0,0 +1,173 @@
+import { Camera3D, Container3D, Vector3, View3D as PixiView3D } from '@pixi/3d';
+import type { View3DOptions } from '@pixi/3d';
+import { Application, bindAllMethods, isMobile, WithLifecycle, WithSignals } from '@caperjs/core';
+import type { Size } from '@caperjs/core';
+import { Point, type Container, type Ticker } from 'pixi.js';
+import { fitFov } from './fit';
+import { createFactory3D } from './factory3d';
+import type { Factory3D } from './factory3d';
+import { Owned3D, ownedByView } from './owned';
+import type { Vec3 } from './props';
+import { toVec3 } from './props';
+import type { IPlugin3D } from './Plugin3D';
+import { resolveQuality } from './quality';
+import { assertRenderer3D } from './renderer';
+
+type CameraProps = {
+  position?: Vec3;
+  lookAt?: Vec3;
+  /** Vertical field of view in degrees. */
+  fov?: number;
+  near?: number;
+  far?: number;
+  /**
+   * The aspect ratio (width / height) the scene is framed for, e.g. `16 / 9`. On a narrower view (a phone
+   * held upright) the field of view grows so the sides stay in frame. Leave it out to keep `fov` fixed.
+   */
+  fitAspect?: number;
+};
+
+export interface View3DProps extends Omit<View3DOptions, 'camera'> {
+  camera?: Camera3D | CameraProps;
+  interactive?: boolean;
+}
+
+/** Something an add-on attaches to a view. The view drives it; games never call these. */
+export interface View3DPart {
+  /** Every frame the view updates (on app.ticker), after model clips. */
+  update?(ticker: Ticker): void;
+  /** Once when owned with the current size, then on every view resize. */
+  resize?(size: Size): void;
+  /** Before the view frees its nodes and resources, while the view is still usable. */
+  destroy(): void;
+}
+
+const world = new Vector3();
+const screen = new Point();
+type Point3 = ReturnType<typeof toVec3>;
+type Pin = { target: Container3D | Point3; offset: Point3 };
+
+export class View3D extends WithLifecycle(WithSignals(PixiView3D)) {
+  readonly add: Factory3D;
+  readonly make: Factory3D;
+  private readonly owned = new Owned3D();
+  private readonly parts = new Set<View3DPart>();
+  private readonly pins = new Map<Container, Pin>();
+  private readonly fillsScreen: boolean;
+  private readonly fit?: { fov: number; aspect: number };
+
+  constructor(props: View3DProps = {}) {
+    const app = Application.getInstance();
+    assertRenderer3D(app.renderer);
+    const plugin = app.getPlugin<IPlugin3D>('3d');
+    const { camera, interactive = true, ...viewProps } = props;
+    const fillsScreen = props.width === undefined && props.height === undefined;
+    const quality = resolveQuality(plugin?.options.quality ?? 'auto', {
+      isMobile,
+      resolution: app.renderer.resolution,
+    });
+    super({
+      ...quality,
+      environment: { skyColor: 0xbcd4f0, groundColor: 0x6b6250, intensity: 0.7 },
+      autoResize: fillsScreen,
+      // 'static' picks 3D and takes taps over the whole view; 'none' lets them reach 2D behind it.
+      // Never 'passive': it turns picking off and still blocks.
+      eventMode: interactive ? 'static' : 'none',
+      ...viewProps,
+      ...(camera instanceof Camera3D ? { camera } : {}),
+    });
+    this.fillsScreen = fillsScreen;
+    ownedByView.set(this, this.owned);
+    bindAllMethods(this);
+    this._initLifecycle({ autoResize: true, autoUpdate: true });
+    if (!(camera instanceof Camera3D)) {
+      this.camera.position = toVec3(camera?.position ?? [0, 1.5, 4]);
+      this.camera.lookAt(toVec3(camera?.lookAt ?? [0, 0, 0]));
+      if (camera?.fov !== undefined) this.camera.fov = camera.fov;
+      if (camera?.near !== undefined) this.camera.near = camera.near;
+      if (camera?.far !== undefined) this.camera.far = camera.far;
+      if (camera?.fitAspect) this.fit = { fov: this.camera.fov, aspect: camera.fitAspect };
+    }
+    this.add = createFactory3D(this.root, this.owned, true, this);
+    this.make = createFactory3D(this.root, this.owned, false, this);
+    this.fitCamera();
+  }
+
+  /** For add-ons: the view updates `part` every frame, tells it about resizes, and destroys it with itself. */
+  own<T extends View3DPart>(part: T): T {
+    this.parts.add(part);
+    part.resize?.(this.viewSize);
+    return part;
+  }
+
+  /** Keeps a 2D node over a 3D point, hidden while the point is behind the camera. Returns the function that unpins it. */
+  pin(node: Container, target: Container3D | Vec3, options: { offset?: Vec3 } = {}): () => void {
+    const pin: Pin = { target: target instanceof Container3D ? target : toVec3(target), offset: toVec3(options.offset ?? [0, 0, 0]) };
+    this.pins.set(node, pin);
+    // A pin hides its node behind the camera, so a pin that ends shows it again.
+    return () => {
+      if (this.pins.get(node) !== pin) return;
+      this.pins.delete(node);
+      node.visible = true;
+    };
+  }
+
+  added(): void {
+    this.resize();
+  }
+
+  resize(_size?: Size): void {
+    this.placeFullScreen();
+    this.fitCamera();
+    for (const part of this.parts) part.resize?.(this.viewSize);
+  }
+
+  update(_ticker?: Ticker | number): void {
+    this.owned.update(this.app.ticker);
+    for (const part of this.parts) part.update?.(this.app.ticker);
+    this.placePins();
+  }
+
+  private placePins(): void {
+    for (const [node, { target, offset }] of this.pins) {
+      const node3d = target instanceof Container3D ? target : null;
+      if (node.destroyed || node3d?.destroyed) {
+        this.pins.delete(node);
+        if (!node.destroyed) node.visible = true;
+        continue;
+      }
+      const at = node3d ? node3d.getGlobalPosition(world) : (target as Point3);
+      world.set(at.x + offset.x, at.y + offset.y, at.z + offset.z);
+      // null: the point is at or behind the camera.
+      const point = this.worldToScreen(world, screen);
+      node.visible = point !== null;
+      if (!point) continue;
+      if (node.parent) node.parent.toLocal(point, undefined, node.position);
+      else node.position.copyFrom(point);
+    }
+  }
+
+  destroy(_options?: Parameters<PixiView3D['destroy']>[0] | boolean): void {
+    this.pins.clear();
+    for (const part of this.parts) part.destroy();
+    this.parts.clear();
+    // glTF sources share materials; destroying them crashes the next visit.
+    super.destroy({ children: true });
+    this.owned.destroy();
+  }
+
+  private fitCamera(): void {
+    if (!this.fit) return;
+    const { width, height } = this.viewSize;
+    this.camera.fov = fitFov(this.fit.fov, width / height, this.fit.aspect);
+  }
+
+  private get viewSize(): Size {
+    const size = this.fillsScreen ? this.app.size : this;
+    return { width: size.width, height: size.height };
+  }
+
+  private placeFullScreen(): void {
+    if (this.fillsScreen) this.position.set(-this.app.size.width / 2, -this.app.size.height / 2);
+  }
+}

package/src/factory3d.ts

@@ -0,0 +1,188 @@
+import {
+  AmbientLight,
+  Camera3D,
+  Container3D,
+  CubeGeometry,
+  CylinderGeometry,
+  DirectionalLight,
+  Material3D,
+  Mesh3D,
+  PlaneGeometry,
+  PointLight,
+  SphereGeometry,
+  SpotLight,
+} from '@pixi/3d';
+import type { Geometry3D, Light, Scene3DSource } from '@pixi/3d';
+import { Assets } from 'pixi.js';
+import { getEntityCtor, getRegisteredEntityIds } from '@caperjs/core';
+import { Model } from './Model';
+import { Owned3D } from './owned';
+import type {
+  Camera3DProps,
+  Entity3DId,
+  Entity3DInstance,
+  Entity3DNodeProps,
+  Entity3DProps,
+  Light3DProps,
+  Material3DProps,
+  Mesh3DProps,
+  Model3DProps,
+  Node3DProps,
+} from './props';
+import { resolveNodeOptions, toVec3 } from './props';
+import type { View3D } from './View3D';
+
+/** Add-on methods on every 3D factory. Augment with the call-site shape:
+ * declare module '@caperjs/plugin-3d' { interface Factory3DOverrides { cameraRig: (props?: P) => CameraRig } } */
+export interface Factory3DOverrides {}
+
+/** Registered methods receive the view before their call-site arguments. */
+export type Factory3DMethods = {
+  [K in keyof Factory3DOverrides]: Factory3DOverrides[K] extends (...args: infer A) => infer R
+    ? (view: View3D, ...args: A) => R : never;
+};
+
+interface BuiltInFactory3D {
+  container(props?: Node3DProps): Container3D;
+  mesh(props?: Mesh3DProps): Mesh3D;
+  /** A material owned by the view: freed with it. Pass it to many meshes. A material has no parent, so add.material and make.material are the same. */
+  material(props?: Material3DProps): Material3D;
+  entity<K extends Entity3DId>(id: K, props?: Entity3DProps<K> & Entity3DNodeProps): Entity3DInstance<K>;
+  model(props: Model3DProps): Model;
+  light(props?: Light3DProps): Light;
+  camera(props?: Camera3DProps): Camera3D;
+  existing<T extends Container3D>(node: T, props?: Node3DProps): T;
+}
+
+export interface Factory3D extends BuiltInFactory3D, Factory3DOverrides {}
+
+const BUILT_IN_METHODS = {
+  container: true, mesh: true, material: true, entity: true,
+  model: true, light: true, camera: true, existing: true,
+} satisfies Record<keyof BuiltInFactory3D, true>;
+const registered = new Map<string, (...args: any[]) => any>();
+
+/** Register methods for factories built afterwards. Register before creating views: a view builds its
+ * factories in its constructor, and an entity builds them on first add/make use. A disposer only affects
+ * future factories. Registered methods have the same behavior on add and make; neither parents their result.
+ */
+export function registerFactory3DMethods(methods: Partial<Factory3DMethods>): () => void {
+  const entries = Object.entries(methods) as Array<[string, (...args: any[]) => any]>;
+  for (const [name, method] of entries) {
+    if (Object.hasOwn(BUILT_IN_METHODS, name)) {
+      throw new Error(`[caper] registerFactory3DMethods: "${name}" is a built-in 3D factory method and cannot be replaced. Pick another name.`);
+    }
+    if (typeof method !== 'function') {
+      throw new Error(`[caper] registerFactory3DMethods: "${name}" must be a function.`);
+    }
+    const previous = registered.get(name);
+    if (previous && previous !== method) {
+      throw new Error(`[caper] registerFactory3DMethods: "${name}" is already registered (by function "${previous.name || 'anonymous'}"); cannot register function "${method.name || 'anonymous'}" under the same name.`);
+    }
+  }
+  const added = entries.filter(([name]) => !registered.has(name));
+  for (const [name, method] of added) registered.set(name, method);
+  return () => {
+    for (const [name, method] of added) {
+      if (registered.get(name) === method) registered.delete(name);
+    }
+  };
+}
+
+const BUILT_IN_GEOMETRY = {
+  box: () => new CubeGeometry(),
+  cylinder: () => new CylinderGeometry({ radiusTop: 0.5, radiusBottom: 0.5, height: 1 }),
+  plane: () => new PlaneGeometry(),
+  sphere: () => new SphereGeometry({ radius: 0.5 }),
+};
+
+const ENTITY_PLACEMENT = ['position', 'rotation', 'scale', 'x', 'y', 'z', 'visible', 'lookAt', 'parent'] as const;
+
+const LIGHTS = { directional: DirectionalLight, point: PointLight, spot: SpotLight, ambient: AmbientLight };
+
+export function createFactory3D(root: Container3D, owned: Owned3D, parent: boolean, view: View3D): Factory3D {
+  const options = <T extends Node3DProps>(props: T) => {
+    const resolved = resolveNodeOptions(props);
+    return parent && !resolved.parent ? { ...resolved, parent: root } : resolved;
+  };
+  const finish = <T extends Container3D>(node: T, props: Node3DProps): T => {
+    if (props.lookAt) node.lookAt(toVec3(props.lookAt));
+    return node;
+  };
+  const existing = <T extends Container3D>(node: T, props: Node3DProps = {}): T => {
+    const { parent: to = root, ...rest } = resolveNodeOptions(props);
+    Object.assign(node, rest);
+    if (parent) to.addChild(node);
+    // After parenting: lookAt aims in world space.
+    return finish(node, props);
+  };
+
+  const builtIns: BuiltInFactory3D = {
+    container(props = {}) {
+      return finish(new Container3D(options(props)), props);
+    },
+    material(props = {}) {
+      const { color, ...options } = props;
+      return owned.material(new Material3D(color === undefined ? options : { baseColor: color, ...options }));
+    },
+    entity(id, props) {
+      const Ctor = getEntityCtor(id);
+      if (!Ctor) {
+        const known = getRegisteredEntityIds();
+        throw new Error(
+          `Unknown entity id '${id}'. Known: ${known.length ? known.map((key) => `'${key}'`).join(', ') : '(none)'}`,
+        );
+      }
+      if (!(Ctor.prototype instanceof Container3D)) {
+        throw new Error(
+          `Entity '${id}' is not a 3D entity (its class does not extend Container3D). Use this.add.entity for 2D entities.`,
+        );
+      }
+      const node = new (Ctor as new (props?: unknown) => Container3D)(props);
+      // Only placement is applied to the node; every other prop is the entity's own.
+      const placement: Entity3DNodeProps = Object.fromEntries(
+        ENTITY_PLACEMENT.filter((key) => props && key in props).map((key) => [key, props![key]]),
+      );
+      return existing(node, placement) as Entity3DInstance<typeof id>;
+    },
+    mesh(props = {}) {
+      const { geometry = 'box', material, color, roughness, metallic, ...nodeProps } = props;
+      let actualGeometry: Geometry3D;
+      if (typeof geometry !== 'string') actualGeometry = geometry;
+      else if (geometry in BUILT_IN_GEOMETRY) actualGeometry = owned.geometry(geometry, BUILT_IN_GEOMETRY[geometry]);
+      else throw new Error(`Unknown 3D geometry '${geometry}'. Use box, plane, sphere, or cylinder.`);
+      const actualMaterial = material ?? owned.material(new Material3D({
+        baseColor: color ?? 0xffffff,
+        ...(roughness !== undefined && { roughness }),
+        ...(metallic !== undefined && { metallic }),
+      }));
+      return finish(new Mesh3D({ ...options(nodeProps), geometry: actualGeometry, material: actualMaterial }), props);
+    },
+    model(props) {
+      const { asset, ...nodeProps } = props;
+      const source = typeof asset === 'string' ? Assets.get<Scene3DSource>(asset) : asset;
+      if (!source)
+        throw new Error(`Model asset '${asset}' is not loaded. Add its bundle to the scene's assets.preload.`);
+      const model = finish(new Model({ ...options(nodeProps), source, autoUpdate: false }), props);
+      if (model.player) owned.player(model);
+      return model;
+    },
+    light(props = {}) {
+      const { type = 'directional', ...nodeProps } = props;
+      const lightOptions = options(nodeProps);
+      if (type === 'directional' && !props.rotation && !props.quaternion && !props.lookAt) {
+        lightOptions.rotation = { x: -Math.PI / 4, y: Math.PI / 6, z: 0 };
+      }
+      const light = new LIGHTS[type](lightOptions);
+      return finish(light, props);
+    },
+    camera(props = {}) {
+      return finish(new Camera3D(options(props)), props);
+    },
+    existing,
+  };
+  const bound = Object.fromEntries(
+    [...registered].map(([name, method]) => [name, (...args: any[]) => method(view, ...args)]),
+  );
+  return Object.assign(builtIns, bound) as Factory3D;
+}

package/src/fit.ts

@@ -0,0 +1,10 @@
+/**
+ * The vertical field of view (degrees) that keeps everything a `fitAspect` screen would show in frame.
+ * Screens at least as wide as `fitAspect` keep `fov`; narrower ones (portrait) get a taller field of view,
+ * so the sides are not cropped. Without `fitAspect` the answer is always `fov`.
+ */
+export function fitFov(fov: number, aspect: number, fitAspect?: number): number {
+  if (!fitAspect || !(aspect > 0) || aspect >= fitAspect) return fov;
+  const halfTan = Math.tan((fov * Math.PI) / 360);
+  return (2 * Math.atan((halfTan * fitAspect) / aspect) * 180) / Math.PI;
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export { default, Plugin3D } from './Plugin3D';
+export type { IPlugin3D, Plugin3DOptions } from './Plugin3D';
+export { View3D } from './View3D';
+export { Entity3D } from './Entity3D';
+export type { View3DProps, View3DPart } from './View3D';
+export { Model } from './Model';
+export type { PlayOptions } from './Model';
+export { registerFactory3DMethods } from './factory3d';
+export type { Factory3D, Factory3DOverrides, Factory3DMethods } from './factory3d';
+export { fitFov } from './fit';
+export type { Node3DProps, Mesh3DProps, Model3DProps, ModelAsset, Light3DProps, Camera3DProps, Vec3 } from './props';
+export type { Entity3DId, Entity3DNodeProps, Material3DProps } from './props';
+export type { Quality3D } from './quality';