@codehz/ecs 0.0.5 → 0.0.7

package/README.md

@@ -120,6 +120,39 @@ world.addComponent(entity, positionRelation, { x: 10, y: 20 });
 world.flushCommands(); // 通配符钩子会被触发
 ```
 
+### Exclusive Relations
+
+ECS 支持 Exclusive Relations，确保实体对于指定的组件类型最多只能有一个关系。当添加新的关系时，会自动移除之前的所有同类型关系：
+
+```typescript
+import { World, component, relation } from "@codehz/ecs";
+
+// 定义组件ID
+const ChildOf = component(); // 空组件，用于关系
+
+// 创建世界
+const world = new World();
+
+// 设置 ChildOf 为独占关系
+world.setExclusive(ChildOf);
+
+// 创建实体
+const child = world.createEntity();
+const parent1 = world.createEntity();
+const parent2 = world.createEntity();
+
+// 添加第一个关系
+world.addComponent(child, relation(ChildOf, parent1));
+world.flushCommands();
+console.log(world.hasComponent(child, relation(ChildOf, parent1))); // true
+
+// 添加第二个关系 - 会自动移除第一个
+world.addComponent(child, relation(ChildOf, parent2));
+world.flushCommands();
+console.log(world.hasComponent(child, relation(ChildOf, parent1))); // false
+console.log(world.hasComponent(child, relation(ChildOf, parent2))); // true
+```
+
 ### 运行示例
 
 ```bash
@@ -139,8 +172,9 @@ bun run examples/simple/demo.ts
 - `createEntity()`: 创建新实体
 - `addComponent(entity, componentId, data)`: 向实体添加组件
 - `removeComponent(entity, componentId)`: 从实体移除组件
+- `setExclusive(componentId)`: 将组件标记为独占关系
 - `createQuery(componentIds)`: 创建查询
-- `registerSystem(system, dependencies?)`: 注册系统，可选指定依赖系统列表
+- `registerSystem(system)`: 注册系统
 - `registerLifecycleHook(componentId, hook)`: 注册组件或通配符关系生命周期钩子
 - `unregisterLifecycleHook(componentId, hook)`: 注销组件或通配符关系生命周期钩子
 - `update(deltaTime)`: 更新世界

package/archetype.d.ts

@@ -66,13 +66,13 @@ export declare class Archetype {
      * @param entityId The entity
      * @param componentType The wildcard relation type
      */
-    getComponent<T>(entityId: EntityId, componentType: WildcardRelationId<T>): [EntityId<unknown>, any][] | undefined;
+    getComponent<T>(entityId: EntityId, componentType: WildcardRelationId<T>): [EntityId<unknown>, any][];
     /**
      * 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;
     /**
      * Set component data for a specific entity and component type
      * @param entityId The entity

package/changeset.d.ts

@@ -0,0 +1,36 @@
+import type { EntityId } from "./entity";
+/**
+ * @internal Represents a set of component changes to be applied to an entity
+ */
+export declare class ComponentChangeset {
+    readonly adds: Map<EntityId<any>, any>;
+    readonly removes: Set<EntityId<any>>;
+    /**
+     * Add a component to the changeset
+     */
+    addComponent<T>(componentType: EntityId<T>, component: T): void;
+    /**
+     * Remove a component from the changeset
+     */
+    removeComponent<T>(componentType: EntityId<T>): void;
+    /**
+     * Check if the changeset has any changes
+     */
+    hasChanges(): boolean;
+    /**
+     * Clear all changes
+     */
+    clear(): void;
+    /**
+     * Merge another changeset into this one
+     */
+    merge(other: ComponentChangeset): void;
+    /**
+     * Apply the changeset to existing components and return the final state
+     */
+    applyTo(existingComponents: Map<EntityId<any>, any>): Map<EntityId<any>, any>;
+    /**
+     * Get the final component types after applying changes
+     */
+    getFinalComponentTypes(existingComponents: Map<EntityId<any>, any>): EntityId<any>[];
+}

package/command-buffer.d.ts

@@ -21,7 +21,8 @@ export declare class CommandBuffer {
     /**
      * Add a component to an entity (deferred)
      */
-    addComponent<T>(entityId: EntityId, componentType: EntityId<T>, component: T): void;
+    addComponent(entityId: EntityId, componentType: EntityId<void>): void;
+    addComponent<T>(entityId: EntityId, componentType: EntityId<T>, component: NoInfer<T>): void;
     /**
      * Remove a component from an entity (deferred)
      */

package/entity.d.ts

@@ -153,5 +153,5 @@ export declare class ComponentIdAllocator {
 /**
  * Allocate a new component ID from the global allocator
  */
-export declare function component<T>(): ComponentId<T>;
+export declare function component<T = void>(): ComponentId<T>;
 export {};

package/index.js

@@ -226,6 +226,8 @@ function getOrCreateWithSideEffect(cache, key, create) {
 }
 
 // src/archetype.ts
+var MISSING_COMPONENT = Symbol("missing component");
+
 class Archetype {
   componentTypes;
   entities = [];
@@ -257,10 +259,7 @@ class Archetype {
     this.entityToIndex.set(entityId, index);
     for (const componentType of this.componentTypes) {
       const data = componentData.get(componentType);
-      if (data === undefined) {
-        throw new Error(`Missing component data for type ${componentType}`);
-      }
-      this.componentData.get(componentType).push(data);
+      this.componentData.get(componentType).push(data === undefined ? MISSING_COMPONENT : data);
     }
   }
   removeEntity(entityId) {
@@ -287,11 +286,7 @@ class Archetype {
   getComponent(entityId, componentType) {
     const index = this.entityToIndex.get(entityId);
     if (index === undefined) {
-      if (getIdType(componentType) === "wildcard-relation") {
-        return [];
-      } else {
-        return;
-      }
+      throw new Error(`Entity ${entityId} is not in this archetype`);
     }
     if (isWildcardRelationId(componentType)) {
       const decoded = decodeRelationId(componentType);
@@ -302,24 +297,26 @@ class Archetype {
         if ((relDetailed.type === "entity-relation" || relDetailed.type === "component-relation") && relDetailed.componentId === componentId) {
           const dataArray = this.componentData.get(relType);
           if (dataArray && dataArray[index] !== undefined) {
-            relations.push([relDetailed.targetId, dataArray[index]]);
+            const data = dataArray[index];
+            relations.push([relDetailed.targetId, data === MISSING_COMPONENT ? undefined : data]);
           }
         }
       }
       return relations;
     } else {
-      return this.componentData.get(componentType)?.[index];
+      const data = this.componentData.get(componentType)?.[index];
+      return data === MISSING_COMPONENT ? undefined : data;
     }
   }
   setComponent(entityId, componentType, data) {
+    if (!this.componentData.has(componentType)) {
+      throw new Error(`Component type ${componentType} is not in this archetype`);
+    }
     const index = this.entityToIndex.get(entityId);
     if (index === undefined) {
       throw new Error(`Entity ${entityId} is not in this archetype`);
     }
     const dataArray = this.componentData.get(componentType);
-    if (!dataArray) {
-      throw new Error(`Component type ${componentType} is not in this archetype`);
-    }
     dataArray[index] = data;
   }
   getEntities() {
@@ -364,14 +361,16 @@ class Archetype {
           for (const relType of matchingRelations) {
             const dataArray = this.componentData.get(relType);
             if (dataArray && dataArray[entityIndex] !== undefined) {
+              const data = dataArray[entityIndex];
               const decodedRel = decodeRelationId(relType);
-              relations.push([decodedRel.targetId, dataArray[entityIndex]]);
+              relations.push([decodedRel.targetId, data === MISSING_COMPONENT ? undefined : data]);
             }
           }
           return relations;
         } else {
           const dataArray = dataSource;
-          return dataArray ? dataArray[entityIndex] : undefined;
+          const data = dataArray ? dataArray[entityIndex] : undefined;
+          return data === MISSING_COMPONENT ? undefined : data;
         }
       });
       callback(entity, ...components);
@@ -381,13 +380,59 @@ class Archetype {
     for (let i = 0;i < this.entities.length; i++) {
       const components = new Map;
       for (const componentType of this.componentTypes) {
-        components.set(componentType, this.componentData.get(componentType)[i]);
+        const data = this.componentData.get(componentType)[i];
+        components.set(componentType, data === MISSING_COMPONENT ? undefined : data);
       }
       callback(this.entities[i], components);
     }
   }
 }
 
+// src/changeset.ts
+class ComponentChangeset {
+  adds = new Map;
+  removes = new Set;
+  addComponent(componentType, component2) {
+    this.adds.set(componentType, component2);
+    this.removes.delete(componentType);
+  }
+  removeComponent(componentType) {
+    this.removes.add(componentType);
+    this.adds.delete(componentType);
+  }
+  hasChanges() {
+    return this.adds.size > 0 || this.removes.size > 0;
+  }
+  clear() {
+    this.adds.clear();
+    this.removes.clear();
+  }
+  merge(other) {
+    for (const [componentType, component2] of other.adds) {
+      this.adds.set(componentType, component2);
+      this.removes.delete(componentType);
+    }
+    for (const componentType of other.removes) {
+      this.removes.add(componentType);
+      this.adds.delete(componentType);
+    }
+  }
+  applyTo(existingComponents) {
+    const finalComponents = new Map(existingComponents);
+    for (const componentType of this.removes) {
+      finalComponents.delete(componentType);
+    }
+    for (const [componentType, component2] of this.adds) {
+      finalComponents.set(componentType, component2);
+    }
+    return finalComponents;
+  }
+  getFinalComponentTypes(existingComponents) {
+    const finalComponents = this.applyTo(existingComponents);
+    return Array.from(finalComponents.keys()).sort((a, b) => a - b);
+  }
+}
+
 // src/command-buffer.ts
 class CommandBuffer {
   commands = [];
@@ -555,26 +600,19 @@ class Query {
 
 // src/system-scheduler.ts
 class SystemScheduler {
-  systems = new Map;
-  allSystems = new Set;
-  addSystem(system, dependencies = []) {
-    this.systems.set(system, dependencies);
-    this.allSystems.add(system);
-    for (const dep of dependencies) {
-      this.allSystems.add(dep);
-    }
-  }
-  removeSystem(system) {
-    this.systems.delete(system);
-    this.allSystems.delete(system);
-    for (const [sys, deps] of this.systems) {
-      const index = deps.indexOf(system);
-      if (index !== -1) {
-        deps.splice(index, 1);
-      }
+  systems = new Set;
+  cachedExecutionOrder = null;
+  addSystem(system) {
+    this.systems.add(system);
+    for (const dep of system.dependencies || []) {
+      this.systems.add(dep);
     }
+    this.cachedExecutionOrder = null;
   }
   getExecutionOrder() {
+    if (this.cachedExecutionOrder !== null) {
+      return this.cachedExecutionOrder;
+    }
     const result = [];
     const visited = new Set;
     const visiting = new Set;
@@ -585,24 +623,24 @@ class SystemScheduler {
         throw new Error("Circular dependency detected in system scheduling");
       }
       visiting.add(system);
-      const dependencies = this.systems.get(system) || [];
-      for (const dep of dependencies) {
+      for (const dep of system.dependencies || []) {
         visit(dep);
       }
       visiting.delete(system);
       visited.add(system);
       result.push(system);
     };
-    for (const system of this.allSystems) {
+    for (const system of this.systems) {
       if (!visited.has(system)) {
         visit(system);
       }
     }
+    this.cachedExecutionOrder = result;
     return result;
   }
   clear() {
     this.systems.clear();
-    this.allSystems.clear();
+    this.cachedExecutionOrder = null;
   }
 }
 
@@ -619,6 +657,7 @@ class World {
   componentToArchetypes = new Map;
   lifecycleHooks = new Map;
   entityReverseIndex = new Map;
+  exclusiveComponents = new Set;
   constructor() {
     this.commandBuffer = new CommandBuffer((entityId, commands) => this.executeEntityCommands(entityId, commands));
   }
@@ -706,19 +745,12 @@ class World {
   getComponent(entityId, componentType) {
     const archetype = this.entityToArchetype.get(entityId);
     if (!archetype) {
-      if (getIdType(componentType) === "wildcard-relation") {
-        return [];
-      } else {
-        return;
-      }
+      throw new Error(`Entity ${entityId} does not exist`);
     }
     return archetype.getComponent(entityId, componentType);
   }
-  registerSystem(system, dependencies = []) {
-    this.systemScheduler.addSystem(system, dependencies);
-  }
-  unregisterSystem(system) {
-    this.systemScheduler.removeSystem(system);
+  registerSystem(system) {
+    this.systemScheduler.addSystem(system);
   }
   registerLifecycleHook(componentType, hook) {
     if (!this.lifecycleHooks.has(componentType)) {
@@ -735,6 +767,9 @@ class World {
       }
     }
   }
+  setExclusive(componentId) {
+    this.exclusiveComponents.add(componentId);
+  }
   update(...params) {
     const systems = this.systemScheduler.getExecutionOrder();
     for (const system of systems) {
@@ -859,30 +894,35 @@ class World {
     }
   }
   executeEntityCommands(entityId, commands) {
+    const changeset = new ComponentChangeset;
     const hasDestroy = commands.some((cmd) => cmd.type === "destroyEntity");
     if (hasDestroy) {
       this._destroyEntity(entityId);
-      return;
+      return changeset;
     }
     const currentArchetype = this.entityToArchetype.get(entityId);
     if (!currentArchetype) {
-      return;
+      return changeset;
     }
     const currentComponents = new Map;
     for (const componentType of currentArchetype.componentTypes) {
       const data = currentArchetype.getComponent(entityId, componentType);
-      if (data !== undefined) {
-        currentComponents.set(componentType, data);
-      }
+      currentComponents.set(componentType, data);
     }
-    const adds = new Map;
-    const removes = new Set;
     for (const cmd of commands) {
       switch (cmd.type) {
         case "addComponent":
-          if (cmd.componentType && cmd.component !== undefined) {
-            adds.set(cmd.componentType, cmd.component);
-            removes.delete(cmd.componentType);
+          if (cmd.componentType) {
+            const detailedType = getDetailedIdType(cmd.componentType);
+            if ((detailedType.type === "entity-relation" || detailedType.type === "component-relation") && this.exclusiveComponents.has(detailedType.componentId)) {
+              for (const componentType of currentArchetype.componentTypes) {
+                const componentDetailedType = getDetailedIdType(componentType);
+                if ((componentDetailedType.type === "entity-relation" || componentDetailedType.type === "component-relation") && componentDetailedType.componentId === detailedType.componentId) {
+                  changeset.removeComponent(componentType);
+                }
+              }
+            }
+            changeset.addComponent(cmd.componentType, cmd.component);
           }
           break;
         case "removeComponent":
@@ -894,27 +934,19 @@ class World {
                 const componentDetailedType = getDetailedIdType(componentType);
                 if (componentDetailedType.type === "entity-relation" || componentDetailedType.type === "component-relation") {
                   if (componentDetailedType.componentId === baseComponentId) {
-                    removes.add(componentType);
-                    adds.delete(componentType);
+                    changeset.removeComponent(componentType);
                   }
                 }
               }
             } else {
-              removes.add(cmd.componentType);
-              adds.delete(cmd.componentType);
+              changeset.removeComponent(cmd.componentType);
             }
           }
           break;
       }
     }
-    const finalComponents = new Map(currentComponents);
-    for (const componentType of removes) {
-      finalComponents.delete(componentType);
-    }
-    for (const [componentType, component2] of adds) {
-      finalComponents.set(componentType, component2);
-    }
-    const finalComponentTypes = Array.from(finalComponents.keys()).sort((a, b) => a - b);
+    const finalComponents = changeset.applyTo(currentComponents);
+    const finalComponentTypes = changeset.getFinalComponentTypes(currentComponents);
     const currentComponentTypes = currentArchetype.componentTypes.sort((a, b) => a - b);
     const needsArchetypeChange = finalComponentTypes.length !== currentComponentTypes.length || !finalComponentTypes.every((type, index) => type === currentComponentTypes[index]);
     if (needsArchetypeChange) {
@@ -923,11 +955,11 @@ class World {
       newArchetype.addEntity(entityId, finalComponents);
       this.entityToArchetype.set(entityId, newArchetype);
     } else {
-      for (const [componentType, component2] of adds) {
+      for (const [componentType, component2] of changeset.adds) {
         currentArchetype.setComponent(entityId, componentType, component2);
       }
     }
-    for (const componentType of removes) {
+    for (const componentType of changeset.removes) {
       const detailedType = getDetailedIdType(componentType);
       if (detailedType.type === "entity-relation") {
         const targetEntityId = detailedType.targetId;
@@ -936,7 +968,7 @@ class World {
         this.removeComponentReference(entityId, componentType, componentType);
       }
     }
-    for (const [componentType, component2] of adds) {
+    for (const [componentType, component2] of changeset.adds) {
       const detailedType = getDetailedIdType(componentType);
       if (detailedType.type === "entity-relation") {
         const targetEntityId = detailedType.targetId;
@@ -945,7 +977,8 @@ class World {
         this.addComponentReference(entityId, componentType, componentType);
       }
     }
-    this.executeComponentLifecycleHooks(entityId, adds, removes);
+    this.executeComponentLifecycleHooks(entityId, changeset.adds, changeset.removes);
+    return changeset;
   }
   getOrCreateArchetype(componentTypes) {
     const sortedTypes = [...componentTypes].sort((a, b) => a - b);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codehz/ecs",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",

package/system-scheduler.d.ts

@@ -4,18 +4,12 @@ import type { System } from "./system";
  */
 export declare class SystemScheduler<ExtraParams extends any[] = [deltaTime: number]> {
     private systems;
-    private allSystems;
+    private cachedExecutionOrder;
     /**
      * Add a system with optional dependencies
      * @param system The system to add
-     * @param dependencies Systems that this system depends on (must run before this system)
      */
-    addSystem(system: System<ExtraParams>, dependencies?: System<ExtraParams>[]): void;
-    /**
-     * Remove a system
-     * @param system The system to remove
-     */
-    removeSystem(system: System<ExtraParams>): void;
+    addSystem(system: System<ExtraParams>): void;
     /**
      * Get the execution order of systems based on dependencies
      * Uses topological sort

package/system.d.ts

@@ -7,4 +7,8 @@ export interface System<ExtraParams extends any[] = [deltaTime: number]> {
      * Update the system
      */
     update(world: World<ExtraParams>, ...params: ExtraParams): void;
+    /**
+     * Dependencies of this system (systems that must run before this one)
+     */
+    readonly dependencies?: readonly System<ExtraParams>[];
 }

package/world.d.ts

@@ -1,4 +1,5 @@
 import { Archetype } from "./archetype";
+import { ComponentChangeset } from "./changeset";
 import { type Command } from "./command-buffer";
 import type { EntityId, WildcardRelationId } from "./entity";
 import { Query } from "./query";
@@ -29,6 +30,11 @@ export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
      * This includes both relation components and direct usage of entities as component types
      */
     private entityReverseIndex;
+    /**
+     * Set of component IDs that are marked as exclusive relations
+     * For exclusive relations, an entity can have at most one relation per base component
+     */
+    private exclusiveComponents;
     constructor();
     /**
      * Generate a hash key for component types array
@@ -49,7 +55,8 @@ export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
     /**
      * Add a component to an entity (deferred)
      */
-    addComponent<T>(entityId: EntityId, componentType: EntityId<T>, component: T): void;
+    addComponent(entityId: EntityId, componentType: EntityId<void>): void;
+    addComponent<T>(entityId: EntityId, componentType: EntityId<T>, component: NoInfer<T>): void;
     /**
      * Remove a component from an entity (deferred)
      */
@@ -63,21 +70,22 @@ export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
      */
     hasComponent<T>(entityId: EntityId, componentType: EntityId<T>): boolean;
     /**
-     * Get wildcard relations from an entity
+     * 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;
+    getComponent<T>(entityId: EntityId, componentType: WildcardRelationId<T>): [EntityId<unknown>, T][];
     /**
-     * Get a component from an entity
+     * 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;
     /**
      * Register a system with optional dependencies
      */
-    registerSystem(system: System<ExtraParams>, dependencies?: System<ExtraParams>[]): void;
-    /**
-     * Unregister a system
-     */
-    unregisterSystem(system: System<ExtraParams>): void;
+    registerSystem(system: System<ExtraParams>): void;
     /**
      * Register a lifecycle hook for component or wildcard relation events
      */
@@ -86,6 +94,11 @@ export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
      * Unregister a lifecycle hook for component or wildcard relation events
      */
     unregisterLifecycleHook<T>(componentType: EntityId<T>, hook: LifecycleHook<T>): void;
+    /**
+     * Mark a component as exclusive relation
+     * For exclusive relations, an entity can have at most one relation per base component
+     */
+    setExclusive(componentId: EntityId): void;
     /**
      * Update the world (run all systems in dependency order)
      */
@@ -126,7 +139,7 @@ export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
     /**
      * @internal Execute commands for a single entity (for internal use by CommandBuffer)
      */
-    executeEntityCommands(entityId: EntityId, commands: Command[]): void;
+    executeEntityCommands(entityId: EntityId, commands: Command[]): ComponentChangeset;
     /**
      * Get or create an archetype for the given component types
      */