@vworlds/vecs 1.0.0

package/src/entity.ts

@@ -0,0 +1,276 @@
+import { Component } from "./component.js";
+import type { World } from "./world.js";
+import { ArrayMap } from "./util/array_map.js";
+import { type System } from "./system.js";
+import { Events } from "./util/events.js";
+import { Bitset } from "./util/bitset.js";
+
+type EntityEvents = Events<{ destroy(): void }>;
+
+/**
+ * A game object — a unique identifier with an arbitrary set of
+ * {@link Component | components} attached to it.
+ *
+ * You never construct an `Entity` directly. Use {@link World.createEntity} for
+ * locally-owned entities or {@link World.getOrCreateEntity} when the id is
+ * assigned by an external authority (e.g. the server):
+ *
+ * ```ts
+ * const e = world.createEntity();
+ * const pos = e.add(Position);
+ * pos.x = 100;
+ * pos.modified();
+ * ```
+ *
+ * Entities support a parent–child hierarchy. When a parent is destroyed its
+ * children are destroyed recursively. The `children` set is created lazily.
+ */
+export class Entity {
+  private components = new ArrayMap<Component>(); //maps component types to Components
+  private deletedComponents = new ArrayMap<Component>(); //maps deleted component types to Components
+
+  /**
+   * Bitmask representing the set of component types currently attached to this
+   * entity. Used by the world to efficiently match entities against system
+   * queries.
+   */
+  public readonly componentBitmask = new Bitset();
+  private readonly systems = new Set<System>();
+  private readonly newSystems: System[] = [];
+
+  /**
+   * A free-form property bag that modules can use to associate arbitrary data
+   * with an entity without registering a component.
+   */
+  public properties = new Map<string, any>();
+  public declare _events: EntityEvents;
+
+  /** Parent entity in the scene hierarchy, or `undefined` if root. */
+  public parent: Entity | undefined;
+  private _children: Set<Entity> | undefined;
+  public _archetypeChanged: boolean = false;
+  private destroyed = false;
+
+  constructor(
+    /** The {@link World} that owns this entity. */
+    public readonly world: World,
+    /** Unique numeric entity id assigned at creation time. */
+    public readonly eid: number
+  ) {}
+
+  /**
+   * The set of direct child entities in the scene hierarchy.
+   *
+   * The set is created lazily on first access. Mutate it only through
+   * {@link Entity.destroy} or by setting {@link Entity.parent} on a child —
+   * both will keep the parent–child links consistent.
+   */
+  public get children(): Set<Entity> {
+    if (!this._children) this._children = new Set<Entity>();
+    return this._children;
+  }
+
+  /**
+   * Add a component of type `Class` to this entity and return the instance.
+   *
+   * If the component is already present the existing instance is returned and
+   * no callback is fired. Pass `markAsModified = false` to suppress the
+   * initial `onSet` / `update` notification (useful when bulk-loading
+   * network snapshots before systems are running).
+   *
+   * @param Class - The component class to instantiate.
+   * @param markAsModified - Whether to immediately queue an `update`
+   *   notification. Defaults to `true`.
+   * @returns The new (or existing) component instance, typed as
+   *   `InstanceType<Class>`.
+   */
+  public add<C extends typeof Component>(
+    Class: C,
+    markAsModified?: boolean
+  ): InstanceType<C>;
+  /**
+   * Add a component by its numeric type id.
+   *
+   * @param type - Numeric component type id (as returned by
+   *   {@link World.getComponentType}).
+   * @param markAsModified - Whether to queue an update notification.
+   */
+  public add(type: number, markAsModified?: boolean): Component;
+  public add(
+    typeOrClass: number | typeof Component,
+    markAsModified: boolean = true
+  ) {
+    const type = this.world.getComponentType(typeOrClass);
+
+    let c = this.components.get(type);
+    if (c) {
+      return c;
+    }
+    c = this.world["getComponentInstance"](typeOrClass, this);
+
+    this.components.set(type, c);
+    this.componentBitmask.add(type);
+    this.world._notifyComponentAdded(this, c);
+    if (markAsModified) this.world._queueUpdatedComponent(c);
+
+    return c;
+  }
+
+  /**
+   * Remove the component of the given class from this entity.
+   *
+   * The `onRemove` hook and any `exit` callbacks on matching systems are
+   * called when archetype changes are flushed at the end of the next system
+   * run. Does nothing if the component is not present.
+   *
+   * @param Class - The component class to remove.
+   */
+  public remove<C extends typeof Component>(Class: C): void;
+  /**
+   * Remove a component by its numeric type id.
+   *
+   * @param type - Numeric component type id.
+   */
+  public remove(type: number): void;
+  public remove(typeOrClass: number | typeof Component): void {
+    const type = this.world.getComponentType(typeOrClass);
+    const c = this.components.get(type);
+    if (c) {
+      this.components.delete(type);
+      this.deletedComponents.set(type, c);
+      this.componentBitmask.delete(type);
+      this.world._notifyComponentRemoved(this, c);
+    }
+  }
+
+  /** @internal Called by systems to deliver update notifications. */
+  public _notifyModified(component: Component) {
+    this.systems.forEach((s) => {
+      s.notifyModified(component);
+    });
+  }
+
+  /**
+   * Retrieve the component of type `Class`, or `undefined` if not present.
+   *
+   * @param typeOrClass - Component class or numeric type id.
+   * @param get_deleted - If `true`, also search components that were removed
+   *   in the current frame but not yet garbage-collected. Useful inside
+   *   `exit` callbacks to read final component values.
+   * @returns The component instance or `undefined`.
+   */
+  public get<C extends typeof Component>(
+    typeOrClass: number | C,
+    get_deleted: boolean = false
+  ): InstanceType<C> | undefined {
+    const type = this.world.getComponentType(typeOrClass);
+
+    const c = this.components.get(type);
+    if (!c && get_deleted) {
+      return this.deletedComponents.get(type) as InstanceType<C> | undefined;
+    }
+    return c as InstanceType<C> | undefined;
+  }
+
+  /**
+   * Typed event emitter for entity-level lifecycle events.
+   *
+   * Currently emits one event:
+   * - `"destroy"` — fired just before the entity is fully torn down.
+   *
+   * The emitter is created lazily on first access.
+   */
+  public get events(): EntityEvents {
+    if (!this._events) {
+      this._events = new Events();
+    }
+    return this._events;
+  }
+
+  /** @internal */
+  public _hasSystem(s: System) {
+    return this.systems.has(s);
+  }
+
+  /** @internal */
+  public _addSystem(s: System) {
+    if (!this.systems.has(s)) {
+      this.newSystems.push(s);
+      s._enter(this);
+    }
+  }
+
+  /** @internal */
+  public _removeSystem(s: System) {
+    if (this.systems.delete(s)) {
+      s._exit(this);
+    }
+  }
+
+  /** @internal */
+  public _updateSystems() {
+    this.newSystems.forEach((s) => {
+      this.systems.add(s);
+    });
+    this.newSystems.length = 0;
+  }
+
+  /** `true` when the entity has no components attached. */
+  public get empty() {
+    return this.components.size == 0;
+  }
+
+  private _destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this.systems.forEach((s) => {
+      s._exit(this);
+    });
+    this.systems.clear();
+
+    if (this._events) {
+      this._events.emit("destroy");
+      this._events.removeAllListeners("destroy");
+    }
+  }
+
+  /**
+   * Destroy this entity and recursively destroy all of its children.
+   *
+   * All components are removed (triggering `onRemove` hooks and `exit`
+   * callbacks), the entity is unregistered from the world, and the `"destroy"`
+   * event is emitted. The entity must not be used after calling this method.
+   */
+  public destroy() {
+    this.world._notifyEntityDestroyed(this);
+    this.children.forEach((child) => {
+      child.destroy();
+    });
+    this.children.clear();
+    if (this.parent) {
+      this.parent.children.delete(this);
+      this.world.archetypeChanged(this.parent);
+      this.parent = undefined;
+    }
+  }
+
+  /** @internal */
+  public clearDeletedComponents() {
+    this.deletedComponents.clear();
+  }
+
+  /**
+   * Iterate over every component currently attached to this entity.
+   *
+   * @param callback - Called with each component instance. Iteration order is
+   *   not guaranteed.
+   */
+  public forEachComponent(callback: (c: Component) => void) {
+    this.components.forEach(callback);
+  }
+
+  /** Returns `"EntityN"` where N is the entity id. */
+  public toString(): string {
+    return `Entity${this.eid}`;
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { type System } from "./system.js";
+export { World } from "./world.js";
+export { Component, type ComponentMeta } from "./component.js";
+export { type Entity } from "./entity.js";
+export { type IPhase } from "./phase.js";
+export { Bitset } from "./util/bitset.js";

package/src/phase.ts

@@ -0,0 +1,49 @@
+import { type System } from "./system.js";
+import { type World } from "./world.js";
+
+/**
+ * A named, ordered bucket of {@link System | systems} within the world's
+ * update pipeline.
+ *
+ * Created internally by {@link World.addPhase}. The systems in a phase run in
+ * the order they were registered. Between each system run the world flushes
+ * pending archetype changes, so `enter` / `exit` callbacks are always
+ * delivered before the next system executes.
+ *
+ * @internal The concrete class is not part of the public API. Use
+ * {@link IPhase} to refer to phases in user code.
+ */
+export class Phase {
+  /** Systems that belong to this phase, in execution order. */
+  public systems: System[] = [];
+
+  constructor(
+    /** Name used to look up the phase in the pipeline. */
+    public readonly name: string,
+    public world: World
+  ) {}
+}
+
+/**
+ * Public interface for a pipeline phase returned by {@link World.addPhase}.
+ *
+ * Pass an `IPhase` to {@link System.phase} to assign a system to that phase,
+ * or to {@link World.runPhase} to execute it:
+ *
+ * ```ts
+ * const preUpdate = world.addPhase("preupdate");
+ * const send      = world.addPhase("send");
+ *
+ * world.system("NetworkUpdate").phase(preUpdate).run(tick);
+ *
+ * // each frame:
+ * world.runPhase(preUpdate, now, delta);
+ * world.runPhase(send,      now, delta);
+ * ```
+ */
+export interface IPhase {
+  /** The name this phase was registered under. */
+  get name(): string;
+  /** The world that owns this phase. */
+  get world(): World;
+}