@vworlds/vecs 1.0.0

package/dist/util/bitset.js

@@ -0,0 +1,177 @@
+/**
+ * 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 {
+    constructor() {
+        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`.
+     *
+     * @param n - Non-negative integer bit index.
+     */
+    add(n) {
+        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) {
+        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) {
+        return this.hasIndexBitmask(bptr.arrayIndex, bptr.bitmask);
+    }
+    /**
+     * Return `true` if bit `n` is set.
+     *
+     * @param n - Non-negative integer bit index.
+     */
+    has(n) {
+        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, bitmask) {
+        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) {
+        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) {
+        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() {
+        const idx = [];
+        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 {
+    constructor(
+    /** The raw bit index this pointer refers to. */
+    value) {
+        this.value = value;
+        this.arrayIndex = Math.floor(value / 32);
+        this.bitmask = 1 << value % 32;
+    }
+    /** Return `true` if both pointers refer to the same bit position. */
+    equals(other) {
+        return this.arrayIndex == other.arrayIndex && this.bitmask == other.bitmask;
+    }
+}
+//# sourceMappingURL=bitset.js.map

package/dist/util/bitset.js.map

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

package/dist/util/events.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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
+ */
+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;
+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

@@ -0,0 +1,43 @@
+/**
+ * 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;
+class events {
+    on(event, fn, context) {
+        return 0;
+    }
+    emit(event, ...args) {
+        return 0;
+    }
+    once(event, fn, context) {
+        return 0;
+    }
+    eventNames() {
+        return 0;
+    }
+    listeners(event) {
+        return 0;
+    }
+    listenerCount(event) {
+        return 0;
+    }
+    removeListener(event, fn, context, once) {
+        return 0;
+    }
+    removeAllListeners(event) {
+        return 0;
+    }
+    off(event, fn, context, once) {
+        return 0;
+    }
+    addListener(event, fn, context) {
+        return 0;
+    }
+}
+events = EventEmitter;
+export class Events extends events {
+}
+//# sourceMappingURL=events.js.map

package/dist/util/events.js.map

@@ -0,0 +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;AAyBvC,MAAM,MAAM;IACH,EAAE,CACP,KAAQ,EACR,EAA8B,EAC9B,OAAa;QAEb,OAAO,CAAQ,CAAC;IAClB,CAAC;IACM,IAAI,CACT,KAAQ,EACR,GAAG,IAA4B;QAE/B,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,MAEX,SAAQ,MAAgB;CAAG"}

package/dist/util/ordered_set.d.ts

@@ -0,0 +1,17 @@
+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;
+}

package/dist/util/ordered_set.js

@@ -0,0 +1,69 @@
+export class OrderedSet {
+    constructor(compare) {
+        this.items = [];
+        this.compare = compare;
+    }
+    bisect(value) {
+        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) {
+        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) {
+        const i = this.bisect(value);
+        return i < this.items.length && this.compare(this.items[i], value) === 0;
+    }
+    delete(value) {
+        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() {
+        this.items.length = 0;
+    }
+    get size() {
+        return this.items.length;
+    }
+    forEach(callbackfn, thisArg) {
+        for (const item of this.items) {
+            callbackfn.call(thisArg, item, item, this);
+        }
+    }
+    [Symbol.iterator]() {
+        return this.items[Symbol.iterator]();
+    }
+    *entries() {
+        for (const item of this.items) {
+            yield [item, item];
+        }
+    }
+    keys() {
+        return this.items[Symbol.iterator]();
+    }
+    values() {
+        return this.items[Symbol.iterator]();
+    }
+    get [Symbol.toStringTag]() {
+        return "OrderedSet";
+    }
+}
+//# sourceMappingURL=ordered_set.js.map

package/dist/util/ordered_set.js.map

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

package/dist/world.d.ts

@@ -0,0 +1,279 @@
+import { Component, ComponentClassOrType, ComponentMeta, Hook } from "./component.js";
+import { Entity } from "./entity.js";
+import { System } from "./system.js";
+import { IPhase } from "./phase.js";
+/**
+ * The central ECS container.
+ *
+ * A `World` owns all entities, components, systems, and the update pipeline.
+ * Typical lifecycle:
+ *
+ * 1. **Register components** — call {@link registerComponent} (and optionally
+ *    {@link registerComponentType}) for every component class.
+ * 2. **Register systems** — call {@link system} (or {@link addSystem}) to
+ *    create and configure {@link System | systems}.
+ * 3. **Start** — call {@link start} to freeze registration and sort systems
+ *    into their phases.
+ * 4. **Run loop** — call {@link runPhase} once per frame for each phase.
+ *
+ * ```ts
+ * const world = new World();
+ *
+ * world.registerComponent(Position);
+ * world.registerComponent(Velocity);
+ *
+ * world.system("Move")
+ *   .requires(Position, Velocity)
+ *   .update(Position, (pos) => { pos.x += vel.x; });
+ *
+ * world.start();
+ *
+ * // game loop:
+ * world.runPhase(updatePhase, Date.now(), 16);
+ * ```
+ */
+export declare class World {
+    private entities;
+    private componentNameTypeMap;
+    private archChangeQueue;
+    private destroyedEntities;
+    private pendingSystems;
+    private allSystems;
+    private Class2Meta;
+    private Type2Meta;
+    private updatedComponents;
+    private localComponentCounter;
+    private componentRegistrationDisabled;
+    private systemRegistrationDisabled;
+    private pipeline;
+    private eidCounter;
+    constructor();
+    /**
+     * Return the entity with id `eid`, creating it if it does not yet exist.
+     *
+     * Used by networking code to materialise server-assigned entities:
+     *
+     * ```ts
+     * const e = world.getOrCreateEntity(snapshot.eid, (e) => {
+     *   networkEntities.add(e);
+     * });
+     * const c = e.add(snapshot.type, false);
+     * ```
+     *
+     * @param eid - The entity id to look up or create.
+     * @param onCreateCallback - Optional callback invoked only when a **new**
+     *   entity is created, before it is returned. Use this to initialise
+     *   bookkeeping (e.g. tracking it in a local set).
+     * @returns The existing or newly created entity.
+     */
+    getOrCreateEntity(eid: number, onCreateCallback?: (e: Entity) => void): Entity;
+    /**
+     * Look up an entity by id.
+     *
+     * @param id - Numeric entity id.
+     * @returns The entity, or `undefined` if no entity with that id exists.
+     */
+    entity(id: number): Entity | undefined;
+    /**
+     * Create a new entity with an auto-assigned id and register it in the world.
+     *
+     * The id counter starts at 0 (or at the value set by
+     * {@link setEntityIdRange}) and increments by one for each call.
+     *
+     * @returns The new entity.
+     */
+    createEntity(): Entity;
+    /**
+     * Set the starting value for the auto-incrementing entity id counter.
+     *
+     * Must be called **before** {@link start} (or
+     * {@link disableComponentRegistration}). Useful when the world runs alongside
+     * a server that owns a different id range — for example, locally-created
+     * client entities can start at a high offset to avoid collisions with
+     * server-assigned ids.
+     *
+     * @param min - The first id that will be assigned by {@link createEntity}.
+     * @throws If called after registration has been disabled.
+     */
+    setEntityIdRange(min: number): void;
+    private getComponentInstance;
+    /**
+     * Retrieve the {@link ComponentMeta} record for a registered component.
+     *
+     * @param typeOrClass - A component class constructor or a numeric type id.
+     * @returns The corresponding `ComponentMeta`.
+     * @throws If no component with that class or type id has been registered.
+     */
+    getComponentMeta(typeOrClass: ComponentClassOrType): ComponentMeta;
+    /**
+     * Resolve a component class or type id to its numeric type id.
+     *
+     * @param typeOrClass - A component class constructor or a numeric type id.
+     * @returns The numeric type id.
+     */
+    getComponentType(typeOrClass: ComponentClassOrType): number;
+    /**
+     * Mark an entity's archetype as changed, queuing it for re-evaluation
+     * against all system queries at the end of the current system run.
+     *
+     * Also recursively marks all children as changed so that `{ PARENT: ... }`
+     * queries are re-evaluated.
+     *
+     * @internal Called automatically by {@link Entity.add} and
+     * {@link Entity.remove}.
+     */
+    archetypeChanged(e: Entity): void;
+    /** @internal */
+    _notifyComponentAdded(e: Entity, c: Component): void;
+    /** @internal */
+    _notifyComponentRemoved(e: Entity, c: Component): void;
+    /** @internal */
+    _notifyEntityDestroyed(e: Entity): void;
+    private updateArchetypes;
+    /** @internal Queues a component for onSet / update delivery. */
+    _queueUpdatedComponent(c: Component): void;
+    /**
+     * Register a component class with the world.
+     *
+     * Must be called before any entity can use the component. Registration is
+     * disabled once {@link start} is called.
+     *
+     * **Overloads:**
+     * - `registerComponent(Class)` — type id auto-assigned from the name map, or
+     *   from a local counter (≥ 256) if the name is not yet mapped.
+     * - `registerComponent(Class, type)` — explicit numeric type id.
+     * - `registerComponent(Class, componentName)` — auto-assigned id, custom
+     *   display name (useful when the class name differs from the network name).
+     * - `registerComponent(Class, type, componentName)` — explicit id + name.
+     *
+     * @param ComponentClass - The component class to register.
+     * @throws If the class has already been registered, or if registration is
+     *   disabled.
+     */
+    registerComponent(ComponentClass: typeof Component): void;
+    registerComponent(ComponentClass: typeof Component, type: number): void;
+    registerComponent(ComponentClass: typeof Component, componentName?: string): void;
+    registerComponent(ComponentClass: typeof Component, type: number, componentName: string): void;
+    /**
+     * Pre-register a component name → type id mapping without associating a
+     * class.
+     *
+     * Useful when network messages refer to components by type id and the
+     * corresponding class may be registered later. Call this before
+     * {@link registerComponent} to ensure the class picks up the server-assigned
+     * id rather than a locally generated one.
+     *
+     * @param componentName - The string name used in network payloads.
+     * @param type - The numeric type id assigned by the server.
+     */
+    registerComponentType(componentName: string, type: number): void;
+    /**
+     * Register a pre-built {@link System} with the world.
+     *
+     * In most cases it is more convenient to use {@link system} which both
+     * creates and registers in one call. Use `addSystem` when you need to
+     * subclass `System` directly.
+     *
+     * @param s - The system to add.
+     * @throws If system registration is disabled (after {@link start}).
+     */
+    addSystem(s: System): void;
+    /**
+     * Create a new {@link System}, register it, and return it for configuration.
+     *
+     * This is the primary way to define systems:
+     *
+     * ```ts
+     * world.system("Render")
+     *   .phase("update")
+     *   .requires(Position, Sprite)
+     *   .enter([Sprite], (e, [sprite]) => sprite.initialize(scene))
+     *   .update(Position, (pos) => { ... });
+     * ```
+     *
+     * @param name - A unique display name for the system.
+     * @returns The new `System` instance.
+     */
+    system(name: string): System<[]>;
+    /**
+     * Prevent any further calls to {@link registerComponent}.
+     *
+     * Called automatically by {@link start}. Can be called early if you want to
+     * lock component registration before systems are fully configured.
+     */
+    disableComponentRegistration(): void;
+    /**
+     * Freeze registration and prepare the world for running.
+     *
+     * Disables both component and system registration, then distributes all
+     * pending systems into their assigned pipeline phases (defaulting to
+     * `"update"`). Logs the resulting phase → system order to the console.
+     *
+     * Call this once, after all components and systems are registered but before
+     * the first {@link runPhase} call.
+     */
+    start(): void;
+    private reindexSystems;
+    /**
+     * Return the {@link Hook} for a component class.
+     *
+     * Hooks let you react to component lifecycle events (add / remove / set)
+     * without building a full {@link System}. The hook is backed by the
+     * component's {@link ComponentMeta} and the same object is returned on every
+     * call.
+     *
+     * ```ts
+     * world.hook(Sprite)
+     *   .onAdd(c  => c.initialize(scene))
+     *   .onRemove(c => c.destroy());
+     * ```
+     *
+     * @param C - The component class.
+     * @returns The `Hook` for that component type.
+     */
+    hook<T extends typeof Component>(C: T): Hook<InstanceType<T>>;
+    /**
+     * Add a named phase to the update pipeline and return it.
+     *
+     * Phases are executed in insertion order when you call {@link runPhase} for
+     * each one. Systems are assigned to a phase via {@link System.phase}.
+     *
+     * ```ts
+     * const preUpdate = world.addPhase("preupdate");
+     * const update    = world.addPhase("update");
+     * const send      = world.addPhase("send");
+     * ```
+     *
+     * @param name - Unique phase name. Systems can reference it by this string.
+     * @returns The new {@link IPhase}.
+     */
+    addPhase(name: string): IPhase;
+    /**
+     * Execute all systems in the given phase for one tick.
+     *
+     * After each system runs, pending archetype changes (entity add/remove
+     * component events) are flushed so that `enter` / `exit` callbacks are
+     * delivered before the next system in the same phase executes.
+     *
+     * @param phase - The {@link IPhase} to run (returned by {@link addPhase}).
+     * @param now - Absolute timestamp in milliseconds (e.g. `Date.now()`).
+     * @param delta - Milliseconds elapsed since the previous tick.
+     */
+    runPhase(phase: IPhase, now: number, delta: number): void;
+    /**
+     * Run every phase in the pipeline in insertion order (the order phases were
+     * registered via {@link addPhase}). Equivalent to calling
+     * {@link runPhase} for each phase manually.
+     *
+     * @param now - Absolute timestamp in milliseconds (e.g. `Date.now()`).
+     * @param delta - Milliseconds elapsed since the previous tick.
+     */
+    progress(now: number, delta: number): void;
+    /**
+     * Destroy every entity currently tracked by the world.
+     *
+     * Triggers all `onRemove` hooks and `exit` callbacks. Useful when
+     * transitioning between game sessions or resetting to a clean state.
+     */
+    clearAllEntities(): void;
+}