@woosh/meep-engine 3.11.2 → 3.12.0

package/src/engine/graphics3/AnimationSystem3.js

@@ -1,352 +1,10 @@
-import { assert } from "../../core/assert.js";
-import { PosePlayback } from "../../shade/renderer/animation/pose/PosePlayback.js";
-import { Animation } from "../ecs/animation/Animation.js";
-import { System } from "../ecs/System.js";
-import { SGMesh } from "../graphics/ecs/mesh-v2/aggregate/SGMesh.js";
-import { ClipListPlayer } from "./animation/ClipListPlayer.js";
-import { write_clip_playback } from "./animation/write_clip_playback.js";
-import {
-    register_instance_clips,
-    unregister_instance_clips
-} from "./register_instance_animation.js";
+import { AnimationSystem } from "./AnimationSystem.js";
 
 /**
- * @type {ClipPlayback[]}
- */
-const NOTHING = Object.freeze([]);
-
-/**
- * Drives every entity's {@link Animation} component: runs the clocks of the clips its list names,
- * and tells the renderer what each of them weighs and where it is playing.
- *
- * The list path is what the game uses wherever there is no state machine — buildings, critters and
- * the strategy map's groups — and {@link ClipListPlayer} is what plays it. This is the ECS half:
- * which entity has which model, and when the ids the renderer issued for it stopped meaning
- * anything.
- *
- * **It is the CPU that plays the animation and the GPU that draws it.** Shade can advance a clip
- * itself, and this never asks it to — `AnimationClipFlags.Playing` is left clear and every audible
- * clip's time is written down each frame from the player's own clock. That is I-4: the pose
- * gameplay reads and the pose on the screen have to be the same pose, and they cannot be if two
- * clocks are running.
+ * @deprecated Renamed to {@link AnimationSystem}. The trailing `3` marked the 2.x → 3.x renderer transition;
+ * the 2.x name it disambiguated against is gone, so the suffix no longer distinguishes anything.
  *
- * **Nothing here is culled.** The legacy system skipped entities under 32 px², which let camera
- * framing decide whether a clip ever reached its end. What may be culled is drawing, and drawing is
- * Shade's to cull.
+ * Kept as a re-export rather than removed: this is a library, and an import path is as much a
+ * published interface as a class name.
  */
-export class AnimationSystem3 extends System {
-    /**
-     * @type {GraphicsEngine3}
-     */
-    #graphics;
-
-    /**
-     * The system that owns the scene, the model instances, and the ids the animation manager issued
-     * for them.
-     *
-     * @type {MeshSystem3}
-     */
-    #meshes;
-
-    /**
-     * @type {Map<number, {player: ClipListPlayer, instance: SceneBundleInstance|null, clip_registration: InstanceClipRegistration|null, played_slots: Int32Array, written: Float32Array, poses: PosePlayback[]}>}
-     */
-    #entries = new Map();
-
-    /**
-     * @param {GraphicsEngine3} graphics
-     * @param {MeshSystem3} meshes
-     */
-    constructor(graphics, meshes) {
-        super();
-
-        assert.defined(graphics, 'graphics');
-        assert.defined(meshes, 'meshes');
-
-        this.#graphics = graphics;
-        this.#meshes = meshes;
-
-        this.dependencies = [Animation, SGMesh];
-    }
-
-    /**
-     * What an entity is playing, and where each of them is.
-     *
-     * One entry per clip in the component's list, in the list's own order. Empty for an entity this
-     * system is not driving — one that has left, or one whose model has not arrived, which is the
-     * same wait the clip durations are on.
-     *
-     * @param {number} entity
-     * @returns {ClipPlayback[]}
-     */
-    playbacks_of(entity) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return NOTHING;
-        }
-
-        return entry.player.playbacks;
-    }
-
-    /**
-     * What the entity's model is playing, in the form the CPU pose evaluator takes: one entry per
-     * clip the model carries, at the weight and the time the renderer has been given.
-     *
-     * **Only the clips the list names are here, because they are the only ones registered** (D37).
-     * The GPU's accumulator marks a joint dirty for every bound clip that writes to it, weight and
-     * all — so a bound clip at weight zero resolves the joints only it drives to zero rather than
-     * leaving them at rest. The answer is not to hand the surplus to the evaluator so it agrees with
-     * a mistake; it is not to bind them, and then a clip of the model nothing names moves nothing.
-     *
-     * The entries are this system's own and are rewritten by the next call, which is what keeps a
-     * query on a per-frame path from allocating.
-     *
-     * @param {PosePlayback[]} target appended to
-     * @param {number} entity
-     * @returns {boolean} whether this system is driving the entity — `false` for one with no
-     * {@link Animation}, and for one whose model has not arrived
-     */
-    write_pose_playbacks(target, entity) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined || entry.instance === null) {
-            return false;
-        }
-
-        const clips = entry.instance.clips;
-        const weights = entry.player.weights;
-        const poses = entry.poses;
-        const played = entry.played_slots;
-
-        for (let i = 0; i < played.length; i++) {
-            const slot = played[i];
-            const pose = poses[slot];
-
-            pose.clip = clips[slot];
-            pose.weight = weights[slot];
-
-            // a clip the list names but has stopped playing is where it stopped, and at weight zero
-            // that is nowhere in particular
-            pose.time = 0;
-        }
-
-        const playbacks = entry.player.playbacks;
-
-        for (let i = 0; i < playbacks.length; i++) {
-            const playback = playbacks[i];
-
-            poses[playback.slot].time = playback.time;
-        }
-
-        for (let i = 0; i < played.length; i++) {
-            target.push(poses[played[i]]);
-        }
-
-        return true;
-    }
-
-    /**
-     * @param {Animation} component
-     * @param {SGMesh} model
-     * @param {number} entity
-     */
-    link(component, model, entity) {
-        this.#entries.set(entity, {
-            player: ClipListPlayer.from(component),
-            instance: null,
-            clip_registration: null,
-            played_slots: new Int32Array(0),
-            written: new Float32Array(0),
-            poses: []
-        });
-    }
-
-    /**
-     * @param {Animation} component
-     * @param {SGMesh} model
-     * @param {number} entity
-     */
-    unlink(component, model, entity) {
-        const entry = this.#entries.get(entity);
-
-        if (entry !== undefined) {
-            this.#release_clips(entry);
-        }
-
-        this.#entries.delete(entity);
-    }
-
-    async shutdown(entityManager) {
-        for (const entry of this.#entries.values()) {
-            this.#release_clips(entry);
-        }
-
-        this.#entries.clear();
-    }
-
-    /**
-     * Give this entity's clips back, if the manager that issued them is still the one running.
-     *
-     * **An id may only be handed back to the manager that issued it.** A renderer restart replaces
-     * the GPU scene context and voids every id it gave out, so a registration stamped with a context
-     * that is no longer current is forgotten rather than returned.
-     *
-     * @param {object} entry
-     */
-    #release_clips(entry) {
-        this.#release_clips_only(entry);
-
-        entry.played_slots = new Int32Array(0);
-    }
-
-    /**
-     * The registration alone, leaving {@link #refresh_played_slots}'s answer where it is — which is
-     * what a re-registration wants, since the set it is about to register with is the current one.
-     *
-     * @param {object} entry
-     */
-    #release_clips_only(entry) {
-        const registration = entry.clip_registration;
-
-        if (registration === null) {
-            return;
-        }
-
-        if (registration.context === this.#graphics.scene_context(this.#meshes.scene)) {
-            unregister_instance_clips(registration);
-        }
-
-        entry.clip_registration = null;
-    }
-
-    /**
-     * Which of the model's clips the list currently names, kept up to date.
-     *
-     * **The list is edited while the game runs** — `ClipListPlayer` reconciles its playbacks against
-     * it every tick, and `StopAnimationBehavior` empties it outright — so which clips are playable
-     * is not settled once at bind.
-     *
-     * Maintained here rather than alongside the registration because **the pose evaluator needs it
-     * whether or not there is a device**: `query_entity_node_world_pose` answers on the CPU, from
-     * the clips this driver plays, and a game with rendering disabled still asks (I-4).
-     *
-     * @param {object} entry
-     * @returns {boolean} whether the set changed
-     */
-    #refresh_played_slots(entry) {
-        const playbacks = entry.player.playbacks;
-        const played = entry.played_slots;
-
-        /*
-         The distinct slots, and distinct is the point: two entries of the list can name one clip of
-         the model, so the number of playbacks is not the number of clips. Comparing the two would
-         report a change on every frame for a list that had not moved, and a change here is a
-         re-registration.
-        */
-        const wanted = [];
-
-        for (let i = 0; i < playbacks.length; i++) {
-            const slot = playbacks[i].slot;
-
-            if (wanted.indexOf(slot) === -1) {
-                wanted.push(slot);
-            }
-        }
-
-        if (wanted.length === played.length) {
-            let same = true;
-
-            for (let i = 0; i < wanted.length; i++) {
-                if (played[i] !== wanted[i]) {
-                    same = false;
-                    break;
-                }
-            }
-
-            if (same) {
-                return false;
-            }
-        }
-
-        entry.played_slots = Int32Array.from(wanted);
-
-        return true;
-    }
-
-    /**
-     * Keep the registered clips equal to the ones the list names.
-     *
-     * A clip that leaves the list has to be unregistered, or it stays bound at weight zero and takes
-     * the joints only it drives down to zero with it.
-     *
-     * @param {object} entry
-     * @param {SceneBundleInstance} instance
-     * @param {GPUSceneContext} context
-     * @param {boolean} set_changed whether {@link #refresh_played_slots} just moved
-     * @returns {boolean} whether the registration was replaced
-     */
-    #refresh_clips(entry, instance, context, set_changed) {
-        const registration = entry.clip_registration;
-
-        if (!set_changed && registration !== null && registration.context === context) {
-            return false;
-        }
-
-        this.#release_clips_only(entry);
-
-        entry.clip_registration = register_instance_clips(context, instance, entry.played_slots);
-
-        return true;
-    }
-
-    /**
-     * @param {number} time_delta_seconds
-     */
-    update(time_delta_seconds) {
-        const ecd = this.entityManager.dataset;
-
-        const context = this.#graphics.scene_context(this.#meshes.scene);
-
-        // No device — before the first start, and again after a stop. The clocks still run: a clip
-        // that ends while the renderer is being replaced still says so.
-        const manager = context === null ? null : context.animation_manager;
-
-        for (const [entity, entry] of this.#entries) {
-            const instance = this.#meshes.instance_of(entity);
-
-            if (instance === null) {
-                // the model has not arrived, and its clips are what say how long they run
-                continue;
-            }
-
-            if (instance !== entry.instance) {
-                entry.instance = instance;
-
-                entry.player.bind(entity, ecd, instance);
-
-                entry.written = new Float32Array(instance.clips.length).fill(-1);
-                entry.poses = instance.clips.map(() => new PosePlayback());
-
-                // ids the manager issued for the model that was here before name clips this one
-                // does not have
-                this.#release_clips(entry);
-            }
-
-            entry.player.tick(time_delta_seconds);
-
-            const set_changed = this.#refresh_played_slots(entry);
-
-            if (context === null) {
-                continue;
-            }
-
-            if (this.#refresh_clips(entry, instance, context, set_changed)) {
-                // whatever the last registration was told is not what this one knows
-                entry.written.fill(-1);
-            }
-
-            write_clip_playback(manager, entry.player, entry.clip_registration.ids, entry.written);
-        }
-    }
-}
+export const AnimationSystem3 = AnimationSystem;

package/src/engine/graphics3/CameraSystem.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Drives the camera the frame is drawn from, from whichever camera entity is active.
+ *
+ * The old system gave every camera entity a three camera of its own and pointed
+ * `graphics.camera` at one of them. Shade's facade **owns** its camera — one of them, for the whole
+ * engine — so this does the other thing: whichever entity is active has its pose and its lens copied
+ * onto that one. Nothing is swapped, so there is no state to get out of step, and a camera entity
+ * appearing or leaving cannot leave the renderer pointed at a camera nobody owns.
+ *
+ * **Read once per tick rather than followed by signal**, which is the opposite of how
+ * {@link MeshSystem} and {@link LightSystem} work, for a reason that is specific to cameras: the
+ * component's clip planes are plain fields whose setters write straight through to the three camera
+ * object it used to own, so there is no signal to bind to. A camera that changed its near plane while
+ * standing still would silently keep the old one. It also happens to be the cheaper arrangement — a
+ * game camera moves on almost every frame, so a signal per property would fire constantly to do work
+ * this does once.
+ */
+export class CameraSystem extends System<any> {
+    /**
+     * @param {GraphicsEngine} graphics
+     */
+    constructor(graphics: GraphicsEngine);
+    dependencies: (typeof Transform | typeof Camera)[];
+    startup(entityManager: any): Promise<void>;
+    shutdown(entityManager: any): Promise<void>;
+    /**
+     * Which entity is driving the render camera, or −1.
+     *
+     * @returns {number}
+     */
+    get active_entity(): number;
+    /**
+     * @param {Camera} camera
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(camera: Camera, transform: Transform, entity: number): void;
+    /**
+     * @param {Camera} camera
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(camera: Camera, transform: Transform, entity: number): void;
+    #private;
+}
+import { System } from "../ecs/System.js";
+import { Transform } from "../ecs/transform/Transform.js";
+import { Camera } from "../graphics/ecs/camera/Camera.js";
+//# sourceMappingURL=CameraSystem.d.ts.map

package/src/engine/graphics3/CameraSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CameraSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/CameraSystem.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;GAgBG;AACH;IAoBI;;OAEG;IACH,sCAQC;IADG,mDAAuC;IAG3C,2CAEC;IAED,4CAIC;IAED;;;;OAIG;IACH,4BAEC;IAED;;;;OAIG;IACH,aAJW,MAAM,aACN,SAAS,UACT,MAAM,QAUhB;IAED;;;;OAIG;IACH,eAJW,MAAM,aACN,SAAS,UACT,MAAM,QAIhB;;CAsEJ;uBAtKsB,kBAAkB;0BACf,+BAA+B;uBAClC,kCAAkC"}

package/src/engine/graphics3/CameraSystem.js

@@ -0,0 +1,170 @@
+import { assert } from "../../core/assert.js";
+import { SignalBinding } from "../../core/events/signal/SignalBinding.js";
+import { DEG_TO_RAD } from "../../core/math/DEG_TO_RAD.js";
+import { System } from "../ecs/System.js";
+import { Transform } from "../ecs/transform/Transform.js";
+import { Camera } from "../graphics/ecs/camera/Camera.js";
+import { camera_sync_from_transform } from "./camera_sync_from_transform.js";
+
+/**
+ * Drives the camera the frame is drawn from, from whichever camera entity is active.
+ *
+ * The old system gave every camera entity a three camera of its own and pointed
+ * `graphics.camera` at one of them. Shade's facade **owns** its camera — one of them, for the whole
+ * engine — so this does the other thing: whichever entity is active has its pose and its lens copied
+ * onto that one. Nothing is swapped, so there is no state to get out of step, and a camera entity
+ * appearing or leaving cannot leave the renderer pointed at a camera nobody owns.
+ *
+ * **Read once per tick rather than followed by signal**, which is the opposite of how
+ * {@link MeshSystem} and {@link LightSystem} work, for a reason that is specific to cameras: the
+ * component's clip planes are plain fields whose setters write straight through to the three camera
+ * object it used to own, so there is no signal to bind to. A camera that changed its near plane while
+ * standing still would silently keep the old one. It also happens to be the cheaper arrangement — a
+ * game camera moves on almost every frame, so a signal per property would fire constantly to do work
+ * this does once.
+ */
+export class CameraSystem extends System {
+    /**
+     * @type {GraphicsEngine}
+     */
+    #graphics;
+
+    /**
+     * The camera entities present, and the binding watching each one's active flag.
+     *
+     * @type {Map<number, {camera: Camera, transform: Transform, binding: SignalBinding}>}
+     */
+    #entries = new Map();
+
+    /**
+     * Which entity is driving the render camera, or −1 when none is.
+     *
+     * @type {number}
+     */
+    #active = -1;
+
+    /**
+     * @param {GraphicsEngine} graphics
+     */
+    constructor(graphics) {
+        super();
+
+        assert.equal(graphics.isGraphicsEngine, true, 'graphics.isGraphicsEngine !== true');
+
+        this.#graphics = graphics;
+
+        this.dependencies = [Camera, Transform];
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+    }
+
+    async shutdown(entityManager) {
+        for (const entity of Array.from(this.#entries.keys())) {
+            this.#drop(entity);
+        }
+    }
+
+    /**
+     * Which entity is driving the render camera, or −1.
+     *
+     * @returns {number}
+     */
+    get active_entity() {
+        return this.#active;
+    }
+
+    /**
+     * @param {Camera} camera
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(camera, transform, entity) {
+        const binding = new SignalBinding(camera.active.onChanged, () => this.#elect());
+
+        binding.link();
+
+        this.#entries.set(entity, { camera, transform, binding });
+
+        this.#elect();
+    }
+
+    /**
+     * @param {Camera} camera
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(camera, transform, entity) {
+        this.#drop(entity);
+    }
+
+    /**
+     * Copy the active camera entity onto the camera Shade draws with, and its frustum back.
+     *
+     * @param {number} time_delta
+     */
+    update(time_delta) {
+        const entry = this.#entries.get(this.#active);
+
+        if (entry === undefined) {
+            // no camera entity is active; the facade keeps whatever it was last given, which is what
+            // lets a scene without a camera still render from wherever the last one left it
+            return;
+        }
+
+        const target = this.#graphics.camera.camera;
+
+        // degrees on the component, radians on Shade's; the facade's own `render` owns the aspect
+        // ratio, because only it knows what resolution the frame is going out at
+        target.fov = entry.camera.fov.getValue() * DEG_TO_RAD;
+        target.near = entry.camera.clip_near;
+        target.far = entry.camera.clip_far;
+
+        camera_sync_from_transform(target, entry.transform);
+
+        /*
+         The return trip. Gameplay asks what the camera can see — which armies to generate now,
+         which terrain tiles a scene has to have before it is shown — and the honest answer is the
+         frustum the renderer is drawing with, not a second one derived from the component. It is
+         copied rather than aliased because the renderer's camera is one object and any number of
+         camera entities can pass through it.
+        */
+        entry.camera.publishFrustum(target.frustum);
+    }
+
+    /**
+     * Settle on which entity drives the camera.
+     *
+     * First active one wins, and it is re-decided from scratch rather than tracked incrementally so
+     * that two entities both claiming to be active resolve the same way however they got there.
+     */
+    #elect() {
+        this.#active = -1;
+
+        for (const [entity, entry] of this.#entries) {
+            if (entry.camera.active.getValue()) {
+                this.#active = entity;
+
+                return;
+            }
+        }
+    }
+
+    /**
+     * @param {number} entity
+     */
+    #drop(entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        entry.binding.unlink();
+
+        this.#entries.delete(entity);
+
+        this.#elect();
+    }
+}

package/src/engine/graphics3/CameraSystem3.d.ts

@@ -1,49 +1,10 @@
 /**
- * Drives the camera the frame is drawn from, from whichever camera entity is active.
+ * @deprecated Renamed to {@link CameraSystem}. The trailing `3` marked the 2.x → 3.x renderer transition;
+ * the 2.x name it disambiguated against is gone, so the suffix no longer distinguishes anything.
  *
- * The old system gave every camera entity a three camera of its own and pointed
- * `graphics.camera` at one of them. Shade's facade **owns** its camera — one of them, for the whole
- * engine — so this does the other thing: whichever entity is active has its pose and its lens copied
- * onto that one. Nothing is swapped, so there is no state to get out of step, and a camera entity
- * appearing or leaving cannot leave the renderer pointed at a camera nobody owns.
- *
- * **Read once per tick rather than followed by signal**, which is the opposite of how
- * {@link MeshSystem3} and {@link LightSystem3} work, for a reason that is specific to cameras: the
- * component's clip planes are plain fields whose setters write straight through to the three camera
- * object it used to own, so there is no signal to bind to. A camera that changed its near plane while
- * standing still would silently keep the old one. It also happens to be the cheaper arrangement — a
- * game camera moves on almost every frame, so a signal per property would fire constantly to do work
- * this does once.
+ * Kept as a re-export rather than removed: this is a library, and an import path is as much a
+ * published interface as a class name.
  */
-export class CameraSystem3 extends System<any> {
-    /**
-     * @param {GraphicsEngine3} graphics
-     */
-    constructor(graphics: GraphicsEngine3);
-    dependencies: (typeof Transform | typeof Camera)[];
-    startup(entityManager: any): Promise<void>;
-    shutdown(entityManager: any): Promise<void>;
-    /**
-     * Which entity is driving the render camera, or −1.
-     *
-     * @returns {number}
-     */
-    get active_entity(): number;
-    /**
-     * @param {Camera} camera
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    link(camera: Camera, transform: Transform, entity: number): void;
-    /**
-     * @param {Camera} camera
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    unlink(camera: Camera, transform: Transform, entity: number): void;
-    #private;
-}
-import { System } from "../ecs/System.js";
-import { Transform } from "../ecs/transform/Transform.js";
-import { Camera } from "../graphics/ecs/camera/Camera.js";
+export const CameraSystem3: typeof CameraSystem;
+import { CameraSystem } from "./CameraSystem.js";
 //# sourceMappingURL=CameraSystem3.d.ts.map

package/src/engine/graphics3/CameraSystem3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CameraSystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/CameraSystem3.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;GAgBG;AACH;IAoBI;;OAEG;IACH,uCAQC;IADG,mDAAuC;IAG3C,2CAEC;IAED,4CAIC;IAED;;;;OAIG;IACH,4BAEC;IAED;;;;OAIG;IACH,aAJW,MAAM,aACN,SAAS,UACT,MAAM,QAUhB;IAED;;;;OAIG;IACH,eAJW,MAAM,aACN,SAAS,UACT,MAAM,QAIhB;;CAsEJ;uBAtKsB,kBAAkB;0BACf,+BAA+B;uBAClC,kCAAkC"}
+{"version":3,"file":"CameraSystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/CameraSystem3.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,gDAA0C;6BATb,mBAAmB"}