@codehz/ecs 0.7.2 → 0.7.3

package/src/types/index.ts

@@ -0,0 +1,99 @@
+import type { EntityId, WildcardRelationId } from "../entity";
+import type { QueryFilter } from "../query/filter";
+
+/**
+ * Type-erased component ID, used for runtime container storage
+ * @internal
+ */
+export type AnyComponentId = EntityId<any>;
+
+/**
+ * Type-erased entity ID, used for runtime container storage
+ * @internal
+ */
+export type AnyEntityId = EntityId<any>;
+
+/**
+ * Lifecycle hook definition for reacting to component additions, updates, and removals.
+ * Register hooks with {@link World.hook}.
+ */
+export interface LifecycleHook<T extends readonly ComponentType<any>[]> {
+  /**
+   * Called once for each entity that already matches the hook's component types
+   * when the hook is first registered, and then for every new matching entity.
+   */
+  on_init?: (entityId: EntityId, ...components: ComponentTuple<T>) => void;
+  /**
+   * Called whenever a matching entity's component data is updated via `set()`.
+   */
+  on_set?: (entityId: EntityId, ...components: ComponentTuple<T>) => void;
+  /**
+   * Called whenever a matching entity loses one of the required components
+   * or is deleted.
+   */
+  on_remove?: (entityId: EntityId, ...components: ComponentTuple<T>) => void;
+}
+
+/**
+ * Shorthand callback style for multi-component lifecycle hooks.
+ * The same function receives all three events distinguished by the `type` parameter.
+ *
+ * @example
+ * world.hook([Position, Velocity], (type, entityId, position, velocity) => {
+ *   if (type === "init") console.log("spawned");
+ *   if (type === "set") console.log("updated");
+ *   if (type === "remove") console.log("despawned");
+ * });
+ */
+export type LifecycleCallback<T extends readonly ComponentType<any>[]> = (
+  type: "init" | "set" | "remove",
+  entityId: EntityId,
+  ...components: ComponentTuple<T>
+) => void;
+
+/**
+ * A component type used in queries and hooks.
+ * Can be a plain {@link EntityId} or an {@link OptionalEntityId} wrapped with `.optional`.
+ */
+export type ComponentType<T> = EntityId<T> | OptionalEntityId<T>;
+
+/**
+ * Wrapper that marks a component as optional in queries and hooks.
+ * When a component is optional, entities missing it are still included in results.
+ *
+ * @example
+ * world.createQuery([Position, { optional: Velocity }]);
+ */
+export type OptionalEntityId<T> = { optional: EntityId<T> };
+
+export function isOptionalEntityId<T>(type: ComponentType<T>): type is OptionalEntityId<T> {
+  return typeof type === "object" && type !== null && "optional" in type;
+}
+
+export type ComponentTypeToData<T> = T extends { optional: infer U }
+  ? { value: ComponentTypeToData<U> } | undefined
+  : T extends WildcardRelationId<infer U>
+    ? [EntityId<unknown>, U][]
+    : T extends EntityId<infer U>
+      ? U
+      : never;
+
+/**
+ * Maps an array of {@link ComponentType} to their corresponding data tuples.
+ * Used by {@link World.query} and {@link Query.forEach} to type component results.
+ */
+export type ComponentTuple<T extends readonly ComponentType<any>[]> = {
+  readonly [K in keyof T]: ComponentTypeToData<T[K]>;
+};
+
+export interface LifecycleHookEntry {
+  componentTypes: readonly ComponentType<any>[];
+  requiredComponents: EntityId<any>[];
+  optionalComponents: EntityId<any>[];
+  filter: QueryFilter;
+  hook: LifecycleHook<any>;
+  /** Raw callback function; takes precedence over hook.on_* when present */
+  callback?: LifecycleCallback<any>;
+  /** Archetypes that match this hook, used for precise cleanup on unsubscription */
+  matchedArchetypes?: Set<any>;
+}

package/src/utils/bit-set.ts

@@ -0,0 +1,133 @@
+export class BitSet {
+  private data: Uint32Array;
+  private _length: number;
+
+  constructor(length: number) {
+    this._length = length;
+    const numWords = Math.ceil(length / 32);
+    this.data = new Uint32Array(numWords);
+  }
+
+  get length(): number {
+    return this._length;
+  }
+
+  has(index: number): boolean {
+    if (index < 0 || index >= this._length) return false;
+    const word = index >>> 5; // divide by 32
+    const bit = index & 31;
+    return ((this.data[word]! >>> bit) & 1) !== 0;
+  }
+
+  set(index: number): void {
+    if (index < 0 || index >= this._length) return;
+    const word = index >>> 5;
+    const bit = index & 31;
+    this.data[word]! |= 1 << bit;
+  }
+
+  clear(index: number): void {
+    if (index < 0 || index >= this._length) return;
+    const word = index >>> 5;
+    const bit = index & 31;
+    this.data[word]! &= ~(1 << bit);
+  }
+
+  // set a range [lo, hi] inclusive to 1
+  setRange(lo: number, hi: number): void {
+    if (lo > hi) return;
+    if (lo < 0) lo = 0;
+    if (hi >= this._length) hi = this._length - 1;
+
+    const firstWord = lo >>> 5;
+    const lastWord = hi >>> 5;
+    const loBit = lo & 31;
+    const hiBit = hi & 31;
+
+    // helper to produce mask for [a..b] within a single 32-bit word
+    const maskFor = (a: number, b: number) => {
+      const width = b - a + 1;
+      if (width <= 0) return 0 >>> 0;
+      if (width >= 32) return 0xffffffff >>> 0;
+      return (((1 << width) - 1) << a) >>> 0;
+    };
+
+    if (firstWord === lastWord) {
+      const mask = maskFor(loBit, hiBit);
+      this.data[firstWord]! = (this.data[firstWord]! | mask) >>> 0;
+      return;
+    }
+
+    // first partial word
+    const firstMask = maskFor(loBit, 31);
+    this.data[firstWord]! = (this.data[firstWord]! | firstMask) >>> 0;
+
+    // middle full words
+    for (let w = firstWord + 1; w <= lastWord - 1; w++) {
+      this.data[w] = 0xffffffff >>> 0;
+    }
+
+    // last partial word
+    const lastMask = maskFor(0, hiBit);
+    this.data[lastWord]! = (this.data[lastWord]! | lastMask) >>> 0;
+  }
+
+  // check whether any bit in [lo, hi] is zero (i.e. not set)
+  anyClearInRange(lo: number, hi: number): boolean {
+    if (lo > hi) return false;
+    if (lo < 0) lo = 0;
+    if (hi >= this._length) hi = this._length - 1;
+
+    const firstWord = lo >>> 5;
+    const lastWord = hi >>> 5;
+    const loBit = lo & 31;
+    const hiBit = hi & 31;
+
+    const maskFor = (a: number, b: number) => {
+      const width = b - a + 1;
+      if (width <= 0) return 0 >>> 0;
+      if (width >= 32) return 0xffffffff >>> 0;
+      return (((1 << width) - 1) << a) >>> 0;
+    };
+
+    if (firstWord === lastWord) {
+      const mask = maskFor(loBit, hiBit);
+      const bits = (this.data[firstWord]! & mask) >>> 0;
+      return bits !== mask >>> 0;
+    }
+
+    // first partial word: if any bit in the mask is clear -> return true
+    const firstMask = maskFor(loBit, 31);
+    if ((this.data[firstWord]! & firstMask) >>> 0 !== firstMask >>> 0) return true;
+
+    // middle full words
+    for (let w = firstWord + 1; w <= lastWord - 1; w++) {
+      if (this.data[w] !== 0xffffffff >>> 0) return true;
+    }
+
+    // last partial word
+    const lastMask = maskFor(0, hiBit);
+    if ((this.data[lastWord]! & lastMask) >>> 0 !== lastMask >>> 0) return true;
+
+    return false;
+  }
+
+  // reset all bits to zero
+  reset(): void {
+    this.data.fill(0);
+  }
+
+  *[Symbol.iterator](): IterableIterator<number> {
+    for (let wordIndex = 0; wordIndex < this.data.length; wordIndex++) {
+      let word = this.data[wordIndex]!;
+      if (word === 0) continue;
+      const baseIndex = wordIndex * 32;
+      for (let bit = 0; bit < 32 && baseIndex + bit < this._length; bit++) {
+        if (word & 1) {
+          yield baseIndex + bit;
+        }
+        word >>>= 1;
+      }
+    }
+  }
+}

package/src/utils/multi-map.ts

@@ -0,0 +1,96 @@
+// A lightweight generic MultiMap implementation backed by Map<K, Set<V>>.
+// Provides usual operations: add, remove, get, has, keys, values, entries,
+// clear, deleteKey and size accessors.
+
+const _MISSING = Symbol("missing");
+
+class MultiMap<K, V> {
+  private map: Map<K, Set<V>> = new Map();
+
+  // Number of value entries across all keys (not number of keys).
+  private _valueCount = 0;
+
+  get valueCount(): number {
+    return this._valueCount;
+  }
+
+  get keyCount(): number {
+    return this.map.size;
+  }
+
+  hasKey(key: K): boolean {
+    return this.map.has(key);
+  }
+
+  has(key: K, value: V | typeof _MISSING = _MISSING): boolean {
+    const set = this.map.get(key);
+    if (!set) return false;
+    if (value === _MISSING) return true;
+    return set.has(value);
+  }
+
+  add(key: K, value: V): void {
+    let set = this.map.get(key);
+    if (!set) {
+      set = new Set();
+      this.map.set(key, set);
+    }
+    if (!set.has(value)) {
+      set.add(value);
+      this._valueCount++;
+    }
+  }
+
+  // Remove a specific value for a key. Returns true if removed.
+  remove(key: K, value: V): boolean {
+    const set = this.map.get(key);
+    if (!set) return false;
+    if (!set.has(value)) return false;
+    set.delete(value);
+    this._valueCount--;
+    if (set.size === 0) this.map.delete(key);
+    return true;
+  }
+
+  // Delete entire key and all its values. Returns true if key existed.
+  deleteKey(key: K): boolean {
+    const set = this.map.get(key);
+    if (!set) return false;
+    this._valueCount -= set.size;
+    this.map.delete(key);
+    return true;
+  }
+
+  get(key: K): Set<V> {
+    const set = this.map.get(key);
+    return set ? new Set(set) : new Set();
+  }
+
+  // iterate keys, values and entries (key -> Set copy)
+  *keys(): IterableIterator<K> {
+    yield* this.map.keys();
+  }
+
+  *values(): IterableIterator<V> {
+    for (const set of this.map.values()) {
+      for (const v of set) yield v;
+    }
+  }
+
+  [Symbol.iterator](): IterableIterator<[K, V]> {
+    return this.entries();
+  }
+
+  *entries(): IterableIterator<[K, V]> {
+    for (const [k, set] of this.map.entries()) {
+      for (const v of set) yield [k, v];
+    }
+  }
+
+  clear(): void {
+    this.map.clear();
+    this._valueCount = 0;
+  }
+}
+
+export { MultiMap };

package/src/utils/utils.ts

@@ -0,0 +1,19 @@
+/**
+ * Utility functions for ECS library
+ */
+
+/**
+ * Get a value from cache or compute and cache it if not present
+ * @param cache The cache map
+ * @param key The cache key
+ * @param compute Function to compute the value if not cached (may have side effects)
+ * @returns The cached or computed value
+ */
+export function getOrCompute<K, V>(cache: Map<K, V>, key: K, compute: () => V): V {
+  let value = cache.get(key);
+  if (value === undefined) {
+    value = compute();
+    cache.set(key, value);
+  }
+  return value;
+}

package/src/world/builder.ts

@@ -0,0 +1,100 @@
+import type { ComponentId, EntityId } from "../entity";
+import { relation } from "../entity";
+import type { World } from "./world";
+
+// =============================================================================
+// EntityBuilder - Fluent Entity Creation (moved from testing utilities)
+// =============================================================================
+
+/**
+ * A component definition for entity building, supporting both regular components and relations
+ */
+export type ComponentDef<T = unknown> =
+  | { type: "component"; id: EntityId<T>; value: T }
+  | { type: "relation"; componentId: ComponentId<T>; targetId: EntityId<any>; value: T };
+
+/**
+ * Fluent API for constructing entities with multiple components.
+ * Create instances via {@link World.spawn}.
+ *
+ * @example
+ * const entity = world.spawn()
+ *   .with(Position, { x: 0, y: 0 })
+ *   .withRelation(Parent, parentEntity)
+ *   .build();
+ * world.sync();
+ */
+export class EntityBuilder {
+  private world: World;
+  private components: ComponentDef[] = [];
+
+  constructor(world: World) {
+    this.world = world;
+  }
+
+  /**
+   * Add a regular component to the entity under construction.
+   *
+   * @template T - The component data type
+   * @param componentId - The component type to add
+   * @param args - Component data (omit for void components)
+   * @returns This builder for chaining
+   *
+   * @example
+   * builder.with(Position, { x: 10, y: 20 });
+   * builder.with(Marker); // void component
+   */
+  with<T extends void>(componentId: EntityId<T>): this;
+  with<T>(componentId: EntityId<T>, value: T): this;
+  with<T>(componentId: EntityId<T>, value?: T): this {
+    this.components.push({ type: "component", id: componentId, value: value as T });
+    return this;
+  }
+
+  /**
+   * Add a relation component to the entity under construction.
+   *
+   * @template T - The relation data type
+   * @param componentId - The base component type for the relation
+   * @param targetEntity - The target entity or component for the relation
+   * @param args - Relation data (omit for void relations)
+   * @returns This builder for chaining
+   *
+   * @example
+   * builder.withRelation(Parent, parentEntity);
+   * builder.withRelation(ChildOf, childEntity, { order: 1 });
+   */
+  withRelation<T extends void>(componentId: ComponentId<T>, targetEntity: EntityId<any>): this;
+  withRelation<T>(componentId: ComponentId<T>, targetEntity: EntityId<any>, value: T): this;
+  withRelation<T>(componentId: ComponentId<T>, targetEntity: EntityId<any>, value?: T): this {
+    this.components.push({ type: "relation", componentId, targetId: targetEntity, value: value as T });
+    return this;
+  }
+
+  /**
+   * Create the entity and enqueue all configured components.
+   * The entity and components are only materialised after {@link World.sync} is called.
+   *
+   * @returns The newly created entity ID
+   *
+   * @example
+   * const entity = world.spawn()
+   *   .with(Position, { x: 0, y: 0 })
+   *   .build();
+   * world.sync(); // Apply changes
+   */
+  build(): EntityId {
+    const entity = this.world.new();
+
+    for (const def of this.components) {
+      if (def.type === "component") {
+        this.world.set(entity, def.id, def.value as any);
+      } else {
+        const relationId = relation(def.componentId, def.targetId);
+        this.world.set(entity, relationId, def.value as any);
+      }
+    }
+
+    return entity;
+  }
+}