@codehz/ecs 0.1.7 → 0.1.9

package/archetype.d.ts

@@ -1,5 +1,5 @@
 import type { EntityId, WildcardRelationId } from "./entity";
-import type { ComponentTuple } from "./types";
+import { type ComponentTuple, type ComponentType } from "./types";
 /**
  * Archetype class for ECS architecture
  * Represents a group of entities that share the same set of components
@@ -89,13 +89,19 @@ export declare class Archetype {
      * @param componentType The component type
      */
     getComponentData<T>(componentType: EntityId<T>): T[];
+    /**
+     * Get optional component data for all entities of a specific component type
+     * @param componentType The component type
+     * @returns An array of component data or undefined if not present
+     */
+    getOptionalComponentData<T>(componentType: EntityId<T>): T[] | undefined;
     /**
      * Get entities with their component data for specified component types
      * Optimized for bulk component access with pre-computed indices
      * @param componentTypes Array of component types to retrieve
      * @returns Array of objects with entity and component data
      */
-    getEntitiesWithComponents<const T extends readonly EntityId<any>[]>(componentTypes: T): Array<{
+    getEntitiesWithComponents<const T extends readonly ComponentType<any>[]>(componentTypes: T): Array<{
         entity: EntityId;
         components: ComponentTuple<T>;
     }>;
@@ -105,7 +111,7 @@ export declare class Archetype {
      * @param componentTypes Array of component types to retrieve
      * @param callback Function called for each entity with its components
      */
-    forEachWithComponents<const T extends readonly EntityId<any>[]>(componentTypes: T, callback: (entity: EntityId, ...components: ComponentTuple<T>) => void): void;
+    forEachWithComponents<const T extends readonly ComponentType<any>[]>(componentTypes: T, callback: (entity: EntityId, ...components: ComponentTuple<T>) => void): void;
     /**
      * Iterate over all entities with their component data
      * @param callback Function called for each entity with its component data

package/index.js

@@ -217,6 +217,11 @@ var globalComponentIdAllocator = new ComponentIdAllocator;
 function component() {
   return globalComponentIdAllocator.allocate();
 }
+// src/types.ts
+function isOptionalEntityId(type) {
+  return typeof type === "object" && type !== null && "optional" in type;
+}
+
 // src/utils.ts
 function getOrComputeCache(cache, key, compute) {
   let value = cache.get(key);
@@ -348,6 +353,9 @@ class Archetype {
     }
     return data;
   }
+  getOptionalComponentData(componentType) {
+    return this.componentData.get(componentType);
+  }
   getEntitiesWithComponents(componentTypes) {
     const result = [];
     this.forEachWithComponents(componentTypes, (entity, ...components) => {
@@ -359,6 +367,11 @@ class Archetype {
     const cacheKey = componentTypes.map((id) => id.toString()).join(",");
     const componentDataSources = getOrComputeCache(this.componentDataSourcesCache, cacheKey, () => {
       return componentTypes.map((compType) => {
+        let optional = false;
+        if (isOptionalEntityId(compType)) {
+          compType = compType.optional;
+          optional = true;
+        }
         const detailedType = getDetailedIdType(compType);
         if (detailedType.type === "wildcard-relation") {
           const componentId = detailedType.componentId;
@@ -368,17 +381,29 @@ class Archetype {
               return false;
             return detailedCt.componentId === componentId;
           });
-          return matchingRelations;
+          return optional ? matchingRelations.length > 0 ? matchingRelations : undefined : matchingRelations;
         } else {
-          return this.getComponentData(compType);
+          return optional ? this.getOptionalComponentData(compType) : this.getComponentData(compType);
         }
       });
     });
     for (let entityIndex = 0;entityIndex < this.entities.length; entityIndex++) {
       const entity = this.entities[entityIndex];
       const components = componentDataSources.map((dataSource, i) => {
-        const compType = componentTypes[i];
+        let compType = componentTypes[i];
+        let optional = false;
+        if (isOptionalEntityId(compType)) {
+          compType = compType.optional;
+          optional = true;
+        }
         if (getIdType(compType) === "wildcard-relation") {
+          if (dataSource === undefined) {
+            if (optional) {
+              return;
+            } else {
+              throw new Error(`No matching relations found for mandatory wildcard relation component type`);
+            }
+          }
           const matchingRelations = dataSource;
           const relations = [];
           for (const relType of matchingRelations) {
@@ -387,11 +412,19 @@ class Archetype {
             const decodedRel = decodeRelationId(relType);
             relations.push([decodedRel.targetId, data === MISSING_COMPONENT ? undefined : data]);
           }
-          return relations;
+          return optional ? { value: relations } : relations;
         } else {
+          if (dataSource === undefined) {
+            if (optional) {
+              return;
+            } else {
+              throw new Error(`No matching relations found for mandatory wildcard relation component type`);
+            }
+          }
           const dataArray = dataSource;
-          const data = dataArray ? dataArray[entityIndex] : undefined;
-          return data === MISSING_COMPONENT ? undefined : data;
+          const data = dataArray[entityIndex];
+          const result = data === MISSING_COMPONENT ? undefined : data;
+          return optional ? { value: result } : result;
         }
       });
       callback(entity, ...components);
@@ -656,6 +689,24 @@ class SystemScheduler {
     this.cachedExecutionOrder = result;
     return result;
   }
+  update(...params) {
+    const executionOrder = this.getExecutionOrder();
+    const systemPromises = new Map;
+    for (const system of executionOrder) {
+      const deps = Array.from(this.systemDependencies.get(system) || []);
+      const depPromises = deps.map((dep) => systemPromises.get(dep)).filter(Boolean);
+      if (depPromises.length > 0) {
+        const promise = Promise.all(depPromises).then(() => system.update(...params));
+        systemPromises.set(system, promise);
+      } else {
+        const result = system.update(...params);
+        if (result instanceof Promise) {
+          systemPromises.set(system, result);
+        }
+      }
+    }
+    return Promise.all(systemPromises.values());
+  }
   clear() {
     this.systems.clear();
     this.cachedExecutionOrder = null;
@@ -825,11 +876,12 @@ class World {
     this.exclusiveComponents.add(componentId);
   }
   update(...params) {
-    const systems = this.systemScheduler.getExecutionOrder();
-    for (const system of systems) {
-      system.update(...params);
+    const result = this.systemScheduler.update(...params);
+    if (result instanceof Promise) {
+      return result.then(() => this.commandBuffer.execute());
+    } else {
+      this.commandBuffer.execute();
     }
-    this.commandBuffer.execute();
   }
   sync() {
     this.commandBuffer.execute();
@@ -1164,6 +1216,7 @@ export {
   relation,
   isWildcardRelationId,
   isRelationId,
+  isOptionalEntityId,
   isEntityId,
   isComponentId,
   inspectEntityId,

package/package.json

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

package/query.d.ts

@@ -1,7 +1,7 @@
 import { Archetype } from "./archetype";
 import type { EntityId } from "./entity";
 import { type QueryFilter } from "./query-filter";
-import type { ComponentTuple } from "./types";
+import type { ComponentTuple, ComponentType } from "./types";
 import type { World } from "./world";
 /**
  * Query class for efficient entity queries with cached archetypes
@@ -23,7 +23,7 @@ export declare class Query {
      * @param componentTypes Array of component types to retrieve
      * @returns Array of objects with entity and component data
      */
-    getEntitiesWithComponents<const T extends readonly EntityId<any>[]>(componentTypes: T): Array<{
+    getEntitiesWithComponents<const T extends readonly ComponentType<any>[]>(componentTypes: T): Array<{
         entity: EntityId;
         components: ComponentTuple<T>;
     }>;
@@ -32,7 +32,7 @@ export declare class Query {
      * @param componentTypes Array of component types to retrieve
      * @param callback Function called for each entity with its components
      */
-    forEach<const T extends readonly EntityId<any>[]>(componentTypes: T, callback: (entity: EntityId, ...components: ComponentTuple<T>) => void): void;
+    forEach<const T extends readonly ComponentType<any>[]>(componentTypes: T, callback: (entity: EntityId, ...components: ComponentTuple<T>) => void): void;
     /**
      * Get component data arrays for all matching entities
      * @param componentType The component type to retrieve

package/system-scheduler.d.ts

@@ -2,7 +2,7 @@ import type { System } from "./system";
 /**
  * System Scheduler for managing system dependencies and execution order
  */
-export declare class SystemScheduler<UpdateParams extends any[] = [deltaTime: number]> {
+export declare class SystemScheduler<UpdateParams extends any[] = []> {
     private systems;
     private systemDependencies;
     private cachedExecutionOrder;
@@ -17,6 +17,7 @@ export declare class SystemScheduler<UpdateParams extends any[] = [deltaTime: nu
      * Uses topological sort
      */
     getExecutionOrder(): System<UpdateParams>[];
+    update(...params: UpdateParams): Promise<void[]> | void;
     /**
      * Clear all systems and dependencies
      */

package/system.d.ts

@@ -5,7 +5,7 @@ export interface System<UpdateParams extends any[] = []> {
     /**
      * Update the system
      */
-    update(...params: UpdateParams): void;
+    update(...params: UpdateParams): void | Promise<void>;
     /**
      * Dependencies of this system (systems that must run before this one)
      */

package/types.d.ts

@@ -12,9 +12,19 @@ export interface LifecycleHook<T = unknown> {
      */
     onRemoved?: (entityId: EntityId, componentType: EntityId<T>) => void;
 }
+export type ComponentType<T> = EntityId<T> | OptionalEntityId<T>;
+export type OptionalEntityId<T> = {
+    optional: EntityId<T>;
+};
+export declare function isOptionalEntityId<T>(type: ComponentType<T>): type is OptionalEntityId<T>;
+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;
 /**
  * Type helper for component tuples extracted from EntityId array
  */
-export type ComponentTuple<T extends readonly EntityId<any>[]> = {
-    readonly [K in keyof T]: T[K] extends WildcardRelationId<infer U> ? [EntityId<unknown>, U][] : T[K] extends EntityId<infer U> ? U : never;
+export type ComponentTuple<T extends readonly ComponentType<any>[]> = {
+    readonly [K in keyof T]: ComponentTypeToData<T[K]>;
 };

package/world.d.ts

@@ -110,8 +110,10 @@ export declare class World<UpdateParams extends any[] = []> {
     setExclusive(componentId: EntityId): void;
     /**
      * Update the world (run all systems in dependency order)
+     * This function is synchronous when all systems are synchronous,
+     * and asynchronous (returns a Promise) when any system is asynchronous.
      */
-    update(...params: UpdateParams): void;
+    update(...params: UpdateParams): Promise<void> | void;
     /**
      * Execute all deferred commands immediately without running systems
      */