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

package/README.md

@@ -1,3 +1,191 @@
-# Temporary Holding Version
+# @caperjs/plugin-3d
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Experimental** — `@pixi/3d` is in open beta; this package pins an exact version and the API
+we expose may change until upstream stabilizes.
+
+Official 3D for [Caper](https://github.com/anthonysapp/caper) games, built on Pixi's
+[`@pixi/3d`](https://pixijs.com/3d). A `View3D` is a normal node on the 2D stage; lights,
+models, and meshes live in a separate tree inside it. Interactive 2D UI you add **after** the
+view draws on top and receives taps first.
+
+## Install
+
+```bash
+npx caper add 3d
+```
+
+Then `npx caper doctor`. The command:
+
+- Installs `@caperjs/plugin-3d`, `@pixi/3d` at the pin this package expects, and `pixi.js` only if
+  yours is older than the version Caper pins; announces packages and the install command before running it.
+- Adds `'3d'` to `plugins` in `caper.config.ts` (or prints the line if there is no `plugins` array).
+- Creates `src/scenes/Sample3DScene.ts` when missing (never overwrites).
+- On pnpm ≥ 10.16, may add `@pixi/3d` to `minimumReleaseAgeExclude` in `pnpm-workspace.yaml`.
+
+### By hand
+
+```bash
+pnpm add @caperjs/plugin-3d @pixi/3d@0.1.0
+```
+
+Peers: `@caperjs/core` (requires `pixi.js@8.23.0`), `pixi.js`, `@pixi/3d@0.1.0` (exact). Add `'3d'`
+to `plugins` in `caper.config.ts`. On **pnpm 11**, you may need
+`minimumReleaseAgeExclude: ['@pixi/3d@0.1.0']` in `pnpm-workspace.yaml`; `caper add 3d` adds it when
+needed.
+
+## Use
+
+```ts
+// caper.config.ts
+export default defineConfig({
+  plugins: [
+    '3d',
+    // or, with options:
+    // ['3d', { options: { quality: 'low' } }],
+  ],
+});
+```
+
+```ts
+// any Scene
+const view = this.add.view3d({
+  camera: { position: [0, 1.5, 4], lookAt: [0, 0, 0] },
+});
+const hero = view.add.model({ asset: 'robot', y: 0 });
+view.add.light({ type: 'directional', intensity: 2, castShadow: true });
+const cube = view.add.mesh({ geometry: 'box', color: 0xe85d5d, x: -1 });
+hero.play('Walking');
+```
+
+Put self-contained `.glb` files in your assets folder (AssetPack pass-through). v1 supports
+**.glb only** — multi-file `.gltf` and `.hdr` are not tested.
+
+## Animation
+
+`model.play(name, options?)` replaces whatever is playing and restarts the clip from the start
+(unlike 0.7, which layered by default). Use `layer: true` to blend on purpose. Options
+(`loop`, `fade`, `onComplete`, …) do not carry over to the next call. A replaced clip does not run
+its previous `onComplete`.
+
+```ts
+model.play('Walking');
+model.play('Wave', { loop: false, fade: 0.2, onComplete: () => model.play('Walking') });
+```
+
+## Entities
+
+Declare a 3D game object the way you declare any Caper entity, on the `Entity3D` base class.
+Scaffold with `npx caper add entity <Name> --3d`.
+
+```ts
+// src/entities/Car.ts
+import { defineEntity } from '@caperjs/core';
+import { Entity3D } from '@caperjs/plugin-3d';
+
+export const entity = defineEntity({ id: 'car' });
+
+export default class Car extends Entity3D<{ color?: number }> {
+  added() {
+    // this.add / this.make are the 3D factory, parented to the entity
+    this.add.mesh({ geometry: 'box', color: this.props.color ?? 0xd9534f, scale: [2, 0.6, 1] });
+  }
+  update() {
+    this.rotation.y += 0.02 * this.app.ticker.deltaTime;
+  }
+}
+```
+
+```ts
+const car = view.add.entity('car', { color: 0x4a90d9, x: -2, y: 0.3 });
+```
+
+- `id`, props and the returned instance are typed from the class. Only ids whose class extends
+  `Container3D` are accepted; `this.add.entity('car')` on a 2D container is a type error.
+- `view.add.entity` applies the placement props (`position`, `rotation`, `scale`, `x` / `y` / `z`,
+  `visible`, `lookAt`, `parent`); the rest are the entity's own, on `this.props`.
+- Build parts in `added()`, not in the constructor: the entity's factory belongs to the view it is
+  in. What it creates is freed with that view, and its models' clips follow `app.ticker`.
+- `update()` runs every frame while the entity is in the scene, and stops with `app.pause()`.
+- `view.make.entity` builds without parenting; `this.add.entity(...)` inside an entity nests one.
+- `entity.on('pointertap', …)` opts the entity into picking on itself and passive parts (set
+  `eventMode = 'static'` yourself for property handlers).
+
+## Many meshes: share one material
+
+`color` gives each mesh its own material for the life of the view; materials are never shared by
+colour behind your back. For a spawner, make one material and pass it. The view frees it.
+
+```ts
+const red = view.make.material({ color: 0xd9534f, roughness: 0.6 });
+for (let i = 0; i < 200; i++) view.add.mesh({ geometry: 'box', material: red, x: i });
+```
+
+`color` is shorthand for `baseColor`; every other key is a raw `Material3D` option. Writing to
+`red` recolours every mesh that uses it. (`view.add.material` is the same function: a material has
+no parent.) A `new Material3D(...)` you build yourself also works and stays yours to destroy.
+
+## Portrait screens
+
+Optional `camera.fitAspect` on props cameras (not a raw `Camera3D`) is the width/height ratio you
+frame for (e.g. `16 / 9`). On a narrower view, vertical FOV grows so the same width stays in frame.
+
+```ts
+const view = this.add.view3d({
+  camera: { position: [0, 1.5, 4], lookAt: [0, 0, 0], fitAspect: 16 / 9 },
+});
+```
+
+## Quality
+
+Plugin option `quality: 'auto' | 'low' | 'high'` (default `'auto'`):
+
+| Value | Shadows | Resolution cap |
+| --- | --- | --- |
+| `high` | high | inherit |
+| `low` | low | capped at 1 |
+| `auto` | low on mobile, medium otherwise | cap 2 on mobile, inherit on desktop |
+
+Per-view `shadowQuality` and `resolution` props override the global default.
+
+## Interaction
+
+`interactive` on the view (default `true`):
+
+- `true` → `eventMode: 'static'`: 3D picking on; the view's rectangle captures taps, so put
+  buttons and HUD **above** the view in the 2D tree.
+- `false` → `eventMode: 'none'`: taps pass through to 2D behind the view; no 3D picking.
+
+Do not use `'passive'` on the view: it disables picking and still blocks taps to 2D behind the view.
+
+`view.pin(2dNode, target3d, { offset? })` keeps a 2D node over a 3D point (updates each frame;
+the view owns `visible` while pinned).
+
+## Boot cost
+
+Opting in loads `@pixi/3d` in the **pre-renderer** phase, before the Pixi renderer is created.
+That is required for 3D to work, but it means every app start pays roughly **~490 KB raw /
+~155 KB gzip** even if no scene uses 3D. The import pulls both WebGL and WebGPU backend
+chunks at boot. Apps without `'3d'` in `plugins` pay nothing.
+
+## Teardown
+
+Never destroy a loaded model or the view with `{ material: true }` (or blanket geometry flags
+on glTF nodes): glTF materials are shared on the cached source and the next visit crashes every
+frame. The plugin destroys only geometry and materials **it** created; models use
+`{ children: true }` only.
+
+Nodes made by a view's factory belong to that view: the built-in geometry, `color` materials and
+`make.material` materials are freed when the view is destroyed, so do not keep such a node alive past its view. A raw
+`geometry` or `material` you pass in stays yours to destroy.
+
+## Types
+
+No import needed in scenes: with `'3d'` in `plugins` and this package installed, regenerated
+`src/types/caper-app.d.ts` includes `import type {} from '@caperjs/plugin-3d'` so
+`this.add.view3d` typechecks. When AssetPack ships `.glb`/`.gltf` models, `caper-assets.d.ts`
+defines `AssetModels`; `view.add.model({ asset: '…' })` only accepts known manifest names or a
+loaded `Scene3DSource` (`asset: await Assets.load(url)`).
+
+## License
+
+MIT

package/lib/Entity3D.d.ts

@@ -0,0 +1,28 @@
+import { Container3D } from '@pixi/3d';
+import { Factory3D } from './factory3d';
+type Listen<Self> = (event: string | symbol, fn: (...args: any[]) => void, context?: any) => Self;
+declare const Entity3D_base: typeof Container3D & import('@caperjs/core').Constructor<import('@caperjs/core').ISignalContainer> & import('@caperjs/core').Constructor<import('@caperjs/core').ILifecycle>;
+/**
+ * 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 declare class Entity3D<Props = void> extends Entity3D_base {
+    readonly props: Props;
+    private factories?;
+    constructor(props?: Props);
+    on: Container3D['on'] & Listen<this>;
+    once: Container3D['once'] & Listen<this>;
+    /** Listening is the opt-in: a passive ancestor is skipped when a part's event bubbles. */
+    private enablePointerEvents;
+    get add(): Factory3D;
+    get make(): Factory3D;
+    private resolveFactories;
+}
+export {};
+//# sourceMappingURL=Entity3D.d.ts.map

package/lib/Entity3D.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Entity3D.d.ts","sourceRoot":"","sources":["../src/Entity3D.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAGvC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAK7C,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,EAAE,OAAO,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;;AAElG;;;;;;;;;GASG;AACH,qBAAa,QAAQ,CAAC,KAAK,GAAG,IAAI,CAAE,SAAQ,aAAuC;IACjF,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,OAAO,CAAC,SAAS,CAAC,CAAsD;gBAE5D,KAAK,CAAC,EAAE,KAAK;IAQhB,EAAE,EAAE,WAAW,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAGN;IAE9B,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAGR;IAEzC,0FAA0F;IAC1F,OAAO,CAAC,mBAAmB;IAM3B,IAAI,GAAG,IAAI,SAAS,CAEnB;IAED,IAAI,IAAI,IAAI,SAAS,CAEpB;IAED,OAAO,CAAC,gBAAgB;CAczB"}

package/lib/Model.d.ts

@@ -0,0 +1,13 @@
+import { Model3D, AnimationState } from '@pixi/3d';
+import { Ticker } from 'pixi.js';
+export type PlayOptions = Partial<Pick<AnimationState, 'loop' | 'animationSpeed' | 'weight' | 'onComplete' | 'onLoop'>> & {
+    fade?: number;
+    layer?: boolean;
+};
+export declare class Model extends Model3D {
+    private transition?;
+    play(name: string, options?: PlayOptions): AnimationState;
+    stop(): void;
+    update(ticker: Ticker): void;
+}
+//# sourceMappingURL=Model.d.ts.map

package/lib/Model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Model.d.ts","sourceRoot":"","sources":["../src/Model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEtC,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,gBAAgB,GAAG,QAAQ,GAAG,YAAY,GAAG,QAAQ,CAAC,CAAC,GAAG;IACxH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAIF,qBAAa,KAAM,SAAQ,OAAO;IAChC,OAAO,CAAC,UAAU,CAAC,CAAO;IAE1B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,cAAc;IAuC7D,IAAI,IAAI,IAAI;IAKZ,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;CAc7B"}

package/lib/Plugin3D.d.ts

@@ -0,0 +1,20 @@
+import { Plugin, IApplication, IPlugin } from '@caperjs/core';
+import { View3D, View3DProps } from './View3D';
+import { Quality3D } from './quality';
+export interface Plugin3DOptions {
+    quality: Quality3D;
+}
+export interface IPlugin3D extends IPlugin<Plugin3DOptions> {
+}
+declare module '@caperjs/core' {
+    interface FactoryMethodOverrides {
+        view3d: (props?: View3DProps) => View3D;
+    }
+}
+export declare class Plugin3D extends Plugin<Plugin3DOptions> implements IPlugin3D {
+    id: string;
+    initialize(options?: Partial<Plugin3DOptions>): void;
+    postInitialize(app: IApplication): void;
+}
+export default Plugin3D;
+//# sourceMappingURL=Plugin3D.d.ts.map

package/lib/Plugin3D.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Plugin3D.d.ts","sourceRoot":"","sources":["../src/Plugin3D.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAA0B,MAAM,eAAe,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAG3C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,SAAS,CAAC;CACpB;AACD,MAAM,WAAW,SAAU,SAAQ,OAAO,CAAC,eAAe,CAAC;CAAG;AAE9D,OAAO,QAAQ,eAAe,CAAC;IAC7B,UAAU,sBAAsB;QAC9B,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,WAAW,KAAK,MAAM,CAAC;KACzC;CACF;AAKD,qBAAa,QAAS,SAAQ,MAAM,CAAC,eAAe,CAAE,YAAW,SAAS;IACxE,EAAE,SAAQ;IAEV,UAAU,CAAC,OAAO,GAAE,OAAO,CAAC,eAAe,CAAM,GAAG,IAAI;IAKxD,cAAc,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;CAGxC;AAED,eAAe,QAAQ,CAAC"}

package/lib/View3D.d.ts

@@ -0,0 +1,58 @@
+import { Camera3D, Container3D, View3D as PixiView3D, View3DOptions } from '@pixi/3d';
+import { Size } from '@caperjs/core';
+import { Container, Ticker } from 'pixi.js';
+import { Factory3D } from './factory3d';
+import { Vec3 } from './props';
+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;
+}
+declare const View3D_base: (new (options?: View3DOptions<Container3D> | undefined) => PixiView3D<Container3D>) & import('@caperjs/core').Constructor<import('@caperjs/core').ISignalContainer> & import('@caperjs/core').Constructor<import('@caperjs/core').ILifecycle>;
+export declare class View3D extends View3D_base {
+    readonly add: Factory3D;
+    readonly make: Factory3D;
+    private readonly owned;
+    private readonly parts;
+    private readonly pins;
+    private readonly fillsScreen;
+    private readonly fit?;
+    constructor(props?: View3DProps);
+    /** 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;
+    /** 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;
+    added(): void;
+    resize(_size?: Size): void;
+    update(_ticker?: Ticker | number): void;
+    private placePins;
+    destroy(_options?: Parameters<PixiView3D['destroy']>[0] | boolean): void;
+    private fitCamera;
+    private get viewSize();
+    private placeFullScreen;
+}
+export {};
+//# sourceMappingURL=View3D.d.ts.map

package/lib/View3D.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"View3D.d.ts","sourceRoot":"","sources":["../src/View3D.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAW,MAAM,IAAI,UAAU,EAAE,MAAM,UAAU,CAAC;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAS,KAAK,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAG7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAMpC,KAAK,WAAW,GAAG;IACjB,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,MAAM,CAAC,EAAE,IAAI,CAAC;IACd,yCAAyC;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC;IAChE,MAAM,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;IAChC,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,0FAA0F;AAC1F,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,MAAM,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,wEAAwE;IACxE,MAAM,CAAC,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,qFAAqF;IACrF,OAAO,IAAI,IAAI,CAAC;CACjB;;AAOD,qBAAa,MAAO,SAAQ,WAAsC;IAChE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;IAC/C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6B;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;IACtC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAkC;gBAE3C,KAAK,GAAE,WAAgB;IAqCnC,6GAA6G;IAC7G,GAAG,CAAC,CAAC,SAAS,UAAU,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC;IAMrC,yHAAyH;IACzH,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,EAAE,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,IAAI,CAAA;KAAO,GAAG,MAAM,IAAI;IAW7F,KAAK,IAAI,IAAI;IAIb,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,GAAG,IAAI;IAM1B,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAMvC,OAAO,CAAC,SAAS;IAmBjB,OAAO,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,IAAI;IASxE,OAAO,CAAC,SAAS;IAMjB,OAAO,KAAK,QAAQ,GAGnB;IAED,OAAO,CAAC,eAAe;CAGxB"}