@woosh/meep-engine 3.21.0 → 3.23.0

package/src/core/primitives/TypedArray.js

@@ -0,0 +1,27 @@
+/**
+ * Any of the ECMAScript typed array views over an `ArrayBuffer`.
+ *
+ * `{TypedArray}` is written in this tree's JSDoc without ever having been declared, in the same way
+ * `{Class}` was — see {@link Class}. There is no such type in the language: `TypedArray` is a
+ * specification abstraction with no global binding, so the name resolved to nothing and every
+ * signature spelled that way emitted as `any`. The union below is what it has always meant.
+ *
+ * Use it where the element type genuinely is not known — a texture readback whose format is decided
+ * at runtime, an attribute buffer that could be any width. Where a function really does take one
+ * width, name that width instead; `ArrayLike<number>` is the better spelling for "indexable, and I
+ * only read numbers out of it".
+ *
+ * @typedef {Int8Array
+ *   | Uint8Array
+ *   | Uint8ClampedArray
+ *   | Int16Array
+ *   | Uint16Array
+ *   | Int32Array
+ *   | Uint32Array
+ *   | Float32Array
+ *   | Float64Array
+ *   | BigInt64Array
+ *   | BigUint64Array} TypedArray
+ */
+
+export {};

package/src/core/process/ConcurrencyGate.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Runs at most {@link max_concurrent} tasks at a time, highest priority first across everything
+ * submitted to it.
+ *
+ * The point of putting one of these between a caller and its work is almost never the cap on its
+ * own — a caller can count its own in-flight requests. It is that **one** gate shared by several
+ * callers orders their work against each other. Per-caller caps do not compose: the number a
+ * browser, a CDN or a disk cares about is the total, and a caller that knows about one file cannot
+ * see it. Neither can a per-caller queue say that the second caller's request matters more than the
+ * first caller's, however truthfully their priorities compare.
+ *
+ * Ties are broken arbitrarily. Two tasks submitted at the same priority are, by the only measure the
+ * gate has, equally worth running.
+ *
+ * Nothing here is a new idea in this engine, which is why it ended up here rather than inside any
+ * one of its callers. `AssetManager` has capped concurrent top-level loads on `load_concurrency` for the
+ * same stated reason — keeping network slots free for higher-priority requests — and orders its
+ * pending queue through `get_pending_asset_priority_score`, which negates the priority for exactly
+ * the reason this heap does: `BinaryHeap` pops the lowest score first. `VirtualTextureManager` caps
+ * `max_concurrent_loads` against `#loads_in_flight`. When the virtual-geometry residency layer
+ * wanted the cap a third time and wrote that same negation a second time, it stopped being a detail
+ * of any one caller. The other two keep their own queues anyway, deliberately, and each says why
+ * where its cap is declared; the three paragraphs below are those reasons.
+ *
+ * **Priority is read once, at {@link submit}.** A gate keyed on a number captured at submission is
+ * the wrong shape for work whose importance moves while it waits, or whose priorities were never on
+ * a common scale: `AssetRequestScope.final_priority` is a richer model than a bare number, but it
+ * propagates hierarchically from an asset's requesting scopes and so compares only inside one
+ * hierarchy. For either, keep a queue over live records and re-score it (see below).
+ *
+ * **A task must not wait on another submission to the same gate.** The parent holds a slot while the
+ * child waits for one, so at a full gate that is a deadlock, and the gate cannot detect it: it sees
+ * a task that has not settled. Work that nests needs the parent's slot to cover the child, which
+ * means dispatching the child over the cap — `AssetManager` does exactly that for the requests its
+ * loaders make while servicing a load, and keeps its own queue for it.
+ *
+ * **What it deliberately is not.** There is no cancellation, and no way to drop or re-order a
+ * submission once it is made: a queued entry holds a closure and the gate will eventually run it.
+ * A caller that wants to *discard* pending work — because the page stopped being on screen, or a
+ * coarser mip arrived instead — wants a queue of live records it can filter, drained on its own
+ * clock, not a gate that owns closures. `VirtualTextureManager` drops queued requests untouched for
+ * `queue_stale_window` frames; it is that second thing, and no worse for it.
+ *
+ * Nothing bounds how long a low-priority submission waits. A caller that keeps feeding the gate
+ * higher-priority work will starve it indefinitely, which is what a priority queue means and is
+ * fine for the admission gates named above — where a dropped want is re-derived next frame — and not
+ * fine for work that has to finish eventually.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ConcurrencyGate {
+    /**
+     * @param {number} max_concurrent how many tasks may be running at once
+     */
+    constructor(max_concurrent: number);
+    /**
+     * Raising this starts whatever was already waiting. Lowering it starts nothing and stops
+     * nothing — tasks already running are left to finish, and the gate admits again once they have
+     * drained below the new value.
+     *
+     * @param {number} value
+     */
+    set max_concurrent(value: number);
+    /**
+     * @returns {number}
+     */
+    get max_concurrent(): number;
+    /**
+     * @returns {number}
+     */
+    get in_flight(): number;
+    /**
+     * @returns {number}
+     */
+    get queued(): number;
+    /**
+     * How many tasks this gate has started. Telemetry.
+     * @returns {number}
+     */
+    get admitted(): number;
+    /**
+     * The most that were ever in flight at once — which should never exceed the cap that was in
+     * force when they started, and is here so that a test can say so rather than assume it.
+     * @returns {number}
+     */
+    get peak_in_flight(): number;
+    /**
+     * Run a task when there is room, highest priority first.
+     *
+     * The task is never invoked synchronously, even when the gate is empty: it runs from a
+     * microtask, so a task that throws on its first line is a rejected promise here rather than an
+     * exception thrown back at whoever called {@link submit}.
+     *
+     * @template T
+     * @param {number} priority higher runs sooner
+     * @param {function(): Promise<T>} task
+     * @returns {Promise<T>} whatever the task settled to, once it ran
+     */
+    submit<T>(priority: number, task: () => Promise<T>): Promise<T>;
+    #private;
+}
+//# sourceMappingURL=ConcurrencyGate.d.ts.map

package/src/core/process/ConcurrencyGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConcurrencyGate.d.ts","sourceRoot":"","sources":["../../../../src/core/process/ConcurrencyGate.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH;IA2BI;;OAEG;IACH,4BAFW,MAAM,EAMhB;IASD;;;;;;OAMG;IACH,kCAMC;IApBD;;OAEG;IACH,6BAEC;IAiBD;;OAEG;IACH,wBAEC;IAED;;OAEG;IACH,qBAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;;OAIG;IACH,6BAEC;IAED;;;;;;;;;;;OAWG;IACH,oBAJW,MAAM,sCAahB;;CA0CJ"}

package/src/core/process/ConcurrencyGate.js

@@ -0,0 +1,207 @@
+import { assert } from "../assert.js";
+import BinaryHeap from "../collection/heap/BinaryHeap.js";
+
+/**
+ * Runs at most {@link max_concurrent} tasks at a time, highest priority first across everything
+ * submitted to it.
+ *
+ * The point of putting one of these between a caller and its work is almost never the cap on its
+ * own — a caller can count its own in-flight requests. It is that **one** gate shared by several
+ * callers orders their work against each other. Per-caller caps do not compose: the number a
+ * browser, a CDN or a disk cares about is the total, and a caller that knows about one file cannot
+ * see it. Neither can a per-caller queue say that the second caller's request matters more than the
+ * first caller's, however truthfully their priorities compare.
+ *
+ * Ties are broken arbitrarily. Two tasks submitted at the same priority are, by the only measure the
+ * gate has, equally worth running.
+ *
+ * Nothing here is a new idea in this engine, which is why it ended up here rather than inside any
+ * one of its callers. `AssetManager` has capped concurrent top-level loads on `load_concurrency` for the
+ * same stated reason — keeping network slots free for higher-priority requests — and orders its
+ * pending queue through `get_pending_asset_priority_score`, which negates the priority for exactly
+ * the reason this heap does: `BinaryHeap` pops the lowest score first. `VirtualTextureManager` caps
+ * `max_concurrent_loads` against `#loads_in_flight`. When the virtual-geometry residency layer
+ * wanted the cap a third time and wrote that same negation a second time, it stopped being a detail
+ * of any one caller. The other two keep their own queues anyway, deliberately, and each says why
+ * where its cap is declared; the three paragraphs below are those reasons.
+ *
+ * **Priority is read once, at {@link submit}.** A gate keyed on a number captured at submission is
+ * the wrong shape for work whose importance moves while it waits, or whose priorities were never on
+ * a common scale: `AssetRequestScope.final_priority` is a richer model than a bare number, but it
+ * propagates hierarchically from an asset's requesting scopes and so compares only inside one
+ * hierarchy. For either, keep a queue over live records and re-score it (see below).
+ *
+ * **A task must not wait on another submission to the same gate.** The parent holds a slot while the
+ * child waits for one, so at a full gate that is a deadlock, and the gate cannot detect it: it sees
+ * a task that has not settled. Work that nests needs the parent's slot to cover the child, which
+ * means dispatching the child over the cap — `AssetManager` does exactly that for the requests its
+ * loaders make while servicing a load, and keeps its own queue for it.
+ *
+ * **What it deliberately is not.** There is no cancellation, and no way to drop or re-order a
+ * submission once it is made: a queued entry holds a closure and the gate will eventually run it.
+ * A caller that wants to *discard* pending work — because the page stopped being on screen, or a
+ * coarser mip arrived instead — wants a queue of live records it can filter, drained on its own
+ * clock, not a gate that owns closures. `VirtualTextureManager` drops queued requests untouched for
+ * `queue_stale_window` frames; it is that second thing, and no worse for it.
+ *
+ * Nothing bounds how long a low-priority submission waits. A caller that keeps feeding the gate
+ * higher-priority work will starve it indefinitely, which is what a priority queue means and is
+ * fine for the admission gates named above — where a dropped want is re-derived next frame — and not
+ * fine for work that has to finish eventually.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ConcurrencyGate {
+    /**
+     * @type {number}
+     */
+    #max_concurrent;
+
+    /**
+     * @type {number}
+     */
+    #in_flight = 0;
+
+    /**
+     * Waiting tasks, highest priority first — a min-heap on the negated priority.
+     * @type {BinaryHeap<{priority: number, task: function(): Promise<*>, resolve: function(*): void, reject: function(*): void}>}
+     */
+    #queue = new BinaryHeap((entry) => -entry.priority);
+
+    /**
+     * @type {number}
+     */
+    #admitted = 0;
+
+    /**
+     * @type {number}
+     */
+    #peak_in_flight = 0;
+
+    /**
+     * @param {number} max_concurrent how many tasks may be running at once
+     */
+    constructor(max_concurrent) {
+        assert.isPositiveInteger(max_concurrent, 'max_concurrent');
+
+        this.#max_concurrent = max_concurrent;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get max_concurrent() {
+        return this.#max_concurrent;
+    }
+
+    /**
+     * Raising this starts whatever was already waiting. Lowering it starts nothing and stops
+     * nothing — tasks already running are left to finish, and the gate admits again once they have
+     * drained below the new value.
+     *
+     * @param {number} value
+     */
+    set max_concurrent(value) {
+        assert.isPositiveInteger(value, 'max_concurrent');
+
+        this.#max_concurrent = value;
+
+        this.#pump();
+    }
+
+    /**
+     * @returns {number}
+     */
+    get in_flight() {
+        return this.#in_flight;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get queued() {
+        return this.#queue.size();
+    }
+
+    /**
+     * How many tasks this gate has started. Telemetry.
+     * @returns {number}
+     */
+    get admitted() {
+        return this.#admitted;
+    }
+
+    /**
+     * The most that were ever in flight at once — which should never exceed the cap that was in
+     * force when they started, and is here so that a test can say so rather than assume it.
+     * @returns {number}
+     */
+    get peak_in_flight() {
+        return this.#peak_in_flight;
+    }
+
+    /**
+     * Run a task when there is room, highest priority first.
+     *
+     * The task is never invoked synchronously, even when the gate is empty: it runs from a
+     * microtask, so a task that throws on its first line is a rejected promise here rather than an
+     * exception thrown back at whoever called {@link submit}.
+     *
+     * @template T
+     * @param {number} priority higher runs sooner
+     * @param {function(): Promise<T>} task
+     * @returns {Promise<T>} whatever the task settled to, once it ran
+     */
+    submit(priority, task) {
+        assert.isNumber(priority, 'priority');
+        assert.isFunction(task, 'task');
+
+        return new Promise((resolve, reject) => {
+            this.#queue.push({ priority, task, resolve, reject });
+
+            this.#pump();
+        });
+    }
+
+    /**
+     * Start whatever fits.
+     */
+    #pump() {
+        while (this.#in_flight < this.#max_concurrent && !this.#queue.isEmpty()) {
+            const entry = this.#queue.pop();
+
+            this.#in_flight++;
+            this.#admitted++;
+
+            if (this.#in_flight > this.#peak_in_flight) {
+                this.#peak_in_flight = this.#in_flight;
+            }
+
+            /*
+             Settled through two explicit branches rather than `.finally`, because `.finally` returns
+             a promise of its own and a rejection travelling through it with nothing attached is an
+             unhandled rejection — which at the scale a gate is reached for is not a warning in a
+             log, it is a process that stops.
+            */
+            const settle = () => {
+                this.#in_flight--;
+
+                this.#pump();
+            };
+
+            Promise.resolve().then(() => entry.task()).then(
+                (value) => {
+                    settle();
+
+                    entry.resolve(value);
+                },
+                (error) => {
+                    settle();
+
+                    entry.reject(error);
+                }
+            );
+        }
+    }
+}

package/src/core/process/buildPromiseChain.d.ts

@@ -1,9 +1,14 @@
 /**
  *
- * @param {Array<function(*):Promise>} factories
- * @param {Promise} [head] chain head, promise to be resolved before rest of the links
- * @param {Array} [parameters] parameters are passed into each factory
+ * @param {Object} options
+ * @param {Array<function(*):Promise>} options.factories
+ * @param {Promise} [options.head] chain head, promise to be resolved before rest of the links
+ * @param {Array} [options.parameters] parameters are passed into each factory
  * @returns {Promise}
  */
-export function buildPromiseChain({ factories, head, parameters }: Array<(arg0: any) => Promise<any>>): Promise<any>;
+export function buildPromiseChain({ factories, head, parameters }: {
+    factories: Array<(arg0: any) => Promise<any>>;
+    head?: Promise<any>;
+    parameters?: any[];
+}): Promise<any>;
 //# sourceMappingURL=buildPromiseChain.d.ts.map

package/src/core/process/buildPromiseChain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildPromiseChain.d.ts","sourceRoot":"","sources":["../../../../src/core/process/buildPromiseChain.js"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,mEALW,kCAA0B,gBAmCpC"}
+{"version":3,"file":"buildPromiseChain.d.ts","sourceRoot":"","sources":["../../../../src/core/process/buildPromiseChain.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH;IAL+C,SAAS,EAA7C,kCAA0B;IACR,IAAI;IACN,UAAU;iBAiCpC"}

package/src/core/process/buildPromiseChain.js

@@ -3,9 +3,10 @@ import { assert } from "../assert.js";
 
 /**
  *
- * @param {Array<function(*):Promise>} factories
- * @param {Promise} [head] chain head, promise to be resolved before rest of the links
- * @param {Array} [parameters] parameters are passed into each factory
+ * @param {Object} options
+ * @param {Array<function(*):Promise>} options.factories
+ * @param {Promise} [options.head] chain head, promise to be resolved before rest of the links
+ * @param {Array} [options.parameters] parameters are passed into each factory
  * @returns {Promise}
  */
 export function buildPromiseChain(

package/src/core/process/executor/ConcurrentExecutor.d.ts

@@ -1,4 +1,6 @@
 export default ConcurrentExecutor;
+export type Task = import("../task/Task.js").Task;
+export type TaskGroup = import("../task/TaskGroup.js").default;
 /**
  * @class
  */

package/src/core/process/executor/ConcurrentExecutor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConcurrentExecutor.d.ts","sourceRoot":"","sources":["../../../../../src/core/process/executor/ConcurrentExecutor.js"],"names":[],"mappings":";AAgBA;;GAEG;AACH;IAaI;;;;;OAKG;IACH,wBAJW,MAAM,aACN,MAAM,EAwChB;IApCG;;;OAGG;IACH,WAFU,MAAM,CAEU;IAC1B;;;OAGG;IACH,UAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,iBAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,YAFU,MAAM,CAEI;IAEpB;;;;MAIC;IAED,cAAiB;IAEjB;;;OAGG;IACH,QAFU,MAAM,GAAC,gBAAgB,CAES;IAG9C;;;OAGG;IACH,qCAmEC;IAED;;;OAGG;IACH,oCAaC;IAED;;;;OAIG;IACH,wBAFY,OAAO,CAwBlB;IAED;;;OAGG;IACH,sBAGC;IAED;;;OAGG;IACH,eAFW,MAAM,QAMhB;IAED;;;;OAIG;IACH,kBAkCC;IAED;;OAEG;IACH,qBAyCC;IAED;;;;OAIG;IACH,sBAFa,OAAO,CAYnB;IAwLD;;;OAGG;IACH,aAQC;IAED,0BAMC;;CACJ;;;;mBA3gBkB,+BAA+B;wBA+gBxC,MAAM"}
+{"version":3,"file":"ConcurrentExecutor.d.ts","sourceRoot":"","sources":["../../../../../src/core/process/executor/ConcurrentExecutor.js"],"names":[],"mappings":";mBAQa,OAAO,iBAAiB,EAAE,IAAI;wBAC9B,OAAO,sBAAsB,EAAE,OAAO;AAYnD;;GAEG;AACH;IAaI;;;;;OAKG;IACH,wBAJW,MAAM,aACN,MAAM,EAwChB;IApCG;;;OAGG;IACH,WAFU,MAAM,CAEU;IAC1B;;;OAGG;IACH,UAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,iBAFU,IAAI,EAAE,CAES;IAEzB;;;OAGG;IACH,YAFU,IAAI,EAAE,CAEI;IAEpB;;;;MAIC;IAED,cAAiB;IAEjB;;;OAGG;IACH,QAFU,MAAM,GAAC,gBAAgB,CAES;IAG9C;;;OAGG;IACH,oBAFW,SAAS,QAqEnB;IAED;;;OAGG;IACH,mBAFW,SAAS,QAenB;IAED;;;;OAIG;IACH,iBAHW,IAAI,GACH,OAAO,CAwBlB;IAED;;;OAGG;IACH,UAFW,IAAI,QAKd;IAED;;;OAGG;IACH,eAFW,IAAI,EAAE,QAMhB;IAED;;;;OAIG;IACH,kBAkCC;IAED;;OAEG;IACH,qBAyCC;IAED;;;;OAIG;IACH,eAHW,IAAI,GACF,OAAO,CAYnB;IAwLD;;;OAGG;IACH,aAQC;IAED,0BAMC;;CACJ;;;;mBAhhBkB,+BAA+B;wBAohBxC,MAAM"}

package/src/core/process/executor/ConcurrentExecutor.js

@@ -5,6 +5,11 @@ import { objectKeyByValue } from "../../model/object/objectKeyByValue.js";
 import { TaskSignal } from "../task/TaskSignal.js";
 import TaskState from "../task/TaskState.js";
 
+/**
+ * @typedef {import("../task/Task.js").Task} Task
+ * @typedef {import("../task/TaskGroup.js").default} TaskGroup
+ */
+
 /**
  *
  * @param {TaskGroup|Task} t

package/src/core/process/task/Task.d.ts

@@ -30,15 +30,23 @@ export class Task {
     static joinAll(tasks: Task[], resolve: Function, reject: Function): void;
     /**
      *
-     * @param {string} [name] useful for identifying the task later on, for various UI and debug purposes
-     * @param {(task: Task, executor: ConcurrentExecutor) => void} [initializer] function to be executed just before task starts
-     * @param {function():TaskSignal} cycleFunction
-     * @param {function():number} [computeProgress]
-     * @param {Task[]} [dependencies=[]]
-     * @param {number} [estimatedDuration=1] in seconds
+     * @param {Object} options
+     * @param {string} [options.name] useful for identifying the task later on, for various UI and debug purposes
+     * @param {(task: Task, executor: ConcurrentExecutor) => void} [options.initializer] function to be executed just before task starts
+     * @param {function():TaskSignal} options.cycleFunction
+     * @param {function():number} [options.computeProgress]
+     * @param {Task[]} [options.dependencies=[]]
+     * @param {number} [options.estimatedDuration=1] in seconds
      * @constructor
      */
-    constructor({ name, initializer, cycleFunction, computeProgress, dependencies, estimatedDuration }?: string);
+    constructor({ name, initializer, cycleFunction, computeProgress, dependencies, estimatedDuration }: {
+        name?: string;
+        initializer?: (task: Task, executor: ConcurrentExecutor) => void;
+        cycleFunction: () => TaskSignal;
+        computeProgress?: () => number;
+        dependencies?: Task[];
+        estimatedDuration?: number;
+    });
     /**
      * @readonly
      * @type {number}
@@ -147,6 +155,8 @@ export class Task {
     readonly isTask: boolean;
 }
 export default Task;
+export type ConcurrentExecutor = import("../executor/ConcurrentExecutor.js").default;
+export type TaskGroup = import("./TaskGroup.js").default;
 import Signal from "../../events/signal/Signal.js";
 import ObservedInteger from "../../model/ObservedInteger.js";
 import { TaskSignal } from "./TaskSignal.js";

package/src/core/process/task/Task.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Task.d.ts","sourceRoot":"","sources":["../../../../../src/core/process/task/Task.js"],"names":[],"mappings":"AAeA;;;GAGG;AACH;IA8NI;;;;OAIG;IACH,yBAHW,MAAM,CAAC,IAAI,YAAU,CAAC,CAAC,gBAOjC;IAED;;;OAGG;IACH,qBAFW,IAAI,YAAU,gBAIxB;IAED;;;;;OAKG;IACH,kBAJW,IAAI,6CAqBd;IAED;;;;;OAKG;IACH,sBAJW,IAAI,EAAE,6CAgChB;IA7PD;;;;;;;;;OASG;IACH,qGARW,MAAM,EA6DhB;IA7GD;;;OAGG;IACH,aAFU,MAAM,CAEE;IAElB;;OAEG;IACH;QACI;;;WAGG;0BADO,MAAM;QAGhB;;;WAGG;4BADO,MAAM;QAGhB;;;WAGG;yBADO,MAAM;MAGlB;IAEF;;;OAGG;IACH,OAFU,eAAe,CAEsB;IAE/C;;;;OAIG;IACH,0BAHU,MAAM,CAGM;IACtB;;;;OAIG;IACH,6BAHU,MAAM,CAGS;IA4BrB;;;OAGG;IACH,cAFU,IAAI,EAAE,CAEgB;IAEhC;;;OAGG;IACH,mBAFU,MAAM,CAE0B;IAE1C;;;OAGG;IACH,MAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,aAFsB,UAAU,CAEN;IAE1B;;;OAGG;IACH,YAFU,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,oBAAoB,KAAK,IAAI,CAE/B;IAWjC,0BAUC;IAED;;;OAGG;IACH,sBAFa,MAAM,CAIlB;IAED,+BAEC;IAED;;;;OAIG;IACH,oBAHW,IAAI,YAAU,QAuBxB;IAED;;;OAGG;IACH,uBAFW,MAAM,CAAC,IAAI,YAAU,CAAC,CAAC,QAWjC;IAED,mBAEC;IAED;;;;OAIG;IACH,gDAEC;IAED;;OAEG;IACH,sBAkBC;IAED;;;OAGG;IACH,wBAEC;IAmFL;;;OAGG;IACH,iBAFU,OAAO,CAEI;CANpB;;mBA9TkB,+BAA+B;4BAGtB,gCAAgC;2BACjC,iBAAiB"}
+{"version":3,"file":"Task.d.ts","sourceRoot":"","sources":["../../../../../src/core/process/task/Task.js"],"names":[],"mappings":"AAoBA;;;GAGG;AACH;IA+NI;;;;OAIG;IACH,yBAHW,MAAM,CAAC,IAAI,GAAC,SAAS,CAAC,CAAC,gBAOjC;IAED;;;OAGG;IACH,qBAFW,IAAI,GAAC,SAAS,gBAIxB;IAED;;;;;OAKG;IACH,kBAJW,IAAI,6CAqBd;IAED;;;;;OAKG;IACH,sBAJW,IAAI,EAAE,6CAgChB;IA9PD;;;;;;;;;;OAUG;IACH;QAR4B,IAAI,GAArB,MAAM;QACuD,WAAW,GAAxE,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,kBAAkB,KAAK,IAAI;QACnB,aAAa,QAAjC,UAAU;QACO,eAAe,SAAhC,MAAM;QACA,YAAY,GAA7B,IAAI,EAAE;QACW,iBAAiB,GAAlC,MAAM;OAwDhB;IA9GD;;;OAGG;IACH,aAFU,MAAM,CAEE;IAElB;;OAEG;IACH;QACI;;;WAGG;0BADO,MAAM;QAGhB;;;WAGG;4BADO,MAAM;QAGhB;;;WAGG;yBADO,MAAM;MAGlB;IAEF;;;OAGG;IACH,OAFU,eAAe,CAEsB;IAE/C;;;;OAIG;IACH,0BAHU,MAAM,CAGM;IACtB;;;;OAIG;IACH,6BAHU,MAAM,CAGS;IA6BrB;;;OAGG;IACH,cAFU,IAAI,EAAE,CAEgB;IAEhC;;;OAGG;IACH,mBAFU,MAAM,CAE0B;IAE1C;;;OAGG;IACH,MAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,aAFsB,UAAU,CAEN;IAE1B;;;OAGG;IACH,YAFU,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,kBAAkB,KAAK,IAAI,CAE/B;IAWjC,0BAUC;IAED;;;OAGG;IACH,sBAFa,MAAM,CAIlB;IAED,+BAEC;IAED;;;;OAIG;IACH,oBAHW,IAAI,GAAC,SAAS,QAuBxB;IAED;;;OAGG;IACH,uBAFW,MAAM,CAAC,IAAI,GAAC,SAAS,CAAC,CAAC,QAWjC;IAED,mBAEC;IAED;;;;OAIG;IACH,gDAEC;IAED;;OAEG;IACH,sBAkBC;IAED;;;OAGG;IACH,wBAEC;IAmFL;;;OAGG;IACH,iBAFU,OAAO,CAEI;CANpB;;iCA5TY,OAAO,mCAAmC,EAAE,OAAO;wBACnD,OAAO,gBAAgB,EAAE,OAAO;mBAT1B,+BAA+B;4BAGtB,gCAAgC;2BACjC,iBAAiB"}

package/src/core/process/task/Task.js

@@ -7,6 +7,11 @@ import ObservedInteger from "../../model/ObservedInteger.js";
 import { TaskSignal } from "./TaskSignal.js";
 import TaskState from "./TaskState.js";
 
+/**
+ * @typedef {import("../executor/ConcurrentExecutor.js").default} ConcurrentExecutor
+ * @typedef {import("./TaskGroup.js").default} TaskGroup
+ */
+
 /**
  *
  * @type {number}
@@ -66,12 +71,13 @@ export class Task {
 
     /**
      *
-     * @param {string} [name] useful for identifying the task later on, for various UI and debug purposes
-     * @param {(task: Task, executor: ConcurrentExecutor) => void} [initializer] function to be executed just before task starts
-     * @param {function():TaskSignal} cycleFunction
-     * @param {function():number} [computeProgress]
-     * @param {Task[]} [dependencies=[]]
-     * @param {number} [estimatedDuration=1] in seconds
+     * @param {Object} options
+     * @param {string} [options.name] useful for identifying the task later on, for various UI and debug purposes
+     * @param {(task: Task, executor: ConcurrentExecutor) => void} [options.initializer] function to be executed just before task starts
+     * @param {function():TaskSignal} options.cycleFunction
+     * @param {function():number} [options.computeProgress]
+     * @param {Task[]} [options.dependencies=[]]
+     * @param {number} [options.estimatedDuration=1] in seconds
      * @constructor
      */
     constructor(

package/src/engine/Engine.d.ts

@@ -1,15 +1,22 @@
 export default Engine;
+export type EnginePlatform = import("./platform/EnginePlatform.js").EnginePlatform;
 declare class Engine {
     /**
      *
      * @param {EnginePlatform} platform
-     * @param {EntityManager} [entityManager]
-     * @param {boolean} [enableGraphics]
-     * @param {boolean} [enableAudio]
-     * @param {boolean} [debug]
+     * @param {Object} [options]
+     * @param {EntityManager} [options.entityManager]
+     * @param {boolean} [options.enableGraphics]
+     * @param {boolean} [options.enableAudio]
+     * @param {boolean} [options.debug]
      * @constructor
      */
-    constructor(platform: EnginePlatform, { entityManager, enableGraphics, enableAudio, debug }?: EntityManager);
+    constructor(platform: EnginePlatform, { entityManager, enableGraphics, enableAudio, debug }?: {
+        entityManager?: EntityManager;
+        enableGraphics?: boolean;
+        enableAudio?: boolean;
+        debug?: boolean;
+    });
     /**
      * Absent when the engine is constructed with `enableGraphics: false`.
      * @type {GraphicsEngine|null}
@@ -60,7 +67,7 @@ declare class Engine {
      */
     performance: MetricCollection;
     __using_external_entity_manager: boolean;
-    entityManager: any;
+    entityManager: EntityManager;
     /**
      *
      * @type {AssetManager<Engine>}
@@ -152,11 +159,15 @@ import { EnginePluginManager } from "./plugin/EnginePluginManager.js";
 import Ticker from "./simulation/Ticker.js";
 import ConcurrentExecutor from '../core/process/executor/ConcurrentExecutor.js';
 import { MetricCollection } from "./development/performance/MetricCollection.js";
+import { EntityManager } from "./ecs/EntityManager.js";
 import { AssetManager } from './asset/AssetManager.js';
 import { PeriodicConsolePrinter } from "./development/performance/monitor/PeriodicConsolePrinter.js";
 import { OptionGroup } from "./options/OptionGroup.js";
 import { ModuleRegistry } from "../core/model/ModuleRegistry.js";
 import { BinarySerializationRegistry } from "./ecs/storage/binary/BinarySerializationRegistry.js";
+/**
+ * @typedef {import("./platform/EnginePlatform.js").EnginePlatform} EnginePlatform
+ */
 declare class EngineSettings {
     graphics_control_viewport_size: ObservedBoolean;
     simulation_speed: Vector1;
@@ -170,7 +181,6 @@ import KeyboardDevice from "./input/devices/KeyboardDevice.js";
 import { GamepadDevice } from "./input/devices/GamepadDevice.js";
 import EmptyView from "../view/elements/EmptyView.js";
 import { AssetPreloader } from "./asset/preloader/AssetPreloader.js";
-import { EntityManager } from "./ecs/EntityManager.js";
 import ObservedBoolean from "../core/model/ObservedBoolean.js";
 import Vector1 from "../core/geom/Vector1.js";
 //# sourceMappingURL=Engine.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Engine.d.ts","sourceRoot":"","sources":["../../../src/engine/Engine.js"],"names":[],"mappings":";AA6DA;IAoEI;;;;;;;;OAQG;IACH,8FANW,aAAa,EA8OvB;IA/RD;;;OAGG;IACH,UAFU,cAAc,GAAC,IAAI,CAEb;IAEhB;;;OAGG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IAEb,qBAA4B;IAE5B;;;;;;;;;OASG;IACH,0BAFU,uBAAuB,CAEe;IAEhD;;;OAGG;IACH,kBAFU,mBAAmB,CAEO;IAEpC;;;;OAIG;IACH,iBAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,mBAFU,kBAAkB,CAEa;IAmBrC;;;OAGG;IACH,yBAAwB;IAKxB;;;OAGG;IACH,aAFU,gBAAgB,CAEe;IAGzC,yCAAkE;IAK9D,mBAAkC;IAMtC;;;OAGG;IACH,cAFU,aAAa,MAAM,CAAC,CAK5B;IAEF,8CAiCE;IA4BF;;;OAGG;IACH,SAFU,WAAW,CAEoB;IAEzC;;;OAGG;IACH,oCAA0C;IAE1C;;;OAGG;IACH,sCAFU,2BAA2B,CAE+B;IAEpE,yBAAoC;IAGpC;;OAEG;IACH,aAAkB;IAElB;;;OAGG;IACH,SAFU,OAAO,CAEwB;IAGzC,2BAAsC;IAuCtC;;;OAGG;IACH,KAFU,SAAS,CAEO;IAE1B;;;OAGG;IACH,uBAFU,YAAY,CAEqD;IAI3E;;;;MAIC;IA6BD;;;OAGG;IACH,kBAFU,OAAO,CAEW;IAwIhC,wBAgCC;IApBG,oBAAwB;IAsB5B,2BAgCC;IAED,oBAiBC;IAED;;;OAGG;IACH,+CAUC;IAED,eA6BC;IAED;;;OAGG;IACH,sBAkEC;IAqBD;;OAEG;IACH,sBAyCC;IAED,aAEC;IAED;;OAEG;IACH,4BAOC;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;;CAPxB;+BA/vB8B,+BAA+B;wBAUtC,wBAAwB;0BApBtB,0CAA0C;wCAcN,iDAAiD;oCAG3E,iCAAiC;mBAElD,wBAAwB;+BArBZ,gDAAgD;iCAO9C,+CAA+C;6BAFnD,yBAAyB;uCAIf,6DAA6D;4BASxE,0BAA0B;+BApBvB,iCAAiC;4CAapB,qDAAqD;AAgBjG;IACI,gDAA2D;IAC3D,0BAAkC;IAClC,iCAAyC;CAC5C;6BAlC4B,sCAAsC;sBA2B7C,mBAAmB;yBAJhB,yBAAyB;8BALpB,kCAAkC;2BADrC,mCAAmC;8BADhC,kCAAkC;sBAZ1C,+BAA+B;+BAKtB,qCAAqC;8BAItC,wBAAwB;4BAX1B,kCAAkC;oBAH1C,yBAAyB"}
+{"version":3,"file":"Engine.d.ts","sourceRoot":"","sources":["../../../src/engine/Engine.js"],"names":[],"mappings":";6BAoCa,OAAO,8BAA8B,EAAE,cAAc;AA6BlE;IAoEI;;;;;;;;;OASG;IACH,sBARW,cAAc;QAEU,aAAa,GAArC,aAAa;QACK,cAAc,GAAhC,OAAO;QACW,WAAW,GAA7B,OAAO;QACW,KAAK,GAAvB,OAAO;OA2OjB;IAhSD;;;OAGG;IACH,UAFU,cAAc,GAAC,IAAI,CAEb;IAEhB;;;OAGG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IAEb,qBAA4B;IAE5B;;;;;;;;;OASG;IACH,0BAFU,uBAAuB,CAEe;IAEhD;;;OAGG;IACH,kBAFU,mBAAmB,CAEO;IAEpC;;;;OAIG;IACH,iBAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,mBAFU,kBAAkB,CAEa;IAoBrC;;;OAGG;IACH,UAFU,cAAc,CAEA;IAKxB;;;OAGG;IACH,aAFU,gBAAgB,CAEe;IAGzC,yCAAkE;IAK9D,6BAAkC;IAMtC;;;OAGG;IACH,cAFU,aAAa,MAAM,CAAC,CAK5B;IAEF,8CAiCE;IA4BF;;;OAGG;IACH,SAFU,WAAW,CAEoB;IAEzC;;;OAGG;IACH,oCAA0C;IAE1C;;;OAGG;IACH,sCAFU,2BAA2B,CAE+B;IAEpE,yBAAoC;IAGpC;;OAEG;IACH,aAAkB;IAElB;;;OAGG;IACH,SAFU,OAAO,CAEwB;IAGzC,2BAAsC;IAuCtC;;;OAGG;IACH,KAFU,SAAS,CAEO;IAE1B;;;OAGG;IACH,uBAFU,YAAY,CAEqD;IAI3E;;;;MAIC;IA6BD;;;OAGG;IACH,kBAFU,OAAO,CAEW;IAwIhC,wBAgCC;IApBG,oBAAwB;IAsB5B,2BAgCC;IAED,oBAiBC;IAED;;;OAGG;IACH,+CAUC;IAED,eA6BC;IAED;;;OAGG;IACH,sBAkEC;IAqBD;;OAEG;IACH,sBAyCC;IAED,aAEC;IAED;;OAEG;IACH,4BAOC;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;;CAPxB;+BApwB8B,+BAA+B;wBAUtC,wBAAwB;0BApBtB,0CAA0C;wCAcN,iDAAiD;oCAG3E,iCAAiC;mBAElD,wBAAwB;+BArBZ,gDAAgD;iCAO9C,+CAA+C;8BAGlD,wBAAwB;6BALzB,yBAAyB;uCAIf,6DAA6D;4BASxE,0BAA0B;+BApBvB,iCAAiC;4CAapB,qDAAqD;AAejG;;GAEG;AAGH;IACI,gDAA2D;IAC3D,0BAAkC;IAClC,iCAAyC;CAC5C;6BAtC4B,sCAAsC;sBA2B7C,mBAAmB;yBAJhB,yBAAyB;8BALpB,kCAAkC;2BADrC,mCAAmC;8BADhC,kCAAkC;sBAZ1C,+BAA+B;+BAKtB,qCAAqC;4BAPxC,kCAAkC;oBAH1C,yBAAyB"}

package/src/engine/Engine.js

@@ -33,6 +33,10 @@ import SoundEngine from './sound/SoundEngine.js';
 
 import GUIEngine from './ui/GUIEngine.js';
 
+/**
+ * @typedef {import("./platform/EnginePlatform.js").EnginePlatform} EnginePlatform
+ */
+
 
 class EngineSettings {
     graphics_control_viewport_size = new ObservedBoolean(true);
@@ -130,10 +134,11 @@ class Engine {
     /**
      *
      * @param {EnginePlatform} platform
-     * @param {EntityManager} [entityManager]
-     * @param {boolean} [enableGraphics]
-     * @param {boolean} [enableAudio]
-     * @param {boolean} [debug]
+     * @param {Object} [options]
+     * @param {EntityManager} [options.entityManager]
+     * @param {boolean} [options.enableGraphics]
+     * @param {boolean} [options.enableAudio]
+     * @param {boolean} [options.debug]
      * @constructor
      */
     constructor(platform, {