steamsheep-ts-game-engine 3.1.1 → 3.1.2

package/dist/index.js

@@ -201,159 +201,6 @@ function getStateDiff(oldState, newState) {
   return diff;
 }
 
-// systems/events.ts
-var EventBus = class {
-  constructor() {
-    /**
-     * 事件监听器的内部存储
-     * 将事件名映射到监听器回调函数数组
-     * 使用 Listener[]（默认为 Listener<unknown>[]）以允许同一事件名有不同类型的监听器
-     * 类型安全在订阅/发射时强制执行
-     */
-    __publicField(this, "listeners", /* @__PURE__ */ new Map());
-  }
-  /**
-   * 订阅事件
-   *
-   * @template T - 事件载荷的预期类型
-   * @param event - 要订阅的事件名称
-   * @param callback - 事件触发时调用的监听器函数
-   * @returns 取消订阅的函数
-   *
-   * @example
-   * ```typescript
-   * const handler = (data: { count: number }) => console.log(data.count);
-   * const unsubscribe = eventBus.on('update', handler);
-   * // 稍后取消订阅
-   * unsubscribe();
-   * ```
-   */
-  on(event, callback) {
-    if (!this.listeners.has(event)) {
-      this.listeners.set(event, []);
-    }
-    this.listeners.get(event).push(callback);
-    return () => this.off(event, callback);
-  }
-  /**
-   * 取消订阅事件
-   *
-   * @template T - 事件载荷的预期类型
-   * @param event - 要取消订阅的事件名称
-   * @param callback - 要移除的监听器函数
-   *
-   * @example
-   * ```typescript
-   * const handler = (data: number) => console.log(data);
-   * eventBus.on('count', handler);
-   * eventBus.off('count', handler); // 移除监听器
-   * ```
-   */
-  off(event, callback) {
-    const callbacks = this.listeners.get(event);
-    if (callbacks) {
-      this.listeners.set(
-        event,
-        callbacks.filter((cb) => cb !== callback)
-      );
-    }
-  }
-  /**
-   * 发射事件并携带可选的类型化载荷数据
-   * 该事件的所有已注册监听器都将被调用并传入数据
-   * 单个监听器中的错误会被捕获并记录，不会影响其他监听器
-   *
-   * @template T - 事件载荷的类型
-   * @param event - 要发射的事件名称
-   * @param data - 传递给监听器的可选载荷数据
-   *
-   * @example
-   * ```typescript
-   * eventBus.emit<{ userId: string }>('login', { userId: '123' });
-   * eventBus.emit('logout'); // 无载荷
-   * ```
-   */
-  emit(event, data) {
-    const callbacks = this.listeners.get(event);
-    if (callbacks) {
-      callbacks.forEach((cb) => {
-        try {
-          cb(data);
-        } catch (error) {
-          console.error(`Error in event listener for "${event}":`, error);
-        }
-      });
-    }
-  }
-  /**
-   * 清空所有事件的所有监听器
-   * 用于清理或重置事件系统
-   *
-   * @example
-   * ```typescript
-   * eventBus.clear(); // 所有监听器被移除
-   * ```
-   */
-  clear() {
-    this.listeners.clear();
-  }
-};
-var GLOBAL_KEY = "__STEAMSHEEP_GAME_EVENTS__";
-function getGlobalEventBus() {
-  const globalObj = typeof globalThis !== "undefined" ? globalThis : typeof window !== "undefined" ? window : typeof self !== "undefined" ? self : {};
-  if (!globalObj[GLOBAL_KEY]) {
-    globalObj[GLOBAL_KEY] = new EventBus();
-  }
-  return globalObj[GLOBAL_KEY];
-}
-var gameEvents = getGlobalEventBus();
-var EngineEvents = {
-  /** 当角色属性变化时触发 */
-  STAT_CHANGE: "engine:stat_change",
-  /** 当物品添加到背包时触发 */
-  ITEM_ADD: "engine:item_add",
-  /** 当物品从背包移除时触发 */
-  ITEM_REMOVE: "engine:item_remove",
-  /** 当游戏标志变化时触发 */
-  FLAG_CHANGE: "engine:flag_change",
-  /** 当动作执行时触发 */
-  ACTION_EXECUTED: "engine:action_exec",
-  /** 当游戏时间推进时触发 */
-  TIME_PASS: "engine:time_pass",
-  /** 当需要显示瞬时通知时触发（Toast/Modal，不持久化） */
-  NOTIFICATION: "engine:notification",
-  /** 用于自定义触发事件 */
-  CUSTOM: "engine:custom_trigger"
-};
-function isEventBusSingleton() {
-  const GLOBAL_KEY2 = "__STEAMSHEEP_GAME_EVENTS__";
-  const globalObj = typeof globalThis !== "undefined" ? globalThis : typeof window !== "undefined" ? window : typeof self !== "undefined" ? self : {};
-  return globalObj[GLOBAL_KEY2] === gameEvents;
-}
-function getEventListenerCounts() {
-  const counts = {};
-  const listeners = gameEvents.listeners;
-  listeners.forEach((callbacks, event) => {
-    counts[event] = callbacks.length;
-  });
-  return counts;
-}
-function debugEventSystem() {
-  console.log("\n========== EventBus \u8C03\u8BD5\u4FE1\u606F ==========");
-  console.log("\u5355\u4F8B\u72B6\u6001:", isEventBusSingleton() ? "\u2713 \u6B63\u5E38" : "\u2717 \u5F02\u5E38\uFF08\u591A\u4E2A\u5B9E\u4F8B\uFF09");
-  const counts = getEventListenerCounts();
-  const eventCount = Object.keys(counts).length;
-  if (eventCount === 0) {
-    console.log("\u5DF2\u6CE8\u518C\u7684\u4E8B\u4EF6: \u65E0");
-  } else {
-    console.log("\u5DF2\u6CE8\u518C\u7684\u4E8B\u4EF6:");
-    Object.entries(counts).forEach(([event, count]) => {
-      console.log(`  - ${event}: ${count} \u4E2A\u76D1\u542C\u5668`);
-    });
-  }
-  console.log("=====================================\n");
-}
-
 // state/history.ts
 var HistoryManager = class {
   /**
@@ -665,346 +512,205 @@ var HistoryManager = class {
   }
 };
 
-// state/store.ts
-var createGameEngineStore = (initialState, persistName = "generic-rpg-save") => {
-  const history = new HistoryManager(
-    DEFAULT_CONFIG.MAX_HISTORY_SNAPSHOTS
-  );
-  return zustand.create()(
-    middleware.persist(
-      (set, get2) => ({
-        // 展开初始状态，包含所有游戏数据
-        ...initialState,
-        // ========== 数值属性操作实现 ==========
-        /**
-         * 实现：更新单个数值属性
-         * 使用增量更新，保持其他属性不变
-         * 发射 STAT_CHANGE 事件通知监听器
-         */
-        updateStat: (stat, delta) => set((state) => {
-          const currentVal = state.stats[stat] || 0;
-          const newVal = currentVal + delta;
-          gameEvents.emit(EngineEvents.STAT_CHANGE, {
-            stat,
-            delta,
-            current: newVal
-          });
-          return {
-            stats: {
-              ...state.stats,
-              [stat]: newVal
-            }
-          };
-        }),
-        /**
-         * 实现：批量更新多个数值属性
-         * 遍历所有变化并应用到新的stats对象
-         */
-        setStats: (changes) => set((state) => {
-          const newStats = { ...state.stats };
-          Object.entries(changes).forEach(([k, v]) => {
-            newStats[k] = (newStats[k] || 0) + v;
-          });
-          return { stats: newStats };
-        }),
-        // ========== 扩展数据操作实现 ==========
-        /**
-         * 实现：更新扩展数据
-         * 
-         * 支持两种更新方式：
-         * 1. 直接传入部分更新对象
-         * 2. 传入更新函数，接收当前值返回部分更新
-         * 
-         * @example
-         * ```typescript
-         * // 方式1：直接更新
-         * setExtra({ reputation: 100 });
-         * 
-         * // 方式2：基于当前值更新
-         * setExtra((prev) => ({ reputation: prev.reputation + 10 }));
-         * ```
-         */
-        setExtra: (updater) => set((state) => {
-          const update = typeof updater === "function" ? updater(state.extra) : updater;
-          return {
-            extra: { ...state.extra, ...update }
-          };
-        }),
-        // ========== 物品操作实现 ==========
-        /**
-         * 实现：添加物品到库存
-         * 创建新数组，保持不可变性
-         * 发射 ITEM_ADD 事件通知监听器
-         */
-        addItem: (item) => set((state) => {
-          gameEvents.emit(EngineEvents.ITEM_ADD, { item });
-          return {
-            inventory: [...state.inventory, item]
-          };
-        }),
-        /**
-         * 实现：从库存移除物品
-         * 使用filter移除第一个匹配的物品
-         * 发射 ITEM_REMOVE 事件通知监听器
-         */
-        removeItem: (item) => set((state) => {
-          gameEvents.emit(EngineEvents.ITEM_REMOVE, { item });
-          return {
-            inventory: state.inventory.filter((i) => i !== item)
-          };
-        }),
-        // ========== 标记操作实现 ==========
-        /**
-         * 实现：设置布尔标记
-         * 创建新的flags对象，更新指定标记
-         * 发射 FLAG_CHANGE 事件通知监听器
-         */
-        setFlag: (flag, value) => set((state) => {
-          gameEvents.emit(EngineEvents.FLAG_CHANGE, { flag, value });
-          return {
-            flags: { ...state.flags, [flag]: value }
-          };
-        }),
-        // ========== 系统操作实现 ==========
-        /**
-         * 实现：添加日志条目
-         * 
-         * 创建新日志并添加到日志数组开头。
-         * 使用 MAX_LOG_ENTRIES 限制日志数量，防止内存泄漏。
-         * 日志ID使用时间戳+随机数确保唯一性。
-         * 
-         * ⚠️ 注意：日志会被持久化到 localStorage
-         */
-        addLog: (text, type = "info") => set((state) => {
-          const newLog = {
-            id: generateId(),
-            text,
-            type,
-            timestamp: state.world.day
-          };
-          return {
-            logs: [newLog, ...state.logs].slice(0, DEFAULT_CONFIG.MAX_LOG_ENTRIES)
-          };
-        }),
-        /**
-         * 实现：显示飘字通知
-         * 
-         * 发射 NOTIFICATION 事件，UI 层监听后显示飘字效果。
-         * 
-         * ⚠️ 注意：通知不会被持久化，仅在当前会话中显示
-         */
-        showToast: (text, type = "info") => {
-          const notification = {
-            text,
-            type,
-            notificationType: "toast",
-            timestamp: Date.now()
-          };
-          gameEvents.emit(EngineEvents.NOTIFICATION, notification);
-        },
-        /**
-         * 实现：显示弹窗通知
-         * 
-         * 发射 NOTIFICATION 事件，UI 层监听后显示模态弹窗。
-         * 
-         * ⚠️ 注意：通知不会被持久化，仅在当前会话中显示
-         */
-        showModal: (text, type = "info") => {
-          const notification = {
-            text,
-            type,
-            notificationType: "modal",
-            timestamp: Date.now()
-          };
-          gameEvents.emit(EngineEvents.NOTIFICATION, notification);
-        },
-        /**
-         * 实现：推进游戏时间
-         * 增加world.day的值
-         */
-        advanceTime: (amount = 1) => set((state) => ({
-          world: { ...state.world, day: state.world.day + amount }
-        })),
-        /**
-         * 实现：传送到指定地点
-         * 更新world.currentLocationId
-         */
-        teleport: (locationId) => set((state) => ({
-          world: { ...state.world, currentLocationId: locationId }
-        })),
-        // ========== 存档操作实现 ==========
-        /**
-         * 实现：重置游戏状态
-         * 恢复到初始状态，清空日志
-         */
-        reset: () => set({ ...initialState, logs: [] }),
-        // ========== 历史记录操作实现 ==========
-        /**
-         * 实现：保存当前状态快照（匿名快照）
-         * 
-         * 保存除日志外的所有状态数据到历史管理器。
-         * 日志通常不需要回退，因此被排除以节省内存。
-         */
-        saveSnapshot: (description) => {
-          const currentState = get2();
-          history.push(currentState, description);
-        },
-        /**
-         * 实现：保存命名快照
-         * 
-         * 保存可以通过名称访问的快照。
-         * 命名快照不受数量限制，适用于重要的游戏节点。
-         */
-        saveNamedSnapshot: (name, description) => {
-          const currentState = get2();
-          history.pushNamed(currentState, name, description);
-        },
-        /**
-         * 实现：撤销到上一个状态
-         * 
-         * 从历史管理器中恢复上一个匿名快照。
-         * 恢复时保留当前的日志，并添加系统提示。
-         * 
-         * @returns 是否成功撤销
-         */
-        undo: () => {
-          const prev = history.pop();
-          if (prev) {
-            set({
-              stats: prev.stats,
-              inventory: prev.inventory,
-              flags: prev.flags,
-              world: prev.world,
-              extra: prev.extra
-              // logs 保留当前的，不回退日志
-            });
-            get2().addLog(SystemMessages.UNDO_SUCCESS, "info");
-            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 保留当前的，不回退日志
-            });
-            get2().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);
-        }
-      }),
-      {
-        // 持久化配置
-        name: persistName,
-        // localStorage中的键名
-        storage: middleware.createJSONStorage(() => localStorage),
-        // 使用localStorage存储
-        /**
-         * 部分持久化 - 只保存数据字段，排除方法
-         * 
-         * 这很重要，因为方法不能被序列化到JSON。
-         * 我们只持久化游戏状态数据，方法会在store重新创建时自动添加。
-         */
-        partialize: (state) => ({
-          stats: state.stats,
-          inventory: state.inventory,
-          flags: state.flags,
-          world: state.world,
-          logs: state.logs,
-          extra: state.extra
-        })
-      }
-    )
-  );
-};
-
-// systems/query.ts
-var QuerySystem = class {
+// systems/events.ts
+var EventBus = class {
+  constructor() {
+    /**
+     * 事件监听器的内部存储
+     * 将事件名映射到监听器回调函数数组
+     * 使用 Listener[]（默认为 Listener<unknown>[]）以允许同一事件名有不同类型的监听器
+     * 类型安全在订阅/发射时强制执行
+     */
+    __publicField(this, "listeners", /* @__PURE__ */ new Map());
+  }
   /**
-   * 检查是否满足所有需求条件（带失败原因）
-   * 
-   * ⚠️ 增强版本：返回详细的检查结果，包括失败原因
-   * 
-   * 这是核心的条件检查方法，用于验证玩家是否满足执行某个动作的所有前置条件。
-   * 内置字段使用 AND 逻辑组合，复杂逻辑使用 custom 函数实现。
-   * 
-   * @template S - 数值属性键的联合类型
-   * @template I - 物品ID的联合类型
-   * @template F - 标记键的联合类型
-   * 
-   * @param state - 当前游戏状态
-   * @param reqs - 需求定义（可选，未定义时返回通过）
-   * 
-   * @returns RequirementCheckResult 包含是否通过和失败原因
-   * 
+   * 订阅事件
+   *
+   * @template T - 事件载荷的预期类型
+   * @param event - 要订阅的事件名称
+   * @param callback - 事件触发时调用的监听器函数
+   * @returns 取消订阅的函数
+   *
    * @example
    * ```typescript
-   * // 检查需求并获取失败原因
-   * const result = QuerySystem.checkRequirementsWithReason(state, {
-   *   hasItems: ['key'],
-   *   stats: { strength: { min: 5 } }
-   * });
-   * 
-   * if (!result.passed) {
-   *   console.log(result.reason); // 显示失败原因
-   * }
+   * const handler = (data: { count: number }) => console.log(data.count);
+   * const unsubscribe = eventBus.on('update', handler);
+   * // 稍后取消订阅
+   * unsubscribe();
    * ```
    */
-  static checkRequirementsWithReason(state, reqs) {
-    if (!reqs) return { passed: true };
-    if (reqs.hasFlags && reqs.hasFlags.length > 0) {
-      const missingFlags = reqs.hasFlags.filter((f) => !state.flags[f]);
-      if (missingFlags.length > 0) {
-        return {
-          passed: false,
-          reason: `\u9700\u8981\u6EE1\u8DB3\u6761\u4EF6\uFF1A${missingFlags.join("\u3001")}`
-        };
-      }
+  on(event, callback) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, []);
     }
-    if (reqs.noFlags && reqs.noFlags.length > 0) {
-      const conflictFlags = reqs.noFlags.filter((f) => state.flags[f]);
-      if (conflictFlags.length > 0) {
+    this.listeners.get(event).push(callback);
+    return () => this.off(event, callback);
+  }
+  /**
+   * 取消订阅事件
+   *
+   * @template T - 事件载荷的预期类型
+   * @param event - 要取消订阅的事件名称
+   * @param callback - 要移除的监听器函数
+   *
+   * @example
+   * ```typescript
+   * const handler = (data: number) => console.log(data);
+   * eventBus.on('count', handler);
+   * eventBus.off('count', handler); // 移除监听器
+   * ```
+   */
+  off(event, callback) {
+    const callbacks = this.listeners.get(event);
+    if (callbacks) {
+      this.listeners.set(
+        event,
+        callbacks.filter((cb) => cb !== callback)
+      );
+    }
+  }
+  /**
+   * 发射事件并携带可选的类型化载荷数据
+   * 该事件的所有已注册监听器都将被调用并传入数据
+   * 单个监听器中的错误会被捕获并记录，不会影响其他监听器
+   *
+   * @template T - 事件载荷的类型
+   * @param event - 要发射的事件名称
+   * @param data - 传递给监听器的可选载荷数据
+   *
+   * @example
+   * ```typescript
+   * eventBus.emit<{ userId: string }>('login', { userId: '123' });
+   * eventBus.emit('logout'); // 无载荷
+   * ```
+   */
+  emit(event, data) {
+    const callbacks = this.listeners.get(event);
+    if (callbacks) {
+      callbacks.forEach((cb) => {
+        try {
+          cb(data);
+        } catch (error) {
+          console.error(`Error in event listener for "${event}":`, error);
+        }
+      });
+    }
+  }
+  /**
+   * 清空所有事件的所有监听器
+   * 用于清理或重置事件系统
+   *
+   * @example
+   * ```typescript
+   * eventBus.clear(); // 所有监听器被移除
+   * ```
+   */
+  clear() {
+    this.listeners.clear();
+  }
+};
+var GLOBAL_KEY = "__STEAMSHEEP_GAME_EVENTS__";
+function getGlobalEventBus() {
+  const globalObj = typeof globalThis !== "undefined" ? globalThis : typeof window !== "undefined" ? window : typeof self !== "undefined" ? self : {};
+  if (!globalObj[GLOBAL_KEY]) {
+    globalObj[GLOBAL_KEY] = new EventBus();
+  }
+  return globalObj[GLOBAL_KEY];
+}
+var gameEvents = getGlobalEventBus();
+var EngineEvents = {
+  /** 当角色属性变化时触发 */
+  STAT_CHANGE: "engine:stat_change",
+  /** 当物品添加到背包时触发 */
+  ITEM_ADD: "engine:item_add",
+  /** 当物品从背包移除时触发 */
+  ITEM_REMOVE: "engine:item_remove",
+  /** 当游戏标志变化时触发 */
+  FLAG_CHANGE: "engine:flag_change",
+  /** 当动作执行时触发 */
+  ACTION_EXECUTED: "engine:action_exec",
+  /** 当游戏时间推进时触发 */
+  TIME_PASS: "engine:time_pass",
+  /** 当需要显示瞬时通知时触发（Toast/Modal，不持久化） */
+  NOTIFICATION: "engine:notification",
+  /** 用于自定义触发事件 */
+  CUSTOM: "engine:custom_trigger"
+};
+function isEventBusSingleton() {
+  const GLOBAL_KEY2 = "__STEAMSHEEP_GAME_EVENTS__";
+  const globalObj = typeof globalThis !== "undefined" ? globalThis : typeof window !== "undefined" ? window : typeof self !== "undefined" ? self : {};
+  return globalObj[GLOBAL_KEY2] === gameEvents;
+}
+function getEventListenerCounts() {
+  const counts = {};
+  const listeners = gameEvents.listeners;
+  listeners.forEach((callbacks, event) => {
+    counts[event] = callbacks.length;
+  });
+  return counts;
+}
+function debugEventSystem() {
+  console.log("\n========== EventBus \u8C03\u8BD5\u4FE1\u606F ==========");
+  console.log("\u5355\u4F8B\u72B6\u6001:", isEventBusSingleton() ? "\u2713 \u6B63\u5E38" : "\u2717 \u5F02\u5E38\uFF08\u591A\u4E2A\u5B9E\u4F8B\uFF09");
+  const counts = getEventListenerCounts();
+  const eventCount = Object.keys(counts).length;
+  if (eventCount === 0) {
+    console.log("\u5DF2\u6CE8\u518C\u7684\u4E8B\u4EF6: \u65E0");
+  } else {
+    console.log("\u5DF2\u6CE8\u518C\u7684\u4E8B\u4EF6:");
+    Object.entries(counts).forEach(([event, count]) => {
+      console.log(`  - ${event}: ${count} \u4E2A\u76D1\u542C\u5668`);
+    });
+  }
+  console.log("=====================================\n");
+}
+
+// systems/query.ts
+var QuerySystem = class {
+  /**
+   * 检查是否满足所有需求条件（带失败原因）
+   * 
+   * ⚠️ 增强版本：返回详细的检查结果，包括失败原因
+   * 
+   * 这是核心的条件检查方法，用于验证玩家是否满足执行某个动作的所有前置条件。
+   * 内置字段使用 AND 逻辑组合，复杂逻辑使用 custom 函数实现。
+   * 
+   * @template S - 数值属性键的联合类型
+   * @template I - 物品ID的联合类型
+   * @template F - 标记键的联合类型
+   * 
+   * @param state - 当前游戏状态
+   * @param reqs - 需求定义（可选，未定义时返回通过）
+   * 
+   * @returns RequirementCheckResult 包含是否通过和失败原因
+   * 
+   * @example
+   * ```typescript
+   * // 检查需求并获取失败原因
+   * const result = QuerySystem.checkRequirementsWithReason(state, {
+   *   hasItems: ['key'],
+   *   stats: { strength: { min: 5 } }
+   * });
+   * 
+   * if (!result.passed) {
+   *   console.log(result.reason); // 显示失败原因
+   * }
+   * ```
+   */
+  static checkRequirementsWithReason(state, reqs) {
+    if (!reqs) return { passed: true };
+    if (reqs.hasFlags && reqs.hasFlags.length > 0) {
+      const missingFlags = reqs.hasFlags.filter((f) => !state.flags[f]);
+      if (missingFlags.length > 0) {
+        return {
+          passed: false,
+          reason: `\u9700\u8981\u6EE1\u8DB3\u6761\u4EF6\uFF1A${missingFlags.join("\u3001")}`
+        };
+      }
+    }
+    if (reqs.noFlags && reqs.noFlags.length > 0) {
+      const conflictFlags = reqs.noFlags.filter((f) => state.flags[f]);
+      if (conflictFlags.length > 0) {
         return {
           passed: false,
           reason: `\u4E0D\u80FD\u6EE1\u8DB3\u6761\u4EF6\uFF1A${conflictFlags.join("\u3001")}`
@@ -1397,6 +1103,300 @@ var FlowSystem = class {
     return true;
   }
 };
+
+// state/store.ts
+var createGameEngineStore = (initialState, persistName = "generic-rpg-save") => {
+  const history = new HistoryManager(
+    DEFAULT_CONFIG.MAX_HISTORY_SNAPSHOTS
+  );
+  return zustand.create()(
+    middleware.persist(
+      (set, get2) => ({
+        // 展开初始状态，包含所有游戏数据
+        ...initialState,
+        // ========== 数值属性操作实现 ==========
+        /**
+         * 实现：更新单个数值属性
+         * 使用增量更新，保持其他属性不变
+         * 发射 STAT_CHANGE 事件通知监听器
+         */
+        updateStat: (stat, delta) => set((state) => {
+          const currentVal = state.stats[stat] || 0;
+          const newVal = currentVal + delta;
+          gameEvents.emit(EngineEvents.STAT_CHANGE, {
+            stat,
+            delta,
+            current: newVal
+          });
+          return {
+            stats: {
+              ...state.stats,
+              [stat]: newVal
+            }
+          };
+        }),
+        /**
+         * 实现：批量更新多个数值属性
+         * 遍历所有变化并应用到新的stats对象
+         */
+        setStats: (changes) => set((state) => {
+          const newStats = { ...state.stats };
+          Object.entries(changes).forEach(([k, v]) => {
+            newStats[k] = (newStats[k] || 0) + v;
+          });
+          return { stats: newStats };
+        }),
+        // ========== 扩展数据操作实现 ==========
+        /**
+         * 实现：更新扩展数据
+         * 
+         * 支持两种更新方式：
+         * 1. 直接传入部分更新对象
+         * 2. 传入更新函数，接收当前值返回部分更新
+         * 
+         * @example
+         * ```typescript
+         * // 方式1：直接更新
+         * setExtra({ reputation: 100 });
+         * 
+         * // 方式2：基于当前值更新
+         * setExtra((prev) => ({ reputation: prev.reputation + 10 }));
+         * ```
+         */
+        setExtra: (updater) => set((state) => {
+          const update = typeof updater === "function" ? updater(state.extra) : updater;
+          return {
+            extra: { ...state.extra, ...update }
+          };
+        }),
+        // ========== 物品操作实现 ==========
+        /**
+         * 实现：添加物品到库存
+         * 创建新数组，保持不可变性
+         * 发射 ITEM_ADD 事件通知监听器
+         */
+        addItem: (item) => set((state) => {
+          gameEvents.emit(EngineEvents.ITEM_ADD, { item });
+          return {
+            inventory: [...state.inventory, item]
+          };
+        }),
+        /**
+         * 实现：从库存移除物品
+         * 使用filter移除第一个匹配的物品
+         * 发射 ITEM_REMOVE 事件通知监听器
+         */
+        removeItem: (item) => set((state) => {
+          gameEvents.emit(EngineEvents.ITEM_REMOVE, { item });
+          return {
+            inventory: state.inventory.filter((i) => i !== item)
+          };
+        }),
+        // ========== 标记操作实现 ==========
+        /**
+         * 实现：设置布尔标记
+         * 创建新的flags对象，更新指定标记
+         * 发射 FLAG_CHANGE 事件通知监听器
+         */
+        setFlag: (flag, value) => set((state) => {
+          gameEvents.emit(EngineEvents.FLAG_CHANGE, { flag, value });
+          return {
+            flags: { ...state.flags, [flag]: value }
+          };
+        }),
+        // ========== 系统操作实现 ==========
+        /**
+         * 实现：添加日志条目
+         * 
+         * 创建新日志并添加到日志数组开头。
+         * 使用 MAX_LOG_ENTRIES 限制日志数量，防止内存泄漏。
+         * 日志ID使用时间戳+随机数确保唯一性。
+         * 
+         * ⚠️ 注意：日志会被持久化到 localStorage
+         */
+        addLog: (text, type = "info") => set((state) => {
+          const newLog = {
+            id: generateId(),
+            text,
+            type,
+            timestamp: state.world.day
+          };
+          return {
+            logs: [newLog, ...state.logs].slice(0, DEFAULT_CONFIG.MAX_LOG_ENTRIES)
+          };
+        }),
+        /**
+         * 实现：显示飘字通知
+         * 
+         * 发射 NOTIFICATION 事件，UI 层监听后显示飘字效果。
+         * 
+         * ⚠️ 注意：通知不会被持久化，仅在当前会话中显示
+         */
+        showToast: (text, type = "info") => {
+          const notification = {
+            text,
+            type,
+            notificationType: "toast",
+            timestamp: Date.now()
+          };
+          gameEvents.emit(EngineEvents.NOTIFICATION, notification);
+        },
+        /**
+         * 实现：显示弹窗通知
+         * 
+         * 发射 NOTIFICATION 事件，UI 层监听后显示模态弹窗。
+         * 
+         * ⚠️ 注意：通知不会被持久化，仅在当前会话中显示
+         */
+        showModal: (text, type = "info") => {
+          const notification = {
+            text,
+            type,
+            notificationType: "modal",
+            timestamp: Date.now()
+          };
+          gameEvents.emit(EngineEvents.NOTIFICATION, notification);
+        },
+        /**
+         * 实现：推进游戏时间
+         * 增加world.day的值
+         */
+        advanceTime: (amount = 1) => set((state) => ({
+          world: { ...state.world, day: state.world.day + amount }
+        })),
+        /**
+         * 实现：传送到指定地点
+         * 更新world.currentLocationId
+         */
+        teleport: (locationId) => set((state) => ({
+          world: { ...state.world, currentLocationId: locationId }
+        })),
+        // ========== 存档操作实现 ==========
+        /**
+         * 实现：重置游戏状态
+         * 恢复到初始状态，清空日志
+         */
+        reset: () => set({ ...initialState, logs: [] }),
+        // ========== 历史记录操作实现 ==========
+        /**
+         * 实现：保存当前状态快照（匿名快照）
+         * 
+         * 保存除日志外的所有状态数据到历史管理器。
+         * 日志通常不需要回退，因此被排除以节省内存。
+         */
+        saveSnapshot: (description) => {
+          const currentState = get2();
+          history.push(currentState, description);
+        },
+        /**
+         * 实现：保存命名快照
+         * 
+         * 保存可以通过名称访问的快照。
+         * 命名快照不受数量限制，适用于重要的游戏节点。
+         */
+        saveNamedSnapshot: (name, description) => {
+          const currentState = get2();
+          history.pushNamed(currentState, name, description);
+        },
+        /**
+         * 实现：撤销到上一个状态
+         * 
+         * 从历史管理器中恢复上一个匿名快照。
+         * 恢复时保留当前的日志，并添加系统提示。
+         * 
+         * @returns 是否成功撤销
+         */
+        undo: () => {
+          const prev = history.pop();
+          if (prev) {
+            set({
+              stats: prev.stats,
+              inventory: prev.inventory,
+              flags: prev.flags,
+              world: prev.world,
+              extra: prev.extra
+              // logs 保留当前的，不回退日志
+            });
+            get2().addLog(SystemMessages.UNDO_SUCCESS, "info");
+            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 保留当前的，不回退日志
+            });
+            get2().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);
+        }
+      }),
+      {
+        // 持久化配置
+        name: persistName,
+        // localStorage中的键名
+        storage: middleware.createJSONStorage(() => localStorage),
+        // 使用localStorage存储
+        /**
+         * 部分持久化 - 只保存数据字段，排除方法
+         * 
+         * 这很重要，因为方法不能被序列化到JSON。
+         * 我们只持久化游戏状态数据，方法会在store重新创建时自动添加。
+         */
+        partialize: (state) => ({
+          stats: state.stats,
+          inventory: state.inventory,
+          flags: state.flags,
+          world: state.world,
+          logs: state.logs,
+          extra: state.extra
+        })
+      }
+    )
+  );
+};
 var Layout = ({
   sidebar,
   main,