@waica/engine 0.25.0 → 0.27.0

package/dist/camera.js

@@ -1,4 +1,5 @@
 import * as THREE from 'three/webgpu';
+import { resolvePerspectiveCamera, } from './scene-camera-3d.js';
 export const CAMERA_DEFAULTS = {
     position: [0, 0],
     zoom: 12,
@@ -9,8 +10,9 @@ export const CAMERA_DEFAULTS = {
     lookaheadY: 0,
     smoothing: 6,
 };
-/** Fills a scene's camera block with the engine defaults. */
 export function resolveSceneCamera(json) {
+    if (json?.kind === 'perspective')
+        return resolvePerspectiveCamera(json);
     return {
         position: json?.position ?? CAMERA_DEFAULTS.position,
         zoom: json?.zoom ?? CAMERA_DEFAULTS.zoom,

package/dist/component.d.ts

@@ -8,12 +8,21 @@ export interface ParamSpec {
     max?: number;
     step?: number;
     /** Specialized editor control for values that are otherwise plain JSON. */
-    kind?: 'string-list' | 'vector2' | 'color' | 'texture';
+    kind?: 'string-list' | 'vector2' | 'vector3' | 'color' | 'texture' | 'model';
     /** Allowed values for a string param; rendered as a dropdown. Takes precedence over ref. */
     options?: string[];
     /** Project value this string param names; rendered and validated as a typed reference. */
     ref?: 'prefab' | 'stat' | 'action' | 'clip' | 'sound' | 'ui';
 }
+/**
+ * The scene space a component belongs to (ADR 0027): `'2d'` components draw,
+ * collide or light the orthographic world, move or query over its x/y plane,
+ * or need a sibling that does; `'3d'` ones need a perspective camera;
+ * `'both'` run anywhere. A component that declares nothing is `'both'`.
+ */
+export type ComponentSpace = '2d' | '3d' | 'both';
+/** The values of `ComponentSpace`, for the checks that read a marker from data (the project component protocol, conformance). */
+export declare const COMPONENT_SPACES: readonly ComponentSpace[];
 export interface ComponentClass<T extends Component = Component> {
     new (): T;
     /**
@@ -27,6 +36,8 @@ export interface ComponentClass<T extends Component = Component> {
     params?: Record<string, ParamSpec>;
     /** Sibling component updates that must complete before this one when present. */
     updateAfter?: readonly string[];
+    /** The scene space this component belongs to; absent means both. */
+    space?: ComponentSpace;
     /**
      * Instance fields holding runtime state rather than authorable defaults.
      * Excluded from authoringDefaults(); a subclass that does not redeclare
@@ -47,6 +58,25 @@ export interface SolidContact {
     readonly axis: 'x' | 'y';
     readonly normal: ContactNormal;
 }
+/** A 3D contact between two entities' solid Colliders, read after the physics step. */
+export interface BodyContact {
+    /** The entity whose component receives the hook. */
+    readonly entity: Entity;
+    /** The entity it is in contact with. */
+    readonly other: Entity;
+    /** Unit normal in world space, pointing from `entity` to `other`. */
+    readonly normal: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+    };
+    /** A world-space point on the contact. */
+    readonly point: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+    };
+}
 /**
  * A pluggable piece of an entity. User behaviors and engine ones are the
  * same thing: Component subclasses with public props.
@@ -56,6 +86,7 @@ export declare abstract class Component {
     static displayName?: string;
     static params?: Record<string, ParamSpec>;
     static updateAfter?: readonly string[];
+    static space?: ComponentSpace;
     static transient?: readonly string[];
     entity: Entity;
     game: Game;
@@ -67,8 +98,13 @@ export declare abstract class Component {
     onUpdate?(dt: number): void;
     /** Runs after the scene changes between identity and projected rendering. */
     onProjectionChange?(projection: 'isometric' | null): void;
-    /** Runs on overlap when this entity's Hitbox mask names the other's layer. */
+    /**
+     * Runs on overlap when this entity's Hitbox (2D) or sensor Collider (3D)
+     * mask names the other's layer.
+     */
     onCollide?(other: Entity): void;
+    /** Runs once per Simulation Step for each entity this entity's solid Collider is in contact with (3D, issue #159). */
+    onBodyContact?(contact: BodyContact): void;
     /** Runs when this entity's DynamicBody physically contacts a Solid. */
     onContact?(contact: SolidContact): void;
     /**

package/dist/component.js

@@ -1,3 +1,5 @@
+/** The values of `ComponentSpace`, for the checks that read a marker from data (the project component protocol, conformance). */
+export const COMPONENT_SPACES = ['2d', '3d', 'both'];
 /**
  * A pluggable piece of an entity. User behaviors and engine ones are the
  * same thing: Component subclasses with public props.
@@ -7,6 +9,7 @@ export class Component {
     static displayName;
     static params;
     static updateAfter;
+    static space;
     static transient;
     entity;
     game;

package/dist/components/animated-sprite.d.ts

@@ -1,5 +1,6 @@
-import { Component } from '../component.js';
+import { Component, type ComponentSpace } from '../component.js';
 import { type ClipDef } from '../animation/clip-player.js';
+import type { ClipTarget } from '../animation/clip-target.js';
 import { type SheetCell, type SheetDef } from '../animation/sheet.js';
 import type { YSortParticipant } from '../render-sort.js';
 /**
@@ -12,8 +13,9 @@ import type { YSortParticipant } from '../render-sort.js';
  * per frame, anchored bottom-center — width/height size the sheet's largest
  * frame and smaller ones keep their feet planted.
  */
-export declare class AnimatedSprite extends Component implements YSortParticipant {
+export declare class AnimatedSprite extends Component implements YSortParticipant, ClipTarget {
     static componentName: string;
+    static space: ComponentSpace;
     static updateAfter: readonly string[];
     static params: {
         offsetX: {
@@ -95,6 +97,10 @@ export declare class AnimatedSprite extends Component implements YSortParticipan
     initialClip?: string;
     /** Clip currently playing. */
     current?: string;
+    /** The names a StateMachine can ask for (the Clip Target seam, issue #166). */
+    get clipNames(): readonly string[];
+    /** True once a non-looping clip has held its last frame for its whole duration; false after `play`. */
+    get clipFinished(): boolean;
     private readonly player;
     private sheets;
     private texs;
@@ -104,7 +110,12 @@ export declare class AnimatedSprite extends Component implements YSortParticipan
     private frameScaleX;
     private frameScaleY;
     onReady(): void;
-    /** Switches clip; repeating the same name doesn't restart the animation. */
+    /**
+     * Switches clip. Repeating the running clip's name doesn't restart it; once
+     * a non-looping clip has finished it does (issue #166 CA-3), so a state
+     * re-entered after its one-shot clip ended replays it instead of reporting
+     * `clip:end` on every step.
+     */
     play(name: string): void;
     onUpdate(dt: number): void;
     onDestroy(): void;

package/dist/components/animated-sprite.js

@@ -21,6 +21,7 @@ const clampAnchor = (value) => Math.min(1, Math.max(0, value));
  */
 export class AnimatedSprite extends Component {
     static componentName = 'AnimatedSprite';
+    static space = '2d';
     static updateAfter = ['StateMachine'];
     static params = {
         offsetX: { label: 'x offset' },
@@ -150,6 +151,14 @@ export class AnimatedSprite extends Component {
     initialClip;
     /** Clip currently playing. */
     current;
+    /** The names a StateMachine can ask for (the Clip Target seam, issue #166). */
+    get clipNames() {
+        return Object.keys(this.clips);
+    }
+    /** True once a non-looping clip has held its last frame for its whole duration; false after `play`. */
+    get clipFinished() {
+        return this.player.finished;
+    }
     player = new ClipPlayer();
     sheets = [];
     texs = [];
@@ -205,9 +214,14 @@ export class AnimatedSprite extends Component {
         if (this.initialClip)
             this.play(this.initialClip);
     }
-    /** Switches clip; repeating the same name doesn't restart the animation. */
+    /**
+     * Switches clip. Repeating the running clip's name doesn't restart it; once
+     * a non-looping clip has finished it does (issue #166 CA-3), so a state
+     * re-entered after its one-shot clip ended replays it instead of reporting
+     * `clip:end` on every step.
+     */
     play(name) {
-        if (this.current === name)
+        if (this.current === name && !this.player.finished)
             return;
         const clip = this.clips[name];
         if (!clip)

package/dist/components/animator.d.ts

@@ -0,0 +1,98 @@
+import type { ClipTarget } from '../animation/clip-target.js';
+import { Component, type ComponentSpace } from '../component.js';
+/** Per-clip overrides, keyed by the glTF's clip name: a one-shot (`loop: false`) and a playback rate. */
+export interface AnimatorClipOverride {
+    /** Defaults to true; false plays the clip once and holds its last pose. */
+    loop?: boolean;
+    /** Playback rate; 1 by default, 2 finishes in half the time. */
+    speed?: number;
+}
+/** What `inspect_runtime` shows of an Animator. */
+export interface AnimatorState {
+    loaded: boolean;
+    /** The playing clip; null before the first play (an undefined would project as an unsupported marker). */
+    current: string | null;
+    /** The current action's time in seconds (0 with none). */
+    time: number;
+    /** False before the model loaded or with no clip playing. */
+    playing: boolean;
+    /** The pose fingerprint of the rig (see poseHash); empty with no skeleton. */
+    poseHash: string;
+}
+/**
+ * Plays the glTF clips of the Model beside it (issue #166, ADR 0029): the
+ * 3D Clip Target. One AnimationMixer over the Model's own clone, one action
+ * per clip, advanced by the Simulation Step in onUpdate — nothing runs per
+ * render frame, so the pose is deterministic and visible step by step. A
+ * StateMachine finds it like it finds an AnimatedSprite and plays the clip of
+ * each state; `clip:end` fires when a `loop: false` clip finishes. A `play`
+ * before the model loaded is remembered and applied when it settles;
+ * otherwise `initialClip` plays then. In a 2D scene it creates nothing.
+ */
+export declare class Animator extends Component implements ClipTarget {
+    static componentName: string;
+    static space: ComponentSpace;
+    static updateAfter: readonly string[];
+    static params: {
+        initialClip: {
+            label: string;
+        };
+        fade: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+    };
+    static transient: string[];
+    /** The clip that plays once the model settles, when nothing asked for one before. */
+    initialClip: string;
+    /** Crossfade between clips, in seconds; 0 cuts. */
+    fade: number;
+    /**
+     * Per-clip overrides by glTF clip name (authored in JSON, like
+     * AnimatedSprite.clips). Read when the actions are built, as the model
+     * settles: a change after that applies on the next build (a Model rebuild).
+     */
+    clips: Record<string, AnimatorClipOverride>;
+    /** The clip playing now; undefined before the first play. */
+    current: string | undefined;
+    private mixer;
+    private readonly actions;
+    private active;
+    /** A play asked for before the model loaded. */
+    private requested;
+    private finished;
+    private root;
+    private readonly warned;
+    private attached;
+    /** The Model handle the mixer was built over, or is waiting on: a Model rebuild replaces it (review of PR #168). */
+    private handle;
+    /** The clip names, computed once per build: the StateMachine reads them every step. */
+    private names;
+    /** True while clips are expected but not listed yet (the glb is loading); false once built, or once no Model can provide them. */
+    private pending;
+    get clipNames(): readonly string[];
+    get clipFinished(): boolean;
+    get clipsPending(): boolean;
+    onReady(): void;
+    /** Plays a clip: a no-op for the running one, a restart for a finished one, a crossfade from any other over `fade` seconds. */
+    play(name: string): void;
+    onUpdate(dt: number): void;
+    onDestroy(): void;
+    inspectState(): AnimatorState;
+    /**
+     * Takes the sibling Model's handle and builds the mixer when it settles. A
+     * Model later in the component order is not there at onReady, so the first
+     * onUpdate tries once more (`final`); a primitive Model warns at once, a
+     * missing one once it is certain, and either way exactly once.
+     */
+    private attach;
+    /** Forgets the Model's old clone and keeps the clip it played as the request for the next build. */
+    private detach;
+    /** Stops and drops the mixer, its actions and the clone they ran over. */
+    private release;
+    private build;
+    private configure;
+    private warnOnce;
+}

package/dist/components/animator.js

@@ -0,0 +1,197 @@
+import * as THREE from 'three/webgpu';
+import { poseHash } from '../animation/pose-hash.js';
+import { Component } from '../component.js';
+import { reportRejection } from '../report-rejection.js';
+import { Model } from './model.js';
+/**
+ * Plays the glTF clips of the Model beside it (issue #166, ADR 0029): the
+ * 3D Clip Target. One AnimationMixer over the Model's own clone, one action
+ * per clip, advanced by the Simulation Step in onUpdate — nothing runs per
+ * render frame, so the pose is deterministic and visible step by step. A
+ * StateMachine finds it like it finds an AnimatedSprite and plays the clip of
+ * each state; `clip:end` fires when a `loop: false` clip finishes. A `play`
+ * before the model loaded is remembered and applied when it settles;
+ * otherwise `initialClip` plays then. In a 2D scene it creates nothing.
+ */
+export class Animator extends Component {
+    static componentName = 'Animator';
+    static space = '3d';
+    static updateAfter = ['StateMachine'];
+    static params = {
+        initialClip: { label: 'Initial clip' },
+        fade: { label: 'Fade (s)', min: 0, max: 1, step: 0.05 },
+    };
+    static transient = ['current', 'mixer', 'actions', 'active', 'requested', 'finished', 'root', 'warned', 'attached', 'handle', 'names', 'pending'];
+    /** The clip that plays once the model settles, when nothing asked for one before. */
+    initialClip = '';
+    /** Crossfade between clips, in seconds; 0 cuts. */
+    fade = 0.15;
+    /**
+     * Per-clip overrides by glTF clip name (authored in JSON, like
+     * AnimatedSprite.clips). Read when the actions are built, as the model
+     * settles: a change after that applies on the next build (a Model rebuild).
+     */
+    clips = {};
+    /** The clip playing now; undefined before the first play. */
+    current;
+    mixer = null;
+    actions = new Map();
+    active = null;
+    /** A play asked for before the model loaded. */
+    requested;
+    finished = false;
+    root = null;
+    warned = new Set();
+    attached = false;
+    /** The Model handle the mixer was built over, or is waiting on: a Model rebuild replaces it (review of PR #168). */
+    handle = null;
+    /** The clip names, computed once per build: the StateMachine reads them every step. */
+    names = [];
+    /** True while clips are expected but not listed yet (the glb is loading); false once built, or once no Model can provide them. */
+    pending = false;
+    get clipNames() {
+        return this.names;
+    }
+    get clipFinished() {
+        return this.finished;
+    }
+    get clipsPending() {
+        return this.pending;
+    }
+    onReady() {
+        if (this.game.space !== '3d')
+            return;
+        this.pending = true;
+        this.attach();
+    }
+    /** Plays a clip: a no-op for the running one, a restart for a finished one, a crossfade from any other over `fade` seconds. */
+    play(name) {
+        if (this.game.space !== '3d')
+            return;
+        if (!this.mixer) {
+            this.requested = name;
+            return;
+        }
+        const action = this.actions.get(name);
+        if (!action) {
+            this.warnOnce(name, `[waica] "${this.entity.name}": no clip "${name}"`);
+            return;
+        }
+        if (action === this.active && !this.finished)
+            return;
+        const previous = this.active;
+        this.active = action;
+        this.current = name;
+        this.finished = false;
+        action.reset().setEffectiveWeight(1).play();
+        if (!previous || previous === action)
+            return;
+        if (this.fade <= 0)
+            previous.stop();
+        else
+            previous.crossFadeTo(action, this.fade, false);
+    }
+    onUpdate(dt) {
+        if (this.game.space !== '3d')
+            return;
+        // A rebuilt Model (a new src or shape) draws a new clone: the mixer over
+        // the old one would animate a graph nobody draws, so it is torn down and
+        // the clip it was playing is asked for again on the new one.
+        if (this.attached && (this.entity.get(Model)?.handle ?? null) !== this.handle)
+            this.detach();
+        if (!this.attached)
+            this.attach(true);
+        this.mixer?.update(dt);
+    }
+    onDestroy() {
+        this.release();
+        this.pending = false;
+    }
+    inspectState() {
+        return {
+            loaded: this.mixer !== null,
+            current: this.current ?? null,
+            time: this.active?.time ?? 0,
+            playing: this.active !== null && this.active.isRunning(),
+            poseHash: this.root ? poseHash(this.root) : '',
+        };
+    }
+    /**
+     * Takes the sibling Model's handle and builds the mixer when it settles. A
+     * Model later in the component order is not there at onReady, so the first
+     * onUpdate tries once more (`final`); a primitive Model warns at once, a
+     * missing one once it is certain, and either way exactly once.
+     */
+    attach(final = false) {
+        const model = this.entity.get(Model);
+        const handle = model?.handle;
+        if (!handle) {
+            if ((model && !model.src) || final) {
+                this.attached = true;
+                this.pending = false;
+                this.warnOnce('model', `[waica] "${this.entity.name}": Animator needs a Model with a src beside it; nothing plays`);
+            }
+            return;
+        }
+        this.attached = true;
+        this.handle = handle;
+        reportRejection(handle.settled.then((outcome) => {
+            // Only the handle still attached builds: a Model rebuilt meanwhile has a newer one.
+            if (outcome === 'loaded' && this.entity.alive && !this.mixer && this.handle === handle)
+                this.build(handle);
+        }), 'animator model settle');
+    }
+    /** Forgets the Model's old clone and keeps the clip it played as the request for the next build. */
+    detach() {
+        this.requested = this.current ?? this.requested;
+        this.release();
+        this.attached = false;
+        this.pending = true;
+    }
+    /** Stops and drops the mixer, its actions and the clone they ran over. */
+    release() {
+        this.mixer?.stopAllAction();
+        if (this.mixer && this.root)
+            this.mixer.uncacheRoot(this.root);
+        this.mixer = null;
+        this.active = null;
+        this.current = undefined;
+        this.finished = false;
+        this.actions.clear();
+        this.names = [];
+        this.root = null;
+        this.handle = null;
+    }
+    build(handle) {
+        const mixer = new THREE.AnimationMixer(handle.root);
+        this.mixer = mixer;
+        this.root = handle.root;
+        for (const clip of handle.animations)
+            this.actions.set(clip.name, this.configure(mixer.clipAction(clip), clip.name));
+        this.names = [...this.actions.keys()];
+        this.pending = false;
+        mixer.addEventListener('finished', (event) => {
+            if (event.action === this.active)
+                this.finished = true;
+        });
+        const first = this.requested ?? this.initialClip;
+        this.requested = undefined;
+        if (first)
+            this.play(first);
+    }
+    configure(action, name) {
+        const override = this.clips[name];
+        if (override?.loop === false) {
+            action.setLoop(THREE.LoopOnce, 1);
+            action.clampWhenFinished = true;
+        }
+        action.timeScale = override?.speed ?? 1;
+        return action;
+    }
+    warnOnce(key, message) {
+        if (this.warned.has(key))
+            return;
+        this.warned.add(key);
+        console.warn(message);
+    }
+}

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;