steamsheep-ts-game-engine 2.0.0 → 3.0.0

package/dist/state/index.mjs

@@ -129,37 +129,85 @@ var HistoryManager = class {
    * @param maxSnapshots - 最大保存的快照数量，默认使用配置中的值
    */
   constructor(maxSnapshots = DEFAULT_CONFIG.MAX_HISTORY_SNAPSHOTS) {
-    /** 存储的状态快照数组 */
+    /** 存储的状态快照数组（按时间顺序） */
     __publicField(this, "snapshots", []);
-    /** 最大快照数量限制 */
+    /** 命名快照映射表（name -> snapshot） */
+    __publicField(this, "namedSnapshots", /* @__PURE__ */ new Map());
+    /** 最大快照数量限制（不包括命名快照） */
     __publicField(this, "maxSnapshots");
     this.maxSnapshots = maxSnapshots;
   }
   /**
-   * 保存当前状态快照
+   * 保存当前状态快照（匿名快照）
    * 
-   * 通过深拷贝保存状态，防止后续修改影响历史记录
-   * 当快照数量超过最大限制时，自动移除最旧的快照
+   * 通过深拷贝保存状态，防止后续修改影响历史记录。
+   * 当快照数量超过最大限制时，自动移除最旧的快照。
+   * 
+   * 匿名快照用于常规的撤销操作，会受到数量限制。
    * 
    * @param state - 要保存的游戏状态
+   * @param description - 快照描述（可选）
    * 
    * @example
    * ```typescript
    * history.push(gameState);
+   * history.push(gameState, '攻击哥布林前');
    * ```
    */
-  push(state) {
-    const snapshot = JSON.parse(JSON.stringify(state));
+  push(state, description) {
+    const stateCopy = JSON.parse(JSON.stringify(state));
+    const snapshot = {
+      id: `snapshot_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+      timestamp: Date.now(),
+      description,
+      state: stateCopy
+    };
     this.snapshots.push(snapshot);
     if (this.snapshots.length > this.maxSnapshots) {
       this.snapshots.shift();
     }
   }
+  /**
+   * 保存命名快照
+   * 
+   * ⚠️ 新功能：保存可以通过名称访问的快照
+   * 
+   * 命名快照不受数量限制，不会被自动清理。
+   * 适用于重要的游戏节点，如Boss战前、章节开始等。
+   * 
+   * 如果已存在同名快照，会被覆盖。
+   * 
+   * @param state - 要保存的游戏状态
+   * @param name - 快照名称（唯一标识符）
+   * @param description - 快照描述（可选）
+   * 
+   * @example
+   * ```typescript
+   * // 保存Boss战前的状态
+   * history.pushNamed(gameState, 'before_boss_fight', '挑战最终Boss前');
+   * 
+   * // 保存章节开始的状态
+   * history.pushNamed(gameState, 'chapter_2_start', '第二章开始');
+   * ```
+   */
+  pushNamed(state, name, description) {
+    const stateCopy = JSON.parse(JSON.stringify(state));
+    const snapshot = {
+      id: `named_${name}_${Date.now()}`,
+      name,
+      timestamp: Date.now(),
+      description,
+      state: stateCopy
+    };
+    this.namedSnapshots.set(name, snapshot);
+  }
   /**
    * 回退到上一个状态（撤销操作）
    * 
-   * 移除并返回最近的一个快照
-   * 如果没有可用的快照，返回 undefined
+   * 移除并返回最近的一个匿名快照。
+   * 如果没有可用的快照，返回 undefined。
+   * 
+   * 注意：此操作不会影响命名快照。
    * 
    * @returns 上一个状态快照，如果历史为空则返回 undefined
    * 
@@ -173,13 +221,136 @@ var HistoryManager = class {
    * ```
    */
   pop() {
-    return this.snapshots.pop();
+    const snapshot = this.snapshots.pop();
+    return snapshot?.state;
+  }
+  /**
+   * 恢复到命名快照
+   * 
+   * ⚠️ 新功能：通过名称恢复到指定的快照
+   * 
+   * 返回指定名称的快照状态，但不从历史记录中删除它。
+   * 这允许多次恢复到同一个命名快照。
+   * 
+   * @param name - 快照名称
+   * @returns 指定名称的状态快照，如果不存在则返回 undefined
+   * 
+   * @example
+   * ```typescript
+   * // 恢复到Boss战前
+   * const savedState = history.restoreNamed('before_boss_fight');
+   * if (savedState) {
+   *   restoreState(savedState);
+   * } else {
+   *   console.log('快照不存在');
+   * }
+   * ```
+   */
+  restoreNamed(name) {
+    const snapshot = this.namedSnapshots.get(name);
+    return snapshot?.state;
+  }
+  /**
+   * 删除命名快照
+   * 
+   * 从历史记录中删除指定名称的快照。
+   * 
+   * @param name - 要删除的快照名称
+   * @returns 是否成功删除
+   * 
+   * @example
+   * ```typescript
+   * history.deleteNamed('before_boss_fight');
+   * ```
+   */
+  deleteNamed(name) {
+    return this.namedSnapshots.delete(name);
+  }
+  /**
+   * 检查命名快照是否存在
+   * 
+   * @param name - 快照名称
+   * @returns 是否存在指定名称的快照
+   * 
+   * @example
+   * ```typescript
+   * if (history.hasNamed('before_boss_fight')) {
+   *   console.log('可以恢复到Boss战前');
+   * }
+   * ```
+   */
+  hasNamed(name) {
+    return this.namedSnapshots.has(name);
+  }
+  /**
+   * 列出所有快照
+   * 
+   * ⚠️ 新功能：获取所有快照的信息列表
+   * 
+   * 返回所有快照（包括匿名和命名快照）的元数据。
+   * 不包含实际的状态数据，只包含快照信息。
+   * 
+   * @returns 快照信息数组，按时间倒序排列（最新的在前）
+   * 
+   * @example
+   * ```typescript
+   * const snapshots = history.listSnapshots();
+   * snapshots.forEach(snap => {
+   *   console.log(`${snap.name || '匿名'}: ${snap.description || '无描述'}`);
+   *   console.log(`  时间: ${new Date(snap.timestamp).toLocaleString()}`);
+   * });
+   * ```
+   */
+  listSnapshots() {
+    const allSnapshots = [];
+    this.snapshots.forEach((snap) => {
+      allSnapshots.push({
+        id: snap.id,
+        name: snap.name,
+        timestamp: snap.timestamp,
+        description: snap.description
+      });
+    });
+    this.namedSnapshots.forEach((snap) => {
+      allSnapshots.push({
+        id: snap.id,
+        name: snap.name,
+        timestamp: snap.timestamp,
+        description: snap.description
+      });
+    });
+    return allSnapshots.sort((a, b) => b.timestamp - a.timestamp);
+  }
+  /**
+   * 列出所有命名快照
+   * 
+   * 只返回命名快照的信息列表。
+   * 
+   * @returns 命名快照信息数组
+   * 
+   * @example
+   * ```typescript
+   * const namedSnaps = history.listNamedSnapshots();
+   * console.log(`共有 ${namedSnaps.length} 个命名快照`);
+   * ```
+   */
+  listNamedSnapshots() {
+    const result = [];
+    this.namedSnapshots.forEach((snap) => {
+      result.push({
+        id: snap.id,
+        name: snap.name,
+        timestamp: snap.timestamp,
+        description: snap.description
+      });
+    });
+    return result.sort((a, b) => b.timestamp - a.timestamp);
   }
   /**
    * 查看最近的快照但不移除
    * 
-   * 返回最新的快照但不从历史记录中删除它
-   * 用于预览上一个状态而不实际执行撤销操作
+   * 返回最新的匿名快照但不从历史记录中删除它。
+   * 用于预览上一个状态而不实际执行撤销操作。
    * 
    * @returns 最近的状态快照，如果历史为空则返回 undefined
    * 
@@ -192,26 +363,36 @@ var HistoryManager = class {
    * ```
    */
   peek() {
-    return this.snapshots[this.snapshots.length - 1];
+    const snapshot = this.snapshots[this.snapshots.length - 1];
+    return snapshot?.state;
   }
   /**
    * 清空所有历史记录
    * 
-   * 移除所有保存的快照，释放内存
-   * 通常在开始新游戏或重置时使用
+   * 移除所有保存的快照（包括匿名和命名快照），释放内存。
+   * 通常在开始新游戏或重置时使用。
+   * 
+   * @param includeNamed - 是否同时清空命名快照（默认为 false）
    * 
    * @example
    * ```typescript
-   * history.clear(); // 清空所有历史
+   * // 只清空匿名快照
+   * history.clear();
+   * 
+   * // 清空所有快照（包括命名快照）
+   * history.clear(true);
    * ```
    */
-  clear() {
+  clear(includeNamed = false) {
     this.snapshots = [];
+    if (includeNamed) {
+      this.namedSnapshots.clear();
+    }
   }
   /**
-   * 获取当前历史记录数量
+   * 获取当前匿名快照数量
    * 
-   * @returns 当前保存的快照数量
+   * @returns 当前保存的匿名快照数量
    * 
    * @example
    * ```typescript
@@ -224,6 +405,32 @@ var HistoryManager = class {
   get size() {
     return this.snapshots.length;
   }
+  /**
+   * 获取命名快照数量
+   * 
+   * @returns 当前保存的命名快照数量
+   * 
+   * @example
+   * ```typescript
+   * console.log(`命名快照数量: ${history.namedSize}`);
+   * ```
+   */
+  get namedSize() {
+    return this.namedSnapshots.size;
+  }
+  /**
+   * 获取总快照数量
+   * 
+   * @returns 所有快照的总数量（匿名 + 命名）
+   * 
+   * @example
+   * ```typescript
+   * console.log(`总快照数量: ${history.totalSize}`);
+   * ```
+   */
+  get totalSize() {
+    return this.snapshots.length + this.namedSnapshots.size;
+  }
 };
 
 // core/messages.ts
@@ -412,19 +619,29 @@ var createGameEngineStore = (initialState, persistName = "generic-rpg-save") =>
         reset: () => set({ ...initialState, logs: [] }),
         // ========== 历史记录操作实现 ==========
         /**
-         * 实现：保存当前状态快照
+         * 实现：保存当前状态快照（匿名快照）
          * 
          * 保存除日志外的所有状态数据到历史管理器。
          * 日志通常不需要回退，因此被排除以节省内存。
          */
-        saveSnapshot: () => {
+        saveSnapshot: (description) => {
           const currentState = get();
-          history.push(currentState);
+          history.push(currentState, description);
+        },
+        /**
+         * 实现：保存命名快照
+         * 
+         * 保存可以通过名称访问的快照。
+         * 命名快照不受数量限制，适用于重要的游戏节点。
+         */
+        saveNamedSnapshot: (name, description) => {
+          const currentState = get();
+          history.pushNamed(currentState, name, description);
         },
         /**
          * 实现：撤销到上一个状态
          * 
-         * 从历史管理器中恢复上一个快照。
+         * 从历史管理器中恢复上一个匿名快照。
          * 恢复时保留当前的日志，并添加系统提示。
          * 
          * @returns 是否成功撤销
@@ -444,6 +661,56 @@ var createGameEngineStore = (initialState, persistName = "generic-rpg-save") =>
             return true;
           }
           return false;
+        },
+        /**
+         * 实现：恢复到命名快照
+         * 
+         * 通过名称恢复到指定的快照。
+         * 快照不会被删除，可以多次恢复。
+         * 
+         * @returns 是否成功恢复
+         */
+        restoreSnapshot: (name) => {
+          const saved = history.restoreNamed(name);
+          if (saved) {
+            set({
+              stats: saved.stats,
+              inventory: saved.inventory,
+              flags: saved.flags,
+              world: saved.world,
+              extra: saved.extra
+              // logs 保留当前的，不回退日志
+            });
+            get().addLog(`\u5DF2\u6062\u590D\u5230\u5FEB\u7167\uFF1A${name}`, "info");
+            return true;
+          }
+          return false;
+        },
+        /**
+         * 实现：删除命名快照
+         * 
+         * 从历史记录中删除指定名称的快照。
+         * 
+         * @returns 是否成功删除
+         */
+        deleteSnapshot: (name) => {
+          return history.deleteNamed(name);
+        },
+        /**
+         * 实现：列出所有快照
+         * 
+         * 返回所有快照的元数据列表。
+         */
+        listSnapshots: () => {
+          return history.listSnapshots();
+        },
+        /**
+         * 实现：检查命名快照是否存在
+         * 
+         * @returns 是否存在指定名称的快照
+         */
+        hasSnapshot: (name) => {
+          return history.hasNamed(name);
         }
       }),
       {