steamsheep-ts-game-engine 1.0.0

package/dist/index.mjs

@@ -0,0 +1,1160 @@
+import { create } from 'zustand';
+import { persist, createJSONStorage } from 'zustand/middleware';
+import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
+import { useRef, useEffect, useState } from 'react';
+
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// core/messages.ts
+var SystemMessages = {
+  /** 资源不足提示 */
+  NOT_ENOUGH_RESOURCES: "sys:not_enough_resources",
+  /** 条件不满足提示 */
+  REQUIREMENT_NOT_MET: "sys:requirement_not_met",
+  /** 操作成功提示 */
+  ACTION_SUCCESS: "sys:action_success",
+  /** 时间回溯成功提示 */
+  UNDO_SUCCESS: "sys:undo_success"
+};
+
+// core/constants.ts
+var ENGINE_VERSION = "1.0.0";
+var DEFAULT_CONFIG = {
+  /** 默认存档键名 */
+  DEFAULT_SAVE_KEY: "game-save",
+  /** 最大日志条数 */
+  MAX_LOG_ENTRIES: 50,
+  /** 最大历史快照数 */
+  MAX_HISTORY_SNAPSHOTS: 20,
+  /** 飘字显示时长（毫秒） */
+  TOAST_DURATION: 3e3
+};
+var LOG_TYPE_COLORS = {
+  info: "#3b82f6",
+  success: "#10b981",
+  warn: "#f59e0b",
+  error: "#ef4444",
+  result: "#6366f1"
+};
+var DEFAULT_STATS = {
+  /** 默认生命值 */
+  DEFAULT_HP: 100,
+  /** 默认金币 */
+  DEFAULT_GOLD: 0
+};
+var TIME_CONSTANTS = {
+  /** 一天的小时数 */
+  HOURS_PER_DAY: 24,
+  /** 早晨开始时间 */
+  MORNING_START: 6,
+  /** 中午开始时间 */
+  NOON_START: 12,
+  /** 傍晚开始时间 */
+  EVENING_START: 18,
+  /** 夜晚开始时间 */
+  NIGHT_START: 22
+};
+var UI_CONSTANTS = {
+  /** 侧边栏宽度 */
+  SIDEBAR_WIDTH: 288,
+  // 72 * 4 = 288px (w-72)
+  /** 日志栏宽度 */
+  LOG_WIDTH: 320,
+  // 80 * 4 = 320px (w-80)
+  /** Toast 容器 z-index */
+  TOAST_Z_INDEX: 1e3,
+  /** Modal 容器 z-index */
+  MODAL_Z_INDEX: 2e3
+};
+var VALIDATION = {
+  /** 最小属性值 */
+  MIN_STAT_VALUE: 0,
+  /** 最大属性值 */
+  MAX_STAT_VALUE: 9999,
+  /** 最大背包容量 */
+  MAX_INVENTORY_SIZE: 100,
+  /** 最小动作 ID 长度 */
+  MIN_ACTION_ID_LENGTH: 1,
+  /** 最大动作 ID 长度 */
+  MAX_ACTION_ID_LENGTH: 50
+};
+
+// core/utils.ts
+function generateId() {
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
+function deepClone(obj) {
+  return JSON.parse(JSON.stringify(obj));
+}
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+function formatNumber(num) {
+  return num.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+function getTimeOfDay(hour) {
+  if (hour >= TIME_CONSTANTS.MORNING_START && hour < TIME_CONSTANTS.NOON_START) {
+    return "\u65E9\u6668";
+  } else if (hour >= TIME_CONSTANTS.NOON_START && hour < TIME_CONSTANTS.EVENING_START) {
+    return "\u4E0B\u5348";
+  } else if (hour >= TIME_CONSTANTS.EVENING_START && hour < TIME_CONSTANTS.NIGHT_START) {
+    return "\u508D\u665A";
+  } else {
+    return "\u591C\u665A";
+  }
+}
+function getPercentage(current, max) {
+  if (max === 0) return 0;
+  return Math.round(current / max * 100);
+}
+function randomInt(min, max) {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+function randomChoice(array) {
+  if (array.length === 0) return void 0;
+  return array[Math.floor(Math.random() * array.length)];
+}
+function shuffle(array) {
+  const result = [...array];
+  for (let i = result.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [result[i], result[j]] = [result[j], result[i]];
+  }
+  return result;
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isEmpty(obj) {
+  return Object.keys(obj).length === 0;
+}
+function get(obj, path, defaultValue) {
+  const keys = path.split(".");
+  let result = obj;
+  for (const key of keys) {
+    if (result && typeof result === "object" && key in result) {
+      result = result[key];
+    } else {
+      return defaultValue;
+    }
+  }
+  return result;
+}
+function debounce(fn, wait) {
+  let timeout = null;
+  return function(...args) {
+    if (timeout) clearTimeout(timeout);
+    timeout = setTimeout(() => fn.apply(this, args), wait);
+  };
+}
+function throttle(fn, wait) {
+  let lastTime = 0;
+  return function(...args) {
+    const now = Date.now();
+    if (now - lastTime >= wait) {
+      lastTime = now;
+      fn.apply(this, args);
+    }
+  };
+}
+function formatGameTime(day, time) {
+  const hour = time % TIME_CONSTANTS.HOURS_PER_DAY;
+  const period = getTimeOfDay(hour);
+  const displayHour = hour === 0 ? 12 : hour > 12 ? hour - 12 : hour;
+  return `\u7B2C ${day} \u5929 ${period} ${displayHour}:00`;
+}
+function getStateDiff(oldState, newState) {
+  const diff = {
+    stats: {},
+    itemsAdded: [],
+    itemsRemoved: [],
+    flagsChanged: {}
+  };
+  for (const key in newState.stats) {
+    const oldValue = oldState.stats[key] || 0;
+    const newValue = newState.stats[key] || 0;
+    if (oldValue !== newValue) {
+      diff.stats[key] = newValue - oldValue;
+    }
+  }
+  const oldItems = new Set(oldState.inventory);
+  const newItems = new Set(newState.inventory);
+  for (const item of newState.inventory) {
+    if (!oldItems.has(item)) {
+      diff.itemsAdded.push(item);
+    }
+  }
+  for (const item of oldState.inventory) {
+    if (!newItems.has(item)) {
+      diff.itemsRemoved.push(item);
+    }
+  }
+  for (const key in newState.flags) {
+    if (oldState.flags[key] !== newState.flags[key]) {
+      diff.flagsChanged[key] = newState.flags[key];
+    }
+  }
+  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 gameEvents = new EventBus();
+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"
+};
+
+// state/history.ts
+var HistoryManager = class {
+  /**
+   * 创建历史管理器实例
+   * @param maxSnapshots - 最大保存的快照数量，默认使用配置中的值
+   */
+  constructor(maxSnapshots = DEFAULT_CONFIG.MAX_HISTORY_SNAPSHOTS) {
+    /** 存储的状态快照数组 */
+    __publicField(this, "snapshots", []);
+    /** 最大快照数量限制 */
+    __publicField(this, "maxSnapshots");
+    this.maxSnapshots = maxSnapshots;
+  }
+  /**
+   * 保存当前状态快照
+   * 
+   * 通过深拷贝保存状态，防止后续修改影响历史记录
+   * 当快照数量超过最大限制时，自动移除最旧的快照
+   * 
+   * @param state - 要保存的游戏状态
+   * 
+   * @example
+   * ```typescript
+   * history.push(gameState);
+   * ```
+   */
+  push(state) {
+    const snapshot = JSON.parse(JSON.stringify(state));
+    this.snapshots.push(snapshot);
+    if (this.snapshots.length > this.maxSnapshots) {
+      this.snapshots.shift();
+    }
+  }
+  /**
+   * 回退到上一个状态（撤销操作）
+   * 
+   * 移除并返回最近的一个快照
+   * 如果没有可用的快照，返回 undefined
+   * 
+   * @returns 上一个状态快照，如果历史为空则返回 undefined
+   * 
+   * @example
+   * ```typescript
+   * const previousState = history.pop();
+   * if (previousState) {
+   *   // 恢复到上一个状态
+   *   restoreState(previousState);
+   * }
+   * ```
+   */
+  pop() {
+    return this.snapshots.pop();
+  }
+  /**
+   * 查看最近的快照但不移除
+   * 
+   * 返回最新的快照但不从历史记录中删除它
+   * 用于预览上一个状态而不实际执行撤销操作
+   * 
+   * @returns 最近的状态快照，如果历史为空则返回 undefined
+   * 
+   * @example
+   * ```typescript
+   * const lastState = history.peek();
+   * if (lastState) {
+   *   console.log('上一个状态:', lastState);
+   * }
+   * ```
+   */
+  peek() {
+    return this.snapshots[this.snapshots.length - 1];
+  }
+  /**
+   * 清空所有历史记录
+   * 
+   * 移除所有保存的快照，释放内存
+   * 通常在开始新游戏或重置时使用
+   * 
+   * @example
+   * ```typescript
+   * history.clear(); // 清空所有历史
+   * ```
+   */
+  clear() {
+    this.snapshots = [];
+  }
+  /**
+   * 获取当前历史记录数量
+   * 
+   * @returns 当前保存的快照数量
+   * 
+   * @example
+   * ```typescript
+   * console.log(`历史记录数量: ${history.size}`);
+   * if (history.size > 0) {
+   *   // 可以执行撤销操作
+   * }
+   * ```
+   */
+  get size() {
+    return this.snapshots.length;
+  }
+};
+
+// state/store.ts
+var createGameEngineStore = (initialState, persistName = "generic-rpg-save") => {
+  const history = new HistoryManager(
+    DEFAULT_CONFIG.MAX_HISTORY_SNAPSHOTS
+  );
+  return create()(
+    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: () => {
+          const currentState = get2();
+          history.push(currentState);
+        },
+        /**
+         * 实现：撤销到上一个状态
+         * 
+         * 从历史管理器中恢复上一个快照。
+         * 恢复时保留当前的日志，并添加系统提示。
+         * 
+         * @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;
+        }
+      }),
+      {
+        // 持久化配置
+        name: persistName,
+        // localStorage中的键名
+        storage: 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 {
+  /**
+   * 检查是否满足所有需求条件
+   * 
+   * 这是核心的条件检查方法，用于验证玩家是否满足执行某个动作的所有前置条件。
+   * 内置字段使用 AND 逻辑组合，复杂逻辑使用 custom 函数实现。
+   * 
+   * @template S - 数值属性键的联合类型
+   * @template I - 物品ID的联合类型
+   * @template F - 标记键的联合类型
+   * 
+   * @param state - 当前游戏状态
+   * @param reqs - 需求定义（可选，未定义时返回true）
+   * 
+   * @returns true表示满足所有条件，false表示至少有一个条件不满足
+   * 
+   * @example
+   * ```typescript
+   * // 简单需求
+   * const simple = QuerySystem.checkRequirements(state, {
+   *   hasItems: ['key'],
+   *   stats: { strength: { min: 5 } }
+   * });
+   * 
+   * // 复杂逻辑使用 custom
+   * const complex = QuerySystem.checkRequirements(state, {
+   *   custom: (state) => {
+   *     // (有钥匙 AND 力量>=5) OR 有万能钥匙
+   *     const hasKeyAndStrength = 
+   *       state.inventory.includes('key') && state.stats.strength >= 5;
+   *     const hasMasterKey = state.inventory.includes('master_key');
+   *     return hasKeyAndStrength || hasMasterKey;
+   *   }
+   * });
+   * ```
+   */
+  static checkRequirements(state, reqs) {
+    if (!reqs) return true;
+    if (reqs.hasFlags && reqs.hasFlags.length > 0) {
+      if (!reqs.hasFlags.every((f) => state.flags[f])) return false;
+    }
+    if (reqs.noFlags && reqs.noFlags.length > 0) {
+      if (reqs.noFlags.some((f) => state.flags[f])) return false;
+    }
+    if (reqs.hasItems && reqs.hasItems.length > 0) {
+      if (!reqs.hasItems.every((i) => state.inventory.includes(i)))
+        return false;
+    }
+    if (reqs.noItems && reqs.noItems.length > 0) {
+      if (reqs.noItems.some((i) => state.inventory.includes(i))) return false;
+    }
+    if (reqs.stats) {
+      for (const [key, condition] of Object.entries(reqs.stats)) {
+        const currentVal = state.stats[key] || 0;
+        const cond = condition;
+        if (typeof cond === "number") {
+          if (currentVal < cond) return false;
+        } else {
+          if (cond.min !== void 0 && currentVal < cond.min) return false;
+          if (cond.max !== void 0 && currentVal > cond.max) return false;
+        }
+      }
+    }
+    if (reqs.custom && !reqs.custom(state)) return false;
+    return true;
+  }
+  /**
+   * 检查是否有足够资源支付成本
+   * 
+   * 验证玩家的数值属性是否足够支付指定的成本。
+   * 这是一个简化的检查，只验证数值是否足够，不实际扣除。
+   * 
+   * 与checkRequirements的区别：
+   * - canAfford只检查数值属性
+   * - checkRequirements检查完整的需求（标记、物品、数值、自定义）
+   * - canAfford用于成本检查，checkRequirements用于前置条件检查
+   * 
+   * @template S - 数值属性键的联合类型
+   * @template I - 物品ID的联合类型
+   * @template F - 标记键的联合类型
+   * 
+   * @param state - 当前游戏状态
+   * @param costs - 成本定义（可选，未定义时返回true）
+   * 
+   * @returns true表示有足够资源，false表示资源不足
+   * 
+   * @example
+   * ```typescript
+   * // 检查是否有足够金币购买物品
+   * const canBuy = QuerySystem.canAfford(state, { gold: 100 });
+   * 
+   * // 检查是否有足够资源施放技能
+   * const canCast = QuerySystem.canAfford(state, {
+   *   mp: 30,
+   *   stamina: 10
+   * });
+   * 
+   * // 在动作执行前使用
+   * if (QuerySystem.canAfford(state, action.costs)) {
+   *   // 执行动作并扣除成本
+   *   executeAction(action);
+   * } else {
+   *   addLog('资源不足！', 'error');
+   * }
+   * ```
+   */
+  static canAfford(state, costs) {
+    if (!costs) return true;
+    for (const [key, cost] of Object.entries(costs)) {
+      const currentVal = state.stats[key] || 0;
+      if (currentVal < cost) return false;
+    }
+    return true;
+  }
+};
+
+// systems/flow.ts
+var FlowSystem = class {
+  /**
+   * 执行一个游戏动作
+   *
+   * 这是核心方法，负责完整的动作执行流程。
+   * 执行过程是原子性的：要么全部成功，要么全部失败。
+   *
+   * 执行步骤：
+   * 1. 最终验证：检查需求和成本（防止UI滞后）
+   * 2. 扣除成本：消耗资源（如体力、金币）
+   * 3. 应用效果：修改状态（属性、物品、标记等）
+   * 4. 记录日志：生成反馈信息
+   *
+   * @template S - 数值属性键的联合类型
+   * @template I - 物品ID的联合类型
+   * @template F - 标记键的联合类型
+   *
+   * @param store - Zustand Store 实例（包含状态和方法）
+   * @param action - 要执行的动作定义
+   *
+   * @returns true表示执行成功，false表示执行失败
+   *
+   * @example
+   * ```typescript
+   * // 定义一个攻击动作
+   * const attackAction: ActionDef<Stats, Items, Flags> = {
+   *   id: 'attack_goblin',
+   *   label: '攻击哥布林',
+   *   costs: { stamina: 10 },
+   *   requirements: { hasItems: ['weapon'] },
+   *   effects: {
+   *     statsChange: { exp: 5 },
+   *     flagsSet: { goblin_defeated: true }
+   *   },
+   *   resultText: '你击败了哥布林！'
+   * };
+   *
+   * // 执行动作
+   * const store = useGameStore.getState();
+   * const success = FlowSystem.executeAction(store, attackAction);
+   * ```
+   */
+  static executeAction(store, action) {
+    const state = store;
+    if (!QuerySystem.checkRequirements(state, action.requirements)) {
+      console.warn(`\u6761\u4EF6\u4E0D\u6EE1\u8DB3: ${action.id}`);
+      return false;
+    }
+    if (!QuerySystem.canAfford(state, action.costs)) {
+      store.addLog(SystemMessages.NOT_ENOUGH_RESOURCES, "warn");
+      return false;
+    }
+    if (action.costs) {
+      const costsToDeduct = {};
+      for (const [key, val] of Object.entries(action.costs)) {
+        costsToDeduct[key] = -val;
+      }
+      store.setStats(costsToDeduct);
+    }
+    const { effects } = action;
+    if (effects) {
+      if (effects.statsChange) {
+        store.setStats(effects.statsChange);
+      }
+      effects.itemsAdd?.forEach((i) => store.addItem(i));
+      effects.itemsRemove?.forEach((i) => store.removeItem(i));
+      if (effects.flagsSet) {
+        Object.entries(effects.flagsSet).forEach(([f, v]) => {
+          store.setFlag(f, v);
+        });
+      }
+      if (effects.teleport) {
+        store.teleport(effects.teleport);
+      }
+      if (effects.triggerEvent) {
+        gameEvents.emit(EngineEvents.CUSTOM, { id: effects.triggerEvent });
+      }
+      if (effects.custom) {
+        const draft = { ...state.extra };
+        const result = effects.custom(draft, state);
+        if (result) {
+          store.setExtra({ ...draft, ...result });
+        } else {
+          store.setExtra(draft);
+        }
+      }
+    }
+    const resultText = typeof action.resultText === "function" ? action.resultText(state) : action.resultText;
+    store.addLog(resultText, "result");
+    gameEvents.emit(EngineEvents.ACTION_EXECUTED, { actionId: action.id });
+    return true;
+  }
+};
+var Layout = ({
+  sidebar,
+  main,
+  logs,
+  className = ""
+}) => {
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: `min-h-screen bg-[#0c0c0e] text-[#a1a1aa] font-sans flex overflow-hidden ${className}`,
+      children: [
+        sidebar && /* @__PURE__ */ jsx("aside", { className: "w-72 bg-[#141417] border-r border-[#27272a] flex flex-col shrink-0 z-10", children: sidebar }),
+        /* @__PURE__ */ jsx("main", { className: "flex-1 flex flex-col min-w-0 relative", children: main }),
+        logs && /* @__PURE__ */ jsx("aside", { className: "w-80 bg-[#0c0c0e] border-l border-[#27272a] flex flex-col shrink-0 z-10", children: logs })
+      ]
+    }
+  );
+};
+var MainContent = ({ header, children }) => /* @__PURE__ */ jsxs(Fragment, { children: [
+  header && /* @__PURE__ */ jsx("div", { className: "p-10 border-b border-[#27272a] bg-[#0c0c0e] shrink-0", children: /* @__PURE__ */ jsx("div", { className: "max-w-3xl mx-auto", children: header }) }),
+  /* @__PURE__ */ jsx("div", { className: "flex-1 overflow-y-auto p-10 bg-[#101012]", children: /* @__PURE__ */ jsx("div", { className: "max-w-3xl mx-auto", children }) })
+] });
+var LogStream = ({
+  logs,
+  className = "",
+  title = "Chronicle"
+}) => {
+  const bottomRef = useRef(null);
+  useEffect(() => {
+    bottomRef.current?.scrollIntoView({ behavior: "smooth" });
+  }, [logs]);
+  const getLogStyle = (type) => {
+    switch (type) {
+      case "warn":
+        return "text-amber-500 border-l-2 border-amber-500/50 pl-2";
+      case "error":
+        return "text-red-500 border-l-2 border-red-500/50 pl-2 font-bold";
+      case "success":
+        return "text-green-500 border-l-2 border-green-500/50 pl-2";
+      case "result":
+        return "text-stone-300 border-l-2 border-stone-600/50 pl-2";
+      // 行动结果
+      case "info":
+      default:
+        return "text-stone-500 border-l-2 border-transparent pl-2";
+    }
+  };
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: `flex flex-col bg-[#0c0c0e] border-l border-[#27272a] h-full ${className}`,
+      children: [
+        /* @__PURE__ */ jsx("div", { className: "p-4 border-b border-[#27272a] bg-[#141417] shrink-0", children: /* @__PURE__ */ jsx("h3", { className: "text-xs font-bold text-stone-500 uppercase tracking-wider", children: title }) }),
+        /* @__PURE__ */ jsxs("div", { className: "flex-1 overflow-y-auto p-6 space-y-4 font-serif scroll-smooth", children: [
+          logs.length === 0 && /* @__PURE__ */ jsx("div", { className: "text-stone-700 text-sm italic text-center mt-10", children: "\u6682\u65E0\u8BB0\u5F55..." }),
+          logs.map((log) => /* @__PURE__ */ jsx(
+            "div",
+            {
+              className: `text-sm leading-relaxed transition-all duration-500 animate-in fade-in slide-in-from-bottom-2 ${getLogStyle(
+                log.type
+              )}`,
+              children: log.text
+            },
+            log.id
+          )),
+          /* @__PURE__ */ jsx("div", { ref: bottomRef })
+        ] })
+      ]
+    }
+  );
+};
+function OverlaySystem() {
+  const [toasts, setToasts] = useState([]);
+  const [modal, setModal] = useState(null);
+  useEffect(() => {
+    const unsubscribe = gameEvents.on(
+      EngineEvents.NOTIFICATION,
+      (payload) => {
+        switch (payload.notificationType) {
+          case "toast": {
+            const toastId = `toast-${payload.timestamp}-${Math.random()}`;
+            const toast = { ...payload, id: toastId };
+            setToasts((prev) => [...prev, toast]);
+            setTimeout(() => {
+              setToasts((prev) => prev.filter((t) => t.id !== toastId));
+            }, DEFAULT_CONFIG.TOAST_DURATION);
+            break;
+          }
+          case "modal": {
+            setModal(payload);
+            break;
+          }
+        }
+      }
+    );
+    return unsubscribe;
+  }, []);
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx("div", { className: "toast-container", children: toasts.map((toast) => /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: `toast toast-${toast.type}`,
+        role: "alert",
+        children: toast.text
+      },
+      toast.id
+    )) }),
+    modal && /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: "modal-overlay",
+        onClick: () => setModal(null),
+        role: "dialog",
+        "aria-modal": "true",
+        children: /* @__PURE__ */ jsxs(
+          "div",
+          {
+            className: "modal-content",
+            onClick: (e) => e.stopPropagation(),
+            children: [
+              /* @__PURE__ */ jsx("div", { className: `modal-message modal-${modal.type}`, children: modal.text }),
+              /* @__PURE__ */ jsx(
+                "button",
+                {
+                  className: "modal-button",
+                  onClick: () => setModal(null),
+                  autoFocus: true,
+                  children: "\u786E\u5B9A"
+                }
+              )
+            ]
+          }
+        )
+      }
+    ),
+    /* @__PURE__ */ jsx("style", { children: `
+        /* \u98D8\u5B57\u5BB9\u5668 */
+        .toast-container {
+          position: fixed;
+          top: 20px;
+          right: 20px;
+          z-index: 1000;
+          display: flex;
+          flex-direction: column;
+          gap: 10px;
+          pointer-events: none;
+        }
+
+        /* \u98D8\u5B57\u6837\u5F0F */
+        .toast {
+          padding: 12px 20px;
+          border-radius: 8px;
+          background: white;
+          box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+          animation: slideIn 0.3s ease-out, fadeOut 0.3s ease-in 2.7s;
+          pointer-events: auto;
+          max-width: 300px;
+          word-wrap: break-word;
+        }
+
+        .toast-info {
+          border-left: 4px solid #3b82f6;
+          color: #1e40af;
+        }
+
+        .toast-success {
+          border-left: 4px solid #10b981;
+          color: #065f46;
+        }
+
+        .toast-warn {
+          border-left: 4px solid #f59e0b;
+          color: #92400e;
+        }
+
+        .toast-error {
+          border-left: 4px solid #ef4444;
+          color: #991b1b;
+        }
+
+        .toast-result {
+          border-left: 4px solid #6366f1;
+          color: #3730a3;
+        }
+
+        @keyframes slideIn {
+          from {
+            transform: translateX(100%);
+            opacity: 0;
+          }
+          to {
+            transform: translateX(0);
+            opacity: 1;
+          }
+        }
+
+        @keyframes fadeOut {
+          from {
+            opacity: 1;
+          }
+          to {
+            opacity: 0;
+          }
+        }
+
+        /* \u6A21\u6001\u5F39\u7A97 */
+        .modal-overlay {
+          position: fixed;
+          inset: 0;
+          background: rgba(0, 0, 0, 0.5);
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          z-index: 2000;
+          animation: fadeIn 0.2s ease-out;
+        }
+
+        .modal-content {
+          background: white;
+          padding: 24px;
+          border-radius: 12px;
+          max-width: 400px;
+          min-width: 300px;
+          box-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.1);
+          animation: scaleIn 0.2s ease-out;
+        }
+
+        .modal-message {
+          margin-bottom: 20px;
+          font-size: 16px;
+          line-height: 1.5;
+          color: #1f2937;
+        }
+
+        .modal-success {
+          color: #10b981;
+        }
+
+        .modal-warn {
+          color: #f59e0b;
+        }
+
+        .modal-error {
+          color: #ef4444;
+        }
+
+        .modal-button {
+          width: 100%;
+          padding: 10px 20px;
+          background: #3b82f6;
+          color: white;
+          border: none;
+          border-radius: 6px;
+          font-size: 14px;
+          font-weight: 500;
+          cursor: pointer;
+          transition: background 0.2s;
+        }
+
+        .modal-button:hover {
+          background: #2563eb;
+        }
+
+        .modal-button:active {
+          background: #1d4ed8;
+        }
+
+        @keyframes fadeIn {
+          from {
+            opacity: 0;
+          }
+          to {
+            opacity: 1;
+          }
+        }
+
+        @keyframes scaleIn {
+          from {
+            transform: scale(0.9);
+            opacity: 0;
+          }
+          to {
+            transform: scale(1);
+            opacity: 1;
+          }
+        }
+      ` })
+  ] });
+}
+
+export { DEFAULT_CONFIG, DEFAULT_STATS, ENGINE_VERSION, EngineEvents, EventBus, FlowSystem, HistoryManager, LOG_TYPE_COLORS, Layout, LogStream, MainContent, OverlaySystem, QuerySystem, SystemMessages, TIME_CONSTANTS, UI_CONSTANTS, VALIDATION, clamp, createGameEngineStore, debounce, deepClone, delay, formatGameTime, formatNumber, gameEvents, generateId, get, getPercentage, getStateDiff, getTimeOfDay, isEmpty, randomChoice, randomInt, shuffle, throttle };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map