@woosh/meep-engine 3.2.0 → 3.4.0

package/src/engine/ecs/util/hideEntityGracefully.js

@@ -1,208 +1,196 @@
-import {
-    TransitionPropertyVectorXBehavior
-} from "../../../../../model/game/story/behaviors/generic/TransitionPropertyVectorXBehavior.js";
-import { TweenVector1Behavior } from "../../../../../model/game/util/behavior/TweenVector1Behavior.js";
-import { TweenVector3Behavior } from "../../../../../model/game/util/behavior/TweenVector3Behavior.js";
-import { max2 } from "../../../core/math/max2.js";
-import { min2 } from "../../../core/math/min2.js";
-import { Light } from "../../graphics/ecs/light/Light.js";
-import { SGMesh, SGMeshFlags } from "../../graphics/ecs/mesh-v2/aggregate/SGMesh.js";
-import Trail2D from "../../graphics/ecs/trail2d/Trail2D.js";
-import { Trail2DFlags } from "../../graphics/ecs/trail2d/Trail2DFlags.js";
-import { ParticleEmitter } from "../../graphics/particles/particular/engine/emitter/ParticleEmitter.js";
-import { ParticleEmitterFlag } from "../../graphics/particles/particular/engine/emitter/ParticleEmitterFlag.js";
-import { SequenceBehavior } from "../../intelligence/behavior/composite/SequenceBehavior.js";
-import { BehaviorComponent } from "../../intelligence/behavior/ecs/BehaviorComponent.js";
-import { DieBehavior } from "../../intelligence/behavior/ecs/DieBehavior.js";
-import { DelayBehavior } from "../../intelligence/behavior/util/DelayBehavior.js";
-import { SoundEmitter } from "../../sound/ecs/emitter/SoundEmitter.js";
-import { Transform } from "../transform/Transform.js";
-
-/**
- * @readonly
- * @type {number}
- */
-const SHUTDOWN_GRACE_PERIOD = 60;
-
-/**
- *
- * @type {Map<Class|function, (component: T, entity?: Entity, createEntity?: function, createEntityContext?: *) => number>}
- */
-const component_shutdown = new Map();
-
-/**
- * @template T
- * @param {Class<T>} type
- * @param {(component: T, entity?: Entity, createEntity?: function, createEntityContext?: *) => number} method
- */
-function addShutdown(type, method) {
-    component_shutdown.set(type, method);
-}
-
-addShutdown(ParticleEmitter, emitter => {
-
-    //stop emission
-    emitter.clearFlag(ParticleEmitterFlag.Emitting);
-
-    //figure out how long the emitter should stay alive
-    const maxLife = emitter.computeMaxEmittingParticleLife(SHUTDOWN_GRACE_PERIOD);
-
-    return maxLife;
-});
-
-addShutdown(Trail2D, trail => {
-    trail.clearFlag(Trail2DFlags.Spawning);
-
-    return trail.maxAge;
-});
-
-addShutdown(SGMesh, (mesh, builder, createEntity, createEntityThisArg) => {
-
-    /**
-     *
-     * @type {Transform}
-     */
-    const transform = builder.getComponent(Transform);
-
-    let delay = 0;
-
-    if (mesh !== null && transform !== null) {
-
-        /*
-         Loaded only. The component this used to read carried an `InView` flag a CPU culling pass
-         wrote, and §4.5 retires that pass — nothing on either renderer can say whether an entity is
-         on screen now, so what is left is whether there is a model to shrink at all.
-        */
-        if (mesh.getFlag(SGMeshFlags.Loaded) && !transform.scale.isZero()) {
-            const scale = new TweenVector3Behavior();
-
-            scale.startValue.copy(transform.scale);
-            scale.targetValue.set(0, 0, 0);
-            scale.target = transform.scale;
-
-            scale.duration = 0.2;
-
-            delay = max2(scale.duration, delay);
-
-            const eb = createEntity.call(createEntityThisArg);
-
-            eb.add(BehaviorComponent.from(SequenceBehavior.from([
-                scale,
-                DieBehavior.create()
-            ])));
-
-        } else {
-            transform.scale.set(0, 0, 0);
-        }
-
-    }
-
-
-    return delay;
-});
-
-addShutdown(Light, (light, builder, createEntity, createEntityThisArg) => {
-
-
-    let delay = 0.2;
-
-
-    const eb = createEntity.call(createEntityThisArg);
-
-    eb.add(BehaviorComponent.from(SequenceBehavior.from([
-        TransitionPropertyVectorXBehavior.from({
-            component: 'Light',
-            path: 'intensity',
-            target: [0],
-            duration: delay,
-            entity: builder.id
-        }),
-        DieBehavior.create()
-    ])));
-
-    return delay;
-});
-
-addShutdown(SoundEmitter, (soundEmitter, builder, createEntity, createEntityThisArg) => {
-    let delay = 0;
-
-    if (soundEmitter.volume.getValue() > 0) {
-
-        const tracks = soundEmitter.tracks.asArray();
-
-        const n = tracks.length;
-
-
-        for (let i = 0; i < n; i++) {
-            const soundTrack = tracks[i];
-
-            if (soundTrack.volume > 0) {
-
-                const setVolume = new TweenVector1Behavior();
-
-                setVolume.startValue = soundEmitter.volume.getValue();
-                setVolume.targetValue = 0;
-
-                setVolume.target = soundEmitter.volume;
-
-                setVolume.duration = 2.7;
-
-                delay = SHUTDOWN_GRACE_PERIOD;
-
-                const eb = createEntity.call(createEntityThisArg);
-
-                eb.add(BehaviorComponent.from(SequenceBehavior.from([
-                    DelayBehavior.from(SHUTDOWN_GRACE_PERIOD - setVolume.duration),
-                    setVolume,
-                    DieBehavior.create()
-                ])));
-
-                break;
-            }
-        }
-    }
-
-    return delay;
-});
-
-/**
- *
- * @param {Entity} builder
- * @param {function():Entity} createEntity
- * @param {*} [createEntityThisArg]
- * @return {number} duration in seconds until the entity is completely hidden
- */
-export function hideEntityGracefully(builder, createEntity, createEntityThisArg) {
-    if (!builder.isBuilt) {
-        // already destroyed
-        return 0;
-    }
-
-    let delay = 0;
-
-    const components = builder.components;
-
-    const component_count = components.length;
-
-    for (let i = 0; i < component_count; i++) {
-        const component = components[i];
-
-        const shutdown_method = component_shutdown.get(Object.getPrototypeOf(component).constructor);
-
-        if (shutdown_method === undefined) {
-            continue;
-        }
-
-        const sd = shutdown_method(component, builder, createEntity, createEntityThisArg);
-
-        if (Number.isNaN(sd) || !Number.isFinite(sd)) {
-            continue;
-        }
-
-        delay = max2(sd, delay);
-    }
-
-    delay = min2(delay, SHUTDOWN_GRACE_PERIOD);
-
-    return delay;
-}
+import {
+    TransitionPropertyVectorXBehavior
+} from "../../../../../model/game/story/behaviors/generic/TransitionPropertyVectorXBehavior.js";
+import { TweenVector1Behavior } from "../../../../../model/game/util/behavior/TweenVector1Behavior.js";
+import { TweenVector3Behavior } from "../../../../../model/game/util/behavior/TweenVector3Behavior.js";
+import { max2 } from "../../../core/math/max2.js";
+import { min2 } from "../../../core/math/min2.js";
+import { Light } from "../../graphics/ecs/light/Light.js";
+import { SGMesh, SGMeshFlags } from "../../graphics/ecs/mesh-v2/aggregate/SGMesh.js";
+import Trail2D from "../../graphics/ecs/trail2d/Trail2D.js";
+import { Trail2DFlags } from "../../graphics/ecs/trail2d/Trail2DFlags.js";
+import { ParticleEmitter } from "../../graphics/particles/particular/engine/emitter/ParticleEmitter.js";
+import { ParticleEmitterFlag } from "../../graphics/particles/particular/engine/emitter/ParticleEmitterFlag.js";
+import { SequenceBehavior } from "../../intelligence/behavior/composite/SequenceBehavior.js";
+import { BehaviorComponent } from "../../intelligence/behavior/ecs/BehaviorComponent.js";
+import { DieBehavior } from "../../intelligence/behavior/ecs/DieBehavior.js";
+import { DelayBehavior } from "../../intelligence/behavior/util/DelayBehavior.js";
+import { AudioEmitter } from "../../sound/ecs/audio/AudioEmitter.js";
+import { Transform } from "../transform/Transform.js";
+
+/**
+ * @readonly
+ * @type {number}
+ */
+const SHUTDOWN_GRACE_PERIOD = 60;
+
+/**
+ *
+ * @type {Map<Class|function, (component: T, entity?: Entity, createEntity?: function, createEntityContext?: *) => number>}
+ */
+const component_shutdown = new Map();
+
+/**
+ * @template T
+ * @param {Class<T>} type
+ * @param {(component: T, entity?: Entity, createEntity?: function, createEntityContext?: *) => number} method
+ */
+function addShutdown(type, method) {
+    component_shutdown.set(type, method);
+}
+
+addShutdown(ParticleEmitter, emitter => {
+
+    //stop emission
+    emitter.clearFlag(ParticleEmitterFlag.Emitting);
+
+    //figure out how long the emitter should stay alive
+    const maxLife = emitter.computeMaxEmittingParticleLife(SHUTDOWN_GRACE_PERIOD);
+
+    return maxLife;
+});
+
+addShutdown(Trail2D, trail => {
+    trail.clearFlag(Trail2DFlags.Spawning);
+
+    return trail.maxAge;
+});
+
+addShutdown(SGMesh, (mesh, builder, createEntity, createEntityThisArg) => {
+
+    /**
+     *
+     * @type {Transform}
+     */
+    const transform = builder.getComponent(Transform);
+
+    let delay = 0;
+
+    if (mesh !== null && transform !== null) {
+
+        /*
+         Loaded only. The component this used to read carried an `InView` flag a CPU culling pass
+         wrote, and §4.5 retires that pass — nothing on either renderer can say whether an entity is
+         on screen now, so what is left is whether there is a model to shrink at all.
+        */
+        if (mesh.getFlag(SGMeshFlags.Loaded) && !transform.scale.isZero()) {
+            const scale = new TweenVector3Behavior();
+
+            scale.startValue.copy(transform.scale);
+            scale.targetValue.set(0, 0, 0);
+            scale.target = transform.scale;
+
+            scale.duration = 0.2;
+
+            delay = max2(scale.duration, delay);
+
+            const eb = createEntity.call(createEntityThisArg);
+
+            eb.add(BehaviorComponent.from(SequenceBehavior.from([
+                scale,
+                DieBehavior.create()
+            ])));
+
+        } else {
+            transform.scale.set(0, 0, 0);
+        }
+
+    }
+
+
+    return delay;
+});
+
+addShutdown(Light, (light, builder, createEntity, createEntityThisArg) => {
+
+
+    let delay = 0.2;
+
+
+    const eb = createEntity.call(createEntityThisArg);
+
+    eb.add(BehaviorComponent.from(SequenceBehavior.from([
+        TransitionPropertyVectorXBehavior.from({
+            component: 'Light',
+            path: 'intensity',
+            target: [0],
+            duration: delay,
+            entity: builder.id
+        }),
+        DieBehavior.create()
+    ])));
+
+    return delay;
+});
+
+addShutdown(AudioEmitter, (audioEmitter, builder, createEntity, createEntityThisArg) => {
+    // `autoplay` is the "is anything actually sounding" test: a non-autoplay emitter is inert —
+    // AudioEmitterSystem never played it — so there is nothing to fade out. A live `volume` write
+    // reaches the instance gain on both play routes, managed and direct, so tweening the component is
+    // all this has to do.
+    if (audioEmitter.volume.getValue() <= 0 || !audioEmitter.autoplay) {
+        return 0;
+    }
+
+    const setVolume = new TweenVector1Behavior();
+
+    setVolume.startValue = audioEmitter.volume.getValue();
+    setVolume.targetValue = 0;
+
+    setVolume.target = audioEmitter.volume;
+
+    // the sound keeps playing through the grace period and fades over its last 2.7 seconds
+    setVolume.duration = 2.7;
+
+    const eb = createEntity.call(createEntityThisArg);
+
+    eb.add(BehaviorComponent.from(SequenceBehavior.from([
+        DelayBehavior.from(SHUTDOWN_GRACE_PERIOD - setVolume.duration),
+        setVolume,
+        DieBehavior.create()
+    ])));
+
+    return SHUTDOWN_GRACE_PERIOD;
+});
+
+/**
+ *
+ * @param {Entity} builder
+ * @param {function():Entity} createEntity
+ * @param {*} [createEntityThisArg]
+ * @return {number} duration in seconds until the entity is completely hidden
+ */
+export function hideEntityGracefully(builder, createEntity, createEntityThisArg) {
+    if (!builder.isBuilt) {
+        // already destroyed
+        return 0;
+    }
+
+    let delay = 0;
+
+    const components = builder.components;
+
+    const component_count = components.length;
+
+    for (let i = 0; i < component_count; i++) {
+        const component = components[i];
+
+        const shutdown_method = component_shutdown.get(Object.getPrototypeOf(component).constructor);
+
+        if (shutdown_method === undefined) {
+            continue;
+        }
+
+        const sd = shutdown_method(component, builder, createEntity, createEntityThisArg);
+
+        if (Number.isNaN(sd) || !Number.isFinite(sd)) {
+            continue;
+        }
+
+        delay = max2(sd, delay);
+    }
+
+    delay = min2(delay, SHUTDOWN_GRACE_PERIOD);
+
+    return delay;
+}

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

@@ -0,0 +1,90 @@
+/**
+ * A baked volumetric lightmap, as the bytes the GPU wants and nothing else.
+ *
+ * **The scene has one of these, and this component is which one.** Shade keeps a single
+ * `Brick4LightMap` per scene — one buffer, read by every indirect-lighting pass while the renderer
+ * is in Brick4 mode — so a level's lightmap is a property of the level, not of a thing standing in
+ * it. Making it a component is what gives it a lifetime an entity already has: it arrives when the
+ * level's entity is built, it is saved with it, and it goes away when the entity does. See
+ * {@link VolumetricLightMapSystem3} for what happens when two entities claim the scene at once.
+ *
+ * **The payload is opaque here on purpose.** It is brick4's own GPU structure — the format
+ * `brick4_to_gpu_structure` writes and the indirect-lighting shaders read — and everything inside
+ * it, the node layout, the probe section, the SH encoding, is the renderer's business. This
+ * component neither validates it nor knows how to make one; a bake writes it, a load reads it off
+ * disk, and this carries it.
+ *
+ * **It is not placed by the entity's transform, and does not need one.** A brick4 structure begins
+ * with the world-space bounds it was baked against, so the map already knows where it is. Moving
+ * the entity that carries it moves nothing.
+ *
+ * @see VolumetricLightMapSystem3
+ * @see Brick4LightMap
+ */
+export class VolumetricLightMap {
+    /**
+     * @param {*} json
+     * @returns {VolumetricLightMap}
+     */
+    static fromJSON(json: any): VolumetricLightMap;
+    /**
+     * @param {ArrayBuffer|null} value
+     */
+    set data(arg: ArrayBuffer);
+    /**
+     * The baked structure, or `null` while there isn't one.
+     *
+     * `null` is a normal state, not a broken one: the component says the entity carries the scene's
+     * lightmap, and the bytes may still be loading. A `null` map lights the scene with nothing.
+     *
+     * @returns {ArrayBuffer|null}
+     */
+    get data(): ArrayBuffer;
+    /**
+     * Bumped every time {@link data} is assigned.
+     *
+     * What the system watches to decide whether the GPU is behind. A megabyte-scale upload per frame
+     * would be the alternative, and comparing the buffers to avoid it costs a full read of both.
+     *
+     * **Assignment is the only thing that moves this.** Writing into the `ArrayBuffer` in place goes
+     * unnoticed — publish such a change by assigning `data` again, even to the same buffer.
+     *
+     * @returns {number}
+     */
+    get version(): number;
+    /**
+     * The bytes, base64'd.
+     *
+     * A lightmap runs to megabytes and base64 adds a third on top of that, so this is the expensive
+     * way to move one and the binary adapter is the cheap one. It exists because a blueprint that
+     * silently dropped the map would be worse than a large blueprint.
+     *
+     * @see VolumetricLightMapSerializationAdapter
+     */
+    toJSON(): {
+        data: string;
+    };
+    /**
+     * @param {string|null} [data]
+     */
+    fromJSON({ data }?: string | null): void;
+    /**
+     * The byte length, and deliberately not the bytes.
+     *
+     * Hashing megabytes to answer "are these two the same component" is not a trade worth making,
+     * and a hash is allowed to collide. {@link equals} is the one that reads the buffer.
+     *
+     * @returns {number}
+     */
+    hash(): number;
+    /**
+     * @param {VolumetricLightMap} other
+     * @returns {boolean}
+     */
+    equals(other: VolumetricLightMap): boolean;
+    #private;
+}
+export namespace VolumetricLightMap {
+    let typeName: string;
+}
+//# sourceMappingURL=VolumetricLightMap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VolumetricLightMap.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/VolumetricLightMap.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAoDI;;;OAGG;IACH,4BAFa,kBAAkB,CAQ9B;IAtCD;;OAEG;IACH,2BAQC;IAvBD;;;;;;;OAOG;IACH,wBAEC;IAeD;;;;;;;;;;OAUG;IACH,sBAEC;IAcD;;;;;;;;OAQG;IACH;;MAIC;IAED;;OAEG;IACH,oBAFW,MAAM,GAAC,IAAI,QAYrB;IAED;;;;;;;OAOG;IACH,QAFa,MAAM,CAMlB;IAED;;;OAGG;IACH,cAHW,kBAAkB,GAChB,OAAO,CAenB;;CACJ;;kBAIS,MAAM"}

package/src/engine/graphics3/VolumetricLightMap.js

@@ -0,0 +1,160 @@
+import { assert } from "../../core/assert.js";
+import { Base64 } from "../../core/binary/base64/Base64.js";
+import { is_array_buffer_equals } from "../../core/collection/array/typed/is_array_buffer_equals.js";
+
+/**
+ * A baked volumetric lightmap, as the bytes the GPU wants and nothing else.
+ *
+ * **The scene has one of these, and this component is which one.** Shade keeps a single
+ * `Brick4LightMap` per scene — one buffer, read by every indirect-lighting pass while the renderer
+ * is in Brick4 mode — so a level's lightmap is a property of the level, not of a thing standing in
+ * it. Making it a component is what gives it a lifetime an entity already has: it arrives when the
+ * level's entity is built, it is saved with it, and it goes away when the entity does. See
+ * {@link VolumetricLightMapSystem3} for what happens when two entities claim the scene at once.
+ *
+ * **The payload is opaque here on purpose.** It is brick4's own GPU structure — the format
+ * `brick4_to_gpu_structure` writes and the indirect-lighting shaders read — and everything inside
+ * it, the node layout, the probe section, the SH encoding, is the renderer's business. This
+ * component neither validates it nor knows how to make one; a bake writes it, a load reads it off
+ * disk, and this carries it.
+ *
+ * **It is not placed by the entity's transform, and does not need one.** A brick4 structure begins
+ * with the world-space bounds it was baked against, so the map already knows where it is. Moving
+ * the entity that carries it moves nothing.
+ *
+ * @see VolumetricLightMapSystem3
+ * @see Brick4LightMap
+ */
+export class VolumetricLightMap {
+
+    /**
+     * @type {ArrayBuffer|null}
+     */
+    #data = null;
+
+    /**
+     * @type {number}
+     */
+    #version = 0;
+
+    /**
+     * The baked structure, or `null` while there isn't one.
+     *
+     * `null` is a normal state, not a broken one: the component says the entity carries the scene's
+     * lightmap, and the bytes may still be loading. A `null` map lights the scene with nothing.
+     *
+     * @returns {ArrayBuffer|null}
+     */
+    get data() {
+        return this.#data;
+    }
+
+    /**
+     * @param {ArrayBuffer|null} value
+     */
+    set data(value) {
+        if (value !== null) {
+            assert.isInstanceOf(value, ArrayBuffer, 'data');
+        }
+
+        this.#data = value;
+
+        this.#version++;
+    }
+
+    /**
+     * Bumped every time {@link data} is assigned.
+     *
+     * What the system watches to decide whether the GPU is behind. A megabyte-scale upload per frame
+     * would be the alternative, and comparing the buffers to avoid it costs a full read of both.
+     *
+     * **Assignment is the only thing that moves this.** Writing into the `ArrayBuffer` in place goes
+     * unnoticed — publish such a change by assigning `data` again, even to the same buffer.
+     *
+     * @returns {number}
+     */
+    get version() {
+        return this.#version;
+    }
+
+    /**
+     * @param {*} json
+     * @returns {VolumetricLightMap}
+     */
+    static fromJSON(json) {
+        const r = new VolumetricLightMap();
+
+        r.fromJSON(json);
+
+        return r;
+    }
+
+    /**
+     * The bytes, base64'd.
+     *
+     * A lightmap runs to megabytes and base64 adds a third on top of that, so this is the expensive
+     * way to move one and the binary adapter is the cheap one. It exists because a blueprint that
+     * silently dropped the map would be worse than a large blueprint.
+     *
+     * @see VolumetricLightMapSerializationAdapter
+     */
+    toJSON() {
+        return {
+            data: this.#data === null ? null : Base64.encode(this.#data)
+        };
+    }
+
+    /**
+     * @param {string|null} [data]
+     */
+    fromJSON({ data = null }) {
+        if (data === null) {
+            this.data = null;
+
+            return;
+        }
+
+        assert.isString(data, 'data');
+
+        this.data = Base64.decode(data);
+    }
+
+    /**
+     * The byte length, and deliberately not the bytes.
+     *
+     * Hashing megabytes to answer "are these two the same component" is not a trade worth making,
+     * and a hash is allowed to collide. {@link equals} is the one that reads the buffer.
+     *
+     * @returns {number}
+     */
+    hash() {
+        const data = this.#data;
+
+        return data === null ? 0 : data.byteLength;
+    }
+
+    /**
+     * @param {VolumetricLightMap} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        const a = this.#data;
+        const b = other.data;
+
+        if (a === null || b === null) {
+            return a === b;
+        }
+
+        if (a.byteLength !== b.byteLength) {
+            return false;
+        }
+
+        return is_array_buffer_equals(a, 0, b, 0, a.byteLength);
+    }
+}
+
+/**
+ * @readonly
+ * @type {string}
+ */
+VolumetricLightMap.typeName = "VolumetricLightMap";