@codehz/ecs 0.1.1 → 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 {
@@ -660,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) {
@@ -1091,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.1",
+  "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>;
 }