@vworlds/vecs 1.0.0

package/src/util/array_map.ts

@@ -0,0 +1,93 @@
+/**
+ * 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<T> {
+  private backend: (T | undefined)[];
+  private _size: number;
+
+  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: number, value: T): void {
+    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: number): T | undefined {
+    return this.backend[key];
+  }
+
+  /**
+   * Remove the entry at `key`. Does nothing if `key` is not present.
+   *
+   * @param key - Non-negative integer key.
+   */
+  delete(key: number): void {
+    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: number): boolean {
+    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: (value: T, key: number, map: ArrayMap<T>) => void): void {
+    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(): number {
+    return this._size;
+  }
+}

package/src/util/bitset.ts

@@ -0,0 +1,199 @@
+/**
+ * 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 class Bitset {
+  private bits: number[];
+
+  constructor() {
+    this.bits = [];
+  }
+
+  /**
+   * Return `true` if this bitset and `other` have exactly the same bits set.
+   */
+  equal(other: Bitset) {
+    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: number, bitmask: number) {
+    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: number, bitmask: number) {
+    this.bits[arrayIndex] = bitmask;
+  }
+
+  /**
+   * Set the bit described by `bptr` (fast path using a pre-computed
+   * {@link BitPtr}).
+   */
+  addBit(bptr: BitPtr) {
+    this.addIndexBitmask(bptr.arrayIndex, bptr.bitmask);
+  }
+
+  /**
+   * Set bit `n`.
+   *
+   * @param n - Non-negative integer bit index.
+   */
+  add(n: number): void {
+    const arrayIndex = Math.floor(n / 32);
+    const bitmask = 1 << n % 32;
+    this.addIndexBitmask(arrayIndex, bitmask);
+  }
+
+  /**
+   * 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 {
+    const arrayIndex = Math.floor(n / 32);
+    const current = this.bits[arrayIndex];
+    if (current === undefined) {
+      return;
+    } else {
+      this.bits[arrayIndex] = current & ~(1 << n % 32);
+    }
+    while (this.bits.length && this.bits[this.bits.length - 1] === 0)
+      this.bits.pop();
+  }
+
+  /**
+   * Return `true` if the bit described by `bptr` is set (fast path).
+   */
+  hasBit(bptr: BitPtr) {
+    return this.hasIndexBitmask(bptr.arrayIndex, bptr.bitmask);
+  }
+
+  /**
+   * Return `true` if bit `n` is set.
+   *
+   * @param n - Non-negative integer bit index.
+   */
+  has(n: number): boolean {
+    const arrayIndex = Math.floor(n / 32);
+    if (arrayIndex >= this.bits.length) return false;
+    const bitIndex = n % 32;
+    const bitmask = 1 << bitIndex;
+    return this.hasIndexBitmask(arrayIndex, bitmask);
+  }
+
+  /**
+   * Return `true` if the given word-level bitmask is fully set at `arrayIndex`.
+   *
+   * @internal
+   */
+  hasIndexBitmask(arrayIndex: number, bitmask: number) {
+    return (this.bits[arrayIndex] & bitmask) !== 0;
+  }
+
+  /**
+   * 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 {
+    if (this.bits.length < other.bits.length) {
+      return false;
+    }
+
+    for (let i = 0; i < other.bits.length; i++) {
+      if ((this.bits[i] & other.bits[i]) !== (other.bits[i] || 0)) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Iterate over every set bit index in ascending order.
+   *
+   * @param callback - Called with each set bit index.
+   */
+  forEach(callback: (n: number) => void): void {
+    this.bits.forEach((b, j) => {
+      for (let i = 0; i < 32; i++) {
+        if ((b & 1) !== 0) {
+          callback(i + j * 32);
+        }
+        b >>= 1;
+      }
+    });
+  }
+
+  /**
+   * Return an array of all set bit indices in ascending order.
+   *
+   * @returns `number[]` of set bit positions.
+   */
+  indices(): number[] {
+    const idx: number[] = [];
+    this.forEach((i) => idx.push(i));
+    return idx;
+  }
+}
+
+/**
+ * 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 class BitPtr {
+  /** Index of the 32-bit word that contains this bit. */
+  public readonly arrayIndex: number;
+  /** Single-bit mask within that word. */
+  public readonly bitmask: number;
+
+  constructor(
+    /** The raw bit index this pointer refers to. */
+    public readonly value: number
+  ) {
+    this.arrayIndex = Math.floor(value / 32);
+    this.bitmask = 1 << value % 32;
+  }
+
+  /** Return `true` if both pointers refer to the same bit position. */
+  public equals(other: BitPtr) {
+    return this.arrayIndex == other.arrayIndex && this.bitmask == other.bitmask;
+  }
+}

package/src/util/events.ts

@@ -0,0 +1,95 @@
+/**
+ * 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
+ */
+
+import eventEmitter3 from "eventemitter3";
+const { EventEmitter } = eventEmitter3;
+
+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;
+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>>;
+export declare type EventNames<T extends ValidEventMap> = T extends
+  | string
+  | symbol
+  ? T
+  : keyof T;
+class events<EventMap extends ValidEventMap = any> {
+  public on<T extends EventNames<EventMap>>(
+    event: T,
+    fn: EventListener<EventMap, T>,
+    context?: any
+  ): events<EventMap> {
+    return 0 as any;
+  }
+  public emit<T extends EventNames<EventMap>>(
+    event: T,
+    ...args: EventArgs<EventMap, T>
+  ): boolean {
+    return 0 as any;
+  }
+  public once<T extends EventNames<EventMap>>(
+    event: T,
+    fn: EventListener<EventMap, T>,
+    context?: any
+  ): events<EventMap> {
+    return 0 as any;
+  }
+  public eventNames(): EventNames<EventMap>[] {
+    return 0 as any;
+  }
+  public listeners(event: EventNames<EventMap>): any[] {
+    return 0 as any;
+  }
+  public listenerCount(event: EventNames<EventMap>): any {
+    return 0 as any;
+  }
+  public removeListener<T extends EventNames<EventMap>>(
+    event: T,
+    fn?: EventListener<EventMap, T>,
+    context?: any,
+    once?: boolean
+  ): this {
+    return 0 as any;
+  }
+  removeAllListeners(event?: EventNames<EventMap>): this {
+    return 0 as any;
+  }
+  public off<T extends EventNames<EventMap>>(
+    event: T,
+    fn?: EventListener<EventMap, T> | undefined,
+    context?: any,
+    once?: boolean | undefined
+  ): events<EventMap> {
+    return 0 as any;
+  }
+  public addListener<T extends EventNames<EventMap>>(
+    event: T,
+    fn: EventListener<EventMap, T>,
+    context?: any
+  ): events<EventMap> {
+    return 0 as any;
+  }
+}
+
+(events as any) = EventEmitter;
+
+export class Events<
+  EventMap extends ValidEventMap = any
+> extends events<EventMap> {}

package/src/util/ordered_set.ts

@@ -0,0 +1,82 @@
+export class OrderedSet<T> implements Set<T> {
+  private items: T[];
+  private readonly compare: (a: T, b: T) => number;
+
+  constructor(compare: (a: T, b: T) => number) {
+    this.items = [];
+    this.compare = compare;
+  }
+
+  private bisect(value: T): number {
+    let lo = 0;
+    let hi = this.items.length;
+    while (lo < hi) {
+      const mid = (lo + hi) >>> 1;
+      if (this.compare(this.items[mid], value) < 0) {
+        lo = mid + 1;
+      } else {
+        hi = mid;
+      }
+    }
+    return lo;
+  }
+
+  add(value: T): this {
+    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);
+    return this;
+  }
+
+  has(value: T): boolean {
+    const i = this.bisect(value);
+    return i < this.items.length && this.compare(this.items[i], value) === 0;
+  }
+
+  delete(value: T): boolean {
+    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;
+  }
+
+  clear(): void {
+    this.items.length = 0;
+  }
+
+  get size(): number {
+    return this.items.length;
+  }
+
+  forEach(callbackfn: (value: T, value2: T, set: Set<T>) => void, thisArg?: unknown): void {
+    for (const item of this.items) {
+      callbackfn.call(thisArg, item, item, this);
+    }
+  }
+
+  [Symbol.iterator](): IterableIterator<T> {
+    return this.items[Symbol.iterator]();
+  }
+
+  *entries(): IterableIterator<[T, T]> {
+    for (const item of this.items) {
+      yield [item, item];
+    }
+  }
+
+  keys(): IterableIterator<T> {
+    return this.items[Symbol.iterator]();
+  }
+
+  values(): IterableIterator<T> {
+    return this.items[Symbol.iterator]();
+  }
+
+  get [Symbol.toStringTag](): string {
+    return "OrderedSet";
+  }
+}