@vworlds/vecs 1.0.0 → 1.0.2

package/src/world.ts

@@ -1,534 +0,0 @@
-import {
-  Component,
-  ComponentClassOrType,
-  ComponentMeta,
-  Hook,
-} from "./component.js";
-import { Entity } from "./entity.js";
-import { System } from "./system.js";
-import { ArrayMap } from "./util/array_map.js";
-import { IPhase, 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 {
-  private entities = new Map<number, Entity>(); // maps entity Id to Entity
-  private componentNameTypeMap = new Map<string, number>();
-  private archChangeQueue: Entity[] = [];
-  private destroyedEntities: Entity[] = [];
-  private pendingSystems: System[] = [];
-  private allSystems: System[] = [];
-
-  private Class2Meta = new Map<typeof Component, ComponentMeta>();
-  private Type2Meta = new ArrayMap<ComponentMeta>();
-  private updatedComponents: Component[] = [];
-  private localComponentCounter = LOCAL_COMPONENT_MIN;
-  private componentRegistrationDisabled = false;
-  private systemRegistrationDisabled = false;
-  private pipeline = new Map<string, Phase>();
-  private eidCounter = 0;
-  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.
-   */
-  public getOrCreateEntity(
-    eid: number,
-    onCreateCallback?: (e: Entity) => void
-  ) {
-    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.
-   */
-  public entity(id: number): Entity | undefined {
-    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.
-   */
-  public createEntity(): Entity {
-    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.
-   */
-  public setEntityIdRange(min: number) {
-    if (this.componentRegistrationDisabled)
-      throw "setEntityIdRange must be called before component registration is disabled";
-    this.eidCounter = min;
-  }
-
-  private getComponentInstance(
-    typeOrClass: ComponentClassOrType,
-    entity: 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.
-   */
-  public getComponentMeta(typeOrClass: ComponentClassOrType) {
-    let meta: ComponentMeta | undefined;
-    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.
-   */
-  public getComponentType(typeOrClass: ComponentClassOrType) {
-    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}.
-   */
-  public archetypeChanged(e: Entity) {
-    if (e._archetypeChanged) return;
-    e._archetypeChanged = true;
-    this.archChangeQueue.push(e);
-    e.children.forEach((child) => this.archetypeChanged(child));
-  }
-
-  /** @internal */
-  public _notifyComponentAdded(e: Entity, c: Component) {
-    this.archetypeChanged(e);
-  }
-
-  /** @internal */
-  public _notifyComponentRemoved(e: Entity, c: Component) {
-    const hook = c.meta["onRemoveHandler"];
-    if (hook) hook(c);
-
-    this.archetypeChanged(e);
-  }
-
-  /** @internal */
-  public _notifyEntityDestroyed(e: Entity) {
-    if (!this.entities.delete(e.eid)) return;
-    e.forEachComponent((c) => {
-      e.remove(c.type);
-    });
-    this.destroyedEntities.push(e);
-  }
-
-  private 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. */
-  public _queueUpdatedComponent(c: Component) {
-    if (c["dirty"]) return;
-    c["dirty"] = true;
-    this.updatedComponents.push(c);
-  }
-
-  /**
-   * 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.
-   */
-  public registerComponent(ComponentClass: typeof Component): void;
-  public registerComponent(
-    ComponentClass: typeof Component,
-    type: number
-  ): void;
-  public registerComponent(
-    ComponentClass: typeof Component,
-    componentName?: string
-  ): void;
-  public registerComponent(
-    ComponentClass: typeof Component,
-    type: number,
-    componentName: string
-  ): void;
-  public registerComponent(
-    ComponentClass: typeof Component,
-    typeOrComponentName?: number | string,
-    componentName?: string
-  ): void {
-    if (this.componentRegistrationDisabled) {
-      throw "World component registartion is disabled";
-    }
-    let type: number | undefined = 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.
-   */
-  public registerComponentType(componentName: string, type: number) {
-    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}).
-   */
-  public addSystem(s: System) {
-    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.
-   */
-  public system(name: string) {
-    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.
-   */
-  public 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.
-   */
-  public start() {
-    this.componentRegistrationDisabled = true;
-    this.systemRegistrationDisabled = true;
-    this.reindexSystems();
-  }
-
-  private 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 as Phase | undefined;
-      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.
-   */
-  public hook<T extends typeof Component>(C: T): Hook<InstanceType<T>> {
-    return this.getComponentMeta(C) as any;
-  }
-
-  /**
-   * 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}.
-   */
-  public addPhase(name: string): IPhase {
-    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.
-   */
-  public runPhase(phase: IPhase, now: number, delta: number) {
-    (phase as 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.
-   */
-  public progress(now: number, delta: number) {
-    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.
-   */
-  public clearAllEntities() {
-    this.entities.forEach((e) => {
-      e.destroy();
-    });
-    this.entities.clear();
-  }
-}

package/tests/_helpers.ts

@@ -1,30 +0,0 @@
-import { World } from "../src/index.js";
-import type { IPhase } from "../src/phase.js";
-
-/**
- * Build a world with a single phase that has at least one (no-op) system,
- * so that calling `tick()` always flushes archetype changes.
- *
- * Returns the world, the phase, and a `tick()` shorthand.
- */
-export function makeWorldWithFlushPhase(name = "p") {
-  const w = new World();
-  const phase = w.addPhase(name);
-  // dummy system on this phase guarantees runPhase(phase) calls updateArchetypes.
-  w.system("__flush__").phase(phase).run(() => {});
-  return {
-    w,
-    phase,
-    tick(now = 0, delta = 0) {
-      w.runPhase(phase, now, delta);
-    },
-    start() {
-      w.start();
-    },
-  } as {
-    w: World;
-    phase: IPhase;
-    tick: (now?: number, delta?: number) => void;
-    start: () => void;
-  };
-}

package/tests/array_map.test.ts

@@ -1,68 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { ArrayMap } from "../src/util/array_map.js";
-
-describe("ArrayMap", () => {
-  it("starts empty", () => {
-    const m = new ArrayMap<string>();
-    expect(m.size).toBe(0);
-    expect(m.get(0)).toBeUndefined();
-    expect(m.has(0)).toBe(false);
-  });
-
-  it("set/get/has round trip", () => {
-    const m = new ArrayMap<string>();
-    m.set(5, "hello");
-    expect(m.get(5)).toBe("hello");
-    expect(m.has(5)).toBe(true);
-    expect(m.size).toBe(1);
-  });
-
-  it("size only increments for new keys", () => {
-    const m = new ArrayMap<number>();
-    m.set(1, 100);
-    m.set(1, 200); // overwrite
-    expect(m.size).toBe(1);
-    expect(m.get(1)).toBe(200);
-  });
-
-  it("delete removes entry and decrements size", () => {
-    const m = new ArrayMap<number>();
-    m.set(2, 42);
-    m.set(7, 99);
-    expect(m.size).toBe(2);
-    m.delete(2);
-    expect(m.has(2)).toBe(false);
-    expect(m.get(2)).toBeUndefined();
-    expect(m.size).toBe(1);
-  });
-
-  it("delete on missing key is a no-op", () => {
-    const m = new ArrayMap<number>();
-    m.set(1, 1);
-    m.delete(50);
-    expect(m.size).toBe(1);
-  });
-
-  it("forEach skips undefined slots and reports key+value", () => {
-    const m = new ArrayMap<string>();
-    m.set(0, "a");
-    m.set(2, "c");
-    m.set(5, "f");
-    const seen: Array<[string, number]> = [];
-    m.forEach((v, k) => seen.push([v, k]));
-    expect(seen).toEqual([
-      ["a", 0],
-      ["c", 2],
-      ["f", 5],
-    ]);
-  });
-
-  it("clear empties the map", () => {
-    const m = new ArrayMap<number>();
-    m.set(1, 1);
-    m.set(2, 2);
-    m.clear();
-    expect(m.has(1)).toBe(false);
-    expect(m.has(2)).toBe(false);
-  });
-});