steamsheep-ts-game-engine 2.0.0 → 3.0.0

package/dist/state/index.d.mts

@@ -1,12 +1,37 @@
-export { a as GameStore, G as GameStoreActions, c as createGameEngineStore } from '../store-xBiJ2MvB.mjs';
-import { G as GameState } from '../types-BLjkeE3R.mjs';
+export { G as GameStore, a as GameStoreActions, c as createGameEngineStore } from '../store-B7yMYHpB.mjs';
+import { a as GameState } from '../types-C3Q7UPWy.mjs';
 import 'zustand/middleware';
 import 'zustand';
 
+/**
+ * 快照信息接口
+ *
+ * 包含快照的元数据和实际状态数据
+ */
+interface SnapshotInfo<S extends string, I extends string, F extends string, X = Record<string, unknown>> {
+    /** 快照的唯一标识符（自动生成的时间戳） */
+    id: string;
+    /** 快照名称（可选，用于命名快照） */
+    name?: string;
+    /** 快照创建时间 */
+    timestamp: number;
+    /** 快照描述（可选） */
+    description?: string;
+    /** 实际的游戏状态数据 */
+    state: GameState<S, I, F, X>;
+}
 /**
  * 历史管理器 - 管理游戏状态的历史快照
  *
- * 提供撤销/重做功能，通过保存游戏状态的快照来实现时间旅行
+ * ⚠️ 增强功能：支持命名快照和多级撤销
+ *
+ * 提供撤销/重做功能，通过保存游戏状态的快照来实现时间旅行。
+ *
+ * 功能特性：
+ * - 多级撤销：支持撤销多个步骤
+ * - 命名快照：可以保存和恢复命名的快照
+ * - 快照列表：查看所有保存的快照
+ * - 自动管理：超过限制时自动清理旧快照
  *
  * @template S - 属性名称的字符串字面量类型
  * @template I - 物品名称的字符串字面量类型
@@ -16,14 +41,29 @@ import 'zustand';
  * @example
  * ```typescript
  * const history = new HistoryManager<'health' | 'mana', 'sword', 'hasKey'>(20);
+ *
+ * // 保存匿名快照
  * history.push(currentState);
- * const previousState = history.pop(); // 撤销到上一个状态
+ *
+ * // 保存命名快照
+ * history.pushNamed(currentState, 'before_boss_fight', '挑战Boss前');
+ *
+ * // 撤销到上一个状态
+ * const previousState = history.pop();
+ *
+ * // 恢复到命名快照
+ * const savedState = history.restoreNamed('before_boss_fight');
+ *
+ * // 查看所有快照
+ * const snapshots = history.listSnapshots();
  * ```
  */
 declare class HistoryManager<S extends string, I extends string, F extends string, X = Record<string, unknown>> {
-    /** 存储的状态快照数组 */
+    /** 存储的状态快照数组（按时间顺序） */
     private snapshots;
-    /** 最大快照数量限制 */
+    /** 命名快照映射表（name -> snapshot） */
+    private namedSnapshots;
+    /** 最大快照数量限制（不包括命名快照） */
     private maxSnapshots;
     /**
      * 创建历史管理器实例
@@ -31,24 +71,54 @@ declare class HistoryManager<S extends string, I extends string, F extends strin
      */
     constructor(maxSnapshots?: 20);
     /**
-     * 保存当前状态快照
+     * 保存当前状态快照（匿名快照）
      *
-     * 通过深拷贝保存状态，防止后续修改影响历史记录
-     * 当快照数量超过最大限制时，自动移除最旧的快照
+     * 通过深拷贝保存状态，防止后续修改影响历史记录。
+     * 当快照数量超过最大限制时，自动移除最旧的快照。
+     *
+     * 匿名快照用于常规的撤销操作，会受到数量限制。
      *
      * @param state - 要保存的游戏状态
+     * @param description - 快照描述（可选）
      *
      * @example
      * ```typescript
      * history.push(gameState);
+     * history.push(gameState, '攻击哥布林前');
+     * ```
+     */
+    push(state: GameState<S, I, F, X>, description?: string): void;
+    /**
+     * 保存命名快照
+     *
+     * ⚠️ 新功能：保存可以通过名称访问的快照
+     *
+     * 命名快照不受数量限制，不会被自动清理。
+     * 适用于重要的游戏节点，如Boss战前、章节开始等。
+     *
+     * 如果已存在同名快照，会被覆盖。
+     *
+     * @param state - 要保存的游戏状态
+     * @param name - 快照名称（唯一标识符）
+     * @param description - 快照描述（可选）
+     *
+     * @example
+     * ```typescript
+     * // 保存Boss战前的状态
+     * history.pushNamed(gameState, 'before_boss_fight', '挑战最终Boss前');
+     *
+     * // 保存章节开始的状态
+     * history.pushNamed(gameState, 'chapter_2_start', '第二章开始');
      * ```
      */
-    push(state: GameState<S, I, F, X>): void;
+    pushNamed(state: GameState<S, I, F, X>, name: string, description?: string): void;
     /**
      * 回退到上一个状态（撤销操作）
      *
-     * 移除并返回最近的一个快照
-     * 如果没有可用的快照，返回 undefined
+     * 移除并返回最近的一个匿名快照。
+     * 如果没有可用的快照，返回 undefined。
+     *
+     * 注意：此操作不会影响命名快照。
      *
      * @returns 上一个状态快照，如果历史为空则返回 undefined
      *
@@ -62,11 +132,96 @@ declare class HistoryManager<S extends string, I extends string, F extends strin
      * ```
      */
     pop(): GameState<S, I, F, X> | undefined;
+    /**
+     * 恢复到命名快照
+     *
+     * ⚠️ 新功能：通过名称恢复到指定的快照
+     *
+     * 返回指定名称的快照状态，但不从历史记录中删除它。
+     * 这允许多次恢复到同一个命名快照。
+     *
+     * @param name - 快照名称
+     * @returns 指定名称的状态快照，如果不存在则返回 undefined
+     *
+     * @example
+     * ```typescript
+     * // 恢复到Boss战前
+     * const savedState = history.restoreNamed('before_boss_fight');
+     * if (savedState) {
+     *   restoreState(savedState);
+     * } else {
+     *   console.log('快照不存在');
+     * }
+     * ```
+     */
+    restoreNamed(name: string): GameState<S, I, F, X> | undefined;
+    /**
+     * 删除命名快照
+     *
+     * 从历史记录中删除指定名称的快照。
+     *
+     * @param name - 要删除的快照名称
+     * @returns 是否成功删除
+     *
+     * @example
+     * ```typescript
+     * history.deleteNamed('before_boss_fight');
+     * ```
+     */
+    deleteNamed(name: string): boolean;
+    /**
+     * 检查命名快照是否存在
+     *
+     * @param name - 快照名称
+     * @returns 是否存在指定名称的快照
+     *
+     * @example
+     * ```typescript
+     * if (history.hasNamed('before_boss_fight')) {
+     *   console.log('可以恢复到Boss战前');
+     * }
+     * ```
+     */
+    hasNamed(name: string): boolean;
+    /**
+     * 列出所有快照
+     *
+     * ⚠️ 新功能：获取所有快照的信息列表
+     *
+     * 返回所有快照（包括匿名和命名快照）的元数据。
+     * 不包含实际的状态数据，只包含快照信息。
+     *
+     * @returns 快照信息数组，按时间倒序排列（最新的在前）
+     *
+     * @example
+     * ```typescript
+     * const snapshots = history.listSnapshots();
+     * snapshots.forEach(snap => {
+     *   console.log(`${snap.name || '匿名'}: ${snap.description || '无描述'}`);
+     *   console.log(`  时间: ${new Date(snap.timestamp).toLocaleString()}`);
+     * });
+     * ```
+     */
+    listSnapshots(): Array<Omit<SnapshotInfo<S, I, F, X>, 'state'>>;
+    /**
+     * 列出所有命名快照
+     *
+     * 只返回命名快照的信息列表。
+     *
+     * @returns 命名快照信息数组
+     *
+     * @example
+     * ```typescript
+     * const namedSnaps = history.listNamedSnapshots();
+     * console.log(`共有 ${namedSnaps.length} 个命名快照`);
+     * ```
+     */
+    listNamedSnapshots(): Array<Omit<SnapshotInfo<S, I, F, X>, 'state'>>;
     /**
      * 查看最近的快照但不移除
      *
-     * 返回最新的快照但不从历史记录中删除它
-     * 用于预览上一个状态而不实际执行撤销操作
+     * 返回最新的匿名快照但不从历史记录中删除它。
+     * 用于预览上一个状态而不实际执行撤销操作。
      *
      * @returns 最近的状态快照，如果历史为空则返回 undefined
      *
@@ -82,19 +237,25 @@ declare class HistoryManager<S extends string, I extends string, F extends strin
     /**
      * 清空所有历史记录
      *
-     * 移除所有保存的快照，释放内存
-     * 通常在开始新游戏或重置时使用
+     * 移除所有保存的快照（包括匿名和命名快照），释放内存。
+     * 通常在开始新游戏或重置时使用。
+     *
+     * @param includeNamed - 是否同时清空命名快照（默认为 false）
      *
      * @example
      * ```typescript
-     * history.clear(); // 清空所有历史
+     * // 只清空匿名快照
+     * history.clear();
+     *
+     * // 清空所有快照（包括命名快照）
+     * history.clear(true);
      * ```
      */
-    clear(): void;
+    clear(includeNamed?: boolean): void;
     /**
-     * 获取当前历史记录数量
+     * 获取当前匿名快照数量
      *
-     * @returns 当前保存的快照数量
+     * @returns 当前保存的匿名快照数量
      *
      * @example
      * ```typescript
@@ -105,6 +266,28 @@ declare class HistoryManager<S extends string, I extends string, F extends strin
      * ```
      */
     get size(): number;
+    /**
+     * 获取命名快照数量
+     *
+     * @returns 当前保存的命名快照数量
+     *
+     * @example
+     * ```typescript
+     * console.log(`命名快照数量: ${history.namedSize}`);
+     * ```
+     */
+    get namedSize(): number;
+    /**
+     * 获取总快照数量
+     *
+     * @returns 所有快照的总数量（匿名 + 命名）
+     *
+     * @example
+     * ```typescript
+     * console.log(`总快照数量: ${history.totalSize}`);
+     * ```
+     */
+    get totalSize(): number;
 }
 
-export { HistoryManager };
+export { HistoryManager, type SnapshotInfo };

package/dist/state/index.d.ts

@@ -1,12 +1,37 @@
-export { a as GameStore, G as GameStoreActions, c as createGameEngineStore } from '../store-D0SE7zJK.js';
-import { G as GameState } from '../types-BLjkeE3R.js';
+export { G as GameStore, a as GameStoreActions, c as createGameEngineStore } from '../store-BKROShPq.js';
+import { a as GameState } from '../types-C3Q7UPWy.js';
 import 'zustand/middleware';
 import 'zustand';
 
+/**
+ * 快照信息接口
+ *
+ * 包含快照的元数据和实际状态数据
+ */
+interface SnapshotInfo<S extends string, I extends string, F extends string, X = Record<string, unknown>> {
+    /** 快照的唯一标识符（自动生成的时间戳） */
+    id: string;
+    /** 快照名称（可选，用于命名快照） */
+    name?: string;
+    /** 快照创建时间 */
+    timestamp: number;
+    /** 快照描述（可选） */
+    description?: string;
+    /** 实际的游戏状态数据 */
+    state: GameState<S, I, F, X>;
+}
 /**
  * 历史管理器 - 管理游戏状态的历史快照
  *
- * 提供撤销/重做功能，通过保存游戏状态的快照来实现时间旅行
+ * ⚠️ 增强功能：支持命名快照和多级撤销
+ *
+ * 提供撤销/重做功能，通过保存游戏状态的快照来实现时间旅行。
+ *
+ * 功能特性：
+ * - 多级撤销：支持撤销多个步骤
+ * - 命名快照：可以保存和恢复命名的快照
+ * - 快照列表：查看所有保存的快照
+ * - 自动管理：超过限制时自动清理旧快照
  *
  * @template S - 属性名称的字符串字面量类型
  * @template I - 物品名称的字符串字面量类型
@@ -16,14 +41,29 @@ import 'zustand';
  * @example
  * ```typescript
  * const history = new HistoryManager<'health' | 'mana', 'sword', 'hasKey'>(20);
+ *
+ * // 保存匿名快照
  * history.push(currentState);
- * const previousState = history.pop(); // 撤销到上一个状态
+ *
+ * // 保存命名快照
+ * history.pushNamed(currentState, 'before_boss_fight', '挑战Boss前');
+ *
+ * // 撤销到上一个状态
+ * const previousState = history.pop();
+ *
+ * // 恢复到命名快照
+ * const savedState = history.restoreNamed('before_boss_fight');
+ *
+ * // 查看所有快照
+ * const snapshots = history.listSnapshots();
  * ```
  */
 declare class HistoryManager<S extends string, I extends string, F extends string, X = Record<string, unknown>> {
-    /** 存储的状态快照数组 */
+    /** 存储的状态快照数组（按时间顺序） */
     private snapshots;
-    /** 最大快照数量限制 */
+    /** 命名快照映射表（name -> snapshot） */
+    private namedSnapshots;
+    /** 最大快照数量限制（不包括命名快照） */
     private maxSnapshots;
     /**
      * 创建历史管理器实例
@@ -31,24 +71,54 @@ declare class HistoryManager<S extends string, I extends string, F extends strin
      */
     constructor(maxSnapshots?: 20);
     /**
-     * 保存当前状态快照
+     * 保存当前状态快照（匿名快照）
      *
-     * 通过深拷贝保存状态，防止后续修改影响历史记录
-     * 当快照数量超过最大限制时，自动移除最旧的快照
+     * 通过深拷贝保存状态，防止后续修改影响历史记录。
+     * 当快照数量超过最大限制时，自动移除最旧的快照。
+     *
+     * 匿名快照用于常规的撤销操作，会受到数量限制。
      *
      * @param state - 要保存的游戏状态
+     * @param description - 快照描述（可选）
      *
      * @example
      * ```typescript
      * history.push(gameState);
+     * history.push(gameState, '攻击哥布林前');
+     * ```
+     */
+    push(state: GameState<S, I, F, X>, description?: string): void;
+    /**
+     * 保存命名快照
+     *
+     * ⚠️ 新功能：保存可以通过名称访问的快照
+     *
+     * 命名快照不受数量限制，不会被自动清理。
+     * 适用于重要的游戏节点，如Boss战前、章节开始等。
+     *
+     * 如果已存在同名快照，会被覆盖。
+     *
+     * @param state - 要保存的游戏状态
+     * @param name - 快照名称（唯一标识符）
+     * @param description - 快照描述（可选）
+     *
+     * @example
+     * ```typescript
+     * // 保存Boss战前的状态
+     * history.pushNamed(gameState, 'before_boss_fight', '挑战最终Boss前');
+     *
+     * // 保存章节开始的状态
+     * history.pushNamed(gameState, 'chapter_2_start', '第二章开始');
      * ```
      */
-    push(state: GameState<S, I, F, X>): void;
+    pushNamed(state: GameState<S, I, F, X>, name: string, description?: string): void;
     /**
      * 回退到上一个状态（撤销操作）
      *
-     * 移除并返回最近的一个快照
-     * 如果没有可用的快照，返回 undefined
+     * 移除并返回最近的一个匿名快照。
+     * 如果没有可用的快照，返回 undefined。
+     *
+     * 注意：此操作不会影响命名快照。
      *
      * @returns 上一个状态快照，如果历史为空则返回 undefined
      *
@@ -62,11 +132,96 @@ declare class HistoryManager<S extends string, I extends string, F extends strin
      * ```
      */
     pop(): GameState<S, I, F, X> | undefined;
+    /**
+     * 恢复到命名快照
+     *
+     * ⚠️ 新功能：通过名称恢复到指定的快照
+     *
+     * 返回指定名称的快照状态，但不从历史记录中删除它。
+     * 这允许多次恢复到同一个命名快照。
+     *
+     * @param name - 快照名称
+     * @returns 指定名称的状态快照，如果不存在则返回 undefined
+     *
+     * @example
+     * ```typescript
+     * // 恢复到Boss战前
+     * const savedState = history.restoreNamed('before_boss_fight');
+     * if (savedState) {
+     *   restoreState(savedState);
+     * } else {
+     *   console.log('快照不存在');
+     * }
+     * ```
+     */
+    restoreNamed(name: string): GameState<S, I, F, X> | undefined;
+    /**
+     * 删除命名快照
+     *
+     * 从历史记录中删除指定名称的快照。
+     *
+     * @param name - 要删除的快照名称
+     * @returns 是否成功删除
+     *
+     * @example
+     * ```typescript
+     * history.deleteNamed('before_boss_fight');
+     * ```
+     */
+    deleteNamed(name: string): boolean;
+    /**
+     * 检查命名快照是否存在
+     *
+     * @param name - 快照名称
+     * @returns 是否存在指定名称的快照
+     *
+     * @example
+     * ```typescript
+     * if (history.hasNamed('before_boss_fight')) {
+     *   console.log('可以恢复到Boss战前');
+     * }
+     * ```
+     */
+    hasNamed(name: string): boolean;
+    /**
+     * 列出所有快照
+     *
+     * ⚠️ 新功能：获取所有快照的信息列表
+     *
+     * 返回所有快照（包括匿名和命名快照）的元数据。
+     * 不包含实际的状态数据，只包含快照信息。
+     *
+     * @returns 快照信息数组，按时间倒序排列（最新的在前）
+     *
+     * @example
+     * ```typescript
+     * const snapshots = history.listSnapshots();
+     * snapshots.forEach(snap => {
+     *   console.log(`${snap.name || '匿名'}: ${snap.description || '无描述'}`);
+     *   console.log(`  时间: ${new Date(snap.timestamp).toLocaleString()}`);
+     * });
+     * ```
+     */
+    listSnapshots(): Array<Omit<SnapshotInfo<S, I, F, X>, 'state'>>;
+    /**
+     * 列出所有命名快照
+     *
+     * 只返回命名快照的信息列表。
+     *
+     * @returns 命名快照信息数组
+     *
+     * @example
+     * ```typescript
+     * const namedSnaps = history.listNamedSnapshots();
+     * console.log(`共有 ${namedSnaps.length} 个命名快照`);
+     * ```
+     */
+    listNamedSnapshots(): Array<Omit<SnapshotInfo<S, I, F, X>, 'state'>>;
     /**
      * 查看最近的快照但不移除
      *
-     * 返回最新的快照但不从历史记录中删除它
-     * 用于预览上一个状态而不实际执行撤销操作
+     * 返回最新的匿名快照但不从历史记录中删除它。
+     * 用于预览上一个状态而不实际执行撤销操作。
      *
      * @returns 最近的状态快照，如果历史为空则返回 undefined
      *
@@ -82,19 +237,25 @@ declare class HistoryManager<S extends string, I extends string, F extends strin
     /**
      * 清空所有历史记录
      *
-     * 移除所有保存的快照，释放内存
-     * 通常在开始新游戏或重置时使用
+     * 移除所有保存的快照（包括匿名和命名快照），释放内存。
+     * 通常在开始新游戏或重置时使用。
+     *
+     * @param includeNamed - 是否同时清空命名快照（默认为 false）
      *
      * @example
      * ```typescript
-     * history.clear(); // 清空所有历史
+     * // 只清空匿名快照
+     * history.clear();
+     *
+     * // 清空所有快照（包括命名快照）
+     * history.clear(true);
      * ```
      */
-    clear(): void;
+    clear(includeNamed?: boolean): void;
     /**
-     * 获取当前历史记录数量
+     * 获取当前匿名快照数量
      *
-     * @returns 当前保存的快照数量
+     * @returns 当前保存的匿名快照数量
      *
      * @example
      * ```typescript
@@ -105,6 +266,28 @@ declare class HistoryManager<S extends string, I extends string, F extends strin
      * ```
      */
     get size(): number;
+    /**
+     * 获取命名快照数量
+     *
+     * @returns 当前保存的命名快照数量
+     *
+     * @example
+     * ```typescript
+     * console.log(`命名快照数量: ${history.namedSize}`);
+     * ```
+     */
+    get namedSize(): number;
+    /**
+     * 获取总快照数量
+     *
+     * @returns 所有快照的总数量（匿名 + 命名）
+     *
+     * @example
+     * ```typescript
+     * console.log(`总快照数量: ${history.totalSize}`);
+     * ```
+     */
+    get totalSize(): number;
 }
 
-export { HistoryManager };
+export { HistoryManager, type SnapshotInfo };