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

package/src/owned.ts

@@ -0,0 +1,42 @@
+import type { Ticker } from 'pixi.js';
+
+type Resource = { destroy(): void };
+type Player = { destroyed: boolean; update(ticker: Ticker): void };
+
+export const ownedByView = new WeakMap<object, Owned3D>();
+
+export class Owned3D {
+  private readonly geometries = new Map<string, Resource>();
+  private readonly materials = new Set<Resource>();
+  private readonly players = new Set<Player>();
+
+  /** One geometry per kind per view: bounded, and meshes that share a geometry can batch. */
+  geometry<T extends Resource>(kind: string, build: () => T): T {
+    if (!this.geometries.has(kind)) this.geometries.set(kind, build());
+    return this.geometries.get(kind) as T;
+  }
+
+  material<T extends Resource>(material: T): T {
+    this.materials.add(material);
+    return material;
+  }
+
+  player<T extends Player>(player: T): T {
+    this.players.add(player);
+    return player;
+  }
+
+  update(ticker: Ticker): void {
+    for (const player of this.players) {
+      if (player.destroyed) this.players.delete(player);
+      else player.update(ticker);
+    }
+  }
+
+  destroy(): void {
+    for (const resource of [...this.geometries.values(), ...this.materials]) resource.destroy();
+    this.geometries.clear();
+    this.materials.clear();
+    this.players.clear();
+  }
+}

package/src/props.ts

@@ -0,0 +1,96 @@
+import type {
+  AmbientLightOptions,
+  Camera3DOptions,
+  Container3D,
+  Container3DOptions,
+  DirectionalLightOptions,
+  Geometry3D,
+  Material3DOptions,
+  Mesh3DOptions as PixiMesh3DOptions,
+  Model3DOptions as PixiModel3DOptions,
+  PointLightOptions,
+  Scene3DSource,
+  SpotLightOptions,
+} from '@pixi/3d';
+import type { BaseMaterial3D } from '@pixi/3d';
+import type { AppTypeOverrides, AssetTypeOverrides } from '@caperjs/core';
+
+export type Vec3 = [number, number, number] | { x: number; y: number; z: number };
+
+export type Node3DProps = Omit<Container3DOptions, 'position' | 'rotation' | 'scale'> & {
+  position?: Vec3;
+  rotation?: Vec3;
+  scale?: Vec3 | number;
+  lookAt?: Vec3;
+};
+
+export type Material3DProps = Material3DOptions & { /** Shorthand for `baseColor`. */ color?: number };
+
+type EntityClasses = AppTypeOverrides extends { EntityClasses: infer E } ? E : {};
+type Entity3DCtor = abstract new (...args: any[]) => Container3D;
+/** Ids of discovered entities whose class extends `Container3D` (usually through `Entity3D`). */
+export type Entity3DId = {
+  [K in keyof EntityClasses]: EntityClasses[K] extends Entity3DCtor ? K : never;
+}[keyof EntityClasses] & string;
+type OwnProps<C extends Entity3DCtor> = Exclude<ConstructorParameters<C>[0], void | undefined>;
+/** The entity's own constructor props; `{}` for a class that takes none (`Entity3D` with no `Props`). */
+export type Entity3DProps<K extends Entity3DId> = EntityClasses[K] extends Entity3DCtor
+  ? [OwnProps<EntityClasses[K]>] extends [never]
+    ? {}
+    : OwnProps<EntityClasses[K]>
+  : never;
+export type Entity3DInstance<K extends Entity3DId> = EntityClasses[K] extends Entity3DCtor
+  ? InstanceType<EntityClasses[K]>
+  : never;
+/** Placement props `view.add.entity` applies to the new entity; everything else is the entity's own. */
+export type Entity3DNodeProps = Pick<
+  Node3DProps,
+  'position' | 'rotation' | 'scale' | 'x' | 'y' | 'z' | 'visible' | 'lookAt' | 'parent'
+>;
+
+export type Mesh3DProps = Omit<PixiMesh3DOptions, keyof Node3DProps | 'geometry' | 'material'> &
+  Node3DProps & {
+    geometry?: 'box' | 'plane' | 'sphere' | 'cylinder' | Geometry3D;
+    material?: BaseMaterial3D;
+    color?: number;
+    roughness?: number;
+    metallic?: number;
+  };
+
+/**
+ * A model's manifest name. Once the app's generated `caper-assets.d.ts` lists models (any `.glb` in the assets
+ * folder), this is that union, so unknown names are type errors; until then it is `string`. A model loaded by
+ * hand is passed as its `Scene3DSource`.
+ */
+// Known names autocomplete; any other string is still allowed, the same as texture and spritesheet names.
+export type ModelAsset = AssetTypeOverrides extends { Model: infer Name extends string }
+  ? Name | (string & {})
+  : string;
+
+export type Model3DProps = Omit<PixiModel3DOptions, keyof Node3DProps | 'source'> &
+  Node3DProps & { asset: ModelAsset | Scene3DSource };
+
+export type Light3DProps = Omit<
+  DirectionalLightOptions & PointLightOptions & SpotLightOptions & AmbientLightOptions,
+  keyof Node3DProps
+> &
+  Node3DProps & { type?: 'directional' | 'point' | 'spot' | 'ambient' };
+
+export type Camera3DProps = Omit<Camera3DOptions, keyof Node3DProps> & Node3DProps;
+
+export function toVec3(value: Vec3): { x: number; y: number; z: number } {
+  return Array.isArray(value) ? { x: value[0], y: value[1], z: value[2] } : value;
+}
+
+export function resolveNodeOptions<T extends Node3DProps>(
+  props: T,
+): Omit<T, 'lookAt' | 'position' | 'rotation' | 'scale'> & Pick<Container3DOptions, 'position' | 'rotation' | 'scale'> {
+  const options: Record<string, unknown> = { ...props };
+  delete options.lookAt;
+  for (const key of ['position', 'rotation', 'scale'] as const) {
+    const value = options[key];
+    if (Array.isArray(value)) options[key] = toVec3(value as Vec3);
+  }
+  return options as Omit<T, 'lookAt' | 'position' | 'rotation' | 'scale'> &
+    Pick<Container3DOptions, 'position' | 'rotation' | 'scale'>;
+}

package/src/quality.ts

@@ -0,0 +1,12 @@
+export type Quality3D = 'auto' | 'low' | 'high';
+
+export function resolveQuality(
+  quality: Quality3D,
+  device: { isMobile: boolean; resolution: number },
+): { shadowQuality: 'low' | 'medium' | 'high'; resolution: number | 'inherit' } {
+  if (quality === 'high') return { shadowQuality: 'high', resolution: 'inherit' };
+  if (quality === 'low') return { shadowQuality: 'low', resolution: Math.min(device.resolution, 1) };
+  return device.isMobile
+    ? { shadowQuality: 'low', resolution: Math.min(device.resolution, 2) }
+    : { shadowQuality: 'medium', resolution: 'inherit' };
+}

package/src/renderer.ts

@@ -0,0 +1,22 @@
+type Renderer3D = {
+  name?: string;
+  gl?: { texImage3D?: unknown };
+  context?: { gl?: { texImage3D?: unknown } };
+  lighting3d?: unknown;
+};
+
+export function assertRenderer3D(value: unknown): void {
+  const renderer = value as Renderer3D | null | undefined;
+  if (!renderer)
+    throw new Error('[@caperjs/plugin-3d] No renderer is available. Create the renderer before a 3D view.');
+  if (renderer.name === 'canvas')
+    throw new Error('[@caperjs/plugin-3d] Canvas renderer cannot draw 3D. Use WebGL2 or WebGPU.');
+  if (renderer.name === 'webgl' && typeof (renderer.gl ?? renderer.context?.gl)?.texImage3D !== 'function') {
+    throw new Error('[@caperjs/plugin-3d] WebGL2 is required; this renderer is using WebGL1.');
+  }
+  if (!renderer.lighting3d) {
+    throw new Error(
+      "[@caperjs/plugin-3d] @pixi/3d was loaded after the renderer was created. Add '3d' to plugins in caper.config.ts and do not mark it autoLoad: false.",
+    );
+  }
+}

package/src/version.ts

@@ -0,0 +1 @@
+export const version = '0.8.0';