@codehz/ecs 0.7.6 → 0.8.1

package/src/world/references.ts

@@ -1,8 +1,41 @@
 import type { EntityId } from "../entity";
 import { MultiMap } from "../utils/multi-map";
 
+/**
+ * Reverse reference index: maps each target entity to the set of (source entity, component) pairs
+ * that currently hold a reference to it.
+ *
+ * Used internally to support efficient entity deletion, including:
+ * - Fast-path deletion for unreferenced entities
+ * - Cascading deletes for relations marked with `cascadeDelete`
+ * - Automatic cleanup of entity-valued components and entity-relations when their target is destroyed
+ *
+ * Structure:
+ *   targetEntityId -> MultiMap<sourceEntityId, componentOrRelationId>
+ *
+ * - For plain entity-valued components (component value is an EntityId):
+ *     componentOrRelationId === the component type (which is also the entity id being pointed to)
+ * - For entity-relations (`relation(Comp, target)`):
+ *     componentOrRelationId is the encoded (negative) relation ID
+ *
+ * This index is maintained in sync with structural changes via `updateEntityReferences` in World.
+ *
+ * @internal
+ */
 export type EntityReferencesMap = Map<EntityId, MultiMap<EntityId, EntityId>>;
 
+/**
+ * Record that `sourceEntityId` holds a reference to `targetEntityId` via the given component/relation.
+ *
+ * Called when an entity-valued component or an entity-relation is added to an entity.
+ *
+ * @param entityReferences - The shared reverse index map
+ * @param sourceEntityId - The entity that contains the reference
+ * @param componentType - The component type or encoded relation ID used for the reference
+ * @param targetEntityId - The entity being referenced
+ *
+ * @internal
+ */
 export function trackEntityReference(
   entityReferences: EntityReferencesMap,
   sourceEntityId: EntityId,
@@ -15,6 +48,19 @@ export function trackEntityReference(
   entityReferences.get(targetEntityId)!.add(sourceEntityId, componentType);
 }
 
+/**
+ * Remove the record that `sourceEntityId` references `targetEntityId` via the given component/relation.
+ *
+ * Called when an entity-valued component or entity-relation is removed (or during deletion).
+ * Automatically prunes empty target entries from the map.
+ *
+ * @param entityReferences - The shared reverse index map
+ * @param sourceEntityId - The entity that no longer holds the reference
+ * @param componentType - The component type or encoded relation ID that was used
+ * @param targetEntityId - The previously referenced entity
+ *
+ * @internal
+ */
 export function untrackEntityReference(
   entityReferences: EntityReferencesMap,
   sourceEntityId: EntityId,
@@ -30,6 +76,19 @@ export function untrackEntityReference(
   }
 }
 
+/**
+ * Iterate over all (sourceEntityId, componentOrRelationId) pairs that currently reference the given target.
+ *
+ * Returns an empty iterable when the target has no incoming references.
+ * The returned iterable yields `[source, componentType]` pairs suitable for cleanup decisions
+ * (e.g. whether to cascade-delete the source or just remove the specific component/relation).
+ *
+ * @param entityReferences - The shared reverse index map
+ * @param targetEntityId - The entity whose referrers we want to inspect
+ * @returns Iterable of [sourceEntityId, componentOrRelationId]
+ *
+ * @internal
+ */
 export function getEntityReferences(
   entityReferences: EntityReferencesMap,
   targetEntityId: EntityId,

package/src/world/world.ts

@@ -444,7 +444,10 @@ export class World {
     if (archetype.componentTypeSet.has(componentType)) return true;
 
     if (isDontFragmentRelation(componentType)) {
-      return this.dontFragmentStore.get(entityId)?.has(componentType) ?? false;
+      // Use getValue; presence check via getAllForEntity only if value can legitimately be undefined
+      const val = this.dontFragmentStore.getValue(entityId, componentType);
+      if (val !== undefined) return true;
+      return this.dontFragmentStore.getAllForEntity(entityId).some(([t]) => t === componentType);
     }
 
     return false;
@@ -493,7 +496,11 @@ export class World {
     if (componentType >= 0 || componentType % RELATION_SHIFT !== 0) {
       const inArchetype = archetype.componentTypeSet.has(componentType);
       const hasDontFragment = isDontFragmentRelation(componentType);
-      const hasComponent = inArchetype || (hasDontFragment && this.dontFragmentStore.get(entityId)?.has(componentType));
+      const hasComponent =
+        inArchetype ||
+        (hasDontFragment &&
+          (this.dontFragmentStore.getValue(entityId, componentType) !== undefined ||
+            this.dontFragmentStore.getAllForEntity(entityId).some(([t]) => t === componentType)));
 
       if (!hasComponent) {
         throw new Error(
@@ -698,25 +705,28 @@ export class World {
    * **Important:** Store the query reference and reuse it across frames for optimal performance.
    * Creating a new query each frame defeats the caching mechanism.
    *
-   * @param componentTypes - Array of component types to match
-   * @param filter - Optional filter for additional constraints (e.g., without specific components)
+   * **Note on optional components:** Only **required** (non-optional) component types should be
+   * passed to `createQuery`. Optional components (wrapped with `{ optional: ... }`) must be
+   * specified at **iteration time** via {@link Query.forEach}, {@link Query.getEntitiesWithComponents},
+   * or {@link Query.iterate} — NOT here. Including optional wrappers in `createQuery` will cause
+   * undefined behavior because the internal normalization relies on numeric sorting of component IDs.
+   *
+   * @param componentTypes - Array of **required** component types to match (do not include optional wrappers)
+   * @param filter - Optional filter for additional constraints (e.g., exclude entities with certain components)
    * @returns A Query instance that can be used to iterate matching entities
    *
    * @example
-   * // Create once, reuse many times
+   * // Create once, reuse many times (required components only)
    * const movementQuery = world.createQuery([Position, Velocity]);
    *
-   * // In game loop
-   * movementQuery.forEach((entity) => {
-   *   const pos = world.get(entity, Position);
-   *   const vel = world.get(entity, Velocity);
-   *   pos.x += vel.x;
-   *   pos.y += vel.y;
+   * // Optional components are passed at iteration time, not creation time:
+   * movementQuery.forEach([Position, { optional: Velocity }], (entity, pos, vel) => {
+   *   pos.x += vel?.value?.x ?? 0;
    * });
    *
    * // With filter
    * const activeQuery = world.createQuery([Position], {
-   *   without: [Disabled]
+   *   negativeComponentTypes: [Disabled]
    * });
    */
   createQuery(componentTypes: EntityId<any>[], filter: QueryFilter = {}): Query {