@codehz/ecs 0.1.0 → 0.1.2

package/README.md

@@ -180,6 +180,80 @@ bun run examples/simple/demo.ts
 - `update(...params)`: 更新世界（参数取决于泛型配置）
 - `sync()`: 应用命令缓冲区
 
+### 序列化（快照）
+
+库提供了对世界状态的「内存快照」序列化接口，用于保存/恢复实体与组件的数据。注意关键点：
+
+- `World.serialize()` 返回一个内存中的快照对象（snapshot），快照会按引用保存组件的实际值；它不会对数据做 JSON.stringify 操作，也不会尝试把组件值转换为可序列化格式。
+- `World.deserialize(snapshot)` 接受由 `World.serialize()` 生成的快照对象并重建世界状态。它期望一个内存对象（非 JSON 字符串）。
+
+为什么采用这种设计？很多情况下组件值可能包含函数、类实例、循环引用或其他无法用 JSON 表示的值。库不对组件值强行进行序列化/字符串化，以避免数据丢失或不可信的自动转换。
+
+示例：内存回环（component 值可为任意对象）
+
+```ts
+// 获取快照（内存对象）
+const snapshot = world.serialize();
+
+// 在同一进程内直接恢复
+const restored = World.deserialize(snapshot);
+```
+
+持久化到磁盘或跨进程传输
+
+如果你需要把世界保存到文件或通过网络传输，需要自己实现组件值的编码/解码策略：
+
+1. 使用 `World.serialize()` 得到 snapshot。
+2. 对 snapshot 中的组件值逐项进行可自定义的编码（例如将类实例转成纯数据、把函数替换为标识符，或使用自定义二进制编码）。
+3. 将编码后的对象字符串化并持久化。恢复时执行相反的解码步骤，得到与 `World.serialize()` 兼容的快照对象，然后调用 `World.deserialize(decodedSnapshot)`。
+
+简单示例：当组件值都是 JSON-友好时
+
+```ts
+const snapshot = world.serialize();
+// 如果组件值都可 JSON 化，可以直接 stringify
+const text = JSON.stringify(snapshot);
+// 写入文件或发送到网络
+
+// 恢复：parse -> deserialize
+const parsed = JSON.parse(text);
+const restored = World.deserialize(parsed);
+```
+
+示例：带自定义编码的持久化（伪代码）
+
+```ts
+const snapshot = world.serialize();
+
+// 将组件值编码为可持久化格式
+const encoded = {
+  ...snapshot,
+  entities: snapshot.entities.map((e) => ({
+    id: e.id,
+    components: e.components.map((c) => ({ type: c.type, value: myEncode(c.value) })),
+  })),
+};
+
+// 持久化 encoded（JSON.stringify / 二进制写入等）
+
+// 恢复时解码回原始组件值
+const decoded = /* parse file and decode */ encoded;
+const readySnapshot = {
+  ...decoded,
+  entities: decoded.entities.map((e) => ({
+    id: e.id,
+    components: e.components.map((c) => ({ type: c.type, value: myDecode(c.value) })),
+  })),
+};
+
+const restored = World.deserialize(readySnapshot);
+```
+
+注意事项
+
+- 快照只包含实体、组件、以及 `EntityIdManager` 的分配器状态（用于保留下一次分配的 ID）；并不会自动恢复已注册的系统、查询缓存或生命周期钩子。恢复后应由应用负责重新注册系统与钩子。
+- 若需要跨版本兼容，建议在持久化格式中包含 `version` 字段，并在恢复时进行格式兼容性检查与迁移。
+
 ### Entity
 
 - `component<T>(id)`: 分配类型安全的组件ID（上限：1022个）

package/entity.d.ts

@@ -129,6 +129,22 @@ export declare class EntityIdManager {
      * Get the next ID that would be allocated (for debugging)
      */
     getNextId(): number;
+    /**
+     * Serialize internal state for persistence.
+     * Returns a plain object representing allocator state. Values may be non-JSON-serializable.
+     */
+    serializeState(): {
+        nextId: number;
+        freelist: number[];
+    };
+    /**
+     * Restore internal state from a previously-serialized object.
+     * Overwrites the current nextId and freelist.
+     */
+    deserializeState(state: {
+        nextId: number;
+        freelist?: number[];
+    }): void;
 }
 /**
  * Component ID Manager for automatic allocation

package/index.js

@@ -184,6 +184,16 @@ class EntityIdManager {
   getNextId() {
     return this.nextId;
   }
+  serializeState() {
+    return { nextId: this.nextId, freelist: Array.from(this.freelist) };
+  }
+  deserializeState(state) {
+    if (typeof state.nextId !== "number") {
+      throw new Error("Invalid state for EntityIdManager.deserializeState");
+    }
+    this.nextId = state.nextId;
+    this.freelist = new Set(state.freelist || []);
+  }
 }
 
 class ComponentIdAllocator {
@@ -259,7 +269,7 @@ class Archetype {
     this.entityToIndex.set(entityId, index);
     for (const componentType of this.componentTypes) {
       const data = componentData.get(componentType);
-      this.componentData.get(componentType).push(data === undefined ? MISSING_COMPONENT : data);
+      this.getComponentData(componentType).push(data === undefined ? MISSING_COMPONENT : data);
     }
   }
   removeEntity(entityId) {
@@ -271,7 +281,7 @@ class Archetype {
     this.entityToIndex.delete(entityId);
     const removedData = new Map;
     for (const componentType of this.componentTypes) {
-      const dataArray = this.componentData.get(componentType);
+      const dataArray = this.getComponentData(componentType);
       removedData.set(componentType, dataArray[index]);
       dataArray.splice(index, 1);
     }
@@ -295,7 +305,7 @@ class Archetype {
       for (const relType of this.componentTypes) {
         const relDetailed = getDetailedIdType(relType);
         if ((relDetailed.type === "entity-relation" || relDetailed.type === "component-relation") && relDetailed.componentId === componentId) {
-          const dataArray = this.componentData.get(relType);
+          const dataArray = this.getComponentData(relType);
           if (dataArray && dataArray[index] !== undefined) {
             const data = dataArray[index];
             relations.push([relDetailed.targetId, data === MISSING_COMPONENT ? undefined : data]);
@@ -304,7 +314,7 @@ class Archetype {
       }
       return relations;
     } else {
-      const data = this.componentData.get(componentType)?.[index];
+      const data = this.getComponentData(componentType)[index];
       return data === MISSING_COMPONENT ? undefined : data;
     }
   }
@@ -316,14 +326,18 @@ class Archetype {
     if (index === undefined) {
       throw new Error(`Entity ${entityId} is not in this archetype`);
     }
-    const dataArray = this.componentData.get(componentType);
+    const dataArray = this.getComponentData(componentType);
     dataArray[index] = data;
   }
   getEntities() {
-    return [...this.entities];
+    return this.entities;
   }
   getComponentData(componentType) {
-    return [...this.componentData.get(componentType) || []];
+    const data = this.componentData.get(componentType);
+    if (!data) {
+      throw new Error(`Component type ${componentType} is not in this archetype`);
+    }
+    return data;
   }
   getEntitiesWithComponents(componentTypes) {
     const result = [];
@@ -347,7 +361,7 @@ class Archetype {
           });
           return matchingRelations;
         } else {
-          return this.componentData.get(compType);
+          return this.getComponentData(compType);
         }
       });
     });
@@ -359,12 +373,10 @@ class Archetype {
           const matchingRelations = dataSource;
           const relations = [];
           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, data === MISSING_COMPONENT ? undefined : data]);
-            }
+            const dataArray = this.getComponentData(relType);
+            const data = dataArray[entityIndex];
+            const decodedRel = decodeRelationId(relType);
+            relations.push([decodedRel.targetId, data === MISSING_COMPONENT ? undefined : data]);
           }
           return relations;
         } else {
@@ -380,7 +392,7 @@ class Archetype {
     for (let i = 0;i < this.entities.length; i++) {
       const components = new Map;
       for (const componentType of this.componentTypes) {
-        const data = this.componentData.get(componentType)[i];
+        const data = this.getComponentData(componentType)[i];
         components.set(componentType, data === MISSING_COMPONENT ? undefined : data);
       }
       callback(this.entities[i], components);
@@ -658,7 +670,8 @@ class World {
   lifecycleHooks = new Map;
   entityReverseIndex = new Map;
   exclusiveComponents = new Set;
-  constructor() {
+  constructor(entityIdManager) {
+    this.entityIdManager = entityIdManager || new EntityIdManager;
     this.commandBuffer = new CommandBuffer((entityId, commands) => this.executeEntityCommands(entityId, commands));
   }
   getComponentTypesHash(componentTypes) {
@@ -1089,6 +1102,63 @@ 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 });
+      }
+      entities.push({ id: entityId, components: compEntries });
+    }
+    return {
+      version: 1,
+      entityManager: this.entityIdManager.serializeState(),
+      exclusiveComponents: Array.from(this.exclusiveComponents),
+      entities
+    };
+  }
+  static deserialize(obj) {
+    if (!obj || typeof obj !== "object") {
+      throw new Error("World.deserialize expects a snapshot object (not a JSON string)");
+    }
+    const entityManager = new EntityIdManager;
+    if (obj && obj.entityManager) {
+      entityManager.deserializeState(obj.entityManager);
+    }
+    const world = new World(entityManager);
+    if (obj && Array.isArray(obj.exclusiveComponents)) {
+      for (const id of obj.exclusiveComponents) {
+        world.exclusiveComponents.add(id);
+      }
+    }
+    if (obj && Array.isArray(obj.entities)) {
+      for (const entry of obj.entities) {
+        const entityId = entry.id;
+        const componentsArray = entry.components || [];
+        const componentMap = new Map;
+        const componentTypes = [];
+        for (const c of componentsArray) {
+          componentMap.set(c.type, c.value);
+          componentTypes.push(c.type);
+        }
+        const archetype = world.getOrCreateArchetype(componentTypes);
+        archetype.addEntity(entityId, componentMap);
+        world.entityToArchetype.set(entityId, archetype);
+        for (const compType of componentTypes) {
+          const detailedType = getDetailedIdType(compType);
+          if (detailedType.type === "entity-relation") {
+            const targetEntityId = detailedType.targetId;
+            world.addComponentReference(entityId, compType, targetEntityId);
+          } else if (detailedType.type === "entity") {
+            world.addComponentReference(entityId, compType, compType);
+          }
+        }
+      }
+    }
+    return world;
+  }
 }
 export {
   relation,

package/package.json

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

package/world.d.ts

@@ -2,6 +2,7 @@ import { Archetype } from "./archetype";
 import { ComponentChangeset } from "./changeset";
 import { type Command } from "./command-buffer";
 import type { EntityId, WildcardRelationId } from "./entity";
+import { EntityIdManager } from "./entity";
 import { Query } from "./query";
 import { type QueryFilter } from "./query-filter";
 import type { System } from "./system";
@@ -35,7 +36,7 @@ export declare class World<UpdateParams extends any[] = []> {
      * For exclusive relations, an entity can have at most one relation per base component
      */
     private exclusiveComponents;
-    constructor();
+    constructor(entityIdManager?: EntityIdManager);
     /**
      * Generate a hash key for component types array
      */
@@ -172,4 +173,20 @@ export declare class World<UpdateParams extends any[] = []> {
      * Execute component lifecycle hooks for added and removed components
      */
     private executeComponentLifecycleHooks;
+    /**
+     * Convert the world into a plain JSON-serializable object.
+     * Note: component values must be JSON-serializable by the caller.
+     */
+    /**
+     * Convert the world into a plain snapshot object.
+     * 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;
+    /**
+     * Deserialize a world from a previously-created snapshot object.
+     * The snapshot must have been produced by `world.serialize()` and may contain
+     * non-JSON values (they will be copied by reference).
+     */
+    static deserialize<T extends any[] = []>(obj: any): World<T>;
 }