@codehz/ecs 0.1.8 → 0.2.0

package/archetype.d.ts

@@ -1,5 +1,9 @@
 import type { EntityId, WildcardRelationId } from "./entity";
-import type { ComponentTuple } from "./types";
+import { type ComponentTuple, type ComponentType } from "./types";
+/**
+ * Special value to represent missing component data
+ */
+export declare const MISSING_COMPONENT: unique symbol;
 /**
  * Archetype class for ECS architecture
  * Represents a group of entities that share the same set of components
@@ -49,6 +53,20 @@ export declare class Archetype {
      * @param componentData Map of component type to component data
      */
     addEntity(entityId: EntityId, componentData: Map<EntityId<any>, any>): void;
+    /**
+     * Get all component data for a specific entity
+     * @param entityId The entity to get data for
+     * @returns Map of component type to component data
+     */
+    getEntity(entityId: EntityId): Map<EntityId<any>, any> | undefined;
+    /**
+     * Dump all entities and their component data in this archetype
+     * @returns Array of objects with entity and component data
+     */
+    dump(): Array<{
+        entity: EntityId;
+        components: Map<EntityId<any>, any>;
+    }>;
     /**
      * Remove an entity from this archetype
      * @param entityId The entity to remove
@@ -89,13 +107,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 +129,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/changeset.d.ts

@@ -29,4 +29,10 @@ export declare class ComponentChangeset {
      * 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 the changeset
+     * @param existingComponentTypes - The current component types on the entity
+     * @returns The final component types or undefined if no changes
+     */
+    getFinalComponentTypes(existingComponentTypes: EntityId<any>[]): EntityId<any>[] | undefined;
 }

package/entity.d.ts

@@ -167,7 +167,22 @@ export declare class ComponentIdAllocator {
     hasAvailableIds(): boolean;
 }
 /**
- * Allocate a new component ID from the global allocator
+ * Allocate a new component ID from the global allocator.
+ * Optionally register a name for the component.
+ * The name is only for serialization/debugging and does not affect base functionality.
+ * @param name Optional name for the component
+ * @returns The allocated component ID
  */
-export declare function component<T = void>(): ComponentId<T>;
+export declare function component<T = void>(name?: string): ComponentId<T>;
+/**
+ * Get a component ID by its registered name
+ * @param name The component name
+ * @returns The component ID if found, undefined otherwise
+ */
+export declare function getComponentIdByName(name: string): ComponentId<any> | undefined;
+/** Get a component name by its ID
+ * @param id The component ID
+ * @returns The component name if found, undefined otherwise
+ */
+export declare function getComponentNameById(id: ComponentId<any>): string | undefined;
 export {};

package/index.js

@@ -214,9 +214,30 @@ class ComponentIdAllocator {
   }
 }
 var globalComponentIdAllocator = new ComponentIdAllocator;
-function component() {
-  return globalComponentIdAllocator.allocate();
+var ComponentNames = new Map;
+var ComponentIdForNames = new Map;
+function component(name) {
+  const id = globalComponentIdAllocator.allocate();
+  if (name) {
+    if (ComponentIdForNames.has(name)) {
+      throw new Error(`Component name "${name}" is already registered`);
+    }
+    ComponentNames.set(id, name);
+    ComponentIdForNames.set(name, id);
+  }
+  return id;
+}
+function getComponentIdByName(name) {
+  return ComponentIdForNames.get(name);
 }
+function getComponentNameById(id) {
+  return ComponentNames.get(id);
+}
+// 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);
@@ -272,6 +293,33 @@ class Archetype {
       this.getComponentData(componentType).push(data === undefined ? MISSING_COMPONENT : data);
     }
   }
+  getEntity(entityId) {
+    const index = this.entityToIndex.get(entityId);
+    if (index === undefined) {
+      return;
+    }
+    const entityData = new Map;
+    for (const componentType of this.componentTypes) {
+      const dataArray = this.getComponentData(componentType);
+      const data = dataArray[index];
+      entityData.set(componentType, data === MISSING_COMPONENT ? undefined : data);
+    }
+    return entityData;
+  }
+  dump() {
+    const result = [];
+    for (let i = 0;i < this.entities.length; i++) {
+      const entity = this.entities[i];
+      const components = new Map;
+      for (const componentType of this.componentTypes) {
+        const dataArray = this.getComponentData(componentType);
+        const data = dataArray[i];
+        components.set(componentType, data === MISSING_COMPONENT ? undefined : data);
+      }
+      result.push({ entity, components });
+    }
+    return result;
+  }
   removeEntity(entityId) {
     const index = this.entityToIndex.get(entityId);
     if (index === undefined) {
@@ -348,6 +396,9 @@ class Archetype {
     }
     return data;
   }
+  getOptionalComponentData(componentType) {
+    return this.componentData.get(componentType);
+  }
   getEntitiesWithComponents(componentTypes) {
     const result = [];
     this.forEachWithComponents(componentTypes, (entity, ...components) => {
@@ -356,9 +407,14 @@ class Archetype {
     return result;
   }
   forEachWithComponents(componentTypes, callback) {
-    const cacheKey = componentTypes.map((id) => id.toString()).join(",");
+    const cacheKey = componentTypes.map((id) => isOptionalEntityId(id) ? `opt(${id.optional})` : `${id}`).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 +424,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 +455,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);
@@ -447,6 +523,25 @@ class ComponentChangeset {
     }
     return existingComponents;
   }
+  getFinalComponentTypes(existingComponentTypes) {
+    const finalComponentTypes = new Set(existingComponentTypes);
+    let changed = false;
+    for (const componentType of this.removes) {
+      if (!finalComponentTypes.has(componentType)) {
+        continue;
+      }
+      changed = true;
+      finalComponentTypes.delete(componentType);
+    }
+    for (const componentType of this.adds.keys()) {
+      if (finalComponentTypes.has(componentType)) {
+        continue;
+      }
+      changed = true;
+      finalComponentTypes.add(componentType);
+    }
+    return changed ? Array.from(finalComponentTypes) : undefined;
+  }
 }
 
 // src/command-buffer.ts
@@ -531,17 +626,15 @@ function matchesFilter(archetype, filter) {
 
 // src/query.ts
 class Query {
-  key;
   world;
   componentTypes;
   filter;
   cachedArchetypes = [];
   isDisposed = false;
-  constructor(world, componentTypes, filter = {}, key) {
+  constructor(world, componentTypes, filter = {}) {
     this.world = world;
     this.componentTypes = [...componentTypes].sort((a, b) => a - b);
     this.filter = filter;
-    this.key = key ?? `${this.componentTypes.join(",")}|`;
     this.updateCache();
     world._registerQuery(this);
   }
@@ -711,8 +804,27 @@ class World {
           const componentMap = new Map;
           const componentTypes = [];
           for (const componentEntry of componentsArray) {
-            componentMap.set(componentEntry.type, componentEntry.value);
-            componentTypes.push(componentEntry.type);
+            const componentTypeRaw = componentEntry.type;
+            let componentType;
+            if (typeof componentTypeRaw === "number") {
+              componentType = componentTypeRaw;
+            } else if (typeof componentTypeRaw === "string") {
+              const compId = getComponentIdByName(componentTypeRaw);
+              if (compId === undefined) {
+                throw new Error(`Unknown component name in snapshot: ${componentTypeRaw}`);
+              }
+              componentType = compId;
+            } else if (typeof componentTypeRaw === "object" && componentTypeRaw !== null && typeof componentTypeRaw.component === "string" && typeof componentTypeRaw.target === "number") {
+              const compId = getComponentIdByName(componentTypeRaw.component);
+              if (compId === undefined) {
+                throw new Error(`Unknown component name in snapshot: ${componentTypeRaw.component}`);
+              }
+              componentType = relation(compId, componentTypeRaw.target);
+            } else {
+              throw new Error(`Invalid component type in snapshot: ${JSON.stringify(componentTypeRaw)}`);
+            }
+            componentMap.set(componentType, componentEntry.value);
+            componentTypes.push(componentType);
           }
           const archetype = this.ensureArchetype(componentTypes);
           archetype.addEntity(entityId, componentMap);
@@ -862,7 +974,7 @@ class World {
       cached.refCount++;
       return cached.query;
     }
-    const query = new Query(this, sortedTypes, filter, key);
+    const query = new Query(this, sortedTypes, filter);
     this.queryCache.set(key, { query, refCount: 1 });
     return query;
   }
@@ -876,27 +988,17 @@ class World {
     }
   }
   releaseQuery(query) {
-    const key = query.key;
     for (const [k, v] of this.queryCache.entries()) {
       if (v.query === query) {
         v.refCount--;
         if (v.refCount <= 0) {
           this.queryCache.delete(k);
+          this._unregisterQuery(query);
           v.query._disposeInternal();
         }
         return;
       }
     }
-    const entry = this.queryCache.get(key);
-    if (!entry) {
-      this._unregisterQuery(query);
-      return;
-    }
-    entry.refCount--;
-    if (entry.refCount <= 0) {
-      this.queryCache.delete(key);
-      entry.query._disposeInternal();
-    }
   }
   getMatchingArchetypes(componentTypes) {
     if (componentTypes.length === 0) {
@@ -977,11 +1079,6 @@ class World {
     if (!currentArchetype) {
       return changeset;
     }
-    const currentComponents = new Map;
-    for (const componentType of currentArchetype.componentTypes) {
-      const componentData = currentArchetype.get(entityId, componentType);
-      currentComponents.set(componentType, componentData);
-    }
     for (const command of commands) {
       switch (command.type) {
         case "set":
@@ -1018,13 +1115,11 @@ class World {
           break;
       }
     }
-    const finalComponents = changeset.applyTo(currentComponents);
-    const currentComponentTypes = currentArchetype.componentTypes;
-    const needsArchetypeChange = finalComponents.size !== currentComponentTypes.length || !currentComponentTypes.every((type) => finalComponents.has(type));
-    if (needsArchetypeChange) {
-      const newArchetype = this.ensureArchetype(finalComponents.keys());
-      currentArchetype.removeEntity(entityId);
-      newArchetype.addEntity(entityId, finalComponents);
+    const finalComponentTypes = changeset.getFinalComponentTypes(currentArchetype.componentTypes);
+    if (finalComponentTypes) {
+      const newArchetype = this.ensureArchetype(finalComponentTypes);
+      const currentComponents = currentArchetype.removeEntity(entityId);
+      newArchetype.addEntity(entityId, changeset.applyTo(currentComponents));
       this.entityToArchetype.set(entityId, newArchetype);
     } else {
       for (const [componentType, component2] of changeset.adds) {
@@ -1163,13 +1258,31 @@ class World {
   }
   serialize() {
     const entities = [];
-    for (const [entityId, archetype] of this.entityToArchetype.entries()) {
-      const compEntries = [];
-      for (const compType of archetype.componentTypes) {
-        const value = archetype.get(entityId, compType);
-        compEntries.push({ type: compType, value });
+    for (const archetype of this.archetypes) {
+      const dumpedEntities = archetype.dump();
+      for (const { entity, components } of dumpedEntities) {
+        entities.push({
+          id: entity,
+          components: Array.from(components.entries()).map(([rawType, value]) => {
+            const detailedType = getDetailedIdType(rawType);
+            let type = rawType;
+            let componentName;
+            switch (detailedType.type) {
+              case "component":
+                type = getComponentNameById(rawType) || rawType;
+                break;
+              case "entity-relation":
+              case "component-relation":
+                componentName = getComponentNameById(detailedType.componentId);
+                if (componentName) {
+                  type = { component: componentName, target: detailedType.targetId };
+                }
+                break;
+            }
+            return { type, value: value === MISSING_COMPONENT ? undefined : value };
+          })
+        });
       }
-      entities.push({ id: entityId, components: compEntries });
     }
     return {
       version: 1,
@@ -1183,11 +1296,14 @@ export {
   relation,
   isWildcardRelationId,
   isRelationId,
+  isOptionalEntityId,
   isEntityId,
   isComponentId,
   inspectEntityId,
   getIdType,
   getDetailedIdType,
+  getComponentNameById,
+  getComponentIdByName,
   decodeRelationId,
   createEntityId,
   createComponentId,
@@ -1197,6 +1313,7 @@ export {
   SystemScheduler,
   RELATION_SHIFT,
   Query,
+  MISSING_COMPONENT,
   INVALID_COMPONENT_ID,
   EntityIdManager,
   ENTITY_ID_START,

package/package.json

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

package/query.d.ts

@@ -1,19 +1,18 @@
 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
  */
 export declare class Query {
-    readonly key: string;
     private world;
     private componentTypes;
     private filter;
     private cachedArchetypes;
     private isDisposed;
-    constructor(world: World<any[]>, componentTypes: EntityId<any>[], filter?: QueryFilter, key?: string);
+    constructor(world: World<any[]>, componentTypes: EntityId<any>[], filter?: QueryFilter);
     /**
      * Get all entities matching the query
      */
@@ -23,7 +22,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 +31,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/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

@@ -40,7 +40,7 @@ export declare class World<UpdateParams extends any[] = []> {
      * If an optional snapshot object is provided (previously produced by `world.serialize()`),
      * the world will be restored from that snapshot. The snapshot may contain non-JSON values.
      */
-    constructor(snapshot?: any);
+    constructor(snapshot?: SerializedWorld);
     /**
      * Generate a signature string for component types array
      * @returns A string signature for the component types
@@ -192,5 +192,22 @@ export declare class World<UpdateParams extends any[] = []> {
      * This returns an in-memory structure and does not perform JSON stringification.
      * Component values are stored as-is (they may be non-JSON-serializable).
      */
-    serialize(): any;
+    serialize(): SerializedWorld;
 }
+export type SerializedWorld = {
+    version: number;
+    entityManager: any;
+    exclusiveComponents: EntityId[];
+    entities: SerializedEntity[];
+};
+export type SerializedEntity = {
+    id: number;
+    components: SerializedComponent[];
+};
+export type SerializedComponent = {
+    type: number | string | {
+        component: string;
+        target: number;
+    };
+    value: any;
+};