feat(world): add support for retrieving wildcard relation components

- Implemented functionality to retrieve wildcard relation components in the World and Archetype classes.
- Added tests to verify the correct behavior of wildcard relations when adding and retrieving components.
- Enhanced the getComponent method to handle wildcard relation types, returning all matching relations for a given entity.

Author: codehz

src/archetype.test.ts

@@ -66,6 +66,41 @@ describe("Archetype", () => {
     expect(retrieved2).toEqual(newPosition);
   });
 
+  it("should get wildcard relation components", () => {
+    // Create relation component types
+    const target1 = createEntityId(1027);
+    const target2 = createEntityId(1028);
+    const relation1 = createRelationId(positionComponent, target1);
+    const relation2 = createRelationId(positionComponent, target2);
+    const wildcardPositionRelation = createRelationId(positionComponent, "*");
+
+    const entity = createEntityId(1024);
+
+    // Archetype with multiple relations
+    const archetype = new Archetype([relation1, relation2]);
+
+    // Add entity with relations to target1 and target2
+    archetype.addEntity(
+      entity,
+      new Map([
+        [relation1, { distance: 10 }],
+        [relation2, { distance: 20 }],
+      ])
+    );
+
+    // Get wildcard relations
+    const relations = archetype.getComponent(entity, wildcardPositionRelation);
+    expect(relations).toEqual([
+      [target2, { distance: 20 }],
+      [target1, { distance: 10 }],
+    ]);
+
+    // Test with entity not in archetype
+    const nonExistentEntity = createEntityId(9999);
+    const result = archetype.getComponent(nonExistentEntity, wildcardPositionRelation);
+    expect(result).toEqual([]);
+  });
+
   it("should iterate over entities", () => {
     const archetype = new Archetype([positionComponent]);
     const entity1 = createEntityId(1024);

src/archetype.ts

@@ -1,4 +1,4 @@
-import type { EntityId } from "./entity";
+import type { EntityId, WildcardRelationId } from "./entity";
 import { getIdType, decodeRelationId } from "./entity";
 import type { ComponentTuple } from "./types";
 import { getOrComputeCache } from "./utils";
@@ -132,17 +132,48 @@ export class Archetype {
     return this.entityToIndex.has(entityId);
   }
 
+  /**
+   * Get component data for a specific entity and wildcard relation type
+   * Returns an array of all matching relation instances
+   * @param entityId The entity
+   * @param componentType The wildcard relation type
+   */
+  getComponent<T>(entityId: EntityId, componentType: WildcardRelationId<T>): [EntityId<unknown>, any][] | undefined;
   /**
    * Get component data for a specific entity and component type
    * @param entityId The entity
    * @param componentType The component type
    */
-  getComponent<T>(entityId: EntityId, componentType: EntityId<T>): T | undefined {
+  getComponent<T>(entityId: EntityId, componentType: EntityId<T>): T | undefined;
+  getComponent<T>(entityId: EntityId, componentType: EntityId<T> | WildcardRelationId<T>): T | [EntityId<unknown>, any][] | undefined {
     const index = this.entityToIndex.get(entityId);
     if (index === undefined) {
-      return undefined;
+      if (getIdType(componentType) === "wildcard-relation") {
+        return [];
+      } else {
+        return undefined;
+      }
+    }
+
+    if (getIdType(componentType) === "wildcard-relation") {
+      const decoded = decodeRelationId(componentType);
+      const componentId = decoded.componentId;
+      const relations: [EntityId<unknown>, any][] = [];
+
+      for (const relType of this.componentTypes) {
+        const relDecoded = decodeRelationId(relType);
+        if (relDecoded.componentId === componentId && (getIdType(relType) === "entity-relation" || getIdType(relType) === "component-relation")) {
+          const dataArray = this.componentData.get(relType);
+          if (dataArray && dataArray[index] !== undefined) {
+            relations.push([relDecoded.targetId, dataArray[index]]);
+          }
+        }
+      }
+
+      return relations;
+    } else {
+      return this.componentData.get(componentType)?.[index];
     }
-    return this.componentData.get(componentType)?.[index];
   }
 
   /**

src/world.test.ts

@@ -114,6 +114,34 @@ describe("World", () => {
       expect(world.hasComponent(entity, relationId2)).toBe(false);
     });
 
+    it("should get wildcard relation components", () => {
+      const world = new World();
+      const entity = world.createEntity();
+      const position: Position = { x: 10, y: 20 };
+      const targetEntity1 = world.createEntity();
+      const targetEntity2 = world.createEntity();
+      const relationId1 = createRelationId(positionComponent, targetEntity1);
+      const relationId2 = createRelationId(positionComponent, targetEntity2);
+
+      // Add multiple relation components with the same base component
+      world.addComponent(entity, relationId1, position);
+      world.addComponent(entity, relationId2, { x: 20, y: 30 });
+      world.flushCommands();
+
+      // Get wildcard relations
+      const wildcardRelation = createRelationId(positionComponent, "*");
+      const relations = world.getComponent(entity, wildcardRelation);
+      expect(relations).toEqual([
+        [targetEntity2, { x: 20, y: 30 }],
+        [targetEntity1, { x: 10, y: 20 }],
+      ]);
+
+      // Test with entity not having components
+      const otherEntity = world.createEntity();
+      const result = world.getComponent(otherEntity, wildcardRelation);
+      expect(result).toEqual([]);
+    });
+
     it("should handle multiple components", () => {
       const world = new World();
       const entity = world.createEntity();

src/world.ts

@@ -1,7 +1,7 @@
 import { Archetype } from "./archetype";
 import { CommandBuffer, type Command } from "./command-buffer";
-import type { EntityId } from "./entity";
-import { EntityIdManager, getDetailedIdType } from "./entity";
+import type { EntityId, WildcardRelationId } from "./entity";
+import { EntityIdManager, getDetailedIdType, getIdType } from "./entity";
 import { Query } from "./query";
 import type { QueryFilter } from "./query-filter";
 import type { ComponentTuple, LifecycleHook } from "./types";
@@ -180,12 +180,24 @@ export class World<ExtraParams extends any[] = [deltaTime: number]> {
     return archetype ? archetype.componentTypes.includes(componentType) : false;
   }
 
+  /**
+   * Get wildcard relations from an entity
+   */
+  getComponent<T>(entityId: EntityId, componentType: WildcardRelationId<T>): [EntityId<unknown>, any][] | undefined;
   /**
    * Get a component from an entity
    */
-  getComponent<T>(entityId: EntityId, componentType: EntityId<T>): T | undefined {
+  getComponent<T>(entityId: EntityId, componentType: EntityId<T>): T | undefined;
+  getComponent<T>(entityId: EntityId, componentType: EntityId<T> | WildcardRelationId<T>): T | [EntityId<unknown>, any][] | undefined {
     const archetype = this.entityToArchetype.get(entityId);
-    return archetype ? archetype.getComponent(entityId, componentType) : undefined;
+    if (!archetype) {
+      if (getIdType(componentType) === "wildcard-relation") {
+        return [];
+      } else {
+        return undefined;
+      }
+    }
+    return archetype.getComponent(entityId, componentType);
   }
 
   /**