@codehz/ecs 0.1.9 → 0.2.1

package/archetype.d.ts

@@ -1,5 +1,9 @@
 import type { EntityId, WildcardRelationId } from "./entity";
 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

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

@@ -47,7 +47,7 @@ export declare function createEntityId(id: number): EntityId;
 /**
  * Type for relation ID based on component and target types
  */
-type RelationIdType<T, R> = R extends ComponentId<infer U> ? U extends void ? ComponentRelationId<T> : ComponentRelationId<T extends void ? U : T & U> : R extends EntityId<any> ? EntityRelationId<T> : never;
+type RelationIdType<T, R> = R extends ComponentId<infer U> ? U extends void ? ComponentRelationId<T> : ComponentRelationId<T extends void ? U : T> : R extends EntityId<any> ? EntityRelationId<T> : never;
 /**
  * Create a relation ID by associating a component with another ID (entity or component)
  * @param componentId The component ID (0-1023)
@@ -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,8 +214,24 @@ 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) {
@@ -277,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) {
@@ -364,7 +407,7 @@ 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;
@@ -480,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
@@ -564,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);
   }
@@ -744,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);
@@ -895,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;
   }
@@ -909,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) {
@@ -1010,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":
@@ -1051,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) {
@@ -1196,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,
@@ -1222,6 +1302,8 @@ export {
   inspectEntityId,
   getIdType,
   getDetailedIdType,
+  getComponentNameById,
+  getComponentIdByName,
   decodeRelationId,
   createEntityId,
   createComponentId,
@@ -1231,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.9",
+  "version": "0.2.1",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",

package/query.d.ts

@@ -7,13 +7,12 @@ 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
      */

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;
+};