steamsheep-ts-game-engine 1.1.0 → 3.0.0

package/dist/types-C3Q7UPWy.d.mts

@@ -0,0 +1,1601 @@
+/**
+ * 批量标记操作定义
+ *
+ * 定义批量清除和设置标记的操作。
+ *
+ * @template F - 标记键的联合类型
+ */
+interface FlagsBatchOperation<_F extends string = string> {
+    /**
+     * 要清除的标记
+     *
+     * 支持三种形式：
+     * - RegExp: 正则表达式，匹配的标记会被设置为 false
+     * - string: 前缀字符串，以此开头的标记会被设置为 false
+     * - string[]: 标记列表，列出的标记会被设置为 false
+     *
+     * @example
+     * ```typescript
+     * // 正则表达式
+     * clear: /^daily_.*$/
+     *
+     * // 前缀字符串
+     * clear: 'temp_'
+     *
+     * // 标记列表
+     * clear: ['flag1', 'flag2', 'flag3']
+     * ```
+     */
+    clear?: RegExp | string | string[];
+    /**
+     * 要设置的标记
+     *
+     * 键值对形式，指定要设置的标记及其值。
+     *
+     * @example
+     * ```typescript
+     * set: {
+     *   new_day: true,
+     *   old_flag: false,
+     *   dynamic_flag: true
+     * }
+     * ```
+     */
+    set?: Record<string, boolean>;
+}
+/**
+ * 游戏Store操作方法接口 - 用于 afterEffects 钩子
+ *
+ * 这是一个简化的接口定义，包含了在 afterEffects 中常用的操作方法。
+ * 完整的接口定义在 state/store.ts 中。
+ *
+ * @template S - 数值属性键的联合类型
+ * @template I - 物品ID的联合类型
+ * @template F - 标记键的联合类型
+ * @template X - 扩展数据类型
+ */
+interface GameStoreActions<S extends string, I extends string, F extends string, X = Record<string, unknown>> {
+    updateStat: (stat: S, delta: number) => void;
+    setStats: (stats: Partial<Record<S, number>>) => void;
+    setExtra: (updater: Partial<X> | ((prev: X) => Partial<X>)) => void;
+    addItem: (item: I) => void;
+    removeItem: (item: I) => void;
+    setFlag: (flag: F, value: boolean) => void;
+    addLog: (text: string, type?: LogEntry['type']) => void;
+    showToast: (text: string, type?: LogEntry['type']) => void;
+    showModal: (text: string, type?: LogEntry['type']) => void;
+    advanceTime: (amount?: number) => void;
+    teleport: (locationId: string) => void;
+    reset: () => void;
+    saveSnapshot: () => void;
+    undo: () => boolean;
+}
+/**
+ * 游戏状态接口 - 存储游戏的完整状态
+ *
+ * 这是整个游戏引擎的核心数据结构，包含了游戏运行所需的所有状态信息。
+ * 使用泛型使其适用于任何类型的游戏，无需修改引擎代码。
+ *
+ * @template S - 数值属性键的联合类型
+ * @template I - 物品ID的联合类型
+ * @template F - 标记键的联合类型
+ *
+ * @example
+ * ```typescript
+ * type RPGState = GameState<
+ *   'hp' | 'mp' | 'gold',
+ *   'sword' | 'potion',
+ *   'dragon_defeated' | 'has_key'
+ * >;
+ * ```
+ */
+interface GameState<S extends string, I extends string, F extends string, X = Record<string, unknown>> {
+    /**
+     * 数值属性记录 (如生命值、金币、经验等)
+     * 使用Record类型确保所有定义的属性都有对应的数值
+     */
+    stats: Record<S, number>;
+    /**
+     * 物品清单 - 存储玩家拥有的物品ID
+     * 使用数组允许同一物品多次出现（如多个药水）
+     */
+    inventory: I[];
+    /**
+     * 布尔标记 - 用于追踪游戏状态、任务进度等
+     * 常用于记录剧情进度、解锁状态、触发条件等
+     */
+    flags: Record<F, boolean>;
+    /**
+     * 世界状态 - 包含位置、时间等世界级信息
+     */
+    world: WorldState;
+    /**
+     * 日志条目数组 - 记录游戏事件
+     * 用于显示游戏历史和玩家操作反馈
+     */
+    logs: LogEntry[];
+    /**
+     * 扩展数据 - 存储游戏特定的额外状态
+     *
+     * 这是一个灵活的字段，允许不同游戏存储自定义数据。
+     * 使用泛型 X 来定义具体的扩展数据类型。
+     *
+     * @example
+     * ```typescript
+     * // 定义扩展数据类型
+     * interface MyGameExtra {
+     *   reputation: number;
+     *   guild: string;
+     *   achievements: string[];
+     * }
+     *
+     * // 使用扩展数据
+     * type MyGameState = GameState<Stats, Items, Flags, MyGameExtra>;
+     * ```
+     */
+    extra: X;
+}
+/**
+ * 世界状态接口 - 追踪游戏世界的时间和位置信息
+ */
+interface WorldState {
+    /** 当前所在位置的唯一标识符 */
+    currentLocationId: string;
+    /** 游戏内的天数 - 用于追踪游戏进度 */
+    day: number;
+    /** 当前时间 - 可以是0-24的小时制或自定义时间单位 */
+    time: number;
+}
+/**
+ * 日志条目接口 - 记录游戏中发生的事件
+ *
+ * ⚠️ 重要：LogEntry 是持久化的历史记录，会被保存到 localStorage
+ *
+ * 用于构建游戏日志系统，记录玩家操作、系统事件等信息。
+ * 每条日志都有类型标记，便于UI层进行样式区分和过滤。
+ *
+ * 日志会：
+ * - 被保存到 localStorage
+ * - 在页面刷新后重新加载
+ * - 永久显示在日志面板中
+ * - 可以被玩家回顾
+ */
+interface LogEntry {
+    /**
+     * 唯一标识符 - 用于React列表渲染的key
+     * 建议使用UUID或时间戳+随机数生成
+     */
+    id: string;
+    /**
+     * 日志文本内容 - 显示给玩家的消息
+     * 可以包含动态内容，如玩家名称、物品名称等
+     */
+    text: string;
+    /**
+     * 日志类型 - 用于UI显示不同样式和图标
+     * - info: 普通信息（灰色）
+     * - warn: 警告信息（黄色）
+     * - error: 错误信息（红色）
+     * - success: 成功信息（绿色）
+     * - result: 动作执行结果（黑色）
+     */
+    type: "info" | "warn" | "error" | "success" | "result";
+    /**
+     * 日志产生的时间戳 - 游戏内时间或真实时间戳
+     * 用于排序和显示时间信息
+     */
+    timestamp: number;
+}
+/**
+ * 通知类型枚举
+ *
+ * ⚠️ 重要：通知是瞬时的 UI 状态，不会被持久化
+ *
+ * 定义不同强度的通知方式：
+ * - toast: 飘字提示（轻量级，自动消失，不阻塞）
+ * - modal: 弹窗消息（强提示，需要用户确认，阻塞式）
+ */
+type NotificationType = 'toast' | 'modal';
+/**
+ * 通知载荷 - 用于事件系统传递瞬时通知
+ *
+ * ⚠️ 与 LogEntry 的区别：
+ * - NotificationPayload: 瞬时通知，不持久化，用于 UI 反馈
+ * - LogEntry: 历史记录，持久化，用于回顾
+ *
+ * 通知会：
+ * - 通过事件系统发送
+ * - 仅在当前会话中显示
+ * - 不会被保存到 localStorage
+ * - 不会在页面刷新后重新出现
+ */
+interface NotificationPayload {
+    /** 通知文本 */
+    text: string;
+    /** 通知类型（影响样式） */
+    type: LogEntry['type'];
+    /** 通知方式（toast 或 modal） */
+    notificationType: NotificationType;
+    /** 时间戳（仅用于生成唯一 ID 和去重，不在 UI 中显示） */
+    timestamp: number;
+}
+/**
+ * 数值需求类型 - 定义属性检查的方式
+ *
+ * 可以是简单的数值（精确匹配）或范围对象（最小/最大值）
+ *
+ * @example
+ * ```typescript
+ * // 精确需求: 必须有10点体力
+ * const exact: StatRequirement = 10;
+ *
+ * // 范围需求: 体力必须在5-20之间
+ * const range: StatRequirement = { min: 5, max: 20 };
+ *
+ * // 最小需求: 至少需要5点体力
+ * const minimum: StatRequirement = { min: 5 };
+ * ```
+ */
+type StatRequirement = number | {
+    min?: number;
+    max?: number;
+};
+/**
+ * 需求检查结果
+ *
+ * 用于返回需求检查的结果，包括是否通过和失败原因。
+ */
+interface RequirementCheckResult {
+    /**
+     * 是否通过需求检查
+     */
+    passed: boolean;
+    /**
+     * 失败原因（可选）
+     *
+     * 当 passed 为 false 时，可以提供失败原因。
+     * UI 层可以显示这个原因给玩家。
+     */
+    reason?: string;
+}
+/**
+ * 需求定义接口 - 定义执行动作前必须满足的条件
+ *
+ * 用于检查玩家是否有资格执行某个动作。
+ * 需求检查不会消耗资源，只是判断是否满足条件。
+ *
+ * @template S - 数值属性键的联合类型
+ * @template I - 物品ID的联合类型
+ * @template F - 标记键的联合类型
+ *
+ * @example
+ * ```typescript
+ * // 简单需求
+ * const simpleReqs: RequirementDef<Stats, Items, Flags> = {
+ *   hasItems: ['key'],
+ *   stats: { strength: { min: 5 } }
+ * };
+ *
+ * // 复杂逻辑使用 custom 函数
+ * const complexReqs: RequirementDef<Stats, Items, Flags> = {
+ *   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;
+ *   }
+ * };
+ * ```
+ */
+interface RequirementDef<S extends string, I extends string, F extends string, X = Record<string, unknown>> {
+    /**
+     * 数值属性需求 - 检查玩家属性是否满足条件
+     * 使用Partial允许只检查部分属性
+     * 所有指定的属性必须同时满足（AND逻辑）
+     */
+    stats?: Partial<Record<S, StatRequirement>>;
+    /**
+     * 必须拥有的物品列表
+     * 玩家库存中必须包含所有列出的物品（AND逻辑）
+     */
+    hasItems?: I[];
+    /**
+     * 不能拥有的物品列表
+     * 玩家库存中不能包含任何列出的物品（OR逻辑）
+     */
+    noItems?: I[];
+    /**
+     * 必须为true的标记列表
+     * 所有列出的标记必须已设置为true（AND逻辑）
+     */
+    hasFlags?: F[];
+    /**
+     * 必须为false的标记列表
+     * 所有列出的标记必须为false或未设置（OR逻辑）
+     */
+    noFlags?: F[];
+    /**
+     * 自定义需求函数 - 用于复杂逻辑
+     *
+     * ⚠️ 增强功能：支持返回失败原因
+     *
+     * 当需要表达复杂的逻辑关系时使用此函数。
+     * 函数接收完整的游戏状态，可以返回：
+     * - boolean: true 表示满足需求，false 表示不满足
+     * - RequirementCheckResult: 包含是否通过和失败原因
+     *
+     * 返回失败原因的优势：
+     * - UI 可以显示具体的失败原因
+     * - 提供更好的用户体验
+     * - 帮助玩家理解为什么不能执行动作
+     *
+     * 可以在函数中实现任意复杂的逻辑，包括：
+     * - OR 逻辑：A || B
+     * - 复杂组合：(A && B) || C
+     * - 嵌套逻辑：((A || B) && C) || D
+     * - 动态计算：基于多个状态的复杂判断
+     *
+     * @param state - 当前游戏状态
+     * @returns boolean 或 RequirementCheckResult
+     *
+     * @example
+     * ```typescript
+     * // 示例1：简单 boolean 返回
+     * custom: (state) =>
+     *   state.inventory.includes('key') ||
+     *   state.inventory.includes('lockpick')
+     *
+     * // 示例2：返回失败原因
+     * custom: (state) => {
+     *   if (!state.inventory.includes('key')) {
+     *     return {
+     *       passed: false,
+     *       reason: "需要钥匙才能打开这扇门"
+     *     };
+     *   }
+     *
+     *   if (state.stats.strength < 5) {
+     *     return {
+     *       passed: false,
+     *       reason: "力量不足（需要 5 点力量）"
+     *     };
+     *   }
+     *
+     *   return { passed: true };
+     * }
+     *
+     * // 示例3：多个条件的详细提示
+     * custom: (state) => {
+     *   const hasKey = state.inventory.includes('key');
+     *   const hasLockpick = state.inventory.includes('lockpick');
+     *   const hasStrength = state.stats.strength >= 10;
+     *
+     *   if (!hasKey && !hasLockpick && !hasStrength) {
+     *     return {
+     *       passed: false,
+     *       reason: "需要钥匙、撬锁工具或 10 点力量"
+     *     };
+     *   }
+     *
+     *   if (hasLockpick && state.stats.dexterity < 5) {
+     *     return {
+     *       passed: false,
+     *       reason: "使用撬锁工具需要 5 点敏捷"
+     *     };
+     *   }
+     *
+     *   return { passed: true };
+     * }
+     *
+     * // 示例4：基于理智值的检查
+     * custom: (state) => {
+     *   if (state.stats.sanity < 20) {
+     *     return {
+     *       passed: false,
+     *       reason: "理智太低，无法集中精神进行仪式"
+     *     };
+     *   }
+     *
+     *   if (state.stats.sanity < 50) {
+     *     return {
+     *       passed: true,
+     *       reason: "你勉强能够进行仪式，但风险很大"
+     *     };
+     *   }
+     *
+     *   return { passed: true };
+     * }
+     *
+     * // 示例5：时间相关的检查
+     * custom: (state) => {
+     *   const time = state.world.time;
+     *
+     *   if (time < 18 && time > 6) {
+     *     return {
+     *       passed: false,
+     *       reason: "只能在夜晚（18:00-6:00）进行此仪式"
+     *     };
+     *   }
+     *
+     *   return { passed: true };
+     * }
+     *
+     * // 示例6：组合多个条件
+     * custom: (state) => {
+     *   const missingItems: string[] = [];
+     *
+     *   if (!state.inventory.includes('candle')) {
+     *     missingItems.push('蜡烛');
+     *   }
+     *   if (!state.inventory.includes('chalk')) {
+     *     missingItems.push('粉笔');
+     *   }
+     *   if (!state.inventory.includes('book')) {
+     *     missingItems.push('古书');
+     *   }
+     *
+     *   if (missingItems.length > 0) {
+     *     return {
+     *       passed: false,
+     *       reason: `缺少必需物品：${missingItems.join('、')}`
+     *     };
+     *   }
+     *
+     *   return { passed: true };
+     * }
+     *
+     * // 示例7：向后兼容 - 仍然可以返回 boolean
+     * custom: (state) => {
+     *   return state.stats.level >= 10;
+     * }
+     * ```
+     */
+    custom?: (state: GameState<S, I, F, X>) => boolean | RequirementCheckResult;
+}
+/**
+ * 效果定义接口 - 定义动作执行后对游戏状态的改变
+ *
+ * 描述执行动作后会产生的所有效果，包括属性变化、物品变化、
+ * 标记设置、位置传送等。
+ *
+ * ⚠️ 重要：效果执行顺序
+ *
+ * 效果按以下顺序执行（从上到下）：
+ *
+ * 【阶段 1：静态效果】
+ * 1. statsChange - 数值属性变更
+ * 2. itemsAdd - 添加物品
+ * 3. itemsRemove - 移除物品
+ * 4. flagsSet - 设置标记
+ * 5. flagsBatch - 批量标记操作
+ * 6. teleport - 传送
+ * 7. timeAdvance + onTimeAdvance - 时间推进及其钩子
+ * 8. triggerEvent - 触发自定义事件
+ *
+ * 【阶段 2：条件效果】
+ * 9. conditionalEffects - 根据当前状态（包含阶段1的修改）决定额外效果
+ *    - 返回的效果会按阶段1的顺序再次执行
+ *
+ * 【阶段 3：自定义效果】
+ * 10. custom - 修改 extra 扩展数据
+ * 11. customFull - 修改完整游戏状态（最强大，可覆盖之前的修改）
+ *
+ * 【阶段 4：后置钩子】
+ * 12. afterEffects - 在所有效果执行完成后调用（在 ActionDef 中定义）
+ *
+ * 【阶段 5：结果文本】
+ * 13. resultText - 生成反馈文本（在 ActionDef 中定义）
+ *
+ * 设计原则：
+ * - 简单效果在前，复杂效果在后
+ * - 静态效果在前，动态效果在后
+ * - 读取状态的效果在后（可以看到之前的修改）
+ * - 最强大的 customFull 在最后（可以覆盖一切）
+ *
+ * 使用建议：
+ * - 大多数情况使用静态效果（statsChange、itemsAdd 等）
+ * - 需要条件判断时使用 conditionalEffects
+ * - 需要修改 extra 时使用 custom
+ * - 需要复杂状态修改时使用 customFull
+ * - 需要基于最终状态执行副作用时使用 afterEffects
+ *
+ * @template S - 数值属性键的联合类型
+ * @template I - 物品ID的联合类型
+ * @template F - 标记键的联合类型
+ *
+ * @example
+ * ```typescript
+ * // 示例1：简单效果（按顺序执行）
+ * const drinkPotionEffect: EffectDef<Stats, Items, Flags> = {
+ *   statsChange: { hp: 20 },      // 1. 恢复20点生命值
+ *   itemsRemove: ['potion'],      // 2. 消耗药水
+ *   flagsSet: { used_potion: true } // 3. 标记已使用过药水
+ * };
+ *
+ * // 示例2：利用执行顺序
+ * const complexEffect: EffectDef<Stats, Items, Flags> = {
+ *   // 阶段1：先修改基础状态
+ *   statsChange: { sanity: -10 },
+ *   itemsAdd: ['cursed_item'],
+ *
+ *   // 阶段2：基于修改后的状态决定额外效果
+ *   conditionalEffects: (state) => {
+ *     // 此时 sanity 已经减少了 10
+ *     if (state.stats.sanity < 20) {
+ *       return {
+ *         flagsSet: { going_mad: true },
+ *         statsChange: { sanity: -5 } // 额外减少
+ *       };
+ *     }
+ *     return null;
+ *   },
+ *
+ *   // 阶段3：最后修改扩展数据
+ *   custom: (draft, state) => {
+ *     // 此时所有之前的效果都已执行
+ *     draft.lastSanityLoss = Date.now();
+ *   }
+ * };
+ *
+ * // 示例3：使用 customFull 覆盖之前的修改
+ * const overrideEffect: EffectDef<Stats, Items, Flags> = {
+ *   statsChange: { hp: -50 }, // 先扣除50点生命
+ *
+ *   customFull: (draft, original) => {
+ *     // 如果有护盾，取消伤害
+ *     if (original.flags.has_shield) {
+ *       draft.stats.hp = original.stats.hp; // 恢复到原始值
+ *       draft.flags.has_shield = false; // 消耗护盾
+ *     }
+ *   }
+ * };
+ * ```
+ */
+interface EffectDef<S extends string, I extends string, F extends string, X = Record<string, unknown>> {
+    /**
+     * 数值属性变更
+     *
+     * 可以是静态对象或动态函数：
+     * - 静态对象：直接指定属性变化量（正数增加，负数减少）
+     * - 动态函数：根据游戏状态动态计算属性变化
+     *
+     * 函数形式的优势：
+     * - 类型自动推断，无需手动标注
+     * - 可以基于当前状态计算变化量
+     * - 支持复杂的计算逻辑
+     *
+     * @example
+     * ```typescript
+     * // 静态变更
+     * statsChange: { hp: 10, gold: -5 }
+     *
+     * // 动态变更 - 基于当前状态计算
+     * statsChange: (state) => {
+     *   // state 类型自动推断，无需手动标注
+     *   const maxAP = state.stats.max_action_point || 4;
+     *   const currentAP = state.stats.action_point || 0;
+     *
+     *   return {
+     *     action_point: maxAP - currentAP  // 恢复到最大值
+     *   };
+     * }
+     *
+     * // 基于时间的动态变更
+     * statsChange: (state) => {
+     *   const isNight = state.world.time >= 18 || state.world.time <= 6;
+     *
+     *   return {
+     *     sanity: isNight ? -10 : -5,  // 夜晚消耗更多理智
+     *     knowledge: isNight ? 3 : 1   // 夜晚获得更多知识
+     *   };
+     * }
+     *
+     * // 基于物品的动态变更
+     * statsChange: (state) => {
+     *   const hasAmulet = state.inventory.includes('protective_amulet' as any);
+     *   const baseDamage = -20;
+     *
+     *   return {
+     *     health: hasAmulet ? baseDamage / 2 : baseDamage  // 护符减半伤害
+     *   };
+     * }
+     *
+     * // 基于百分比的变更
+     * statsChange: (state) => {
+     *   const currentHP = state.stats.health;
+     *   const maxHP = state.stats.max_health || 100;
+     *
+     *   return {
+     *     health: Math.floor(maxHP * 0.5) - currentHP  // 恢复到50%
+     *   };
+     * }
+     *
+     * // 复杂的条件计算
+     * statsChange: (state) => {
+     *   const changes: Partial<Record<S, number>> = {};
+     *
+     *   // 基础消耗
+     *   changes.stamina = -10;
+     *
+     *   // 如果理智低，额外消耗
+     *   if (state.stats.sanity < 30) {
+     *     changes.stamina = -15;
+     *     changes.sanity = -5;
+     *   }
+     *
+     *   // 如果有特殊状态，获得奖励
+     *   if (state.flags.blessed) {
+     *     changes.luck = 1;
+     *   }
+     *
+     *   return changes;
+     * }
+     * ```
+     */
+    statsChange?: Partial<Record<S, number>> | ((state: GameState<S, I, F, X>) => Partial<Record<S, number>>);
+    /**
+     * 添加到库存的物品列表
+     * 物品会被添加到玩家的inventory数组中
+     */
+    itemsAdd?: I[];
+    /**
+     * 从库存移除的物品列表
+     * 每个物品只会移除一次（如果有多个相同物品）
+     */
+    itemsRemove?: I[];
+    /**
+     * 标记设置
+     *
+     * 可以是静态对象或动态函数：
+     * - 静态对象：直接设置指定标记的布尔值
+     * - 动态函数：根据游戏状态动态生成标记
+     *
+     * @example
+     * ```typescript
+     * // 静态标记
+     * flagsSet: { quest_completed: true, door_locked: false }
+     *
+     * // 动态标记 - 根据游戏状态生成
+     * flagsSet: (state) => {
+     *   const day = state.world.day;
+     *   return {
+     *     [`event_day_${day}`]: true,
+     *     [`gazed_stars_day_${day}`]: true
+     *   };
+     * }
+     *
+     * // 混合使用 - 结合静态和动态逻辑
+     * flagsSet: (state) => {
+     *   const flags: Record<string, boolean> = {
+     *     action_taken: true  // 静态标记
+     *   };
+     *
+     *   // 动态添加标记
+     *   if (state.world.time >= 18) {
+     *     flags.night_action = true;
+     *   }
+     *
+     *   return flags;
+     * }
+     * ```
+     */
+    flagsSet?: Partial<Record<F, boolean>> | ((state: GameState<S, I, F, X>) => Record<string, boolean>);
+    /**
+     * 批量标记操作 - 支持模式匹配和批量设置/清除
+     *
+     * ⚠️ 高级功能：用于批量管理大量标记
+     *
+     * 提供更强大的标记操作能力：
+     * - 批量清除：根据模式或列表清除多个标记
+     * - 批量设置：同时设置多个标记
+     * - 模式匹配：使用正则表达式或前缀匹配
+     *
+     * 执行顺序：
+     * 1. 先执行 clear（清除操作）
+     * 2. 再执行 set（设置操作）
+     * 3. flagsBatch 在 flagsSet 之后执行
+     *
+     * @example
+     * ```typescript
+     * // 示例1：清除所有每日标记
+     * flagsBatch: {
+     *   clear: /^daily_.*$/,  // 清除所有 daily_ 开头的标记
+     *   set: { new_day: true }
+     * }
+     *
+     * // 示例2：使用字符串前缀匹配
+     * flagsBatch: {
+     *   clear: 'temp_',  // 清除所有 temp_ 开头的标记
+     *   set: { cleanup_done: true }
+     * }
+     *
+     * // 示例3：清除指定列表的标记
+     * flagsBatch: {
+     *   clear: ['flag1', 'flag2', 'flag3'],
+     *   set: { reset_complete: true }
+     * }
+     *
+     * // 示例4：动态批量操作
+     * flagsBatch: (state) => {
+     *   const currentDay = state.world.day;
+     *   const flagsToClear: string[] = [];
+     *
+     *   // 清除7天前的事件标记
+     *   for (let i = 1; i <= 7; i++) {
+     *     const oldDay = currentDay - 7;
+     *     if (oldDay > 0) {
+     *       flagsToClear.push(`event_day_${oldDay}`);
+     *       flagsToClear.push(`action_day_${oldDay}`);
+     *     }
+     *   }
+     *
+     *   return {
+     *     clear: flagsToClear,
+     *     set: { [`day_${currentDay}_started`]: true }
+     *   };
+     * }
+     *
+     * // 示例5：基于条件的批量清除
+     * flagsBatch: (state) => {
+     *   if (state.flags.game_reset) {
+     *     // 游戏重置时清除所有进度标记
+     *     return {
+     *       clear: /^(quest_|achievement_|unlock_)/,
+     *       set: {
+     *         game_reset: false,
+     *         fresh_start: true
+     *       }
+     *     };
+     *   }
+     *   return null;  // 不执行批量操作
+     * }
+     *
+     * // 示例6：清除过期的临时标记
+     * flagsBatch: (state) => {
+     *   const allFlags = Object.keys(state.flags);
+     *   const tempFlags = allFlags.filter(f => f.startsWith('temp_'));
+     *
+     *   return {
+     *     clear: tempFlags,
+     *     set: { temp_cleanup_done: true }
+     *   };
+     * }
+     *
+     * // 示例7：只清除不设置
+     * flagsBatch: {
+     *   clear: /^cache_/  // 只清除缓存标记
+     * }
+     *
+     * // 示例8：只设置不清除
+     * flagsBatch: {
+     *   set: {
+     *     flag1: true,
+     *     flag2: false,
+     *     flag3: true
+     *   }
+     * }
+     *
+     * // 示例9：组合多种模式
+     * flagsBatch: (state) => {
+     *   const operations: FlagsBatchOperation<F> = {};
+     *
+     *   // 清除所有临时标记
+     *   if (state.world.day % 7 === 0) {
+     *     operations.clear = /^temp_/;
+     *   }
+     *
+     *   // 设置新的周期标记
+     *   operations.set = {
+     *     [`week_${Math.floor(state.world.day / 7)}`]: true
+     *   };
+     *
+     *   return operations;
+     * }
+     * ```
+     */
+    flagsBatch?: FlagsBatchOperation<F> | ((state: GameState<S, I, F, X>) => FlagsBatchOperation<F> | null | undefined);
+    /**
+     * 传送目标位置ID
+     * 如果设置，玩家会被传送到指定位置
+     */
+    teleport?: string;
+    /**
+     * 时间推进
+     *
+     * 增加游戏内的天数。可以是静态数值或动态函数。
+     *
+     * @example
+     * ```typescript
+     * // 静态推进
+     * timeAdvance: 1  // 推进1天
+     *
+     * // 动态推进
+     * timeAdvance: (state) => {
+     *   // 根据状态决定推进天数
+     *   return state.flags.fast_travel ? 3 : 1;
+     * }
+     * ```
+     */
+    timeAdvance?: number | ((state: GameState<S, I, F, X>) => number);
+    /**
+     * 时间推进钩子 - 在时间推进时自动执行
+     *
+     * ⚠️ 实用功能：自动处理时间相关的状态变化
+     *
+     * 当 timeAdvance 执行后，此钩子会被调用。
+     * 可以用于：
+     * - 清除每日标记
+     * - 恢复每日资源
+     * - 触发时间相关事件
+     * - 更新时间相关状态
+     *
+     * 执行时机：
+     * - 在 timeAdvance 修改 world.day 之后立即执行
+     * - 在其他效果之后执行
+     * - 每推进一天调用一次（如果推进多天，会多次调用）
+     *
+     * 注意事项：
+     * 1. 函数接收推进后的天数和推进前的天数
+     * 2. 如果推进多天，钩子会为每一天分别调用
+     * 3. 可以访问和修改游戏状态
+     * 4. 不应返回值，所有修改通过参数进行
+     *
+     * @param currentDay - 推进后的当前天数
+     * @param previousDay - 推进前的天数
+     * @param state - 当前游戏状态（可读）
+     * @param actions - Store 操作方法集合（用于修改状态）
+     *
+     * @example
+     * ```typescript
+     * // 示例1：清除每日标记
+     * {
+     *   timeAdvance: 1,
+     *   onTimeAdvance: (currentDay, previousDay, state, actions) => {
+     *     // 清除所有 daily_ 开头的标记
+     *     const dailyFlags = Object.keys(state.flags)
+     *       .filter(f => f.startsWith('daily_'));
+     *
+     *     dailyFlags.forEach(f => {
+     *       actions.setFlag(f as F, false);
+     *     });
+     *
+     *     // 设置新的一天标记
+     *     actions.setFlag(`day_${currentDay}_started` as F, true);
+     *   }
+     * }
+     *
+     * // 示例2：恢复每日资源
+     * {
+     *   timeAdvance: 1,
+     *   onTimeAdvance: (currentDay, previousDay, state, actions) => {
+     *     // 恢复每日行动点
+     *     const maxAP = state.stats.max_action_point || 4;
+     *     const currentAP = state.stats.action_point || 0;
+     *     actions.setStats({
+     *       action_point: maxAP - currentAP
+     *     });
+     *
+     *     // 恢复部分理智
+     *     actions.setStats({ sanity: 10 });
+     *
+     *     actions.addLog(`第 ${currentDay} 天开始`, 'info');
+     *   }
+     * }
+     *
+     * // 示例3：触发周期性事件
+     * {
+     *   timeAdvance: 1,
+     *   onTimeAdvance: (currentDay, previousDay, state, actions) => {
+     *     // 每7天触发一次特殊事件
+     *     if (currentDay % 7 === 0) {
+     *       actions.setFlag('weekly_event_available', true);
+     *       actions.showToast('新的周期事件可用！', 'info');
+     *     }
+     *
+     *     // 每30天触发月度事件
+     *     if (currentDay % 30 === 0) {
+     *       actions.setFlag('monthly_event_available', true);
+     *       actions.showModal('月圆之夜，诡异的事情即将发生...', 'warn');
+     *     }
+     *   }
+     * }
+     *
+     * // 示例4：清理过期数据
+     * {
+     *   timeAdvance: 1,
+     *   onTimeAdvance: (currentDay, previousDay, state, actions) => {
+     *     // 清理7天前的临时标记
+     *     const oldDay = currentDay - 7;
+     *     if (oldDay > 0) {
+     *       const oldFlags = [
+     *         `temp_event_day_${oldDay}`,
+     *         `daily_action_day_${oldDay}`,
+     *         `cache_day_${oldDay}`
+     *       ];
+     *
+     *       oldFlags.forEach(f => {
+     *         actions.setFlag(f as F, false);
+     *       });
+     *     }
+     *   }
+     * }
+     *
+     * // 示例5：时间相关的状态衰减
+     * {
+     *   timeAdvance: 1,
+     *   onTimeAdvance: (currentDay, previousDay, state, actions) => {
+     *     const daysPassed = currentDay - previousDay;
+     *
+     *     // 每天衰减一些属性
+     *     actions.setStats({
+     *       hunger: daysPassed * 10,  // 饥饿度增加
+     *       fatigue: daysPassed * 5   // 疲劳度增加
+     *     });
+     *
+     *     // 如果有食物，自动消耗
+     *     if (state.inventory.includes('food' as I)) {
+     *       actions.removeItem('food' as I);
+     *       actions.setStats({ hunger: -20 });
+     *     }
+     *   }
+     * }
+     *
+     * // 示例6：使用批量标记操作
+     * {
+     *   timeAdvance: 1,
+     *   onTimeAdvance: (currentDay, previousDay, state, actions) => {
+     *     // 注意：这里不能直接使用 flagsBatch
+     *     // 需要手动实现批量清除逻辑
+     *     const dailyFlags = Object.keys(state.flags)
+     *       .filter(f => f.startsWith('daily_'));
+     *
+     *     dailyFlags.forEach(f => actions.setFlag(f as F, false));
+     *
+     *     // 设置新的每日标记
+     *     actions.setFlag('daily_reset_done', true);
+     *     actions.setFlag(`day_${currentDay}`, true);
+     *   }
+     * }
+     *
+     * // 示例7：多天推进的处理
+     * {
+     *   timeAdvance: (state) => state.flags.fast_travel ? 3 : 1,
+     *   onTimeAdvance: (currentDay, previousDay, state, actions) => {
+     *     // 这个钩子会为每一天分别调用
+     *     // 如果推进3天，会调用3次
+     *
+     *     actions.addLog(`第 ${currentDay} 天`, 'info');
+     *
+     *     // 每天恢复资源
+     *     actions.setStats({ action_point: 4 });
+     *   }
+     * }
+     * ```
+     */
+    onTimeAdvance?: (currentDay: number, previousDay: number, state: GameState<S, I, F, X>, actions: GameStoreActions<S, I, F, X>) => void;
+    /**
+     * 触发特殊事件的标识符
+     * 用于触发游戏中的特殊事件或剧情
+     */
+    triggerEvent?: string;
+    /**
+     * 自定义效果函数 - 用于修改扩展数据
+     *
+     * 当需要修改 extra 字段中的自定义数据时使用。
+     * 函数接收当前的 extra 数据和完整游戏状态。
+     * 可以直接修改 draft（Immer 风格），或返回部分更新。
+     *
+     * @param draft - 当前的扩展数据（可直接修改）
+     * @param state - 完整的游戏状态（只读）
+     * @returns void 或部分更新对象
+     *
+     * @example
+     * ```typescript
+     * // 示例1：直接修改 draft
+     * custom: (draft) => {
+     *   draft.reputation += 10;
+     *   draft.achievements.push('first_quest');
+     * }
+     *
+     * // 示例2：返回部分更新
+     * custom: (draft, state) => {
+     *   return {
+     *     reputation: draft.reputation + 10,
+     *     lastAction: Date.now()
+     *   };
+     * }
+     * ```
+     */
+    custom?: (draft: X, state: GameState<S, I, F, X>) => void | Partial<X>;
+    /**
+     * 条件性效果 - 根据游戏状态动态决定要应用的效果
+     *
+     * ⚠️ 实用功能：根据条件返回不同的效果配置
+     *
+     * 当需要根据游戏状态决定效果内容时使用。函数接收当前游戏状态，
+     * 返回要应用的效果定义。这允许实现：
+     * - 基于条件的不同效果
+     * - 动态计算的效果数值
+     * - 复杂的分支逻辑
+     *
+     * 执行顺序：
+     * 1. 先执行静态效果（statsChange、itemsAdd 等）
+     * 2. 再执行 conditionalEffects 返回的效果
+     * 3. 最后执行 custom 和 customFull
+     *
+     * 注意事项：
+     * 1. conditionalEffects 返回的效果会叠加到静态效果上
+     * 2. 如果只需要条件效果，可以不定义静态效果字段
+     * 3. 返回的效果对象支持所有标准效果字段（除了 conditionalEffects 本身）
+     * 4. 可以返回 null 或 undefined 表示不应用额外效果
+     *
+     * @param state - 当前游戏状态（执行成本扣除后的状态）
+     * @returns 要应用的效果定义，或 null/undefined 表示无额外效果
+     *
+     * @example
+     * ```typescript
+     * // 示例1：基于条件的不同效果
+     * conditionalEffects: (state) => {
+     *   const today = `gazed_stars_day_${state.world.day}`;
+     *
+     *   if (state.flags[today]) {
+     *     // 今天已经观星过，效果减弱
+     *     return {
+     *       statsChange: { sanity: -2, knowledge: 0 },
+     *       flagsSet: { repeated_action: true }
+     *     };
+     *   } else {
+     *     // 第一次观星，正常效果
+     *     return {
+     *       statsChange: { sanity: -5, knowledge: 1 },
+     *       flagsSet: { [today]: true }
+     *     };
+     *   }
+     * }
+     *
+     * // 示例2：基于时间的动态效果
+     * conditionalEffects: (state) => {
+     *   const time = state.world.time;
+     *
+     *   if (time >= 22 || time <= 4) {
+     *     // 深夜时间，效果增强
+     *     return {
+     *       statsChange: { sanity: -10, knowledge: 3 },
+     *       flagsSet: { midnight_ritual: true }
+     *     };
+     *   } else if (time >= 6 && time <= 18) {
+     *     // 白天，效果减弱
+     *     return {
+     *       statsChange: { sanity: -2, knowledge: 1 }
+     *     };
+     *   } else {
+     *     // 黄昏，正常效果
+     *     return {
+     *       statsChange: { sanity: -5, knowledge: 2 }
+     *     };
+     *   }
+     * }
+     *
+     * // 示例3：基于物品的效果变化
+     * conditionalEffects: (state) => {
+     *   const hasProtection = state.inventory.includes('protective_charm' as any);
+     *   const hasCurse = state.flags.cursed;
+     *
+     *   if (hasProtection && hasCurse) {
+     *     // 有护符但被诅咒，护符被摧毁
+     *     return {
+     *       itemsRemove: ['protective_charm' as any],
+     *       statsChange: { sanity: -15 },
+     *       flagsSet: { charm_destroyed: true }
+     *     };
+     *   } else if (hasProtection) {
+     *     // 有护符，减少伤害
+     *     return {
+     *       statsChange: { sanity: -3 }
+     *     };
+     *   } else {
+     *     // 无保护，正常伤害
+     *     return {
+     *       statsChange: { sanity: -10 }
+     *     };
+     *   }
+     * }
+     *
+     * // 示例4：基于数值的动态效果
+     * conditionalEffects: (state) => {
+     *   const sanity = state.stats.sanity;
+     *
+     *   if (sanity < 20) {
+     *     // 理智极低，产生幻觉
+     *     return {
+     *       statsChange: { sanity: -5 },
+     *       itemsAdd: ['hallucination' as any],
+     *       flagsSet: { insane: true },
+     *       triggerEvent: 'madness_event'
+     *     };
+     *   } else if (sanity < 50) {
+     *     // 理智较低，轻微影响
+     *     return {
+     *       statsChange: { sanity: -3 },
+     *       flagsSet: { unstable: true }
+     *     };
+     *   } else {
+     *     // 理智正常
+     *     return {
+     *       statsChange: { sanity: -1 }
+     *     };
+     *   }
+     * }
+     *
+     * // 示例5：无额外效果
+     * conditionalEffects: (state) => {
+     *   // 某些条件下不产生额外效果
+     *   if (state.flags.immune) {
+     *     return null; // 或 undefined
+     *   }
+     *
+     *   return {
+     *     statsChange: { health: -10 }
+     *   };
+     * }
+     *
+     * // 示例6：与静态效果结合
+     * // 静态效果总是执行，条件效果叠加
+     * {
+     *   statsChange: { action_points: -1 }, // 总是消耗行动点
+     *   conditionalEffects: (state) => {
+     *     // 根据条件添加额外效果
+     *     if (state.world.time === 0) {
+     *       return {
+     *         statsChange: { sanity: -5 },
+     *         flagsSet: { midnight_action: true }
+     *       };
+     *     }
+     *     return null;
+     *   }
+     * }
+     * ```
+     */
+    conditionalEffects?: (state: GameState<S, I, F, X>) => Omit<EffectDef<S, I, F, X>, 'conditionalEffects'> | null | undefined;
+    /**
+     * 完整自定义效果函数 - 用于修改完整游戏状态
+     *
+     * ⚠️ 高级功能：提供对完整游戏状态的访问和修改权限
+     *
+     * 当需要执行复杂的状态修改逻辑时使用，可以同时修改：
+     * - stats: 数值属性
+     * - inventory: 物品清单
+     * - flags: 布尔标记
+     * - world: 世界状态
+     * - extra: 扩展数据
+     *
+     * 注意事项：
+     * 1. 不要修改 logs 字段，日志应该通过 resultText 或单独的 addLog 调用添加
+     * 2. 使用 customFull 时，其他效果字段（statsChange、itemsAdd 等）仍会执行
+     * 3. customFull 在其他效果之后执行，可以覆盖或调整之前的修改
+     * 4. 函数接收的是状态的副本，可以直接修改，无需返回值
+     *
+     * @param draft - 完整游戏状态的可修改副本（不包含 logs）
+     * @param originalState - 执行效果前的原始状态（只读，用于参考）
+     *
+     * @example
+     * ```typescript
+     * // 示例1：复杂的条件逻辑
+     * customFull: (draft, original) => {
+     *   // 根据理智值调整多个状态
+     *   if (draft.stats.sanity < 30) {
+     *     draft.stats.sanity -= 10;
+     *     draft.flags.going_insane = true;
+     *     draft.inventory.push('hallucination' as any);
+     *     draft.extra.mentalState = 'critical';
+     *   }
+     * }
+     *
+     * // 示例2：基于时间的复杂效果
+     * customFull: (draft) => {
+     *   const day = draft.world.day;
+     *
+     *   // 每7天触发特殊事件
+     *   if (day % 7 === 0) {
+     *     draft.stats.sanity -= 5;
+     *     draft.flags[`week_${Math.floor(day / 7)}_event`] = true;
+     *   }
+     *
+     *   // 根据物品数量调整属性
+     *   const itemCount = draft.inventory.length;
+     *   if (itemCount > 10) {
+     *     draft.stats.burden = itemCount - 10;
+     *   }
+     * }
+     *
+     * // 示例3：连锁反应
+     * customFull: (draft, original) => {
+     *   // 如果获得了特殊物品，触发连锁效果
+     *   if (draft.inventory.includes('cursed_artifact' as any)) {
+     *     draft.stats.sanity -= 20;
+     *     draft.stats.power += 50;
+     *     draft.flags.cursed = true;
+     *     draft.extra.curseLevel = (draft.extra.curseLevel || 0) + 1;
+     *
+     *     // 移除其他物品
+     *     draft.inventory = draft.inventory.filter(
+     *       item => item !== 'holy_water'
+     *     );
+     *   }
+     * }
+     *
+     * // 示例4：动态计算和状态同步
+     * customFull: (draft) => {
+     *   // 计算总战斗力
+     *   const weaponCount = draft.inventory.filter(
+     *     i => i.toString().includes('weapon')
+     *   ).length;
+     *   draft.extra.combatPower = draft.stats.strength * (1 + weaponCount * 0.1);
+     *
+     *   // 同步标记状态
+     *   draft.flags.well_equipped = weaponCount >= 3;
+     *   draft.flags.unarmed = weaponCount === 0;
+     * }
+     * ```
+     */
+    customFull?: (draft: Omit<GameState<S, I, F, X>, 'logs'>, originalState: GameState<S, I, F, X>) => void;
+}
+/**
+ * 动作定义接口 - 定义玩家可以执行的动作
+ *
+ * 动作是游戏交互的核心，包含了动作的显示信息、执行条件、
+ * 消耗成本和产生的效果。
+ *
+ * @template S - 数值属性键的联合类型
+ * @template I - 物品ID的联合类型
+ * @template F - 标记键的联合类型
+ *
+ * @example
+ * ```typescript
+ * const attackAction: ActionDef<Stats, Items, Flags> = {
+ *   id: 'attack_goblin',
+ *   label: '攻击哥布林',
+ *   description: '用你的武器攻击哥布林',
+ *   costs: { stamina: 10 },       // 消耗10点体力
+ *   requirements: {
+ *     hasItems: ['weapon']         // 需要武器
+ *   },
+ *   effects: {
+ *     statsChange: { exp: 5 },     // 获得5点经验
+ *     flagsSet: { goblin_defeated: true }
+ *   },
+ *   resultText: '你击败了哥布林！'
+ * };
+ * ```
+ */
+interface ActionDef<S extends string, I extends string, F extends string, X = Record<string, unknown>> {
+    /** 动作的唯一标识符 */
+    id: string;
+    /**
+     * 动作标签 - 显示在UI上的动作名称
+     * 可以是静态字符串或根据游戏状态动态生成的函数
+     */
+    label: string | ((state: GameState<S, I, F>) => string);
+    /**
+     * 动作描述 - 详细说明动作的效果
+     * 可选，可以是静态字符串或动态函数
+     */
+    description?: string | ((state: GameState<S, I, F>) => string);
+    /**
+     * 执行成本 - 执行动作时刚性扣除的资源
+     *
+     * 与requirements不同，costs会实际消耗资源。
+     * 例如: { stamina: 10, gold: 5 } 会扣除10点体力和5金币
+     */
+    costs?: Partial<Record<S, number>>;
+    /**
+     * 执行需求 - 执行动作前必须满足的条件
+     *
+     * 需求检查不会消耗资源，只是判断是否有资格执行。
+     * 如果不满足需求，动作将无法执行。
+     */
+    requirements?: RequirementDef<S, I, F, X>;
+    /**
+     * 执行效果 - 动作成功执行后产生的效果
+     *
+     * 包括属性变化、物品获得/失去、标记设置等。
+     * 所有效果会在扣除costs后立即应用。
+     */
+    effects?: EffectDef<S, I, F, X>;
+    /**
+     * 后置效果钩子 - 在所有效果执行完成后调用
+     *
+     * ⚠️ 职责分离：用于执行副作用逻辑，不应返回值
+     *
+     * 这个钩子在以下所有效果执行完成后调用：
+     * 1. 静态效果（statsChange、itemsAdd 等）
+     * 2. conditionalEffects
+     * 3. custom（修改 extra）
+     * 4. customFull（修改完整状态）
+     *
+     * 执行时机：在 resultText 之前执行
+     *
+     * 使用场景：
+     * - 基于最终状态设置额外标记
+     * - 触发连锁反应
+     * - 执行清理逻辑
+     * - 发送自定义事件
+     * - 调用外部 API
+     *
+     * 注意事项：
+     * 1. 这是最后的修改机会，之后只会生成 resultText
+     * 2. 可以访问所有之前效果修改后的最终状态
+     * 3. 不应返回值，所有修改通过 store 方法进行
+     * 4. 避免在这里执行耗时操作，会阻塞 UI
+     *
+     * @param state - 当前游戏状态（所有效果执行后的最终状态）
+     * @param originalState - 动作执行前的原始状态（只读，用于对比）
+     * @param actions - Store 操作方法集合（用于修改状态）
+     *
+     * @example
+     * ```typescript
+     * // 示例1：基于最终状态设置标记
+     * afterEffects: (state, original, actions) => {
+     *   // 检查是否达成成就
+     *   if (state.stats.knowledge >= 100 && !state.flags.scholar_achievement) {
+     *     actions.setFlag('scholar_achievement', true);
+     *     actions.showToast('成就解锁：博学者', 'success');
+     *   }
+     * }
+     *
+     * // 示例2：连锁反应
+     * afterEffects: (state, original, actions) => {
+     *   // 如果理智值过低，触发疯狂事件
+     *   if (state.stats.sanity < 10) {
+     *     actions.setFlag('going_mad', true);
+     *     actions.addLog('你感觉自己正在失去理智...', 'warn');
+     *
+     *     // 随机移除一个物品（幻觉中丢失）
+     *     if (state.inventory.length > 0) {
+     *       const randomIndex = Math.floor(Math.random() * state.inventory.length);
+     *       const lostItem = state.inventory[randomIndex];
+     *       actions.removeItem(lostItem);
+     *       actions.showModal(`你在恍惚中失去了 ${lostItem}`, 'error');
+     *     }
+     *   }
+     * }
+     *
+     * // 示例3：时间推进和状态同步
+     * afterEffects: (state, original, actions) => {
+     *   // 某些动作会推进时间
+     *   const timePassed = state.world.day - original.world.day;
+     *
+     *   if (timePassed > 0) {
+     *     // 每天恢复一些理智
+     *     actions.setStats({ sanity: 5 * timePassed });
+     *
+     *     // 设置每日标记
+     *     for (let i = 0; i < timePassed; i++) {
+     *       const day = original.world.day + i + 1;
+     *       actions.setFlag(`day_${day}_passed` as F, true);
+     *     }
+     *   }
+     * }
+     *
+     * // 示例4：清理过期标记
+     * afterEffects: (state, original, actions) => {
+     *   const currentDay = state.world.day;
+     *
+     *   // 清理7天前的临时标记
+     *   for (let i = 1; i <= 7; i++) {
+     *     const oldDay = currentDay - 7;
+     *     if (oldDay > 0) {
+     *       actions.setFlag(`temp_event_day_${oldDay}` as F, false);
+     *     }
+     *   }
+     * }
+     *
+     * // 示例5：触发自定义事件（需要导入 gameEvents）
+     * afterEffects: (state, original, actions) => {
+     *   // 检查特殊组合条件
+     *   const hasAllArtifacts =
+     *     state.inventory.includes('artifact_1' as I) &&
+     *     state.inventory.includes('artifact_2' as I) &&
+     *     state.inventory.includes('artifact_3' as I);
+     *
+     *   if (hasAllArtifacts && !state.flags.ritual_available) {
+     *     actions.setFlag('ritual_available', true);
+     *     // 注意：需要在游戏代码中导入 gameEvents 和 EngineEvents
+     *     // gameEvents.emit(EngineEvents.CUSTOM, {
+     *     //   id: 'artifacts_collected',
+     *     //   data: { day: state.world.day }
+     *     // });
+     *   }
+     * }
+     *
+     * // 示例6：保存快照
+     * afterEffects: (state, original, actions) => {
+     *   // 在重要节点自动保存快照
+     *   if (state.flags.boss_defeated) {
+     *     actions.saveSnapshot();
+     *     actions.showToast('进度已自动保存', 'info');
+     *   }
+     * }
+     * ```
+     */
+    afterEffects?: (state: GameState<S, I, F, X>, originalState: GameState<S, I, F, X>, actions: GameStoreActions<S, I, F, X>) => void;
+    /**
+     * 结果文本 - 动作执行后显示给玩家的反馈信息
+     *
+     * ⚠️ 职责分离：只负责生成文本，不应执行副作用
+     *
+     * 可以是静态字符串或根据游戏状态动态生成的函数。
+     * 如果是函数，它会在所有效果（包括 afterEffects）执行完成后调用，
+     * 因此可以基于最终状态生成准确的反馈文本。
+     *
+     * 注意事项：
+     * 1. 不应在这里修改游戏状态（使用 afterEffects 代替）
+     * 2. 函数接收的是所有效果执行后的最终状态
+     * 3. 返回的文本会作为 'result' 类型的日志添加到游戏日志中
+     *
+     * @example
+     * ```typescript
+     * // 静态文本
+     * resultText: '你完成了探索'
+     *
+     * // 动态文本 - 基于最终状态
+     * resultText: (state) => {
+     *   const sanity = state.stats.sanity;
+     *   if (sanity < 20) {
+     *     return '你勉强完成了仪式，但代价是巨大的...';
+     *   } else if (sanity < 50) {
+     *     return '仪式完成了，你感到有些不安。';
+     *   } else {
+     *     return '仪式顺利完成！';
+     *   }
+     * }
+     *
+     * // 基于标记生成文本
+     * resultText: (state) => {
+     *   if (state.flags.scholar_achievement) {
+     *     return '你的知识达到了新的高度！【成就解锁：博学者】';
+     *   }
+     *   return '你学到了新的知识。';
+     * }
+     *
+     * // 基于多个状态生成复杂文本
+     * resultText: (state) => {
+     *   const parts: string[] = ['你凝视着星空'];
+     *
+     *   if (state.world.time === 0) {
+     *     parts.push('午夜的星空格外诡异');
+     *   }
+     *
+     *   if (state.stats.sanity < 30) {
+     *     parts.push('你看到了不该看到的东西');
+     *   }
+     *
+     *   if (state.flags.going_mad) {
+     *     parts.push('理智正在崩溃...');
+     *   }
+     *
+     *   return parts.join('，') + '。';
+     * }
+     * ```
+     */
+    resultText: string | ((state: GameState<S, I, F, X>) => string);
+}
+/**
+ * 地点定义接口 - 定义游戏中的一个地点/场景
+ *
+ * 地点是游戏世界的基本单位，包含地点信息和可执行的动作列表。
+ * 玩家在不同地点之间移动，每个地点提供不同的动作选项。
+ *
+ * @template S - 数值属性键的联合类型
+ * @template I - 物品ID的联合类型
+ * @template F - 标记键的联合类型
+ * @template X - 扩展数据类型（默认为 Record<string, unknown>）
+ *
+ * @example
+ * ```typescript
+ * // 基础用法
+ * const tavern: LocationDef<Stats, Items, Flags> = {
+ *   id: 'tavern',
+ *   name: '酒馆',
+ *   description: '一个热闹的酒馆，充满了冒险者',
+ *   actionIds: ['buy_drink', 'talk_bartender', 'rest'],
+ *   extra: {}
+ * };
+ *
+ * // 使用自定义扩展数据
+ * interface LocationEnvironment {
+ *   temperature: number;
+ *   humidity: number;
+ *   lightLevel: number;
+ * }
+ *
+ * const cave: LocationDef<Stats, Items, Flags, LocationEnvironment> = {
+ *   id: 'cave',
+ *   name: '洞穴',
+ *   description: (state) => {
+ *     // 可以访问 state.extra
+ *     const temp = state.extra.temperature;
+ *     return temp < 0 ? '寒冷的洞穴' : '阴暗的洞穴';
+ *   },
+ *   actionIds: ['explore'],
+ *   extra: {
+ *     temperature: -5,
+ *     humidity: 80,
+ *     lightLevel: 2
+ *   }
+ * };
+ * ```
+ */
+interface LocationDef<S extends string, I extends string, F extends string, X = Record<string, unknown>> {
+    /** 地点的唯一标识符 */
+    id: string;
+    /** 地点名称 - 显示在UI上的地点名称 */
+    name: string;
+    /**
+     * 地点描述 - 描述地点的外观、氛围等
+     * 可以是静态字符串或根据游戏状态动态生成的函数
+     * 例如：根据时间显示不同的描述
+     */
+    description: string | ((state: GameState<S, I, F, X>) => string);
+    /**
+     * 该地点可执行的动作ID列表
+     *
+     * 存储动作ID而非完整的ActionDef对象，通过动作注册表查找实际定义。
+     * 这种设计提供了更好的解耦和灵活性：
+     * - 同一个动作可以在多个地点复用
+     * - 动作定义可以独立修改而不影响地点定义
+     * - 减少数据冗余和内存占用
+     *
+     * 使用时需要配合ActionRegistry来查找完整的动作定义。
+     */
+    actionIds: string[];
+    /**
+     * 扩展数据 - 存储地点特定的额外信息
+     *
+     * 这是一个灵活的字段，允许不同游戏为地点存储自定义元数据。
+     * 使用泛型 X 来定义具体的扩展数据类型。
+     *
+     * 常见用途：
+     * - 环境参数（温度、湿度、光照等）
+     * - 地点元数据（类别、发现时间、访问次数等）
+     * - 特殊属性（危险度、资源丰富度等）
+     * - 动态状态（天气、时间相关的变化等）
+     *
+     * @example
+     * ```typescript
+     * // 定义环境参数类型
+     * interface LocationEnvironment {
+     *   temperature: number;
+     *   humidity: number;
+     *   lightLevel: number;
+     *   danger: number;
+     * }
+     *
+     * // 使用扩展数据
+     * type MyLocation = LocationDef<Stats, Items, Flags, LocationEnvironment>;
+     *
+     * const location: MyLocation = {
+     *   id: 'forest',
+     *   name: '森林',
+     *   description: (state) => {
+     *     // 在 description 函数中访问扩展数据
+     *     if (state.extra.danger > 5) {
+     *       return '这片森林看起来很危险...';
+     *     }
+     *     return '一片宁静的森林';
+     *   },
+     *   actionIds: ['explore'],
+     *   extra: {
+     *     temperature: 20,
+     *     humidity: 60,
+     *     lightLevel: 8,
+     *     danger: 3
+     *   }
+     * };
+     * ```
+     */
+    extra: X;
+}
+
+export type { ActionDef as A, EffectDef as E, FlagsBatchOperation as F, GameStoreActions as G, LogEntry as L, NotificationType as N, RequirementCheckResult as R, StatRequirement as S, WorldState as W, GameState as a, NotificationPayload as b, RequirementDef as c, LocationDef as d };