@codehz/ecs 0.7.2 → 0.7.3

package/src/query/filter.ts

@@ -0,0 +1,75 @@
+import type { Archetype } from "../archetype/archetype";
+import type { EntityId } from "../entity";
+import {
+  getComponentIdFromRelationId,
+  getDetailedIdType,
+  isDontFragmentComponent,
+  isRelationId,
+  relation,
+} from "../entity";
+
+/**
+ * Filter options for queries
+ */
+export interface QueryFilter {
+  negativeComponentTypes?: EntityId<any>[];
+}
+
+/**
+ * Serialize a QueryFilter into a deterministic string suitable for cache keys.
+ * Currently only serializes `negativeComponentTypes`.
+ */
+export function serializeQueryFilter(filter: QueryFilter = {}): string {
+  const negative = (filter.negativeComponentTypes || []).slice().sort((a, b) => a - b);
+  if (negative.length === 0) return "";
+  return `neg:${negative.join(",")}`;
+}
+
+/**
+ * Check if an archetype matches the given component types
+ */
+export function matchesComponentTypes(archetype: Archetype, componentTypes: EntityId<any>[]): boolean {
+  return componentTypes.every((type) => {
+    const detailedType = getDetailedIdType(type);
+    if (detailedType.type === "wildcard-relation") {
+      // For wildcard relations, check if archetype contains the component relation
+      return archetype.componentTypes.some((archetypeType) => {
+        if (!isRelationId(archetypeType)) return false;
+        const componentId = getComponentIdFromRelationId(archetypeType);
+        return componentId === detailedType.componentId;
+      });
+    } else if (
+      (detailedType.type === "entity-relation" || detailedType.type === "component-relation") &&
+      detailedType.componentId !== undefined &&
+      isDontFragmentComponent(detailedType.componentId)
+    ) {
+      // For specific dontFragment relations, check if archetype has the wildcard marker
+      const wildcardMarker = relation(detailedType.componentId, "*");
+      return archetype.componentTypeSet.has(wildcardMarker);
+    } else {
+      // For regular components and non-dontFragment relations, check direct inclusion
+      return archetype.componentTypeSet.has(type);
+    }
+  });
+}
+
+/**
+ * Check if an archetype matches the filter conditions (only filtering logic)
+ */
+export function matchesFilter(archetype: Archetype, filter: QueryFilter): boolean {
+  const negativeTypes = filter.negativeComponentTypes || [];
+  return negativeTypes.every((type) => {
+    const detailedType = getDetailedIdType(type);
+    if (detailedType.type === "wildcard-relation") {
+      // For wildcard relations in negative filter, exclude archetypes that contain ANY relation with the same component
+      return !archetype.componentTypes.some((archetypeType) => {
+        if (!isRelationId(archetypeType)) return false;
+        const componentId = getComponentIdFromRelationId(archetypeType);
+        return componentId === detailedType.componentId;
+      });
+    } else {
+      // For regular components, check direct exclusion
+      return !archetype.componentTypeSet.has(type);
+    }
+  });
+}

package/src/query/query.ts

@@ -0,0 +1,313 @@
+import type { Archetype } from "../archetype/archetype";
+import { normalizeComponentTypes } from "../component/type-utils";
+import type { EntityId, WildcardRelationId } from "../entity";
+import { getDetailedIdType, isDontFragmentComponent } from "../entity";
+import type { ComponentTuple, ComponentType } from "../types";
+import type { World } from "../world/world";
+import { matchesComponentTypes, matchesFilter, type QueryFilter } from "./filter";
+import type { QueryRegistry } from "./registry";
+
+/**
+ * Cached query for efficiently iterating entities with specific components.
+ *
+ * Queries are created via {@link World.createQuery} and should be **reused across frames**
+ * for optimal performance. The world automatically keeps the query's internal archetype cache
+ * up to date as entities are created and destroyed.
+ *
+ * @example
+ * const movementQuery = world.createQuery([Position, Velocity]);
+ *
+ * // In the game loop
+ * movementQuery.forEach([Position, Velocity], (entity, pos, vel) => {
+ *   pos.x += vel.x;
+ *   pos.y += vel.y;
+ * });
+ */
+export class Query {
+  private world: World;
+  private componentTypes: EntityId<any>[];
+  private filter: QueryFilter;
+  private cachedArchetypes: Archetype[] = [];
+  private isDisposed = false;
+  /** Cache key assigned by World for O(1) releaseQuery lookup */
+  _cacheKey: string | undefined;
+  /** Cached wildcard component types for faster entity filtering */
+  private wildcardTypes: WildcardRelationId<any>[];
+  /** Cached specific dontFragment relation types that need entity-level filtering */
+  private specificDontFragmentTypes: EntityId<any>[];
+
+  /**
+   * @internal Queries should be created via {@link World.createQuery}, not instantiated directly.
+   */
+  constructor(world: World, componentTypes: EntityId<any>[], filter: QueryFilter = {}, registry?: QueryRegistry) {
+    this.world = world;
+    this.componentTypes = normalizeComponentTypes(componentTypes);
+    this.filter = filter;
+    // Pre-compute wildcard types once
+    this.wildcardTypes = this.componentTypes.filter(
+      (ct) => getDetailedIdType(ct).type === "wildcard-relation",
+    ) as WildcardRelationId<any>[];
+    // Pre-compute specific dontFragment relation types that need entity-level filtering
+    this.specificDontFragmentTypes = this.componentTypes.filter((ct) => {
+      const detailedType = getDetailedIdType(ct);
+      return (
+        (detailedType.type === "entity-relation" || detailedType.type === "component-relation") &&
+        detailedType.componentId !== undefined &&
+        isDontFragmentComponent(detailedType.componentId)
+      );
+    });
+    this.updateCache();
+    // Register with registry for archetype updates
+    if (registry) {
+      registry.register(this);
+    }
+  }
+
+  /**
+   * Check if query is disposed and throw error if so
+   */
+  private ensureNotDisposed(): void {
+    if (this.isDisposed) {
+      throw new Error("Query has been disposed");
+    }
+  }
+
+  /**
+   * Returns all entity IDs that match this query.
+   *
+   * @returns Array of matching entity IDs
+   *
+   * @example
+   * const entities = query.getEntities();
+   * for (const entity of entities) {
+   *   const pos = world.get(entity, Position);
+   * }
+   */
+  getEntities(): EntityId[] {
+    this.ensureNotDisposed();
+
+    // Fast path: no wildcard relations and no specific dontFragment relations
+    if (this.wildcardTypes.length === 0 && this.specificDontFragmentTypes.length === 0) {
+      const result: EntityId[] = [];
+      for (const archetype of this.cachedArchetypes) {
+        for (const entity of archetype.getEntities()) {
+          result.push(entity);
+        }
+      }
+      return result;
+    }
+
+    // Slow path: need to filter entities that actually have the required relations
+    // This is necessary for:
+    // 1. Wildcard relations where an archetype can contain entities with/without the relation
+    // 2. Specific dontFragment relations where the archetype only has the wildcard marker
+    const result: EntityId[] = [];
+    for (const archetype of this.cachedArchetypes) {
+      for (const entity of archetype.getEntities()) {
+        if (this.entityMatchesQuery(archetype, entity)) {
+          result.push(entity);
+        }
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Check if entity matches all query requirements (wildcards and specific dontFragment relations)
+   */
+  private entityMatchesQuery(archetype: Archetype, entity: EntityId): boolean {
+    // Check wildcard relations
+    for (const wildcardType of this.wildcardTypes) {
+      const relations = archetype.get(entity, wildcardType);
+      if (!relations || relations.length === 0) {
+        return false;
+      }
+    }
+
+    // Check specific dontFragment relations
+    for (const specificType of this.specificDontFragmentTypes) {
+      const result = archetype.getOptional(entity, specificType);
+      if (result === undefined) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Returns all matching entities along with their component data.
+   *
+   * @param componentTypes - Array of component types to retrieve
+   * @returns Array of objects containing the entity ID and its component tuple
+   *
+   * @example
+   * const results = query.getEntitiesWithComponents([Position, Velocity]);
+   * results.forEach(({ entity, components: [pos, vel] }) => {
+   *   pos.x += vel.x;
+   * });
+   */
+  getEntitiesWithComponents<const T extends readonly ComponentType<any>[]>(
+    componentTypes: T,
+  ): Array<{
+    entity: EntityId;
+    components: ComponentTuple<T>;
+  }> {
+    this.ensureNotDisposed();
+
+    const result: Array<{
+      entity: EntityId;
+      components: ComponentTuple<T>;
+    }> = [];
+
+    for (const archetype of this.cachedArchetypes) {
+      archetype.appendEntitiesWithComponents(componentTypes, result);
+    }
+
+    return result;
+  }
+
+  /**
+   * Iterates over all matching entities and invokes the callback with their component data.
+   * This is the preferred way to read and mutate components in a hot loop.
+   *
+   * @param componentTypes - Array of component types to retrieve
+   * @param callback - Function called for each matching entity with its components
+   *
+   * @example
+   * query.forEach([Position, Velocity], (entity, pos, vel) => {
+   *   pos.x += vel.x;
+   *   pos.y += vel.y;
+   * });
+   */
+  forEach<const T extends readonly ComponentType<any>[]>(
+    componentTypes: T,
+    callback: (entity: EntityId, ...components: ComponentTuple<T>) => void,
+  ): void {
+    this.ensureNotDisposed();
+
+    for (const archetype of this.cachedArchetypes) {
+      archetype.forEachWithComponents(componentTypes, callback);
+    }
+  }
+
+  /**
+   * Generator that yields each matching entity together with its component data.
+   *
+   * @param componentTypes - Array of component types to retrieve
+   * @yields Tuples of `[entityId, ...components]`
+   *
+   * @example
+   * for (const [entity, pos, vel] of query.iterate([Position, Velocity])) {
+   *   pos.x += vel.x;
+   * }
+   */
+  *iterate<const T extends readonly ComponentType<any>[]>(
+    componentTypes: T,
+  ): IterableIterator<[EntityId, ...ComponentTuple<T>]> {
+    this.ensureNotDisposed();
+
+    for (const archetype of this.cachedArchetypes) {
+      yield* archetype.iterateWithComponents(componentTypes);
+    }
+  }
+
+  /**
+   * Returns an array containing the data of a single component for every matching entity.
+   *
+   * @param componentType - The component type to retrieve
+   * @returns Array of component data (one entry per matching entity)
+   *
+   * @example
+   * const positions = query.getComponentData(Position);
+   */
+  getComponentData<T>(componentType: EntityId<T>): T[] {
+    this.ensureNotDisposed();
+
+    const result: T[] = [];
+    for (const archetype of this.cachedArchetypes) {
+      for (const data of archetype.getComponentData(componentType)) {
+        result.push(data);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * @internal Rebuilds the cached archetype list. Called automatically by the world.
+   */
+  updateCache(): void {
+    if (this.isDisposed) return;
+
+    this.cachedArchetypes = this.world
+      .getMatchingArchetypes(this.componentTypes)
+      .filter((archetype: Archetype) => matchesFilter(archetype, this.filter));
+  }
+
+  /**
+   * @internal Called by the world when a new archetype is created.
+   */
+  checkNewArchetype(archetype: Archetype): void {
+    if (this.isDisposed) return;
+    if (
+      matchesComponentTypes(archetype, this.componentTypes) &&
+      matchesFilter(archetype, this.filter) &&
+      !this.cachedArchetypes.includes(archetype)
+    ) {
+      this.cachedArchetypes.push(archetype);
+    }
+  }
+
+  /**
+   * @internal Called by the world when an archetype is destroyed.
+   */
+  removeArchetype(archetype: Archetype): void {
+    if (this.isDisposed) return;
+    const index = this.cachedArchetypes.indexOf(archetype);
+    if (index !== -1) {
+      this.cachedArchetypes.splice(index, 1);
+    }
+  }
+
+  /**
+   * Request disposal of this query.
+   * This will decrement the world's reference count for the query.
+   * The query will only be fully disposed when the ref count reaches zero.
+   */
+  dispose(): void {
+    // Ask the world to release this query (decrement refcount and fully dispose when zero)
+    this.world.releaseQuery(this);
+  }
+
+  /**
+   * @internal Fully disposes the query when the world's refCount reaches zero.
+   */
+  _disposeInternal(registry?: QueryRegistry): void {
+    if (!this.isDisposed) {
+      // Unregister from registry (remove from notification list)
+      if (registry) {
+        registry.unregister(this);
+      }
+      this.cachedArchetypes = [];
+      this.isDisposed = true;
+    }
+  }
+
+  /**
+   * Using-with-disposals support. Calls {@link dispose} automatically.
+   *
+   * @example
+   * using query = world.createQuery([Position]);
+   * // query is released automatically when the block exits
+   */
+  [Symbol.dispose](): void {
+    this.dispose();
+  }
+
+  /**
+   * Whether the query has been disposed and can no longer be used.
+   */
+  get disposed(): boolean {
+    return this.isDisposed;
+  }
+}

package/src/query/registry.ts

@@ -0,0 +1,101 @@
+import type { Archetype } from "../archetype/archetype";
+import type { EntityId } from "../entity";
+import type { QueryFilter } from "../query/filter";
+import { Query } from "../query/query";
+import type { World } from "../world/world";
+
+/**
+ * Manages the lifecycle and caching of `Query` instances.
+ *
+ * Responsibilities:
+ * - Create / reuse cached queries keyed by component-type + filter signature.
+ * - Track reference counts so queries are only disposed when truly unused.
+ * - Notify registered queries when new archetypes are created or destroyed.
+ *
+ * The `_cacheKey` string that was previously attached directly to `Query` is now
+ * kept in a private `WeakMap` so the `Query` class doesn't need to expose it.
+ */
+export class QueryRegistry {
+  /** All live queries that should receive archetype notifications. */
+  private readonly queries = new Set<Query>();
+  /** Cache of reusable queries keyed by a deterministic signature string. */
+  private readonly cache = new Map<string, { query: Query; refCount: number }>();
+  /** Maps each query to its cache key without polluting the Query public API. */
+  private readonly cacheKeys = new WeakMap<Query, string>();
+
+  /**
+   * Returns (or creates) a cached query for the given component types and filter.
+   * Increments the reference count on cache hits.
+   *
+   * @param world       The world that owns this registry.
+   * @param sortedTypes  Normalized (sorted) component types.
+   * @param key          Combined cache key (`types|filter`).
+   * @param filter       The raw query filter (used when creating a new Query).
+   */
+  getOrCreate(world: World, sortedTypes: EntityId<any>[], key: string, filter: QueryFilter): Query {
+    const cached = this.cache.get(key);
+    if (cached) {
+      cached.refCount++;
+      return cached.query;
+    }
+
+    const query = new Query(world, sortedTypes, filter, this);
+    this.cacheKeys.set(query, key);
+    this.cache.set(key, { query, refCount: 1 });
+    return query;
+  }
+
+  /**
+   * Decrements the reference count for the given query.
+   * When the count reaches zero the query is fully disposed.
+   */
+  release(query: Query): void {
+    const key = this.cacheKeys.get(query);
+    if (!key) return;
+
+    const cached = this.cache.get(key);
+    if (!cached || cached.query !== query) return;
+
+    cached.refCount--;
+    if (cached.refCount <= 0) {
+      this.cache.delete(key);
+      cached.query._disposeInternal(this);
+    }
+  }
+
+  /**
+   * Registers a query so it receives future archetype notifications.
+   * Called automatically by the `Query` constructor via `world._registerQuery`.
+   */
+  register(query: Query): void {
+    this.queries.add(query);
+  }
+
+  /**
+   * Removes a query from the notification list.
+   * Called by `Query._disposeInternal` via `world._unregisterQuery`.
+   */
+  unregister(query: Query): void {
+    this.queries.delete(query);
+  }
+
+  /**
+   * Notifies all live queries that a new archetype has been created.
+   * Queries will add the archetype to their cache if it matches.
+   */
+  onNewArchetype(archetype: Archetype): void {
+    for (const query of this.queries) {
+      query.checkNewArchetype(archetype);
+    }
+  }
+
+  /**
+   * Notifies all live queries that an archetype has been destroyed.
+   * Queries will remove the archetype from their internal cache.
+   */
+  onArchetypeRemoved(archetype: Archetype): void {
+    for (const query of this.queries) {
+      query.removeArchetype(archetype);
+    }
+  }
+}

package/src/storage/serialization.ts

@@ -0,0 +1,130 @@
+import type { ComponentId, EntityId } from "../entity";
+import { getComponentIdByName, getComponentNameById, getDetailedIdType, relation } from "../entity";
+
+// -----------------------------------------------------------------------------
+// Serialization helpers for IDs
+// -----------------------------------------------------------------------------
+
+export type SerializedEntityId = number | string | { component: string; target: number | string | "*" };
+
+/**
+ * Serialized state of EntityIdManager
+ */
+export interface SerializedEntityIdManager {
+  nextId: number;
+  freelist?: number[];
+}
+
+export type SerializedWorld = {
+  version: number;
+  entityManager: SerializedEntityIdManager;
+  entities: SerializedEntity[];
+  componentEntities?: SerializedEntity[];
+};
+
+export type SerializedEntity = {
+  id: SerializedEntityId;
+  components: SerializedComponent[];
+};
+
+export type SerializedComponent = {
+  type: SerializedEntityId;
+  value: any;
+};
+
+/**
+ * Encode an internal EntityId into a SerializedEntityId for snapshots
+ */
+export function encodeEntityId(id: EntityId<any>): SerializedEntityId {
+  const detailed = getDetailedIdType(id);
+  switch (detailed.type) {
+    case "component": {
+      const name = getComponentNameById(id as ComponentId);
+      if (!name) {
+        // Warn if component doesn't have a name; keep numeric fallback
+        console.warn(`Component ID ${id} has no registered name, serializing as number`);
+      }
+      return name || (id as number);
+    }
+    case "entity-relation": {
+      const componentName = getComponentNameById(detailed.componentId);
+      if (!componentName) {
+        console.warn(`Component ID ${detailed.componentId} in relation has no registered name`);
+      }
+      // Safe: targetId is guaranteed to exist for entity-relation type
+      return { component: componentName || (detailed.componentId as number).toString(), target: detailed.targetId };
+    }
+    case "component-relation": {
+      const componentName = getComponentNameById(detailed.componentId);
+      // Safe: targetId is guaranteed to exist for component-relation type
+      const targetName = getComponentNameById(detailed.targetId as ComponentId);
+      if (!componentName) {
+        console.warn(`Component ID ${detailed.componentId} in relation has no registered name`);
+      }
+      if (!targetName) {
+        console.warn(`Target component ID ${detailed.targetId} in relation has no registered name`);
+      }
+      return {
+        component: componentName || (detailed.componentId as number).toString(),
+        target: targetName || (detailed.targetId as number),
+      };
+    }
+    case "wildcard-relation": {
+      const componentName = getComponentNameById(detailed.componentId);
+      if (!componentName) {
+        console.warn(`Component ID ${detailed.componentId} in relation has no registered name`);
+      }
+      return { component: componentName || (detailed.componentId as number).toString(), target: "*" };
+    }
+    default:
+      return id as number;
+  }
+}
+
+/**
+ * Decode a SerializedEntityId back into an internal EntityId
+ */
+export function decodeSerializedId(sid: SerializedEntityId): EntityId<any> {
+  if (typeof sid === "number") {
+    return sid as EntityId<any>;
+  }
+  if (typeof sid === "string") {
+    const id = getComponentIdByName(sid);
+    if (id === undefined) {
+      const num = parseInt(sid, 10);
+      if (!isNaN(num)) return num as EntityId<any>;
+      throw new Error(`Unknown component name in snapshot: ${sid}`);
+    }
+    return id;
+  }
+  if (typeof sid === "object" && sid !== null && typeof sid.component === "string") {
+    let compId = getComponentIdByName(sid.component);
+    if (compId === undefined) {
+      const num = parseInt(sid.component, 10);
+      if (!isNaN(num)) compId = num as ComponentId;
+    }
+    if (compId === undefined) {
+      throw new Error(`Unknown component name in snapshot: ${sid.component}`);
+    }
+
+    if (sid.target === "*") {
+      return relation(compId, "*");
+    }
+
+    let targetId: EntityId<any>;
+    if (typeof sid.target === "string") {
+      const tid = getComponentIdByName(sid.target);
+      if (tid === undefined) {
+        const num = parseInt(sid.target, 10);
+        if (!isNaN(num)) targetId = num as EntityId<any>;
+        else throw new Error(`Unknown target component name in snapshot: ${sid.target}`);
+      } else {
+        targetId = tid;
+      }
+    } else {
+      targetId = sid.target as EntityId<any>;
+    }
+    return relation(compId, targetId as any);
+  }
+  throw new Error(`Invalid ID in snapshot: ${JSON.stringify(sid)}`);
+}