@vworlds/vecs 1.0.0

package/dist/system.js

@@ -0,0 +1,396 @@
+import { ArrayMap } from "./util/array_map.js";
+import { Bitset } from "./util/bitset.js";
+import { OrderedSet } from "./util/ordered_set.js";
+import { Component, calculateComponentBitmask, } from "./component.js";
+import { Phase } from "./phase.js";
+function HAS(world, ...components) {
+    const testBitmask = calculateComponentBitmask(components, world);
+    return (e) => e.componentBitmask.hasBitset(testBitmask);
+}
+function HAS_ONLY(world, ...components) {
+    const testBitmask = calculateComponentBitmask(components, world);
+    return (e) => e.componentBitmask.equal(testBitmask);
+}
+function NOT(func) {
+    return (e) => !func(e);
+}
+function AND(...funcs) {
+    return (e) => funcs.every((f) => f(e));
+}
+function OR(...funcs) {
+    return (e) => funcs.some((f) => f(e));
+}
+function PARENT(func) {
+    return (e) => (e.parent && func(e.parent)) || false;
+}
+const EMPTY_ENTITIES = new Set();
+export class System {
+    constructor(
+    /** Unique name for this system, used in logs and pipeline output. */
+    name, 
+    /** The world that owns this system. */
+    world) {
+        this.name = name;
+        this.world = world;
+        this.componentUpdateCallbacks = new ArrayMap();
+        this._enterCallback = [];
+        this._exitCallback = [];
+        this._belongs = (e) => false;
+        this.updateQueue = [];
+        this.hasQuery = false;
+        this.watchlistBitmask = new Bitset();
+    }
+    /** Returns the system name. */
+    toString() {
+        return this.name;
+    }
+    /**
+     * Read-only view of the entities currently tracked by this system.
+     *
+     * Empty unless {@link track} (or {@link each}, which implies it) was
+     * called during system configuration.
+     */
+    get entities() {
+        return this._entities ?? EMPTY_ENTITIES;
+    }
+    /**
+     * Assign this system to a pipeline phase.
+     *
+     * The phase can be specified by name (the world will resolve it at
+     * {@link World.start | start} time) or by an {@link IPhase} reference
+     * returned from {@link World.addPhase}. Systems without an explicit phase
+     * are placed in the built-in `"update"` phase.
+     *
+     * @param p - Phase name or `IPhase` reference.
+     * @returns `this` for chaining.
+     */
+    phase(p) {
+        if (typeof p !== "string") {
+            if (!(p instanceof Phase))
+                throw "Invalid Phase object";
+            if (p.world !== this.world)
+                throw "Phase does not belong to this system's world";
+        }
+        this._phase = p;
+        return this;
+    }
+    /** @internal Delivers a component-modified notification to this system. */
+    notifyModified(c) {
+        if (!this.watchlistBitmask.hasBit(c.bitPtr))
+            return;
+        this.updateQueue.push(c);
+    }
+    /** Returns `true` if the entity satisfies this system's query. */
+    belongs(e) {
+        return this._belongs(e);
+    }
+    /** @internal Fires `enter` callbacks for a newly matched entity. */
+    _enter(e) {
+        this._enterCallback.forEach((callback) => callback(e));
+        e.forEachComponent((c) => this.notifyModified(c));
+        this._entities?.add(e);
+    }
+    /** @internal Fires `exit` callbacks when an entity leaves the system. */
+    _exit(e) {
+        this._exitCallback.forEach((callback) => callback(e));
+        this._entities?.delete(e);
+        // remove queued updates for components of the exiting entity:
+        this.updateQueue.forEach((c, i) => {
+            if (!c)
+                return;
+            if (c.entity === e)
+                this.updateQueue[i] = undefined;
+        });
+    }
+    /** @internal Execute one tick: run `run`, fire `each`, then drain the update queue. */
+    _run(now, delta) {
+        if (this._runCallback)
+            this._runCallback(now, delta);
+        if (this.eachCallback) {
+            const cb = this.eachCallback;
+            this._entities?.forEach((e) => cb(e));
+        }
+        this.updateQueue.forEach((c) => {
+            if (!c)
+                return;
+            const callback = this.componentUpdateCallbacks.get(c.type);
+            if (callback) {
+                callback(c);
+            }
+        });
+        this.updateQueue.length = 0;
+    }
+    getComponent(e, C, considerDeleted) {
+        let c;
+        if (typeof C === "number") {
+            c = e.get(C, considerDeleted); // obtain an instance of C
+        }
+        else {
+            c = e.parent && e.parent.get(C.parent, considerDeleted);
+        }
+        return c;
+    }
+    getInjected(e, inject, considerDeleted = false) {
+        const injected = [];
+        inject.forEach((C) => {
+            const c = this.getComponent(e, C, considerDeleted);
+            if (!c)
+                throw "system does not contain component";
+            injected.push(c);
+        });
+        return injected;
+    }
+    mapInjectedClassToTypes(inject) {
+        //map injected class constructors to type numbers which are faster to search for later
+        return inject.map((C) => {
+            if (typeof C === "function")
+                return this.world.getComponentType(C);
+            return { parent: this.world.getComponentType(C.parent) };
+        });
+    }
+    // Implement the overloaded function
+    enter(injectOrCallback, callback) {
+        if (typeof injectOrCallback === "function") {
+            // It is the second signature
+            this._enterCallback.push(injectOrCallback);
+        }
+        else {
+            // It is the first signature
+            const inject = this.mapInjectedClassToTypes(injectOrCallback);
+            this._enterCallback.push((e) => {
+                callback(e, this.getInjected(e, inject));
+            });
+        }
+        return this;
+    }
+    // Implement the overloaded function
+    exit(injectOrCallback, callback) {
+        if (typeof injectOrCallback === "function") {
+            // It is the second signature
+            this._exitCallback.push(injectOrCallback);
+        }
+        else {
+            // It is the first signature
+            const inject = this.mapInjectedClassToTypes(injectOrCallback);
+            this._exitCallback.push((e) => {
+                callback(e, this.getInjected(e, inject, true));
+            });
+        }
+        return this;
+    }
+    /**
+     * Register a per-tick callback that runs every time this system's phase
+     * executes, regardless of entity membership.
+     *
+     * Use this for logic that is not driven by component updates — polling,
+     * network flushing, global timers, etc.
+     *
+     * @param callback - Receives `now` (absolute timestamp in ms) and `delta`
+     *   (ms since the last tick).
+     * @returns `this` for chaining.
+     */
+    run(callback) {
+        this._runCallback = callback;
+        return this;
+    }
+    update(ComponentClass, injectOrCallback, callback) {
+        const type = this.world.getComponentType(ComponentClass);
+        if (typeof injectOrCallback === "function") {
+            // Only ComponentClass and callback are passed
+            callback = injectOrCallback;
+            this.componentUpdateCallbacks.set(type, callback);
+        }
+        else {
+            // ComponentClass, inject, and callback are passed
+            const inject = injectOrCallback;
+            //map injected class constructors to component type numbers which are faster to search for later
+            const injectedComponentTypes = inject.map((C) => this.world.getComponentType(C));
+            const cb = (c) => {
+                const injected = [];
+                injectedComponentTypes.forEach((InjectedComponentType) => {
+                    injected.push(c.entity.get(InjectedComponentType));
+                });
+                if (callback) {
+                    callback(c, injected);
+                }
+            };
+            this.componentUpdateCallbacks.set(type, cb);
+        }
+        this.watchlistBitmask.add(type);
+        if (!this.hasQuery) {
+            const watchlist = this.watchlistBitmask.indices();
+            this._belongs = HAS(this.world, ...watchlist);
+        }
+        return this;
+    }
+    /**
+     * Register a callback that fires **every tick** for every entity currently
+     * tracked by this system, with the listed components resolved from each
+     * entity.
+     *
+     * Unlike {@link update} (which only fires when `component.modified()` is
+     * called), `each` fires unconditionally on every tick the system runs,
+     * once per tracked entity. Components declared via {@link requires} are
+     * guaranteed non-null in the resolved tuple; any other component class
+     * may be `undefined` if the entity lacks it.
+     *
+     * `each` does **not** modify the system's query — define membership with
+     * {@link requires} or {@link query} as usual. It does, however, implicitly
+     * enable {@link track}, so matched entities are exposed via {@link entities}.
+     *
+     * Only a single `each` callback may be registered per system; calling
+     * `each` a second time throws.
+     *
+     * @param components - Component classes to resolve from each entity.
+     * @param callback - Receives the entity and a tuple of resolved component
+     *   instances (`undefined` for components not covered by {@link requires}).
+     * @returns `this` for chaining.
+     * @throws If `each` has already been registered on this system.
+     *
+     * @example
+     * ```ts
+     * world.system("Move")
+     *   .requires(Position, Velocity)
+     *   .each([Position, Velocity], (e, [pos, vel]) => {
+     *     pos.x += vel.vx;
+     *     pos.y += vel.vy;
+     *   });
+     * ```
+     */
+    each(components, callback) {
+        if (this.eachCallback) {
+            throw `each already registered for system '${this.name}'`;
+        }
+        this.track();
+        const types = components.map((C) => this.world.getComponentType(C));
+        this.eachCallback = (e) => {
+            const resolved = types.map((t) => e.get(t));
+            callback(e, resolved);
+        };
+        return this;
+    }
+    /**
+     * Enable entity tracking: matched entities are inserted into
+     * {@link entities} as they enter the system and removed as they exit.
+     *
+     * Idempotent. Intended to be called during system configuration before
+     * `world.start()`; entities already matched when `track` is called late
+     * will not be backfilled.
+     *
+     * {@link each} implies `track` — call this directly only when you want
+     * the tracked set without an `each` callback.
+     *
+     * @returns `this` for chaining.
+     */
+    track() {
+        this._entities ?? (this._entities = new Set());
+        return this;
+    }
+    /**
+     * Enable sorted entity tracking: matched entities are stored in insertion
+     * order determined by `compare`, which receives a tuple of resolved
+     * component instances for each pair of entities being ordered.
+     *
+     * Implies {@link track}.
+     *
+     * @param components - Component classes to resolve and pass to `compare`.
+     * @param compare - Returns a negative number, zero, or positive number when
+     *   `a` should sort before, equal to, or after `b`.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * world.system("Render")
+     *   .requires(Position, Sprite)
+     *   .sort([Position], ([posA], [posB]) => posA.z - posB.z);
+     * ```
+     */
+    sort(components, compare) {
+        const types = components.map((C) => this.world.getComponentType(C));
+        this._entities = new OrderedSet((a, b) => compare(types.map((t) => a.get(t, true)), types.map((t) => b.get(t, true))));
+        return this;
+    }
+    queryBuilder(q) {
+        if (typeof q === "number" ||
+            (typeof q === "function" && q.prototype instanceof Component)) {
+            return HAS(this.world, q);
+        }
+        else if (typeof q === "function") {
+            return q;
+        }
+        if (q instanceof Array) {
+            return HAS(this.world, ...q);
+        }
+        if ("HAS" in q) {
+            return this.queryBuilder(q.HAS);
+        }
+        if ("HAS_ONLY" in q) {
+            const v = q.HAS_ONLY;
+            if (v instanceof Array) {
+                return HAS_ONLY(this.world, ...v);
+            }
+            return HAS_ONLY(this.world, v);
+        }
+        if ("AND" in q) {
+            return AND(...q.AND.map((sq) => this.queryBuilder(sq)));
+        }
+        if ("OR" in q) {
+            return OR(...q.OR.map((sq) => this.queryBuilder(sq)));
+        }
+        if ("NOT" in q) {
+            return NOT(this.queryBuilder(q.NOT));
+        }
+        if ("PARENT" in q) {
+            return PARENT(this.queryBuilder(q.PARENT));
+        }
+        throw "Unrecognized query term";
+    }
+    /**
+     * Set the entity membership predicate using the {@link SystemQuery} DSL.
+     *
+     * Replaces any implicit query derived from `update` watchlists and any
+     * previous `requires` call. After calling `query`, auto-expanding of
+     * `update` watchlists is disabled.
+     *
+     * The optional `guaranteed` tuple is a pure type-level hint: it tells
+     * `sort`, `each`, and `update` callbacks which components are guaranteed
+     * to be present on every matched entity, eliminating `| undefined` from
+     * those positions. It has no effect at runtime.
+     *
+     * @param q - A {@link SystemQuery} expression.
+     * @param _guaranteed - Component classes guaranteed present on every matched
+     *   entity (type hint only — not validated at runtime).
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * world.system("Move")
+     *   .query({ AND: [{ HAS: Position }, { HAS: Velocity }] }, [Position, Velocity])
+     *   .each([Position, Velocity], (e, [pos, vel]) => {
+     *     pos.x += vel.vx;  // no ! needed
+     *   });
+     * ```
+     */
+    query(q, _guaranteed) {
+        this._belongs = this.queryBuilder(q);
+        this.hasQuery = true;
+        return this;
+    }
+    /**
+     * Shorthand for `query([...components])` — the system tracks entities that
+     * have **all** of the listed component types.
+     *
+     * Equivalent to `query({ HAS: components })`. Unlike `query`, passing
+     * component classes here also informs the types of {@link sort} and
+     * {@link each} callbacks: listed components will be non-nullable in those
+     * tuples.
+     *
+     * @param components - One or more component classes.
+     * @returns `this` for chaining.
+     */
+    requires(...components) {
+        this.query(components);
+        return this;
+    }
+}
+//# sourceMappingURL=system.js.map

package/dist/system.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system.js","sourceRoot":"","sources":["../src/system.ts"],"names":[],"mappings":"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"}

package/dist/util/array_map.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A `Map<number, T>` backed by a sparse JavaScript array.
+ *
+ * For small, dense integer key spaces this is significantly faster than
+ * `Map` because array index access avoids the hash-table overhead. Used
+ * internally to store per-entity component instances and per-type component
+ * metadata.
+ *
+ * Keys must be non-negative integers. Gaps in the key space are represented
+ * as `undefined` slots and do not count toward `size`.
+ *
+ * @typeParam T - The value type stored in the map.
+ */
+export declare class ArrayMap<T> {
+    private backend;
+    private _size;
+    constructor();
+    /**
+     * Store `value` at `key`, replacing any existing value.
+     *
+     * @param key - Non-negative integer key.
+     * @param value - Value to store.
+     */
+    set(key: number, value: T): void;
+    /**
+     * Return the value stored at `key`, or `undefined` if not present.
+     *
+     * @param key - Non-negative integer key.
+     */
+    get(key: number): T | undefined;
+    /**
+     * Remove the entry at `key`. Does nothing if `key` is not present.
+     *
+     * @param key - Non-negative integer key.
+     */
+    delete(key: number): void;
+    /**
+     * Return `true` if an entry exists at `key`.
+     *
+     * @param key - Non-negative integer key.
+     */
+    has(key: number): boolean;
+    /**
+     * Iterate over all present entries.
+     *
+     * Undefined slots are skipped; the callback is only called for keys that
+     * have an associated value.
+     *
+     * @param callback - Called with `(value, key, map)` for each entry.
+     */
+    forEach(callback: (value: T, key: number, map: ArrayMap<T>) => void): void;
+    /**
+     * Remove all entries and reset the size to zero.
+     */
+    clear(): void;
+    /** The number of entries currently in the map. */
+    get size(): number;
+}

package/dist/util/array_map.js

@@ -0,0 +1,84 @@
+/**
+ * A `Map<number, T>` backed by a sparse JavaScript array.
+ *
+ * For small, dense integer key spaces this is significantly faster than
+ * `Map` because array index access avoids the hash-table overhead. Used
+ * internally to store per-entity component instances and per-type component
+ * metadata.
+ *
+ * Keys must be non-negative integers. Gaps in the key space are represented
+ * as `undefined` slots and do not count toward `size`.
+ *
+ * @typeParam T - The value type stored in the map.
+ */
+export class ArrayMap {
+    constructor() {
+        this.backend = [];
+        this._size = 0;
+    }
+    /**
+     * Store `value` at `key`, replacing any existing value.
+     *
+     * @param key - Non-negative integer key.
+     * @param value - Value to store.
+     */
+    set(key, value) {
+        if (this.backend[key] === undefined) {
+            this._size++;
+        }
+        this.backend[key] = value;
+    }
+    /**
+     * Return the value stored at `key`, or `undefined` if not present.
+     *
+     * @param key - Non-negative integer key.
+     */
+    get(key) {
+        return this.backend[key];
+    }
+    /**
+     * Remove the entry at `key`. Does nothing if `key` is not present.
+     *
+     * @param key - Non-negative integer key.
+     */
+    delete(key) {
+        if (this.backend[key] !== undefined) {
+            this.backend[key] = undefined;
+            this._size--;
+        }
+    }
+    /**
+     * Return `true` if an entry exists at `key`.
+     *
+     * @param key - Non-negative integer key.
+     */
+    has(key) {
+        return this.backend[key] !== undefined;
+    }
+    /**
+     * Iterate over all present entries.
+     *
+     * Undefined slots are skipped; the callback is only called for keys that
+     * have an associated value.
+     *
+     * @param callback - Called with `(value, key, map)` for each entry.
+     */
+    forEach(callback) {
+        this.backend.forEach((value, index) => {
+            if (value !== undefined) {
+                callback(value, index, this);
+            }
+        });
+    }
+    /**
+     * Remove all entries and reset the size to zero.
+     */
+    clear() {
+        this.backend.length = 0;
+    }
+    /** The number of entries currently in the map. */
+    get size() {
+        return this._size;
+    }
+}
+//# sourceMappingURL=array_map.js.map

package/dist/util/array_map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"array_map.js","sourceRoot":"","sources":["../../src/util/array_map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,QAAQ;IAInB;QACE,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;QAClB,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;IACjB,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,GAAW,EAAE,KAAQ;QACvB,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,SAAS,EAAE;YACnC,IAAI,CAAC,KAAK,EAAE,CAAC;SACd;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,GAAW;QAChB,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,SAAS,EAAE;YACnC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;YAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;SACd;IACH,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;IACzC,CAAC;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,QAA2D;QACjE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;YACpC,IAAI,KAAK,KAAK,SAAS,EAAE;gBACvB,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;aAC9B;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,kDAAkD;IAClD,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;CACF"}

package/dist/util/bitset.d.ts

@@ -0,0 +1,117 @@
+/**
+ * A compact, growable set of non-negative integers backed by an array of
+ * 32-bit words.
+ *
+ * Used internally to represent entity archetypes (the set of component type
+ * ids attached to an entity) and system watchlists. Exposed in the public API
+ * so that component data can use it for bit-flag fields:
+ *
+ * ```ts
+ * class Tags extends Component {
+ *   tags    = new Bitset();
+ *   oldTags = new Bitset();
+ * }
+ *
+ * // Check a specific tag bit:
+ * if (tags.tags.has(TAG_VISIBLE)) { ... }
+ * ```
+ */
+export declare class Bitset {
+    private bits;
+    constructor();
+    /**
+     * Return `true` if this bitset and `other` have exactly the same bits set.
+     */
+    equal(other: Bitset): boolean;
+    /**
+     * OR the given `bitmask` word into the word at position `arrayIndex`.
+     *
+     * @internal Low-level bulk operation; prefer {@link add} for single bits.
+     */
+    addIndexBitmask(arrayIndex: number, bitmask: number): void;
+    /**
+     * Replace the word at position `arrayIndex` with `bitmask`.
+     *
+     * @internal Used by network deserialization to set a whole word at once.
+     */
+    setIndexBitmask(arrayIndex: number, bitmask: number): void;
+    /**
+     * Set the bit described by `bptr` (fast path using a pre-computed
+     * {@link BitPtr}).
+     */
+    addBit(bptr: BitPtr): void;
+    /**
+     * Set bit `n`.
+     *
+     * @param n - Non-negative integer bit index.
+     */
+    add(n: number): void;
+    /**
+     * Clear bit `n`.
+     *
+     * Trailing zero words are trimmed so that the internal array stays compact.
+     *
+     * @param n - Non-negative integer bit index.
+     */
+    delete(n: number): void;
+    /**
+     * Return `true` if the bit described by `bptr` is set (fast path).
+     */
+    hasBit(bptr: BitPtr): boolean;
+    /**
+     * Return `true` if bit `n` is set.
+     *
+     * @param n - Non-negative integer bit index.
+     */
+    has(n: number): boolean;
+    /**
+     * Return `true` if the given word-level bitmask is fully set at `arrayIndex`.
+     *
+     * @internal
+     */
+    hasIndexBitmask(arrayIndex: number, bitmask: number): boolean;
+    /**
+     * Return `true` if every bit set in `other` is also set in `this` (i.e.
+     * `other` is a subset of `this`).
+     *
+     * Used by the world to test whether an entity's archetype satisfies a
+     * system's `HAS` query.
+     */
+    hasBitset(other: Bitset): boolean;
+    /**
+     * Iterate over every set bit index in ascending order.
+     *
+     * @param callback - Called with each set bit index.
+     */
+    forEach(callback: (n: number) => void): void;
+    /**
+     * Return an array of all set bit indices in ascending order.
+     *
+     * @returns `number[]` of set bit positions.
+     */
+    indices(): number[];
+}
+/**
+ * A pre-computed pointer into a {@link Bitset}'s internal word array.
+ *
+ * Computing `arrayIndex` and `bitmask` from a raw bit index requires a floor
+ * division and a bitshift. `BitPtr` caches those values so that hot-path
+ * archetype checks ({@link Bitset.hasBit}, {@link Bitset.addBit}) avoid
+ * repeating the arithmetic on every entity update.
+ *
+ * A `BitPtr` is created once per component type and stored on
+ * {@link ComponentMeta.bitPtr}.
+ */
+export declare class BitPtr {
+    /** The raw bit index this pointer refers to. */
+    readonly value: number;
+    /** Index of the 32-bit word that contains this bit. */
+    readonly arrayIndex: number;
+    /** Single-bit mask within that word. */
+    readonly bitmask: number;
+    constructor(
+    /** The raw bit index this pointer refers to. */
+    value: number);
+    /** Return `true` if both pointers refer to the same bit position. */
+    equals(other: BitPtr): boolean;
+}