@woosh/meep-engine 3.2.0 → 3.4.0

package/src/core/color/PQ/PQ_to_linear.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PQ_to_linear.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/PQ/PQ_to_linear.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,iCAPW,MAAM,GACJ,MAAM,CAalB"}

package/src/core/color/PQ/PQ_to_linear.js

@@ -0,0 +1,35 @@
+import { PQ_C1, PQ_C2, PQ_C3, PQ_M1, PQ_M2 } from "./PQ_constants.js";
+
+const PQ_M1_INV = 1 / PQ_M1;
+const PQ_M2_INV = 1 / PQ_M2;
+
+/**
+ * SMPTE ST 2084 EOTF: decode a PQ signal back to linear light. Exact inverse of {@link linear_to_PQ}.
+ *
+ * NORMALIZATION: the result is in PQ's own scale, where `1.0` is {@link PQ_MAX_NITS} (10000 nits) --
+ * not the engine's, where `1.0` is {@link SDR_WHITE_NITS} (203 nits). Divide by
+ * {@link PQ_SDR_WHITE_LINEAR} to land back in engine units:
+ *
+ * ```js
+ * const engine_linear = PQ_to_linear(pq) / PQ_SDR_WHITE_LINEAR;
+ * ```
+ *
+ * The numerator is clamped at `0` so that signals below `linear_to_PQ(0)` -- which the standard's
+ * curve never produces, but quantization and interpolation both do -- decode to black instead of
+ * `NaN` from a negative base under a fractional exponent.
+ *
+ * @param {number} pq PQ signal, in `[0, 1]`
+ * @returns {number} linear light, `1.0` = 10000 nits
+ * @see linear_to_PQ
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function PQ_to_linear(pq) {
+    const y = Math.pow(pq, PQ_M2_INV);
+
+    const numerator = Math.max(y - PQ_C1, 0);
+    const denominator = PQ_C2 - PQ_C3 * y;
+
+    return Math.pow(numerator / denominator, PQ_M1_INV);
+}

package/src/core/color/PQ/linear_to_PQ.d.ts

@@ -0,0 +1,27 @@
+/**
+ * SMPTE ST 2084 OETF: encode a linear light value as a PQ signal.
+ *
+ * NORMALIZATION: the input is in PQ's own scale, where `1.0` is {@link PQ_MAX_NITS} (10000 nits) --
+ * not the engine's, where `1.0` is {@link SDR_WHITE_NITS} (203 nits). Scale an engine-normalized
+ * value by {@link PQ_SDR_WHITE_LINEAR} first:
+ *
+ * ```js
+ * const pq = linear_to_PQ(engine_linear * PQ_SDR_WHITE_LINEAR);
+ * ```
+ *
+ * Keeping the transfer function free of any white-point convention is what makes it and
+ * {@link PQ_to_linear} an exact inverse pair; a scale folded into one side but not the other is the
+ * classic way this round-trip ends up off by a factor of ~49.
+ *
+ * Negative input is clamped to `0`, since `Math.pow` of a negative base to a fractional exponent is
+ * `NaN` and a linear light value below zero has no PQ encoding to give.
+ *
+ * @param {number} linear linear light, `1.0` = 10000 nits
+ * @returns {number} PQ signal, in `[0, 1]`
+ * @see PQ_to_linear
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function linear_to_PQ(linear: number): number;
+//# sourceMappingURL=linear_to_PQ.d.ts.map

package/src/core/color/PQ/linear_to_PQ.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linear_to_PQ.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/PQ/linear_to_PQ.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qCAPW,MAAM,GACJ,MAAM,CAUlB"}

package/src/core/color/PQ/linear_to_PQ.js

@@ -0,0 +1,32 @@
+import { PQ_C1, PQ_C2, PQ_C3, PQ_M1, PQ_M2 } from "./PQ_constants.js";
+
+/**
+ * SMPTE ST 2084 OETF: encode a linear light value as a PQ signal.
+ *
+ * NORMALIZATION: the input is in PQ's own scale, where `1.0` is {@link PQ_MAX_NITS} (10000 nits) --
+ * not the engine's, where `1.0` is {@link SDR_WHITE_NITS} (203 nits). Scale an engine-normalized
+ * value by {@link PQ_SDR_WHITE_LINEAR} first:
+ *
+ * ```js
+ * const pq = linear_to_PQ(engine_linear * PQ_SDR_WHITE_LINEAR);
+ * ```
+ *
+ * Keeping the transfer function free of any white-point convention is what makes it and
+ * {@link PQ_to_linear} an exact inverse pair; a scale folded into one side but not the other is the
+ * classic way this round-trip ends up off by a factor of ~49.
+ *
+ * Negative input is clamped to `0`, since `Math.pow` of a negative base to a fractional exponent is
+ * `NaN` and a linear light value below zero has no PQ encoding to give.
+ *
+ * @param {number} linear linear light, `1.0` = 10000 nits
+ * @returns {number} PQ signal, in `[0, 1]`
+ * @see PQ_to_linear
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function linear_to_PQ(linear) {
+    const y = Math.pow(Math.max(linear, 0), PQ_M1);
+
+    return Math.pow((PQ_C1 + PQ_C2 * y) / (1 + PQ_C3 * y), PQ_M2);
+}

package/src/core/geom/3d/topology/struct/binary/query/bt_edge_other_face.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The first face on `edge_id`'s radial cycle that is not `face_id`, or {@link NULL_POINTER} when the
+ * edge has no such face.
+ *
+ * On a manifold interior edge -- two faces -- that is unambiguously "the face on the other side", which
+ * is what callers walking across a mesh want. The other configurations are worth being explicit about,
+ * because the answer is only interesting in the first case:
+ *
+ *   - a wire edge (no faces) or a boundary edge whose one face IS `face_id`: {@link NULL_POINTER};
+ *   - a non-manifold edge (three faces or more): whichever of the others the radial base pointer
+ *     happens to reach first, which a caller cannot predict. Use {@link bt_edge_count_faces} first if
+ *     that distinction matters;
+ *   - an edge that `face_id` uses twice: the walk skips both of its loops and reports a genuine
+ *     neighbour, rather than reporting `face_id` back.
+ *
+ * Passing a `face_id` that is not on the edge at all is not detected -- it simply reports the edge's
+ * first face. That matches {@link bt_edge_other_vertex}, whose contract is the same shape.
+ *
+ * The walk is bounded by the loop pool's size, so a corrupted radial cycle cannot hang the caller; a
+ * cycle that long is broken, and {@link bt_mesh_validate} will say where.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} edge_id
+ * @param {number} face_id the face already known to sit on this edge
+ * @returns {number} face id, or {@link NULL_POINTER}
+ * @see bt_edge_other_vertex
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bt_edge_other_face(mesh: BinaryTopology, edge_id: number, face_id: number): number;
+//# sourceMappingURL=bt_edge_other_face.d.ts.map

package/src/core/geom/3d/topology/struct/binary/query/bt_edge_other_face.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bt_edge_other_face.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/query/bt_edge_other_face.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,kEARW,MAAM,WACN,MAAM,GACJ,MAAM,CAgClB"}

package/src/core/geom/3d/topology/struct/binary/query/bt_edge_other_face.js

@@ -0,0 +1,59 @@
+import { NULL_POINTER } from "../BinaryTopology.js";
+
+/**
+ * The first face on `edge_id`'s radial cycle that is not `face_id`, or {@link NULL_POINTER} when the
+ * edge has no such face.
+ *
+ * On a manifold interior edge -- two faces -- that is unambiguously "the face on the other side", which
+ * is what callers walking across a mesh want. The other configurations are worth being explicit about,
+ * because the answer is only interesting in the first case:
+ *
+ *   - a wire edge (no faces) or a boundary edge whose one face IS `face_id`: {@link NULL_POINTER};
+ *   - a non-manifold edge (three faces or more): whichever of the others the radial base pointer
+ *     happens to reach first, which a caller cannot predict. Use {@link bt_edge_count_faces} first if
+ *     that distinction matters;
+ *   - an edge that `face_id` uses twice: the walk skips both of its loops and reports a genuine
+ *     neighbour, rather than reporting `face_id` back.
+ *
+ * Passing a `face_id` that is not on the edge at all is not detected -- it simply reports the edge's
+ * first face. That matches {@link bt_edge_other_vertex}, whose contract is the same shape.
+ *
+ * The walk is bounded by the loop pool's size, so a corrupted radial cycle cannot hang the caller; a
+ * cycle that long is broken, and {@link bt_mesh_validate} will say where.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} edge_id
+ * @param {number} face_id the face already known to sit on this edge
+ * @returns {number} face id, or {@link NULL_POINTER}
+ * @see bt_edge_other_vertex
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bt_edge_other_face(mesh, edge_id, face_id) {
+    const start = mesh.edge_read_loop(edge_id);
+
+    if (start === NULL_POINTER) {
+        // wire edge, no faces at all
+        return NULL_POINTER;
+    }
+
+    const limit = mesh.loops.size;
+
+    let loop = start;
+    let visited = 0;
+
+    do {
+        const face = mesh.loop_read_face(loop);
+
+        if (face !== face_id) {
+            return face;
+        }
+
+        visited++;
+
+        loop = mesh.loop_read_radial_next(loop);
+    } while (loop !== start && loop !== NULL_POINTER && visited <= limit);
+
+    return NULL_POINTER;
+}

package/src/core/geom/3d/topology/struct/binary/query/bt_face_third_vertex.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The corner of `face_id` that lies on neither end of `edge_id` -- the apex of a triangle over that
+ * edge -- or {@link NULL_POINTER} when the face has no such corner.
+ *
+ * The edge is read for its two endpoints only; it is never required to be one of the face's own edges.
+ * A caller that hands over an unrelated edge therefore gets the face's first corner rather than an
+ * error, the same contract {@link bt_edge_other_vertex} carries.
+ *
+ * "Third" names the intended use, not a precondition: the face loop is walked to its end, so a polygon
+ * with more corners reports the first one clear of the edge. {@link NULL_POINTER} comes back for an
+ * face with no loop, and for a face all of whose corners sit on the edge -- a degenerate triangle with a
+ * repeated vertex, which {@link bt_mesh_validate} counts as a defect.
+ *
+ * The walk is bounded by the loop pool's size, so a corrupted face cycle cannot hang the caller.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} face_id
+ * @param {number} edge_id
+ * @returns {number} vertex id, or {@link NULL_POINTER}
+ * @see bt_edge_read_diamond for both apexes of an interior edge, with winding respected
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bt_face_third_vertex(mesh: BinaryTopology, face_id: number, edge_id: number): number;
+//# sourceMappingURL=bt_face_third_vertex.d.ts.map

package/src/core/geom/3d/topology/struct/binary/query/bt_face_third_vertex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bt_face_third_vertex.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/query/bt_face_third_vertex.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,oEARW,MAAM,WACN,MAAM,GACJ,MAAM,CAkClB"}

package/src/core/geom/3d/topology/struct/binary/query/bt_face_third_vertex.js

@@ -0,0 +1,55 @@
+import { NULL_POINTER } from "../BinaryTopology.js";
+
+/**
+ * The corner of `face_id` that lies on neither end of `edge_id` -- the apex of a triangle over that
+ * edge -- or {@link NULL_POINTER} when the face has no such corner.
+ *
+ * The edge is read for its two endpoints only; it is never required to be one of the face's own edges.
+ * A caller that hands over an unrelated edge therefore gets the face's first corner rather than an
+ * error, the same contract {@link bt_edge_other_vertex} carries.
+ *
+ * "Third" names the intended use, not a precondition: the face loop is walked to its end, so a polygon
+ * with more corners reports the first one clear of the edge. {@link NULL_POINTER} comes back for an
+ * face with no loop, and for a face all of whose corners sit on the edge -- a degenerate triangle with a
+ * repeated vertex, which {@link bt_mesh_validate} counts as a defect.
+ *
+ * The walk is bounded by the loop pool's size, so a corrupted face cycle cannot hang the caller.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} face_id
+ * @param {number} edge_id
+ * @returns {number} vertex id, or {@link NULL_POINTER}
+ * @see bt_edge_read_diamond for both apexes of an interior edge, with winding respected
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bt_face_third_vertex(mesh, face_id, edge_id) {
+    const start = mesh.face_read_loop(face_id);
+
+    if (start === NULL_POINTER) {
+        return NULL_POINTER;
+    }
+
+    const edge_v1 = mesh.edge_read_vertex1(edge_id);
+    const edge_v2 = mesh.edge_read_vertex2(edge_id);
+
+    const limit = mesh.loops.size;
+
+    let loop = start;
+    let visited = 0;
+
+    do {
+        const vertex = mesh.loop_read_vertex(loop);
+
+        if (vertex !== edge_v1 && vertex !== edge_v2) {
+            return vertex;
+        }
+
+        visited++;
+
+        loop = mesh.loop_read_next(loop);
+    } while (loop !== start && loop !== NULL_POINTER && visited <= limit);
+
+    return NULL_POINTER;
+}

package/src/engine/EntityCreator.d.ts

@@ -1,25 +1,33 @@
 /**
+ * Builds a fire-and-forget sound entity: it plays once and destroys itself when the sound ends.
+ *
+ * Two things destroy it, and both are needed. The emitter's `on.ended` is the normal path — the moment
+ * the sound stops, the entity goes, which is what lets callers await its destruction as "the sound
+ * finished". The `Delay(timeout) + Die` behaviour is the backstop for the sound that never ends on its
+ * own: an asset that fails or never arrives, or an event that loops.
+ *
+ * The event's `maxInstances` is left at its default (32, stealing oldest). Content-equal sounds share
+ * one polyphony bucket, so a burst of identical UI clicks degrades by stealing rather than by piling
+ * up — 32 is ample for that, and the 256 the legacy translator used existed to emulate "play
+ * everything", which a click does not need.
  *
  * @param {Vector3} [position]
- * @param {number} [timeout]
+ * @param {number} [timeout] seconds before the backstop kills the entity regardless
  * @param {String} [url]
- * @param {SoundTrack} [track]
+ * @param {EventDescription} [event]
  * @param {boolean} [positioned]
- * @param {String|SoundEmitterChannels} [channel]
+ * @param {String|SopraDefaultBus} [channel]
  * @param {number} [volume]
  * @returns {Entity}
  */
-export function createSound({ position, timeout, url, track, positioned, channel, volume }?: Vector3): Entity;
+export function createSound({ position, timeout, url, event, positioned, channel, volume }?: Vector3): Entity;
 /**
- *
- * @param timeout
- * @param action
+ * Builds an entity that runs the given action once, after the timeout, and then destroys itself.
+ * @param {number} timeout in seconds
+ * @param {function} action
  * @returns {Entity}
  */
-export function createTimer({ timeout, action }: {
-    timeout: any;
-    action: any;
-}): Entity;
+export function createTimer({ timeout, action }: number): Entity;
 import Vector3 from "../core/geom/Vector3.js";
 import Entity from './ecs/Entity.js';
 //# sourceMappingURL=EntityCreator.d.ts.map

package/src/engine/EntityCreator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EntityCreator.d.ts","sourceRoot":"","sources":["../../../src/engine/EntityCreator.js"],"names":[],"mappings":"AAYA;;;;;;;;;;GAUG;AACH,6FATW,OAAO,GAOL,MAAM,CAiDlB;AAED;;;;;GAKG;AACH;;;IAFa,MAAM,CAkBlB;oBA9FmB,yBAAyB;mBAG1B,iBAAiB"}
+{"version":3,"file":"EntityCreator.d.ts","sourceRoot":"","sources":["../../../src/engine/EntityCreator.js"],"names":[],"mappings":"AAwCA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,6FATW,OAAO,GAOL,MAAM,CAmClB;AAED;;;;;GAKG;AACH,iDAJW,MAAM,GAEJ,MAAM,CAelB;oBApHmB,yBAAyB;mBAE1B,iBAAiB"}

package/src/engine/EntityCreator.js

@@ -1,95 +1,117 @@
-import Vector3 from "../core/geom/Vector3.js";
-import { SerializationMetadata } from "./ecs/components/SerializationMetadata.js";
-import Timer from './ecs/components/Timer.js';
-import Entity from './ecs/Entity.js';
-import { Transform } from './ecs/transform/Transform.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 { SoundEmitterChannels } from "./sound/ecs/emitter/SoundEmitterSystem.js";
-
-/**
- *
- * @param {Vector3} [position]
- * @param {number} [timeout]
- * @param {String} [url]
- * @param {SoundTrack} [track]
- * @param {boolean} [positioned]
- * @param {String|SoundEmitterChannels} [channel]
- * @param {number} [volume]
- * @returns {Entity}
- */
-export function createSound(
-    {
-        position = Vector3.zero,
-        timeout = 60,
-        url,
-
-        track,
-        positioned = true,
-        channel = SoundEmitterChannels.Effects,
-        volume = 1
-    }
-) {
-
-    const builder = new Entity();
-
-    let trackJSON;
-
-    if (url !== undefined) {
-        trackJSON = {
-            url: url,
-            startWhenReady: true
-        };
-    } else {
-        trackJSON = track.toJSON();
-    }
-
-    const soundEmitter = SoundEmitter.fromJSON({
-        tracks: [trackJSON],
-        isPositioned: positioned,
-        volume: volume,
-        loop: false,
-        channel
-    });
-
-
-    const soundTrack = soundEmitter.tracks.last();
-    soundTrack.on.ended.add(builder.destroy, builder);
-
-    builder
-        .add(SerializationMetadata.Transient) //make sound transient
-        .add(BehaviorComponent.from(SequenceBehavior.from([
-            DelayBehavior.from(timeout),
-            DieBehavior.create()
-        ])))
-        .add(Transform.fromJSON({ position: position }))
-        .add(soundEmitter);
-    return builder;
-}
-
-/**
- *
- * @param timeout
- * @param action
- * @returns {Entity}
- */
-export function createTimer({ timeout, action }) {
-    const builder = new Entity();
-
-    function suicide() {
-        builder.destroy();
-    }
-
-    builder.add(new Timer({
-        timeout,
-        actions: [
-            action,
-            suicide
-        ]
-    }));
-
-    return builder;
+import Vector3 from "../core/geom/Vector3.js";
+import { SerializationMetadata } from "./ecs/components/SerializationMetadata.js";
+import Entity from './ecs/Entity.js';
+import { Transform } from './ecs/transform/Transform.js';
+import { SequenceBehavior } from "./intelligence/behavior/composite/SequenceBehavior.js";
+import { IgnoreFailureBehavior } from "./intelligence/behavior/decorator/IgnoreFailureBehavior.js";
+import { BehaviorComponent } from "./intelligence/behavior/ecs/BehaviorComponent.js";
+import { DieBehavior } from "./intelligence/behavior/ecs/DieBehavior.js";
+import { ActionBehavior } from "./intelligence/behavior/primitive/ActionBehavior.js";
+import { DelayBehavior } from "./intelligence/behavior/util/DelayBehavior.js";
+import { AudioEmitter } from "./sound/ecs/audio/AudioEmitter.js";
+import { SampleAudioClip } from "./sound/sopra/definition/clip/SampleAudioClip.js";
+import { EventDescription } from "./sound/sopra/definition/EventDescription.js";
+import { SopraPanningModel } from "./sound/sopra/definition/SopraPanningModel.js";
+import { SopraDefaultBus } from "./sound/sopra/SopraEngine.js";
+
+/**
+ * What a one-shot sound entity is asked to play: either an authored {@link EventDescription}, played
+ * as-is (it already owns its bus and its spatialization, so `channel` and `positioned` do not apply to
+ * it), or a `url` to play once.
+ *
+ * @param {EventDescription} [event]
+ * @param {String} [url]
+ * @param {boolean} [positioned] 3D (attenuates and pans by distance) vs 2D. Ignored when `event` is given
+ * @param {String|SopraDefaultBus} [channel] bus to route to. Ignored when `event` is given
+ * @returns {EventDescription}
+ */
+function resolveSoundEvent({ event, url, positioned, channel }) {
+    if (event !== undefined) {
+        return event;
+    }
+
+    // A 2D sound is position-independent, so it neither attenuates nor pans.
+    return EventDescription.from(url, SampleAudioClip.from(url, { loop: false }), {
+        busId: channel,
+        is3D: positioned,
+        panningModel: positioned ? SopraPanningModel.HRTF : SopraPanningModel.None
+    });
+}
+
+/**
+ * Builds a fire-and-forget sound entity: it plays once and destroys itself when the sound ends.
+ *
+ * Two things destroy it, and both are needed. The emitter's `on.ended` is the normal path — the moment
+ * the sound stops, the entity goes, which is what lets callers await its destruction as "the sound
+ * finished". The `Delay(timeout) + Die` behaviour is the backstop for the sound that never ends on its
+ * own: an asset that fails or never arrives, or an event that loops.
+ *
+ * The event's `maxInstances` is left at its default (32, stealing oldest). Content-equal sounds share
+ * one polyphony bucket, so a burst of identical UI clicks degrades by stealing rather than by piling
+ * up — 32 is ample for that, and the 256 the legacy translator used existed to emulate "play
+ * everything", which a click does not need.
+ *
+ * @param {Vector3} [position]
+ * @param {number} [timeout] seconds before the backstop kills the entity regardless
+ * @param {String} [url]
+ * @param {EventDescription} [event]
+ * @param {boolean} [positioned]
+ * @param {String|SopraDefaultBus} [channel]
+ * @param {number} [volume]
+ * @returns {Entity}
+ */
+export function createSound(
+    {
+        position = Vector3.zero,
+        timeout = 60,
+        url,
+        event,
+
+        positioned = true,
+        channel = SopraDefaultBus.Effects,
+        volume = 1
+    }
+) {
+
+    const builder = new Entity();
+
+    const emitter = new AudioEmitter();
+
+    emitter.event = resolveSoundEvent({ event, url, positioned, channel });
+    emitter.volume.set(volume);
+    emitter.autoplay = true;
+
+    emitter.on.ended.add(builder.destroy, builder);
+
+    builder
+        .add(SerializationMetadata.Transient) //make sound transient
+        .add(BehaviorComponent.from(SequenceBehavior.from([
+            DelayBehavior.from(timeout),
+            DieBehavior.create()
+        ])))
+        .add(Transform.fromJSON({ position: position }))
+        .add(emitter);
+
+    return builder;
+}
+
+/**
+ * Builds an entity that runs the given action once, after the timeout, and then destroys itself.
+ * @param {number} timeout in seconds
+ * @param {function} action
+ * @returns {Entity}
+ */
+export function createTimer({ timeout, action }) {
+    const builder = new Entity();
+
+    builder
+        .add(SerializationMetadata.Transient) //a pending timer is not part of the world state
+        .add(BehaviorComponent.from(SequenceBehavior.from([
+            DelayBehavior.from(timeout),
+            //a throwing action must not strand the entity, callers wait on its destruction
+            IgnoreFailureBehavior.from(ActionBehavior.from(action)),
+            DieBehavior.create()
+        ])));
+
+    return builder;
 }

package/src/engine/achievements/AchievementManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AchievementManager.d.ts","sourceRoot":"","sources":["../../../../src/engine/achievements/AchievementManager.js"],"names":[],"mappings":"AA0CA;IAGI;;;OAGG;IACH,SAFU,qBAAmB,IAAI,CAElB;IAEf;;;OAGG;IACH,SAFU,WAAW,EAAE,CAEV;IAEb;;;OAGG;IACH,cAFU,eAAa,IAAI,CAEP;IAEpB;;;OAGG;IACH,YAFU,aAAW,IAAI,CAEP;IAElB;;;OAGG;IACH,eAFU,gBAAc,IAAI,CAEP;IAErB;;;OAGG;IACH,cAFU,eAAa,IAAI,CAEP;IAIhB;;;OAGG;IACH,oBAFU,eAAe,CAEkB;IAE3C;;;OAGG;IACH,+BAFU,eAAe,CAE6B;IAEtD;;;OAGG;IACH,+BAFU,eAAe,CAE6B;IAEtD;;;OAGG;IACH,mBAFU,WAAW,CAKpB;IAUD,aAAkB;IAGtB;;;;OAIG;IACH,gCAFY,WAAW,GAAC,SAAS,CAIhC;IAGD;;;OAGG;IACH,yBA6BC;IAED;;;OAGG;IACH,sBAcC;IAED;;;OAGG;IACH,wBAUC;IAGD;;OAEG;IACH,iBAUC;IAED;;OAEG;IACH,mBAMC;IAED,uCAMC;IAED;;;OAGG;IACH,2DAaC;IAED;;;OAGG;IACH,qBAFW,WAAW,QA2FrB;IAED;;;OAGG;IACH,+CAOC;IAED,mCAoDC;IAED,yBASC;IAED,0BAEC;CACJ;6BAxZ4B,2BAA2B;4BAG5B,kBAAkB;4BAxBlB,qCAAqC;4BACrC,sDAAsD"}
+{"version":3,"file":"AchievementManager.d.ts","sourceRoot":"","sources":["../../../../src/engine/achievements/AchievementManager.js"],"names":[],"mappings":"AAkDA;IAGI;;;OAGG;IACH,SAFU,qBAAmB,IAAI,CAElB;IAEf;;;OAGG;IACH,SAFU,WAAW,EAAE,CAEV;IAEb;;;OAGG;IACH,cAFU,eAAa,IAAI,CAEP;IAEpB;;;OAGG;IACH,YAFU,aAAW,IAAI,CAEP;IAElB;;;OAGG;IACH,eAFU,gBAAc,IAAI,CAEP;IAErB;;;OAGG;IACH,cAFU,eAAa,IAAI,CAEP;IAIhB;;;OAGG;IACH,oBAFU,eAAe,CAEkB;IAE3C;;;OAGG;IACH,+BAFU,eAAe,CAE6B;IAEtD;;;OAGG;IACH,+BAFU,eAAe,CAE6B;IAEtD;;;OAGG;IACH,mBAFU,WAAW,CAKpB;IAUD,aAAkB;IAGtB;;;;OAIG;IACH,gCAFY,WAAW,GAAC,SAAS,CAIhC;IAGD;;;OAGG;IACH,yBA6BC;IAED;;;OAGG;IACH,sBAcC;IAED;;;OAGG;IACH,wBAUC;IAGD;;OAEG;IACH,iBAUC;IAED;;OAEG;IACH,mBAMC;IAED,uCAMC;IAED;;;OAGG;IACH,2DAaC;IAED;;;OAGG;IACH,qBAFW,WAAW,QAuFrB;IAED;;;OAGG;IACH,+CAOC;IAED,mCAoDC;IAED,yBASC;IAED,0BAEC;CACJ;6BA5Z4B,2BAA2B;4BAK5B,kBAAkB;4BA1BlB,qCAAqC;4BACrC,sDAAsD"}