@vworlds/vecs 1.0.10 → 1.0.12

package/dist/util/bitset.js

@@ -2,53 +2,27 @@
  * 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:
+ * `Bitset` is the data structure the ECS uses to represent entity archetypes
+ * (the set of component type ids attached to an entity) and watchlists
+ * (the set of component types a query reacts to).
+ *
+ * It is exported in the public API so component data can use it for
+ * compact bit-flag fields:
  *
  * ```ts
  * class Tags extends Component {
- *   tags    = new Bitset();
- *   oldTags = new Bitset();
+ *   tags = new Bitset();
  * }
  *
- * // Check a specific tag bit:
+ * tags.tags.add(TAG_VISIBLE);
  * if (tags.tags.has(TAG_VISIBLE)) { ... }
  * ```
  */
 export class Bitset {
     constructor() {
+        /** @internal Underlying word storage; exposed for tests. */
         this._bits = [];
     }
-    /**
-     * Return `true` if this bitset and `other` have exactly the same bits set.
-     */
-    equal(other) {
-        return (this._bits.length === other._bits.length && this._bits.every((v, i) => other._bits[i] === v));
-    }
-    /**
-     * OR the given `bitmask` word into the word at position `arrayIndex`.
-     *
-     * @internal Low-level bulk operation; prefer {@link add} for single bits.
-     */
-    addIndexBitmask(arrayIndex, bitmask) {
-        this._bits[arrayIndex] |= bitmask;
-    }
-    /**
-     * Replace the word at position `arrayIndex` with `bitmask`.
-     *
-     * @internal Used by network deserialization to set a whole word at once.
-     */
-    setIndexBitmask(arrayIndex, bitmask) {
-        this._bits[arrayIndex] = bitmask;
-    }
-    /**
-     * Set the bit described by `bptr` (fast path using a pre-computed
-     * {@link BitPtr}).
-     */
-    addBit(bptr) {
-        this.addIndexBitmask(bptr.arrayIndex, bptr.bitmask);
-    }
     /**
      * Set bit `n`.
      *
@@ -57,12 +31,20 @@ export class Bitset {
     add(n) {
         const arrayIndex = Math.floor(n / 32);
         const bitmask = 1 << (n % 32);
-        this.addIndexBitmask(arrayIndex, bitmask);
+        this._addIndexBitmask(arrayIndex, bitmask);
     }
     /**
-     * Clear bit `n`.
+     * Set the bit described by `bptr` (fast path using a pre-computed
+     * {@link BitPtr}).
      *
-     * Trailing zero words are trimmed so that the internal array stays compact.
+     * @param bptr - Pre-computed pointer to a bit position.
+     */
+    addBit(bptr) {
+        this._addIndexBitmask(bptr.arrayIndex, bptr.bitmask);
+    }
+    /**
+     * Clear bit `n`. Trailing zero words are trimmed so the internal storage
+     * stays compact.
      *
      * @param n - Non-negative integer bit index.
      */
@@ -80,13 +62,7 @@ export class Bitset {
         }
     }
     /**
-     * Return `true` if the bit described by `bptr` is set (fast path).
-     */
-    hasBit(bptr) {
-        return this.hasIndexBitmask(bptr.arrayIndex, bptr.bitmask);
-    }
-    /**
-     * Return `true` if bit `n` is set.
+     * Return `true` when bit `n` is set.
      *
      * @param n - Non-negative integer bit index.
      */
@@ -97,22 +73,32 @@ export class Bitset {
         }
         const bitIndex = n % 32;
         const bitmask = 1 << bitIndex;
-        return this.hasIndexBitmask(arrayIndex, bitmask);
+        return this._hasIndexBitmask(arrayIndex, bitmask);
     }
     /**
-     * Return `true` if the given word-level bitmask is fully set at `arrayIndex`.
+     * Return `true` when the bit described by `bptr` is set (fast path).
      *
-     * @internal
+     * @param bptr - Pre-computed pointer to a bit position.
      */
-    hasIndexBitmask(arrayIndex, bitmask) {
-        return (this._bits[arrayIndex] & bitmask) !== 0;
+    hasBit(bptr) {
+        return this._hasIndexBitmask(bptr.arrayIndex, bptr.bitmask);
+    }
+    /**
+     * Return `true` when this bitset and `other` have exactly the same bits set.
+     *
+     * @param other - Bitset to compare against.
+     */
+    equal(other) {
+        return (this._bits.length === other._bits.length && this._bits.every((v, i) => other._bits[i] === v));
     }
     /**
-     * Return `true` if every bit set in `other` is also set in `this` (i.e.
-     * `other` is a subset of `this`).
+     * Return `true` when every bit set in `other` is also set in this bitset
+     * (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.
+     * `HAS` query.
+     *
+     * @param other - Bitset whose set bits must all appear in this bitset.
      */
     hasBitset(other) {
         if (this._bits.length < other._bits.length) {
@@ -126,9 +112,9 @@ export class Bitset {
         return true;
     }
     /**
-     * Iterate over every set bit index in ascending order.
+     * Visit each set bit index in ascending order.
      *
-     * @param callback - Called with each set bit index.
+     * @param callback - Invoked once per set bit.
      */
     forEach(callback) {
         this._bits.forEach((b, j) => {
@@ -141,26 +127,50 @@ export class Bitset {
         });
     }
     /**
-     * Return an array of all set bit indices in ascending order.
-     *
-     * @returns `number[]` of set bit positions.
+     * Return an array of every set bit index in ascending order.
      */
     indices() {
         const idx = [];
         this.forEach((i) => idx.push(i));
         return idx;
     }
+    /**
+     * OR `bitmask` into the word at position `arrayIndex`.
+     *
+     * @internal Low-level bulk operation; prefer {@link add} or {@link addBit}
+     * for single bits.
+     */
+    _addIndexBitmask(arrayIndex, bitmask) {
+        this._bits[arrayIndex] |= bitmask;
+    }
+    /**
+     * Replace the word at position `arrayIndex` with `bitmask`.
+     *
+     * @internal Used by network deserialization to write a whole word at once.
+     */
+    _setIndexBitmask(arrayIndex, bitmask) {
+        this._bits[arrayIndex] = bitmask;
+    }
+    /**
+     * Return `true` when every bit in `bitmask` is set in the word at
+     * `arrayIndex`.
+     *
+     * @internal
+     */
+    _hasIndexBitmask(arrayIndex, bitmask) {
+        return (this._bits[arrayIndex] & bitmask) !== 0;
+    }
 }
 /**
  * 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
+ * division and a bit shift. `BitPtr` caches both 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}.
+ * One `BitPtr` is created per registered component type and stored on
+ * `ComponentMeta.bitPtr`.
  */
 export class BitPtr {
     constructor(
@@ -170,7 +180,11 @@ export class BitPtr {
         this.arrayIndex = Math.floor(value / 32);
         this.bitmask = 1 << (value % 32);
     }
-    /** Return `true` if both pointers refer to the same bit position. */
+    /**
+     * Return `true` when both pointers refer to the same bit position.
+     *
+     * @param other - Pointer to compare against.
+     */
     equals(other) {
         return this.arrayIndex == other.arrayIndex && this.bitmask == other.bitmask;
     }

package/dist/util/bitset.js.map

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

package/dist/util/events.d.ts

@@ -1,27 +1,23 @@
 /**
- * The following type declarations define an alternative typings interface for eventemitter3
- * Inspired by typings in @yandeu/events https://github.com/yandeu/events
- * Turns out those typings pretty much can be used directly on eventemitter3
+ * Strongly-typed wrapper around `eventemitter3`.
+ *
+ * The class declared in this file is purely a typings shim — at module load
+ * its prototype is swapped out for `EventEmitter` from `eventemitter3` so the
+ * concrete behavior is provided by that library, while consumers see typed
+ * `on` / `emit` / `off` signatures driven by an `EventMap`.
+ *
+ * Inspired by the typings in `@yandeu/events`
+ * (https://github.com/yandeu/events). The original typings turned out to be
+ * usable directly on top of `eventemitter3`.
+ *
+ * @internal Used only inside the package, to expose typed entity-level events.
  */
 declare type ValidEventMap<T = any> = T extends {
     [P in keyof T]: (...args: any[]) => void;
 } ? T : never;
 declare type Handler<T extends any | ((...args: any[]) => R), R = any> = T;
+/** Listener signature inferred from an `EventMap` entry. */
 export declare type EventListener<T extends ValidEventMap, K extends EventNames<T>> = T extends string | symbol ? (...args: any[]) => void : K extends keyof T ? Handler<T[K], void> : never;
-declare type EventArgs<T extends ValidEventMap, K extends EventNames<T>> = Parameters<EventListener<T, K>>;
+/** Names of the events declared on an `EventMap`. */
 export declare type EventNames<T extends ValidEventMap> = T extends string | symbol ? T : keyof T;
-declare class events<EventMap extends ValidEventMap = any> {
-    on<T extends EventNames<EventMap>>(event: T, fn: EventListener<EventMap, T>, context?: any): events<EventMap>;
-    emit<T extends EventNames<EventMap>>(event: T, ...args: EventArgs<EventMap, T>): boolean;
-    once<T extends EventNames<EventMap>>(event: T, fn: EventListener<EventMap, T>, context?: any): events<EventMap>;
-    eventNames(): EventNames<EventMap>[];
-    listeners(event: EventNames<EventMap>): any[];
-    listenerCount(event: EventNames<EventMap>): any;
-    removeListener<T extends EventNames<EventMap>>(event: T, fn?: EventListener<EventMap, T>, context?: any, once?: boolean): this;
-    removeAllListeners(event?: EventNames<EventMap>): this;
-    off<T extends EventNames<EventMap>>(event: T, fn?: EventListener<EventMap, T> | undefined, context?: any, once?: boolean | undefined): events<EventMap>;
-    addListener<T extends EventNames<EventMap>>(event: T, fn: EventListener<EventMap, T>, context?: any): events<EventMap>;
-}
-export declare class Events<EventMap extends ValidEventMap = any> extends events<EventMap> {
-}
 export {};

package/dist/util/events.js

@@ -1,10 +1,23 @@
 /**
- * The following type declarations define an alternative typings interface for eventemitter3
- * Inspired by typings in @yandeu/events https://github.com/yandeu/events
- * Turns out those typings pretty much can be used directly on eventemitter3
+ * Strongly-typed wrapper around `eventemitter3`.
+ *
+ * The class declared in this file is purely a typings shim — at module load
+ * its prototype is swapped out for `EventEmitter` from `eventemitter3` so the
+ * concrete behavior is provided by that library, while consumers see typed
+ * `on` / `emit` / `off` signatures driven by an `EventMap`.
+ *
+ * Inspired by the typings in `@yandeu/events`
+ * (https://github.com/yandeu/events). The original typings turned out to be
+ * usable directly on top of `eventemitter3`.
+ *
+ * @internal Used only inside the package, to expose typed entity-level events.
  */
 import eventEmitter3 from "eventemitter3";
 const { EventEmitter } = eventEmitter3;
+/**
+ * Typed event emitter shape. Replaced at runtime by `EventEmitter` from
+ * `eventemitter3` (see the assignment below the class body).
+ */
 class events {
     on(event, fn, context) {
         return 0;
@@ -38,6 +51,14 @@ class events {
     }
 }
 events = EventEmitter;
+/**
+ * Typed `EventEmitter` parameterised by an `EventMap` of `eventName -> handler`.
+ *
+ * Constructed lazily by `Entity.events`. Inherits its concrete behavior from
+ * `eventemitter3`'s `EventEmitter`.
+ *
+ * @internal
+ */
 export class Events extends events {
 }
 //# sourceMappingURL=events.js.map

package/dist/util/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/util/events.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,aAAa,MAAM,eAAe,CAAC;AAC1C,MAAM,EAAE,YAAY,EAAE,GAAG,aAAa,CAAC;AAmBvC,MAAM,MAAM;IACH,EAAE,CACP,KAAQ,EACR,EAA8B,EAC9B,OAAa;QAEb,OAAO,CAAQ,CAAC;IAClB,CAAC;IACM,IAAI,CAAiC,KAAQ,EAAE,GAAG,IAA4B;QACnF,OAAO,CAAQ,CAAC;IAClB,CAAC;IACM,IAAI,CACT,KAAQ,EACR,EAA8B,EAC9B,OAAa;QAEb,OAAO,CAAQ,CAAC;IAClB,CAAC;IACM,UAAU;QACf,OAAO,CAAQ,CAAC;IAClB,CAAC;IACM,SAAS,CAAC,KAA2B;QAC1C,OAAO,CAAQ,CAAC;IAClB,CAAC;IACM,aAAa,CAAC,KAA2B;QAC9C,OAAO,CAAQ,CAAC;IAClB,CAAC;IACM,cAAc,CACnB,KAAQ,EACR,EAA+B,EAC/B,OAAa,EACb,IAAc;QAEd,OAAO,CAAQ,CAAC;IAClB,CAAC;IACD,kBAAkB,CAAC,KAA4B;QAC7C,OAAO,CAAQ,CAAC;IAClB,CAAC;IACM,GAAG,CACR,KAAQ,EACR,EAA2C,EAC3C,OAAa,EACb,IAA0B;QAE1B,OAAO,CAAQ,CAAC;IAClB,CAAC;IACM,WAAW,CAChB,KAAQ,EACR,EAA8B,EAC9B,OAAa;QAEb,OAAO,CAAQ,CAAC;IAClB,CAAC;CACF;AAEA,MAAc,GAAG,YAAY,CAAC;AAE/B,MAAM,OAAO,MAA6C,SAAQ,MAAgB;CAAG"}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/util/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,aAAa,MAAM,eAAe,CAAC;AAC1C,MAAM,EAAE,YAAY,EAAE,GAAG,aAAa,CAAC;AA0BvC;;;GAGG;AACH,MAAM,MAAM;IACH,EAAE,CACP,KAAQ,EACR,EAA8B,EAC9B,OAAa;QAEb,OAAO,CAAQ,CAAC;IAClB,CAAC;IACM,IAAI,CAAiC,KAAQ,EAAE,GAAG,IAA4B;QACnF,OAAO,CAAQ,CAAC;IAClB,CAAC;IACM,IAAI,CACT,KAAQ,EACR,EAA8B,EAC9B,OAAa;QAEb,OAAO,CAAQ,CAAC;IAClB,CAAC;IACM,UAAU;QACf,OAAO,CAAQ,CAAC;IAClB,CAAC;IACM,SAAS,CAAC,KAA2B;QAC1C,OAAO,CAAQ,CAAC;IAClB,CAAC;IACM,aAAa,CAAC,KAA2B;QAC9C,OAAO,CAAQ,CAAC;IAClB,CAAC;IACM,cAAc,CACnB,KAAQ,EACR,EAA+B,EAC/B,OAAa,EACb,IAAc;QAEd,OAAO,CAAQ,CAAC;IAClB,CAAC;IACM,kBAAkB,CAAC,KAA4B;QACpD,OAAO,CAAQ,CAAC;IAClB,CAAC;IACM,GAAG,CACR,KAAQ,EACR,EAA2C,EAC3C,OAAa,EACb,IAA0B;QAE1B,OAAO,CAAQ,CAAC;IAClB,CAAC;IACM,WAAW,CAChB,KAAQ,EACR,EAA8B,EAC9B,OAAa;QAEb,OAAO,CAAQ,CAAC;IAClB,CAAC;CACF;AAEA,MAAc,GAAG,YAAY,CAAC;AAE/B;;;;;;;GAOG;AACH,MAAM,OAAO,MAA6C,SAAQ,MAAgB;CAAG"}

package/dist/util/ordered_set.d.ts

@@ -1,17 +1 @@
-export declare class OrderedSet<T> implements Set<T> {
-    private items;
-    private readonly compare;
-    constructor(compare: (a: T, b: T) => number);
-    private bisect;
-    add(value: T): this;
-    has(value: T): boolean;
-    delete(value: T): boolean;
-    clear(): void;
-    get size(): number;
-    forEach(callbackfn: (value: T, value2: T, set: Set<T>) => void, thisArg?: unknown): void;
-    [Symbol.iterator](): IterableIterator<T>;
-    entries(): IterableIterator<[T, T]>;
-    keys(): IterableIterator<T>;
-    values(): IterableIterator<T>;
-    get [Symbol.toStringTag](): string;
-}
+export {};

package/dist/util/ordered_set.js

@@ -1,14 +1,32 @@
+/**
+ * A `Set<T>` whose iteration order is determined by a comparator instead of
+ * insertion order.
+ *
+ * Backed by a sorted array. Insertions and lookups are `O(log n)` (binary
+ * search) plus the cost of an array splice on `add` / `delete`.
+ *
+ * Used by `Query.sort` to keep matched entities in a user-defined order so
+ * iteration in `forEach` and `each` walks them sorted.
+ *
+ * @internal Used only inside the package.
+ *
+ * @typeParam T - Element type stored in the set.
+ */
 export class OrderedSet {
     constructor(compare) {
-        this.items = [];
-        this.compare = compare;
+        this._items = [];
+        this._compare = compare;
     }
-    bisect(value) {
+    /**
+     * Return the index where `value` should be inserted to keep the array
+     * sorted (binary search; mirrors Python's `bisect_left`).
+     */
+    _bisect(value) {
         let lo = 0;
-        let hi = this.items.length;
+        let hi = this._items.length;
         while (lo < hi) {
             const mid = (lo + hi) >>> 1;
-            if (this.compare(this.items[mid], value) < 0) {
+            if (this._compare(this._items[mid], value) < 0) {
                 lo = mid + 1;
             }
             else {
@@ -17,53 +35,84 @@ export class OrderedSet {
         }
         return lo;
     }
+    /** Number of elements currently stored. */
+    get size() {
+        return this._items.length;
+    }
+    /** Tag used by `Object.prototype.toString` for stringification. */
+    get [Symbol.toStringTag]() {
+        return "OrderedSet";
+    }
+    /**
+     * Insert `value` at the position determined by the comparator. No-op when
+     * an element compares equal to `value`.
+     *
+     * @param value - Element to insert.
+     */
     add(value) {
-        const i = this.bisect(value);
-        if (i < this.items.length && this.compare(this.items[i], value) === 0) {
+        const i = this._bisect(value);
+        if (i < this._items.length && this._compare(this._items[i], value) === 0) {
             return this;
         }
-        this.items.splice(i, 0, value);
+        this._items.splice(i, 0, value);
         return this;
     }
+    /**
+     * Return `true` when an element comparing equal to `value` is in the set.
+     *
+     * @param value - Element to look up.
+     */
     has(value) {
-        const i = this.bisect(value);
-        return i < this.items.length && this.compare(this.items[i], value) === 0;
+        const i = this._bisect(value);
+        return i < this._items.length && this._compare(this._items[i], value) === 0;
     }
+    /**
+     * Remove the element comparing equal to `value`. Returns `true` if an
+     * element was removed.
+     *
+     * @param value - Element to remove.
+     */
     delete(value) {
-        const i = this.bisect(value);
-        if (i < this.items.length && this.compare(this.items[i], value) === 0) {
-            this.items.splice(i, 1);
+        const i = this._bisect(value);
+        if (i < this._items.length && this._compare(this._items[i], value) === 0) {
+            this._items.splice(i, 1);
             return true;
         }
         return false;
     }
+    /** Remove every element. */
     clear() {
-        this.items.length = 0;
-    }
-    get size() {
-        return this.items.length;
+        this._items.length = 0;
     }
+    /**
+     * Visit each element in sorted order.
+     *
+     * @param callbackfn - Invoked with `(value, value, set)` for each element
+     *   (`Set` interface compatibility — both arguments are the same value).
+     * @param thisArg - Optional `this` binding for the callback.
+     */
     forEach(callbackfn, thisArg) {
-        for (const item of this.items) {
+        for (const item of this._items) {
             callbackfn.call(thisArg, item, item, this);
         }
     }
+    /** Iterator over elements in sorted order. */
     [Symbol.iterator]() {
-        return this.items[Symbol.iterator]();
+        return this._items[Symbol.iterator]();
     }
+    /** Iterator yielding `[value, value]` pairs in sorted order. */
     *entries() {
-        for (const item of this.items) {
+        for (const item of this._items) {
             yield [item, item];
         }
     }
+    /** Iterator over elements in sorted order. */
     keys() {
-        return this.items[Symbol.iterator]();
+        return this._items[Symbol.iterator]();
     }
+    /** Iterator over elements in sorted order. */
     values() {
-        return this.items[Symbol.iterator]();
-    }
-    get [Symbol.toStringTag]() {
-        return "OrderedSet";
+        return this._items[Symbol.iterator]();
     }
 }
 //# sourceMappingURL=ordered_set.js.map

package/dist/util/ordered_set.js.map

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