@waica/engine 0.25.0 → 0.26.0

package/dist/components/collider.d.ts

@@ -0,0 +1,89 @@
+import { Component, type ComponentSpace } from '../component.js';
+import type { Vec3Json } from '../scene-camera-3d.js';
+export type ColliderShape = 'box' | 'sphere' | 'capsule';
+export declare const COLLIDER_SHAPES: readonly ColliderShape[];
+/**
+ * The 3D scene's collision shape (ADR 0028), Rapier's model: alone on an
+ * entity it is a fixed wall or floor, created at the entity's position and
+ * rotation scaled by `entity.scale`, and moving the entity later does not
+ * move it. With a `RigidBody` beside it, it is the body that falls, bounces
+ * or walks. `sensor: true` makes it a trigger instead — it detects and never
+ * pushes — with the 2D Hitbox's `layer` and `collidesWith` semantics (ADR
+ * 0016); with the default mask (`['*']`) a sensor is not told about fixed
+ * solid colliders (the level's walls and floors), as a Hitbox never sees a
+ * Solid — a mask that names their layer still is. `size` is a box's full
+ * extents; `radius` a sphere's or capsule's; `height` a capsule's total
+ * end-to-end height, at least twice its radius; `offset` is in the entity's
+ * local frame. A Collider in a 2D scene creates nothing; one whose params
+ * Rapier cannot take creates no body and warns once (`validate_project`
+ * reports them as `invalid-collider-param`).
+ */
+export declare class Collider extends Component {
+    static componentName: string;
+    static space: ComponentSpace;
+    static params: {
+        shape: {
+            label: string;
+            options: ColliderShape[];
+        };
+        size: {
+            label: string;
+            kind: "vector3";
+        };
+        radius: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        height: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        offset: {
+            label: string;
+            kind: "vector3";
+        };
+        sensor: {
+            label: string;
+        };
+        layer: {
+            label: string;
+        };
+        collidesWith: {
+            label: string;
+            kind: "string-list";
+        };
+        friction: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        restitution: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+    };
+    shape: ColliderShape;
+    /** A box's full extents `[x, y, z]`. */
+    size: Vec3Json;
+    /** A sphere's or capsule's radius. */
+    radius: number;
+    /** A capsule's total end-to-end height. */
+    height: number;
+    /** Where the shape sits in the entity's local frame. */
+    offset: Vec3Json;
+    /** A trigger: detects overlaps, never pushes or is pushed. */
+    sensor: boolean;
+    /** One exact, case-sensitive `^[a-z][a-z0-9-]*$` membership name. */
+    layer: string;
+    /** Outgoing layer interest for `onCollide`; `'*'` means every valid layer and `[]` means none. */
+    collidesWith: string[];
+    friction: number;
+    restitution: number;
+    onReady(): void;
+    onDestroy(): void;
+}

package/dist/components/collider.js

@@ -0,0 +1,57 @@
+import { Component } from '../component.js';
+export const COLLIDER_SHAPES = ['box', 'sphere', 'capsule'];
+/**
+ * The 3D scene's collision shape (ADR 0028), Rapier's model: alone on an
+ * entity it is a fixed wall or floor, created at the entity's position and
+ * rotation scaled by `entity.scale`, and moving the entity later does not
+ * move it. With a `RigidBody` beside it, it is the body that falls, bounces
+ * or walks. `sensor: true` makes it a trigger instead — it detects and never
+ * pushes — with the 2D Hitbox's `layer` and `collidesWith` semantics (ADR
+ * 0016); with the default mask (`['*']`) a sensor is not told about fixed
+ * solid colliders (the level's walls and floors), as a Hitbox never sees a
+ * Solid — a mask that names their layer still is. `size` is a box's full
+ * extents; `radius` a sphere's or capsule's; `height` a capsule's total
+ * end-to-end height, at least twice its radius; `offset` is in the entity's
+ * local frame. A Collider in a 2D scene creates nothing; one whose params
+ * Rapier cannot take creates no body and warns once (`validate_project`
+ * reports them as `invalid-collider-param`).
+ */
+export class Collider extends Component {
+    static componentName = 'Collider';
+    static space = '3d';
+    static params = {
+        shape: { label: 'Shape', options: [...COLLIDER_SHAPES] },
+        size: { label: 'Size', kind: 'vector3' },
+        radius: { label: 'Radius', min: 0.01, step: 0.05 },
+        height: { label: 'Height', min: 0.01, step: 0.05 },
+        offset: { label: 'Offset', kind: 'vector3' },
+        sensor: { label: 'Sensor' },
+        layer: { label: 'Collision Layer' },
+        collidesWith: { label: 'Collision Mask', kind: 'string-list' },
+        friction: { label: 'Friction', min: 0, max: 1, step: 0.05 },
+        restitution: { label: 'Restitution', min: 0, max: 1, step: 0.05 },
+    };
+    shape = 'box';
+    /** A box's full extents `[x, y, z]`. */
+    size = [1, 1, 1];
+    /** A sphere's or capsule's radius. */
+    radius = 0.5;
+    /** A capsule's total end-to-end height. */
+    height = 1.8;
+    /** Where the shape sits in the entity's local frame. */
+    offset = [0, 0, 0];
+    /** A trigger: detects overlaps, never pushes or is pushed. */
+    sensor = false;
+    /** One exact, case-sensitive `^[a-z][a-z0-9-]*$` membership name. */
+    layer = 'default';
+    /** Outgoing layer interest for `onCollide`; `'*'` means every valid layer and `[]` means none. */
+    collidesWith = ['*'];
+    friction = 0.5;
+    restitution = 0;
+    onReady() {
+        this.game.physics.attach(this.entity);
+    }
+    onDestroy() {
+        this.game.physics.detach(this.entity);
+    }
+}

package/dist/components/dynamic-body.d.ts

@@ -1,11 +1,12 @@
 import { type CollisionPoint, type CollisionShape } from '../collision-shape.js';
-import { Component } from '../component.js';
+import { Component, type ComponentSpace } from '../component.js';
 /**
  * Reusable linear body: integrates its public velocity and resolves only
  * against static Solid geometry. Hitbox trigger overlaps remain independent.
  */
 export declare class DynamicBody extends Component {
     static componentName: string;
+    static space: ComponentSpace;
     static params: {
         vx: {
             label: string;

package/dist/components/dynamic-body.js

@@ -17,6 +17,7 @@ const RECOVERY_ITERATIONS = 24;
  */
 export class DynamicBody extends Component {
     static componentName = 'DynamicBody';
+    static space = '2d';
     static params = {
         vx: { label: 'x velocity', step: 0.1 },
         vy: { label: 'y velocity', step: 0.1 },

package/dist/components/hitbox.d.ts

@@ -1,4 +1,4 @@
-import { Component } from '../component.js';
+import { Component, type ComponentSpace } from '../component.js';
 import { type CollisionPoint, type CollisionShape } from '../collision-shape.js';
 /**
  * Trigger collider. A pair is tested when either Hitbox's Collision Mask
@@ -8,6 +8,7 @@ import { type CollisionPoint, type CollisionShape } from '../collision-shape.js'
  */
 export declare class Hitbox extends Component {
     static componentName: string;
+    static space: ComponentSpace;
     static params: {
         layer: {
             label: string;

package/dist/components/hitbox.js

@@ -8,6 +8,7 @@ import { resolveCollisionPoints, } from '../collision-shape.js';
  */
 export class Hitbox extends Component {
     static componentName = 'Hitbox';
+    static space = '2d';
     static params = {
         layer: { label: 'Collision Layer' },
         collidesWith: { label: 'Collision Mask', kind: 'string-list' },

package/dist/components/light.d.ts

@@ -1,4 +1,4 @@
-import { Component } from '../component.js';
+import { Component, type ComponentSpace } from '../component.js';
 import type { LightField } from '../light-field.js';
 /**
  * A source of 2D light owned by its entity (issue #78, `CONTEXT.md` Light):
@@ -10,6 +10,7 @@ import type { LightField } from '../light-field.js';
  */
 export declare class Light extends Component {
     static componentName: string;
+    static space: ComponentSpace;
     static params: {
         radius: {
             label: string;

package/dist/components/light.js

@@ -12,6 +12,7 @@ const finiteOr = (value, fallback) => (Number.isFinite(value) ? value : fallback
  */
 export class Light extends Component {
     static componentName = 'Light';
+    static space = '2d';
     static params = {
         radius: { label: 'Radius', min: 0, step: 0.25 },
         color: { label: 'Color', kind: 'color' },

package/dist/components/model.d.ts

@@ -0,0 +1,63 @@
+import * as THREE from 'three/webgpu';
+import { Component, type ComponentSpace } from '../component.js';
+export type ModelShape = 'box' | 'sphere' | 'plane';
+/**
+ * A 3D thing an entity draws (3D scenes, ADR 0027): a glTF/glb from `src`
+ * (a `waica:` uri or a project path, loaded once through `game.assets`) or a
+ * primitive `shape` of a `color` and a uniform `size`. With both, `src` wins.
+ * Its root hangs under the entity's node, so the entity's position, rotation
+ * and scale place it; the glTF keeps the materials it ships with, a
+ * primitive has a standard (lit) node material. `color` and `size` follow the
+ * inspector live; a new `src` or `shape` rebuilds the content. Destroying it
+ * removes the root and disposes only what it created — never the cached glTF.
+ * In a 2D scene it creates nothing (`validate_project` reports it).
+ */
+export declare class Model extends Component {
+    static componentName: string;
+    static space: ComponentSpace;
+    static params: {
+        src: {
+            label: string;
+            kind: "model";
+        };
+        shape: {
+            label: string;
+            options: ModelShape[];
+        };
+        color: {
+            label: string;
+            kind: "color";
+        };
+        size: {
+            label: string;
+            min: number;
+            step: number;
+        };
+    };
+    static transient: string[];
+    /** What this Model draws, under the entity's node; null until it is ready. The Pointer ray-casts against it. */
+    root: THREE.Group | null;
+    private _src;
+    private _shape;
+    private _color;
+    private _size;
+    private _primitive;
+    /** A `waica:` uri or project path to a `.glb` / `.gltf`; empty draws the primitive `shape`. */
+    get src(): string;
+    set src(value: string);
+    get shape(): ModelShape;
+    set shape(value: ModelShape);
+    /** `0xrrggbb` of a primitive. */
+    get color(): number;
+    set color(value: number);
+    /** Uniform scale of a primitive: the box side, sphere diameter or plane side in world units. */
+    get size(): number;
+    set size(value: number);
+    onReady(): void;
+    onDestroy(): void;
+    private build;
+    private buildPrimitive;
+    private rebuild;
+    /** Empties the root and disposes the primitive this Model created; a glTF's clone only leaves the graph. */
+    private clear;
+}

package/dist/components/model.js

@@ -0,0 +1,117 @@
+import * as THREE from 'three/webgpu';
+import { Component } from '../component.js';
+const SHAPES = ['box', 'sphere', 'plane'];
+/** One unit of the shape: a box of side 1, a sphere of diameter 1, a plane of side 1 lying flat on the ground (normal up). */
+function primitiveGeometry(shape) {
+    switch (shape) {
+        case 'sphere':
+            return new THREE.SphereGeometry(0.5, 32, 16);
+        case 'plane':
+            return new THREE.PlaneGeometry(1, 1).rotateX(-Math.PI / 2);
+        case 'box':
+            return new THREE.BoxGeometry(1, 1, 1);
+    }
+}
+/**
+ * A 3D thing an entity draws (3D scenes, ADR 0027): a glTF/glb from `src`
+ * (a `waica:` uri or a project path, loaded once through `game.assets`) or a
+ * primitive `shape` of a `color` and a uniform `size`. With both, `src` wins.
+ * Its root hangs under the entity's node, so the entity's position, rotation
+ * and scale place it; the glTF keeps the materials it ships with, a
+ * primitive has a standard (lit) node material. `color` and `size` follow the
+ * inspector live; a new `src` or `shape` rebuilds the content. Destroying it
+ * removes the root and disposes only what it created — never the cached glTF.
+ * In a 2D scene it creates nothing (`validate_project` reports it).
+ */
+export class Model extends Component {
+    static componentName = 'Model';
+    static space = '3d';
+    static params = {
+        src: { label: 'Model file', kind: 'model' },
+        shape: { label: 'Shape', options: [...SHAPES] },
+        color: { label: 'Color', kind: 'color' },
+        size: { label: 'Size', min: 0.01, step: 0.1 },
+    };
+    static transient = ['root'];
+    /** What this Model draws, under the entity's node; null until it is ready. The Pointer ray-casts against it. */
+    root = null;
+    _src = '';
+    _shape = 'box';
+    _color = 0xffffff;
+    _size = 1;
+    _primitive = null;
+    /** A `waica:` uri or project path to a `.glb` / `.gltf`; empty draws the primitive `shape`. */
+    get src() {
+        return this._src;
+    }
+    set src(value) {
+        this._src = value;
+        this.rebuild();
+    }
+    get shape() {
+        return this._shape;
+    }
+    set shape(value) {
+        this._shape = SHAPES.includes(value) ? value : 'box';
+        this.rebuild();
+    }
+    /** `0xrrggbb` of a primitive. */
+    get color() {
+        return this._color;
+    }
+    set color(value) {
+        this._color = value;
+        this._primitive?.mesh.material.color.setHex(value);
+    }
+    /** Uniform scale of a primitive: the box side, sphere diameter or plane side in world units. */
+    get size() {
+        return this._size;
+    }
+    set size(value) {
+        this._size = value;
+        this._primitive?.mesh.scale.setScalar(value);
+    }
+    onReady() {
+        // Draws only in a 3D scene, like Sun and PointLight: 2.5D is a later block, and a lit-less mesh would come out black.
+        if (this.game.space !== '3d')
+            return;
+        this.root = new THREE.Group();
+        this.root.name = 'waica:model';
+        this.entity.node.add(this.root);
+        this.build();
+    }
+    onDestroy() {
+        this.clear();
+        this.root?.removeFromParent();
+    }
+    build() {
+        if (!this.root)
+            return;
+        if (this._src)
+            this.root.add(this.game.assets.model(this._src).root);
+        else
+            this.buildPrimitive(this.root);
+    }
+    buildPrimitive(root) {
+        const material = new THREE.MeshStandardNodeMaterial({ color: this._color });
+        const mesh = new THREE.Mesh(primitiveGeometry(this._shape), material);
+        mesh.scale.setScalar(this._size);
+        root.add(mesh);
+        this._primitive = { mesh };
+    }
+    rebuild() {
+        if (!this.root)
+            return;
+        this.clear();
+        this.build();
+    }
+    /** Empties the root and disposes the primitive this Model created; a glTF's clone only leaves the graph. */
+    clear() {
+        this.root?.clear();
+        if (!this._primitive)
+            return;
+        this._primitive.mesh.geometry.dispose();
+        this._primitive.mesh.material.dispose();
+        this._primitive = null;
+    }
+}

package/dist/components/particle-emitter.d.ts

@@ -1,4 +1,4 @@
-import { Component } from '../component.js';
+import { Component, type ComponentSpace } from '../component.js';
 import type { YSortBatchParticipant, YSortEntry } from '../render-sort.js';
 export type ParticleVector = [number, number];
 export type ParticleSpace = 'world' | 'local';
@@ -8,6 +8,7 @@ export type ParticleBlend = 'normal' | 'additive';
 /** A fixed-capacity source of short-lived, batched 2D particles. */
 export declare class ParticleEmitter extends Component implements YSortBatchParticipant {
     static componentName: string;
+    static space: ComponentSpace;
     static displayName: string;
     static params: {
         rate: {

package/dist/components/particle-emitter.js

@@ -5,6 +5,7 @@ import { setEmissive } from '../render-layers.js';
 /** A fixed-capacity source of short-lived, batched 2D particles. */
 export class ParticleEmitter extends Component {
     static componentName = 'ParticleEmitter';
+    static space = '2d';
     static displayName = 'Particle Emitter';
     static params = {
         rate: { label: 'Rate', min: 0 },

package/dist/components/point-light.d.ts

@@ -0,0 +1,75 @@
+import * as THREE from 'three/webgpu';
+import { Component, type ComponentSpace } from '../component.js';
+/**
+ * A point light in a 3D scene (ADR 0027, `CONTEXT.md` Point Light): it shines
+ * in every direction from the entity's position plus an offset (in the
+ * entity's local frame: it turns and scales with the entity, so a lantern's
+ * offset follows the object it hangs on), reaching
+ * `distance` world units (0 = without limit) and fading with `decay` (2 is
+ * physical). Not the 2D `Light`, which paints a light-map. No shadows. In a
+ * 2D scene it creates nothing; the three light lives under the entity's node
+ * and leaves with it.
+ */
+export declare class PointLight extends Component {
+    static componentName: string;
+    static space: ComponentSpace;
+    static displayName: string;
+    static params: {
+        color: {
+            label: string;
+            kind: "color";
+        };
+        intensity: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        distance: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        decay: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        offsetX: {
+            label: string;
+        };
+        offsetY: {
+            label: string;
+        };
+        offsetZ: {
+            label: string;
+        };
+    };
+    static transient: string[];
+    /** The three light, null in a 2D scene or before the component is ready. */
+    light: THREE.PointLight | null;
+    private _color;
+    private _intensity;
+    private _distance;
+    private _decay;
+    private _offsetX;
+    private _offsetY;
+    private _offsetZ;
+    get color(): number;
+    set color(value: number);
+    get intensity(): number;
+    set intensity(value: number);
+    /** World units the light reaches; 0 reaches without limit. */
+    get distance(): number;
+    set distance(value: number);
+    get decay(): number;
+    set decay(value: number);
+    get offsetX(): number;
+    set offsetX(value: number);
+    get offsetY(): number;
+    set offsetY(value: number);
+    get offsetZ(): number;
+    set offsetZ(value: number);
+    onReady(): void;
+    onDestroy(): void;
+    private place;
+}

package/dist/components/point-light.js

@@ -0,0 +1,102 @@
+import * as THREE from 'three/webgpu';
+import { Component } from '../component.js';
+/**
+ * A point light in a 3D scene (ADR 0027, `CONTEXT.md` Point Light): it shines
+ * in every direction from the entity's position plus an offset (in the
+ * entity's local frame: it turns and scales with the entity, so a lantern's
+ * offset follows the object it hangs on), reaching
+ * `distance` world units (0 = without limit) and fading with `decay` (2 is
+ * physical). Not the 2D `Light`, which paints a light-map. No shadows. In a
+ * 2D scene it creates nothing; the three light lives under the entity's node
+ * and leaves with it.
+ */
+export class PointLight extends Component {
+    static componentName = 'PointLight';
+    static space = '3d';
+    static displayName = 'Point light (3D)';
+    static params = {
+        color: { label: 'Color', kind: 'color' },
+        intensity: { label: 'Intensity', min: 0, step: 0.5 },
+        distance: { label: 'Distance (0 = unlimited)', min: 0, step: 0.5 },
+        decay: { label: 'Decay', min: 0, step: 0.1 },
+        offsetX: { label: 'x offset' },
+        offsetY: { label: 'y offset' },
+        offsetZ: { label: 'z offset' },
+    };
+    static transient = ['light'];
+    /** The three light, null in a 2D scene or before the component is ready. */
+    light = null;
+    _color = 0xffffff;
+    _intensity = 1;
+    _distance = 0;
+    _decay = 2;
+    _offsetX = 0;
+    _offsetY = 0;
+    _offsetZ = 0;
+    get color() {
+        return this._color;
+    }
+    set color(value) {
+        this._color = value;
+        this.light?.color.setHex(value);
+    }
+    get intensity() {
+        return this._intensity;
+    }
+    set intensity(value) {
+        this._intensity = value;
+        if (this.light)
+            this.light.intensity = value;
+    }
+    /** World units the light reaches; 0 reaches without limit. */
+    get distance() {
+        return this._distance;
+    }
+    set distance(value) {
+        this._distance = value;
+        if (this.light)
+            this.light.distance = value;
+    }
+    get decay() {
+        return this._decay;
+    }
+    set decay(value) {
+        this._decay = value;
+        if (this.light)
+            this.light.decay = value;
+    }
+    get offsetX() {
+        return this._offsetX;
+    }
+    set offsetX(value) {
+        this._offsetX = value;
+        this.place();
+    }
+    get offsetY() {
+        return this._offsetY;
+    }
+    set offsetY(value) {
+        this._offsetY = value;
+        this.place();
+    }
+    get offsetZ() {
+        return this._offsetZ;
+    }
+    set offsetZ(value) {
+        this._offsetZ = value;
+        this.place();
+    }
+    onReady() {
+        if (this.game.space !== '3d')
+            return;
+        this.light = new THREE.PointLight(this._color, this._intensity, this._distance, this._decay);
+        this.entity.node.add(this.light);
+        this.place();
+    }
+    onDestroy() {
+        this.light?.removeFromParent();
+    }
+    place() {
+        this.light?.position.set(this._offsetX, this._offsetY, this._offsetZ);
+    }
+}