@vworlds/vecs 1.0.0

package/dist/world.js

@@ -0,0 +1,453 @@
+import { ComponentMeta, } from "./component.js";
+import { Entity } from "./entity.js";
+import { System } from "./system.js";
+import { ArrayMap } from "./util/array_map.js";
+import { Phase } from "./phase.js";
+const LOCAL_COMPONENT_MIN = 256;
+/**
+ * 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 class World {
+    constructor() {
+        this.entities = new Map(); // maps entity Id to Entity
+        this.componentNameTypeMap = new Map();
+        this.archChangeQueue = [];
+        this.destroyedEntities = [];
+        this.pendingSystems = [];
+        this.allSystems = [];
+        this.Class2Meta = new Map();
+        this.Type2Meta = new ArrayMap();
+        this.updatedComponents = [];
+        this.localComponentCounter = LOCAL_COMPONENT_MIN;
+        this.componentRegistrationDisabled = false;
+        this.systemRegistrationDisabled = false;
+        this.pipeline = new Map();
+        this.eidCounter = 0;
+    }
+    /**
+     * 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, onCreateCallback) {
+        let e = this.entities.get(eid);
+        if (!e) {
+            e = new Entity(this, eid);
+            this.entities.set(eid, e);
+            if (onCreateCallback)
+                onCreateCallback(e);
+        }
+        return e;
+    }
+    /**
+     * 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) {
+        return this.entities.get(id);
+    }
+    /**
+     * 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() {
+        const eid = this.eidCounter++;
+        const e = new Entity(this, eid);
+        this.entities.set(eid, e);
+        return e;
+    }
+    /**
+     * 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) {
+        if (this.componentRegistrationDisabled)
+            throw "setEntityIdRange must be called before component registration is disabled";
+        this.eidCounter = min;
+    }
+    getComponentInstance(typeOrClass, entity) {
+        const meta = this.getComponentMeta(typeOrClass);
+        const c = new meta.Class(entity, meta);
+        const hook = meta["onAddHandler"];
+        if (hook)
+            hook(c);
+        return c;
+    }
+    /**
+     * 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) {
+        let meta;
+        if (typeof typeOrClass === "function") {
+            meta = this.Class2Meta.get(typeOrClass);
+        }
+        else {
+            meta = this.Type2Meta.get(typeOrClass);
+        }
+        if (!meta)
+            throw `unregistered component meta for component type or class '${typeOrClass}'`;
+        return meta;
+    }
+    /**
+     * 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) {
+        if (typeof typeOrClass === "function") {
+            return this.getComponentMeta(typeOrClass).type;
+        }
+        return typeOrClass;
+    }
+    /**
+     * 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) {
+        if (e._archetypeChanged)
+            return;
+        e._archetypeChanged = true;
+        this.archChangeQueue.push(e);
+        e.children.forEach((child) => this.archetypeChanged(child));
+    }
+    /** @internal */
+    _notifyComponentAdded(e, c) {
+        this.archetypeChanged(e);
+    }
+    /** @internal */
+    _notifyComponentRemoved(e, c) {
+        const hook = c.meta["onRemoveHandler"];
+        if (hook)
+            hook(c);
+        this.archetypeChanged(e);
+    }
+    /** @internal */
+    _notifyEntityDestroyed(e) {
+        if (!this.entities.delete(e.eid))
+            return;
+        e.forEachComponent((c) => {
+            e.remove(c.type);
+        });
+        this.destroyedEntities.push(e);
+    }
+    updateArchetypes() {
+        if (this.archChangeQueue.length > 0) {
+            this.allSystems.forEach((s) => {
+                this.archChangeQueue.forEach((e) => {
+                    if (s.belongs(e)) {
+                        e._addSystem(s);
+                    }
+                    else {
+                        e._removeSystem(s);
+                    }
+                });
+            });
+            this.archChangeQueue.forEach((e) => {
+                e.clearDeletedComponents();
+            });
+        }
+        this.destroyedEntities.forEach((e) => {
+            e["_destroy"]();
+        });
+        this.destroyedEntities.length = 0;
+        this.updatedComponents.forEach((c) => {
+            const hook = c.meta["onSetHandler"];
+            if (hook)
+                hook(c);
+            c.entity._notifyModified(c);
+            c["dirty"] = false;
+        });
+        this.archChangeQueue.forEach((e) => {
+            e._updateSystems();
+            e._archetypeChanged = false;
+        });
+        this.archChangeQueue.length = 0;
+        this.updatedComponents.length = 0;
+    }
+    /** @internal Queues a component for onSet / update delivery. */
+    _queueUpdatedComponent(c) {
+        if (c["dirty"])
+            return;
+        c["dirty"] = true;
+        this.updatedComponents.push(c);
+    }
+    registerComponent(ComponentClass, typeOrComponentName, componentName) {
+        if (this.componentRegistrationDisabled) {
+            throw "World component registartion is disabled";
+        }
+        let type = undefined;
+        // Determine if the second argument is type or componentName based on its type
+        if (typeof typeOrComponentName === "number") {
+            type = typeOrComponentName;
+        }
+        else if (typeof typeOrComponentName === "string") {
+            componentName = typeOrComponentName;
+        }
+        componentName = componentName || ComponentClass.name;
+        let local = false;
+        if (type === undefined) {
+            // attempt to get type id from name->type map
+            type = this.componentNameTypeMap.get(componentName);
+            if (type === undefined) {
+                type = this.localComponentCounter++;
+                local = true;
+            }
+        }
+        let meta = this.Class2Meta.get(ComponentClass);
+        if (meta) {
+            if (local)
+                this.localComponentCounter--;
+            throw `Trying to register ${componentName} with type=${type} which is already registered to ${meta.componentName}`;
+        }
+        this.registerComponentType(componentName, type);
+        meta = new ComponentMeta(ComponentClass, type, componentName);
+        this.Class2Meta.set(ComponentClass, meta);
+        this.Type2Meta.set(type, meta);
+        console.log("Registered component %s with type=%d as %s component", componentName, type, local ? "local" : "networked");
+    }
+    /**
+     * 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, type) {
+        this.componentNameTypeMap.set(componentName, type);
+    }
+    /**
+     * 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) {
+        if (this.systemRegistrationDisabled)
+            throw "System registration is disabled";
+        this.pendingSystems.push(s);
+    }
+    /**
+     * 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) {
+        const system = new System(name, this);
+        this.addSystem(system);
+        return 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() {
+        this.componentRegistrationDisabled = true;
+    }
+    /**
+     * 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() {
+        this.componentRegistrationDisabled = true;
+        this.systemRegistrationDisabled = true;
+        this.reindexSystems();
+    }
+    reindexSystems() {
+        let _defaultPhase = this.pipeline.get("update");
+        if (!_defaultPhase) {
+            _defaultPhase = new Phase("update", this);
+            this.pipeline.set(_defaultPhase.name, _defaultPhase);
+        }
+        const defaultPhase = _defaultPhase;
+        this.pendingSystems.forEach((s) => {
+            let phase = s._phase;
+            if (typeof phase === "string") {
+                phase = this.pipeline.get(phase);
+            }
+            phase = phase || defaultPhase;
+            phase.systems.push(s);
+        });
+        this.pendingSystems.length = 0;
+        this.allSystems.length = 0;
+        this.pipeline.forEach((phase) => {
+            this.allSystems.push(...phase.systems);
+            console.log("Phase %s : %s", phase.name, phase.systems.map((s) => s.name).join(" -> "));
+        });
+    }
+    /**
+     * 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(C) {
+        return this.getComponentMeta(C);
+    }
+    /**
+     * 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) {
+        const phase = new Phase(name, this);
+        this.pipeline.set(name, phase);
+        return phase;
+    }
+    /**
+     * 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, now, delta) {
+        phase.systems.forEach((s) => {
+            s._run(now, delta);
+            this.updateArchetypes();
+        });
+    }
+    /**
+     * 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, delta) {
+        this.pipeline.forEach((phase) => {
+            this.runPhase(phase, now, delta);
+        });
+    }
+    /**
+     * 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() {
+        this.entities.forEach((e) => {
+            e.destroy();
+        });
+        this.entities.clear();
+    }
+}
+//# sourceMappingURL=world.js.map

package/dist/world.js.map

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

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@vworlds/vecs",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "clean": "rimraf dist && rimraf tsconfig.tsbuildinfo",
+    "prepack": "yarn build",
+    "build": "yarn clean && yarn compile",
+    "compile": "tsc --build && cp \"./package.json\" ./dist/",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "rimraf": "^5.0.0",
+    "typescript": "^4.8.4",
+    "vitest": "^1.6.0"
+  },
+  "dependencies": {
+    "eventemitter3": "^4.0.7"
+  },
+  "license": "UNLICENSED"
+}

package/src/component.ts

@@ -0,0 +1,180 @@
+import { BitPtr, Bitset } from "./util/bitset.js";
+import type { Entity } from "./entity.js";
+import { type World } from "./world.js";
+
+/**
+ * Lifecycle hook for a component type. Obtained via {@link World.hook}.
+ *
+ * Hooks let you react to component lifecycle events without building a full
+ * {@link System}. Each call returns the same `Hook` so the methods can be
+ * chained:
+ *
+ * ```ts
+ * world.hook(Sprite)
+ *   .onAdd(c  => initSprite(c))
+ *   .onRemove(c => destroySprite(c))
+ *   .onSet(c  => syncSprite(c));
+ * ```
+ *
+ * Callbacks are invoked synchronously during {@link World.runPhase} when
+ * archetype changes are flushed.
+ *
+ * @typeParam C - The `Component` subclass this hook is bound to.
+ */
+export interface Hook<C extends Component = Component> {
+  /**
+   * Register a callback that fires when a component of this type is added to
+   * an entity.
+   *
+   * @param handler - Receives the newly created component instance.
+   * @returns `this` for chaining.
+   */
+  onAdd(handler: (c: C) => void): Hook<C>;
+
+  /**
+   * Register a callback that fires when a component of this type is removed
+   * from an entity (including when the entity is destroyed).
+   *
+   * @param handler - Receives the component instance being removed.
+   * @returns `this` for chaining.
+   */
+  onRemove(handler: (c: C) => void): Hook<C>;
+
+  /**
+   * Register a callback that fires when {@link Component.modified} is called
+   * on a component of this type.
+   *
+   * @param handler - Receives the component instance that changed.
+   * @returns `this` for chaining.
+   */
+  onSet(handler: (c: C) => void): Hook<C>;
+}
+
+/**
+ * Internal bookkeeping record for a registered component class.
+ *
+ * Every component class that is passed to {@link World.registerComponent} gets
+ * a `ComponentMeta` that maps it to a numeric type id, a string name, and a
+ * pre-computed {@link BitPtr} used for fast archetype checks.
+ *
+ * `ComponentMeta` also implements {@link Hook}, so you can attach lifecycle
+ * callbacks directly on the meta object (as `World.hook()` returns it).
+ */
+export class ComponentMeta implements Hook<Component> {
+  /** The component class constructor. */
+  public readonly Class: typeof Component;
+  /** Numeric type id assigned at registration time. */
+  public readonly type: number;
+  /** Human-readable name used in logs and serialization lookups. */
+  public readonly componentName: string;
+  /** Pre-computed bit-pointer into the entity archetype {@link Bitset}. */
+  public readonly bitPtr: BitPtr;
+  private onAddHandler: ((c: Component) => void) | undefined;
+  private onRemoveHandler: ((c: Component) => void) | undefined;
+  private onSetHandler: ((c: Component) => void) | undefined;
+
+  constructor(Class: typeof Component, type: number, componentName: string) {
+    this.Class = Class;
+    this.type = type;
+    this.componentName = componentName;
+    this.bitPtr = new BitPtr(type);
+  }
+
+  /** @inheritdoc */
+  public onAdd(handler: (c: Component) => void): ComponentMeta {
+    this.onAddHandler = handler;
+    return this;
+  }
+
+  /** @inheritdoc */
+  public onRemove(handler: (c: Component) => void): ComponentMeta {
+    this.onRemoveHandler = handler;
+    return this;
+  }
+
+  /** @inheritdoc */
+  public onSet(handler: (c: Component) => void): ComponentMeta {
+    this.onSetHandler = handler;
+    return this;
+  }
+}
+
+/** A component class constructor or its numeric type id. */
+export type ComponentClassOrType = number | typeof Component;
+
+/** An array of component class constructors or type ids. */
+export type ComponentClassArray = ComponentClassOrType[];
+
+/**
+ * Base class for all ECS components.
+ *
+ * Extend this class to define data that can be attached to an {@link Entity}:
+ *
+ * ```ts
+ * class Position extends Component {
+ *   x = 0;
+ *   y = 0;
+ * }
+ *
+ * world.registerComponent(Position);
+ * const pos = entity.add(Position);
+ * pos.x = 100;
+ * pos.modified(); // notify watching systems
+ * ```
+ *
+ * A component instance is always bound to a single entity and is created by
+ * the world when {@link Entity.add} is called.
+ */
+export class Component {
+  private dirty: boolean = false;
+
+  constructor(
+    /** The entity this component belongs to. */
+    public readonly entity: Entity,
+    /** Registration metadata (type id, name, bit-pointer). */
+    public readonly meta: ComponentMeta
+  ) {}
+
+  /** Numeric type id — shorthand for `this.meta.type`. */
+  public get type(): number {
+    return this.meta.type;
+  }
+
+  /** Pre-computed bit-pointer — shorthand for `this.meta.bitPtr`. */
+  public get bitPtr(): BitPtr {
+    return this.meta.bitPtr;
+  }
+
+  /**
+   * Notify the world that this component's data has changed.
+   *
+   * Queues the component for delivery to all {@link System.update} callbacks
+   * that watch this component type. Call this after mutating the component's
+   * fields to ensure systems react to the new values.
+   */
+  public modified() {
+    this.entity.world._queueUpdatedComponent(this);
+  }
+
+  /** Returns the component's registered name, e.g. `"Position"`. */
+  public toString(): string {
+    return this.meta.componentName;
+  }
+}
+
+/**
+ * Compute a {@link Bitset} that has a bit set for every component class or
+ * type id in `classes`.
+ *
+ * @internal Used internally to build archetype masks for system queries.
+ */
+export function calculateComponentBitmask(
+  classes: ComponentClassArray,
+  world: World
+) {
+  const bitmask = new Bitset();
+  classes.forEach((C) => {
+    bitmask.add(world.getComponentType(C));
+  });
+  return bitmask;
+}