steamsheep-ts-game-engine 2.0.0 → 3.1.0

package/README.md

@@ -1,1087 +1,552 @@
-# 游戏引擎框架使用指南
+# SteamSheep TypeScript Game Engine - 完整 API 参考
 
-## 📋 更新日志
+一个功能强大、类型安全的文字冒险/RPG 游戏引擎框架。
 
-### 最新更新 (2024)
+## 📚 目录
 
-#### ✨ 新增功能
-
-1. **事件系统 (Event System)**
-   - 新增 `EventBus` 类，实现发布-订阅模式
-   - 新增 `EngineEvents` 常量，预定义系统事件
-   - 支持类型安全的事件监听和发射
-   - 自动发射状态变更事件（属性、物品、标记等）
-
-2. **历史管理 (History Manager)**
-   - 新增 `HistoryManager` 类，支持撤销/重做
-   - Store 新增 `saveSnapshot()` 和 `undo()` 方法
-   - 支持最多保存 20 个历史快照
-   - 深拷贝状态，防止引用污染
-
-3. **覆盖层系统 (Overlay System)**
-   - 新增 `OverlaySystem` 组件，处理瞬时通知
-   - 支持飘字 (Toast) 和弹窗 (Modal)
-   - 完全分离持久化日志和瞬时通知
-   - 自动动画和样式
-
-4. **消息通知系统**
-   - Store 新增 `showToast()` 方法 - 显示飘字通知
-   - Store 新增 `showModal()` 方法 - 显示弹窗通知
-   - 新增 `NotificationPayload` 类型
-   - 新增 `NOTIFICATION` 事件
-
-#### 🔧 重要修改
-
-1. **架构优化 - 分离记录与通知**
-   - ⚠️ **重要**：`LogEntry` 现在仅用于持久化的历史记录
-   - 移除了 `LogEntry.display` 字段（之前的错误设计）
-   - 飘字和弹窗不再存入日志，避免持久化灾难
-   - 通过事件系统实现通知，不污染历史记录
-
-2. **Store 方法更新**
-   - `addLog()` - 移除 `display` 参数，仅用于添加历史记录
-   - 所有状态变更方法自动发射对应事件
-   - 新增历史管理相关方法
-
-3. **Flow 系统集成**
-   - 动作执行时自动发射 `ACTION_EXECUTED` 事件
-   - 支持 `effects.triggerEvent` 触发自定义事件
-   - 可选的自动快照功能（注释中）
-
-#### 📚 文档更新
-
-- 新增完整的中文注释
-- 新增架构说明和最佳实践
-- 新增事件系统使用指南
-- 新增消息通知系统说明
-- 更新完整示例代码
-
----
-
-## 目录
-
-- [更新日志](#-更新日志)
-- [概述](#概述)
-- [核心概念](#核心概念)
 - [快速开始](#快速开始)
-- [核心系统](#核心系统)
-  - [状态管理 (Store)](#状态管理-store)
-  - [事件系统 (Events)](#事件系统-events)
-  - [历史管理 (History)](#历史管理-history)
-  - [流程系统 (Flow)](#流程系统-flow)
-  - [查询系统 (Query)](#查询系统-query)
-- [消息通知系统](#消息通知系统)
+- [核心 API 列表](#核心-api-列表)
+- [详细用法](#详细用法)
 - [完整示例](#完整示例)
-- [最佳实践](#最佳实践)
 
 ---
 
-## 概述
-
-这是一个基于 TypeScript 和 Zustand 构建的通用游戏引擎框架，专为文字冒险、RPG 等回合制游戏设计。
-
-### 核心特性
-
-- ✅ **完全类型安全** - 使用 TypeScript 泛型实现类型安全
-- ✅ **状态持久化** - 自动保存到 localStorage
-- ✅ **事件驱动** - 解耦的事件系统
-- ✅ **撤销/重做** - 内置历史管理
-- ✅ **多级消息** - 支持日志/飘字/弹窗
-- ✅ **灵活扩展** - 易于扩展自定义功能
+## 🚀 快速开始
 
-### 架构图
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                      UI Layer                           │
-│  (React Components, Event Listeners)                    │
-└────────────────┬────────────────────────────────────────┘
-                 │
-┌────────────────▼────────────────────────────────────────┐
-│                   Engine Layer                          │
-│                                                         │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐               │
-│  │  Store   │  │  Events  │  │ History  │               │
-│  │ (Zustand)│◄─┤  (Bus)   │  │(Manager) │               │
-│  └────┬─────┘  └──────────┘  └──────────┘               │
-│       │                                                 │
-│  ┌────▼─────┐  ┌──────────┐  ┌──────────-┐              │
-│  │   Flow   │  │  Query   │  │ Messages  │              │
-│  │ (System) │  │ (System) │  │(Constants)│              │
-│  └──────────┘  └──────────┘  └──────────—┘              │
-└─────────────────────────────────────────────────────────┘
+```bash
+npm install steamsheep-ts-game-engine
 ```
 
----
-
-## 核心概念
-
-### 1. 游戏状态 (GameState)
-
-游戏状态包含所有游戏数据：
-
 ```typescript
-interface GameState<S, I, F, X> {
-  stats: Record<S, number>;      // 数值属性（生命值、金币等）
-  inventory: I[];                 // 物品清单
-  flags: Record<F, boolean>;      // 布尔标记（任务进度等）
-  world: WorldState;              // 世界状态（位置、时间）
-  logs: LogEntry[];               // 日志记录
-  extra: X;                       // 扩展数据
-}
-```
-
-### 2. 动作 (Action)
+import { createGameEngineStore } from 'steamsheep-ts-game-engine';
 
-动作是玩家可以执行的操作：
+// 定义游戏类型
+type Stats = 'hp' | 'mp' | 'gold';
+type Items = 'sword' | 'potion';
+type Flags = 'quest_done';
 
-```typescript
-interface ActionDef<S, I, F, X> {
-  id: string;                     // 唯一标识
-  label: string;                  // 显示名称
-  costs?: Partial<Record<S, number>>;      // 执行成本
-  requirements?: RequirementDef;  // 执行条件
-  effects?: EffectDef;            // 执行效果
-  resultText: string;             // 结果文本
-}
+// 创建 Store
+const useGameStore = createGameEngineStore(initialState, 'my-game');
 ```
 
-### 3. 事件 (Event)
-
-事件用于系统间通信，解耦组件：
+---
 
-```typescript
-// 发射事件
-gameEvents.emit(EngineEvents.STAT_CHANGE, { stat: 'hp', delta: -10 });
+## 📋 核心 API 列表
+
+### 1. 类型定义 (core/types.ts)
+
+#### 核心接口
+- `GameState<S, I, F, X>` - 游戏状态
+- `ActionDef<S, I, F, X>` - 动作定义
+- `EffectDef<S, I, F, X>` - 效果定义
+- `RequirementDef<S, I, F, X>` - 需求定义
+- `LocationDef<S, I, F, X>` - 地点定义
+- `RequirementCheckResult` - 需求检查结果
+- `FlagsBatchOperation<F>` - 批量标记操作
+- `GameStoreActions<S, I, F, X>` - Store 操作方法
+- `SnapshotInfo<S, I, F, X>` - 快照信息
+
+### 2. Store API (state/store.ts)
+
+#### 状态操作
+- `updateStat(stat, delta)` - 更新单个属性
+- `setStats(stats)` - 批量更新属性
+- `setExtra(updater)` - 更新扩展数据
+- `addItem(item)` - 添加物品
+- `removeItem(item)` - 移除物品
+- `setFlag(flag, value)` - 设置标记
+
+#### 系统操作
+- `addLog(text, type?)` - 添加日志（持久化）
+- `showToast(text, type?)` - 显示飘字（瞬时）
+- `showModal(text, type?)` - 显示弹窗（瞬时）
+- `advanceTime(amount?)` - 推进时间
+- `teleport(locationId)` - 传送
+- `reset()` - 重置游戏
+
+#### 快照操作
+- `saveSnapshot(description?)` - 保存匿名快照
+- `saveNamedSnapshot(name, description?)` - 保存命名快照
+- `undo()` - 撤销到上一个状态
+- `restoreSnapshot(name)` - 恢复到命名快照
+- `deleteSnapshot(name)` - 删除命名快照
+- `listSnapshots()` - 列出所有快照
+- `hasSnapshot(name)` - 检查快照是否存在
+
+### 3. 效果系统 (EffectDef)
+
+#### 静态效果
+- `statsChange` - 数值属性变更（支持函数）
+- `itemsAdd` - 添加物品
+- `itemsRemove` - 移除物品
+- `flagsSet` - 设置标记（支持函数）
+- `flagsBatch` - 批量标记操作（支持函数）
+- `teleport` - 传送
+- `timeAdvance` - 时间推进（支持函数）
+- `onTimeAdvance` - 时间推进钩子
+- `triggerEvent` - 触发自定义事件
+
+#### 动态效果
+- `conditionalEffects(state)` - 条件性效果
+- `custom(draft, state)` - 修改 extra 数据
+- `customFull(draft, originalState)` - 修改完整状态
+
+#### 后置钩子
+- `afterEffects(state, originalState, actions)` - 后置效果钩子
+
+### 4. 需求系统 (RequirementDef)
+
+- `stats` - 数值属性需求
+- `hasItems` - 必须拥有的物品
+- `noItems` - 不能拥有的物品
+- `hasFlags` - 必须为 true 的标记
+- `noFlags` - 必须为 false 的标记
+- `custom(state)` - 自定义需求（支持返回失败原因）
+
+### 5. 查询系统 (systems/query.ts)
+
+- `QuerySystem.checkRequirements(state, reqs)` - 检查需求（boolean）
+- `QuerySystem.checkRequirementsWithReason(state, reqs)` - 检查需求（带原因）
+- `QuerySystem.canAfford(state, costs)` - 检查成本
+
+### 6. 流程系统 (systems/flow.ts)
+
+- `FlowSystem.executeAction(store, action)` - 执行动作
+
+### 7. 事件系统 (systems/events.ts)
+
+- `gameEvents.on(event, handler)` - 监听事件
+- `gameEvents.emit(event, data)` - 发射事件
+- `gameEvents.off(event, handler)` - 取消监听
 
-// 监听事件
-gameEvents.on(EngineEvents.STAT_CHANGE, (data) => {
-  console.log(`${data.stat} 变化了 ${data.delta}`);
-});
-```
+#### 预定义事件
+- `EngineEvents.STAT_CHANGE` - 属性变化
+- `EngineEvents.ITEM_ADD` - 物品添加
+- `EngineEvents.ITEM_REMOVE` - 物品移除
+- `EngineEvents.FLAG_CHANGE` - 标记变化
+- `EngineEvents.ACTION_EXECUTED` - 动作执行
+- `EngineEvents.NOTIFICATION` - 通知
+- `EngineEvents.CUSTOM` - 自定义事件
+
+### 8. 历史管理 (state/history.ts)
+
+- `history.push(state, description?)` - 保存匿名快照
+- `history.pushNamed(state, name, description?)` - 保存命名快照
+- `history.pop()` - 撤销
+- `history.restoreNamed(name)` - 恢复命名快照
+- `history.deleteNamed(name)` - 删除命名快照
+- `history.hasNamed(name)` - 检查快照是否存在
+- `history.listSnapshots()` - 列出所有快照
+- `history.listNamedSnapshots()` - 列出命名快照
+- `history.peek()` - 查看最近快照
+- `history.clear(includeNamed?)` - 清空快照
+- `history.size` - 匿名快照数量
+- `history.namedSize` - 命名快照数量
+- `history.totalSize` - 总快照数量
 
 ---
 
-## 快速开始
+## 📖 详细用法
 
-### 步骤 1: 定义游戏类型
+### 1. 动态 Flag 支持
 
 ```typescript
-// src/game/types.ts
-
-// 定义你的游戏属性
-type Stats = 'hp' | 'mp' | 'gold' | 'exp';
-
-// 定义你的物品
-type Items = 'sword' | 'potion' | 'key';
-
-// 定义你的标记
-type Flags = 'quest_completed' | 'door_unlocked';
-
-// 定义扩展数据（可选）
-interface ExtraData {
-  reputation: number;
-  guild: string;
+effects: {
+  // 动态生成 flag 名称
+  flagsSet: (state) => {
+    const day = state.world.day;
+    return {
+      [`event_day_${day}`]: true,
+      [`gazed_stars_day_${day}`]: true
+    };
+  }
 }
 ```
 
-### 步骤 2: 创建初始状态
+### 2. 完整状态访问 (customFull)
 
 ```typescript
-// src/game/config/init.ts
-import type { GameState } from 'steamsheep-ts-game-engine/core';
-
-export const initialState: GameState<Stats, Items, Flags, ExtraData> = {
-  stats: {
-    hp: 100,
-    mp: 50,
-    gold: 0,
-    exp: 0,
-  },
-  inventory: [],
-  flags: {
-    quest_completed: false,
-    door_unlocked: false,
-  },
-  world: {
-    currentLocationId: 'town',
-    day: 1,
-    time: 0,
-  },
-  logs: [],
-  extra: {
-    reputation: 0,
-    guild: 'none',
-  },
-};
+effects: {
+  customFull: (draft, original) => {
+    // 可以修改所有状态
+    draft.stats.sanity -= 10;
+    draft.flags.some_flag = true;
+    draft.inventory.push('new_item');
+    draft.extra.customData = 'value';
+  }
+}
 ```
 
-### 步骤 3: 创建 Store
+### 3. 条件性效果
 
 ```typescript
-// src/game/store.ts
-import { createGameEngineStore } from 'steamsheep-ts-game-engine/state';
-import { initialState } from './config/init';
-
-export const useGameStore = createGameEngineStore(
-  initialState,
-  'my-game-save' // localStorage 键名
-);
-
-export type GameStore = ReturnType<typeof useGameStore>;
+effects: {
+  conditionalEffects: (state) => {
+    if (state.flags.some_condition) {
+      return {
+        statsChange: { sanity: -10 },
+        flagsSet: { flag_a: true }
+      };
+    } else {
+      return {
+        statsChange: { sanity: -5 },
+        flagsSet: { flag_b: true }
+      };
+    }
+  }
+}
 ```
 
-### 步骤 4: 定义动作
+### 4. 职责分离 (afterEffects + resultText 双参数)
 
 ```typescript
-// src/game/content/actions.ts
-import type { ActionDef } from 'steamsheep-ts-game-engine/core';
-
-export const attackAction: ActionDef<Stats, Items, Flags, ExtraData> = {
-  id: 'attack_goblin',
-  label: '攻击哥布林',
-  description: '用你的武器攻击哥布林',
-  
-  // 执行成本
-  costs: {
-    mp: 10,
-  },
-  
-  // 执行条件
-  requirements: {
-    hasItems: ['sword'],
-    stats: {
-      hp: { min: 20 }, // 至少需要 20 点生命值
-    },
-  },
-  
-  // 执行效果
+{
   effects: {
-    statsChange: {
-      exp: 10,
-      gold: 5,
-    },
-    flagsSet: {
-      quest_completed: true,
-    },
-    triggerEvent: 'goblin_defeated', // 触发自定义事件
+    statsChange: { sanity: -10 }
   },
   
-  resultText: '你击败了哥布林！获得 10 经验和 5 金币。',
-};
-```
-
-### 步骤 5: 在 UI 中使用
-
-```typescript
-// src/components/GameUI.tsx
-import { useGameStore } from '@/game/store';
-import { FlowSystem } from 'steamsheep-ts-game-engine/systems';
-import { QuerySystem } from 'steamsheep-ts-game-engine/systems';
-import { attackAction } from '@/game/content/actions';
-
-function GameUI() {
-  const hp = useGameStore((state) => state.stats.hp);
-  const gold = useGameStore((state) => state.stats.gold);
-  const inventory = useGameStore((state) => state.inventory);
-  
-  const handleAttack = () => {
-    const store = useGameStore.getState();
-    
-    // 检查是否可以执行
-    const canExecute = QuerySystem.canExecuteAction(store, attackAction);
-    
-    if (canExecute) {
-      // 执行动作
-      FlowSystem.executeAction(store, attackAction);
-    } else {
-      store.showToast('无法执行该动作', 'warn');
+  // 副作用在这里执行
+  afterEffects: (state, original, actions) => {
+    if (state.stats.sanity < 20) {
+      actions.setFlag('going_mad', true);
+      actions.showToast('理智危险！', 'warn');
     }
-  };
+  },
   
-  return (
-    <div>
-      <div>生命值: {hp}</div>
-      <div>金币: {gold}</div>
-      <div>背包: {inventory.join(', ')}</div>
-      <button onClick={handleAttack}>攻击哥布林</button>
-    </div>
-  );
+  // 文本生成 - 可以比较前后状态
+  resultText: (state, original) => {
+    const sanityLoss = original.stats.sanity - state.stats.sanity;
+    return sanityLoss > 15
+      ? `你失去了 ${sanityLoss} 点理智，感到崩溃...`
+      : '仪式完成了。';
+  }
 }
 ```
 
----
-
-## 核心系统
-
-### 状态管理 (Store)
-
-Store 是游戏状态的中心，提供所有状态操作方法。
-
-#### 基本操作
+### 5. 动态 StatsChange
 
 ```typescript
-const store = useGameStore.getState();
-
-// 更新属性
-store.updateStat('hp', -10);  // 减少 10 点生命值
-store.updateStat('gold', 50);  // 增加 50 金币
-
-// 批量更新
-store.setStats({ hp: 10, mp: -5, gold: 100 });
-
-// 物品操作
-store.addItem('potion');
-store.removeItem('potion');
-
-// 标记操作
-store.setFlag('quest_completed', true);
-
-// 日志操作
-store.addLog('你进入了森林', 'info');
-
-// 时间操作
-store.advanceTime(1); // 推进 1 天
-
-// 传送
-store.teleport('dungeon');
-
-// 重置游戏
-store.reset();
-```
-
-#### 扩展数据操作
-
-```typescript
-// 直接更新
-store.setExtra({ reputation: 100 });
-
-// 基于当前值更新
-store.setExtra((prev) => ({
-  reputation: prev.reputation + 10,
-}));
+effects: {
+  statsChange: (state) => {
+    const maxAP = state.stats.max_action_point || 4;
+    return {
+      action_point: maxAP - state.stats.action_point
+    };
+  }
+}
 ```
 
-#### 历史记录操作
+### 6. 批量 Flag 操作
 
 ```typescript
-// 保存快照
-store.saveSnapshot();
-
-// 撤销到上一个状态
-const success = store.undo();
-if (success) {
-  console.log('撤销成功');
+effects: {
+  // 清除所有 daily_ 开头的 flags
+  flagsBatch: {
+    clear: /^daily_/,
+    set: { new_day: true }
+  }
 }
-```
 
----
-
-### 事件系统 (Events)
-
-事件系统用于解耦组件，实现发布-订阅模式。
-
-#### 预定义事件
-
-```typescript
-export const 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',          // 时间推进
-  MESSAGE: 'engine:message',              // 消息通知
-  CUSTOM: 'engine:custom_trigger',        // 自定义事件
-};
+// 或使用函数
+effects: {
+  flagsBatch: (state) => ({
+    clear: Object.keys(state.flags).filter(k => k.startsWith('daily_')),
+    set: { new_day: true }
+  })
+}
 ```
 
-#### 监听事件
+### 7. 时间推进副作用
 
 ```typescript
-import { gameEvents, EngineEvents } from 'steamsheep-ts-game-engine/systems';
-
-// 监听属性变化
-const unsubscribe = gameEvents.on(EngineEvents.STAT_CHANGE, (data) => {
-  console.log(`${data.stat} 变化了 ${data.delta}，当前值: ${data.current}`);
+effects: {
+  timeAdvance: 1,
   
-  // 生命值过低警告
-  if (data.stat === 'hp' && data.current < 20) {
-    playSound('warning');
+  onTimeAdvance: (currentDay, previousDay, state, actions) => {
+    // 恢复每日资源
+    const maxAP = state.stats.max_action_point || 4;
+    actions.setStats({ 
+      action_point: maxAP 
+    });
+    
+    // 清除每日标记
+    Object.keys(state.flags)
+      .filter(f => f.startsWith('daily_'))
+      .forEach(f => actions.setFlag(f as F, false));
   }
-});
-
-// 取消监听
-unsubscribe();
+}
 ```
 
-#### 自定义事件
+### 8. 灵活的 Requirements
 
 ```typescript
-// 在动作中触发
-const action: ActionDef = {
-  id: 'open_chest',
-  effects: {
-    triggerEvent: 'chest_opened',
-  },
-  // ...
-};
-
-// 监听自定义事件
-gameEvents.on(EngineEvents.CUSTOM, (data) => {
-  if (data.id === 'chest_opened') {
-    playSound('treasure');
-    showAnimation('sparkle');
+requirements: {
+  custom: (state) => {
+    if (!state.inventory.includes('key')) {
+      return { 
+        passed: false, 
+        reason: "需要钥匙才能打开" 
+      };
+    }
+    
+    if (state.stats.sanity < 20) {
+      return { 
+        passed: false, 
+        reason: "理智太低，无法集中精神" 
+      };
+    }
+    
+    return { passed: true };
   }
-});
-```
-
----
-
-### 历史管理 (History)
-
-历史管理器提供撤销/重做功能。
-
-#### 基本用法
-
-```typescript
-// 在重要操作前保存快照
-store.saveSnapshot();
-
-// 执行操作
-store.updateStat('hp', -50);
-store.addItem('cursed_item');
-
-// 撤销操作
-if (store.undo()) {
-  console.log('已撤销');
 }
 ```
 
-#### 自动快照
-
-可以在 `flow.ts` 中启用自动快照：
+### 9. 效果执行顺序
 
 ```typescript
-// src/engine/systems/flow.ts
-static executeAction(...) {
-  // 取消注释以启用自动快照
-  store.saveSnapshot();
+effects: {
+  // 【阶段 1：静态效果】按以下顺序执行
+  statsChange: { sanity: -10 },        // 1
+  itemsAdd: ['item'],                  // 2
+  itemsRemove: ['old_item'],           // 3
+  flagsSet: { flag: true },            // 4
+  flagsBatch: { clear: /^temp_/ },     // 5
+  teleport: 'new_location',            // 6
+  timeAdvance: 1,                      // 7
+  onTimeAdvance: (day) => {},          // 7.1
+  triggerEvent: 'custom_event',        // 8
+  
+  // 【阶段 2：条件效果】
+  conditionalEffects: (state) => {     // 9
+    // 基于阶段1后的状态
+  },
   
-  // ... 执行动作
+  // 【阶段 3：自定义效果】
+  custom: (draft, state) => {},        // 10
+  customFull: (draft, original) => {}, // 11
 }
-```
-
----
-
-### 流程系统 (Flow)
-
-流程系统负责执行动作的完整流程。
 
-#### 执行流程
+// 【阶段 4：后置钩子】
+afterEffects: (state, original, actions) => {}, // 12
 
-1. **验证条件** - 检查需求和成本
-2. **扣除成本** - 消耗资源
-3. **应用效果** - 修改游戏状态
-4. **记录日志** - 反馈给玩家
-5. **发射事件** - 通知其他系统
-
-#### 使用方法
-
-```typescript
-import { FlowSystem } from 'steamsheep-ts-game-engine/systems';
-
-const success = FlowSystem.executeAction(store, action);
-
-if (success) {
-  console.log('动作执行成功');
-} else {
-  console.log('动作执行失败');
-}
+// 【阶段 5：结果文本】
+resultText: (state) => {}  // 13
 ```
 
----
-
-### 查询系统 (Query)
-
-查询系统提供各种状态查询方法。
-
-#### 常用查询
+### 10. 命名快照系统
 
 ```typescript
-import { QuerySystem } from 'steamsheep-ts-game-engine/systems';
-
-// 检查是否有物品
-const hasKey = QuerySystem.hasItem(state, 'key');
+// 保存命名快照
+store.saveNamedSnapshot('before_boss_fight', '挑战Boss前');
 
-// 检查是否有足够的资源
-const canAfford = QuerySystem.canAfford(state, { gold: 100 });
+// 恢复到指定快照
+if (store.restoreSnapshot('before_boss_fight')) {
+  console.log('已恢复到Boss战前');
+}
 
-// 检查需求
-const meetsRequirements = QuerySystem.checkRequirements(state, {
-  hasItems: ['sword'],
-  stats: { hp: { min: 20 } },
+// 查看所有快照
+const snapshots = store.listSnapshots();
+snapshots.forEach(snap => {
+  console.log(`${snap.name || '匿名'}: ${snap.description}`);
+  console.log(`时间: ${new Date(snap.timestamp).toLocaleString()}`);
 });
 
-// 检查是否可以执行动作
-const canExecute = QuerySystem.canExecuteAction(state, action);
-
-// 获取可用动作列表
-const availableActions = QuerySystem.getAvailableActions(state, allActions);
-```
-
----
-
-## 消息通知系统
-
-### ⚠️ 重要架构说明
-
-框架严格区分 **持久化记录** 和 **瞬时通知**：
-
-| 类型 | 持久化 | 刷新后 | 撤销后 | 用途 |
-|------|--------|--------|--------|------|
-| **Logs (日志)** | ✅ 是 | ✅ 重新加载 | ✅ 保留 | 历史记录，可回顾 |
-| **Toasts (飘字)** | ❌ 否 | ❌ 消失 | ❌ 消失 | 轻量级反馈 |
-| **Modals (弹窗)** | ❌ 否 | ❌ 消失 | ❌ 消失 | 重要信息，阻塞式 |
-
-### 为什么要分离？
-
-**错误的做法**（将弹窗存入日志）：
-```typescript
-// ❌ 错误：弹窗会被持久化
-store.addLog('打开宝箱', 'info', 'modal');
-
-// Bug 1: 页面刷新后，弹窗再次出现！
-// Bug 2: 撤销操作后，弹窗记录还在，逻辑混乱！
-```
-
-**正确的做法**（分离记录和通知）：
-```typescript
-// ✅ 正确：日志用于记录
-store.addLog('你打开了宝箱', 'result');
-
-// ✅ 正确：弹窗用于通知（不持久化）
-store.showModal('获得传说武器！', 'success');
-```
-
-### 1. 日志 (Logs)
-
-**持久化的历史记录**，会被保存到 localStorage：
-
-```typescript
-// 记录游戏事件
-store.addLog('你进入了森林', 'info');
-store.addLog('击败了哥布林', 'result');
-store.addLog('获得了传说武器', 'success');
-
-// 这些日志会：
-// - 保存到 localStorage
-// - 页面刷新后重新加载
-// - 永久显示在日志面板
-// - 可以被玩家回顾
-```
-
-### 2. 飘字 (Toasts)
-
-**瞬时通知**，不会被持久化：
+// 检查快照是否存在
+if (store.hasSnapshot('before_boss_fight')) {
+  // 可以恢复
+}
 
-```typescript
-// 轻量级反馈
-store.showToast('获得 10 经验值', 'success');
-store.showToast('体力不足', 'warn');
-
-// 飘字会：
-// - 显示 3 秒后自动消失
-// - 不保存到 localStorage
-// - 页面刷新后不会重新出现
-// - 不阻塞用户操作
+// 删除快照
+store.deleteSnapshot('before_boss_fight');
 ```
 
-### 3. 弹窗 (Modals)
-
-**瞬时通知**，不会被持久化：
+### 11. ResultText 比较前后状态
 
 ```typescript
-// 重要信息
-store.showModal('恭喜！你升级了！', 'success');
-store.showModal('警告：此操作不可撤销', 'warn');
-
-// 弹窗会：
-// - 需要用户点击确认
-// - 不保存到 localStorage
-// - 页面刷新后不会重新出现
-// - 阻塞用户操作
-```
-
-### UI 层实现
+// 简化前：需要通过 afterEffects + extra 传递信息
+{
+  effects: {
+    conditionalEffects: () => {
+      if (Math.random() < 0.15) {
+        return { statsChange: { gnosis: 1 } };
+      }
+      return null;
+    }
+  },
+  afterEffects: (state, original, actions) => {
+    const gainedGnosis = state.stats.gnosis > original.stats.gnosis;
+    actions.setExtra({ lastMeditateGainedGnosis: gainedGnosis });
+  },
+  resultText: (state) => {
+    return state.extra.lastMeditateGainedGnosis
+      ? "获得了灵知！"
+      : "平静地冥想。";
+  }
+}
 
-使用 `OverlaySystem` 组件处理瞬时通知：
+// 简化后：直接比较前后状态
+{
+  effects: {
+    conditionalEffects: () => {
+      if (Math.random() < 0.15) {
+        return { statsChange: { gnosis: 1 } };
+      }
+      return null;
+    }
+  },
+  resultText: (state, original) => {
+    const gainedGnosis = state.stats.gnosis > original.stats.gnosis;
+    return gainedGnosis
+      ? "获得了灵知！"
+      : "平静地冥想。";
+  }
+}
 
-```typescript
-// src/App.tsx
-import { OverlaySystem } from 'steamsheep-ts-game-engine/ui';
-import { LogStream } from 'steamsheep-ts-game-engine/ui';
-
-function App() {
-  return (
-    <div className="app">
-      {/* 日志面板（持久化） */}
-      <LogStream />
-      
-      {/* 覆盖层系统（瞬时通知） */}
-      <OverlaySystem />
-      
-      {/* 游戏内容 */}
-      <GameContent />
-    </div>
-  );
+// 显示具体变化量
+resultText: (state, original) => {
+  const hpChange = state.stats.hp - original.stats.hp;
+  const goldChange = state.stats.gold - original.stats.gold;
+  
+  const parts = [];
+  if (hpChange < 0) parts.push(`失去 ${-hpChange} HP`);
+  if (goldChange > 0) parts.push(`获得 ${goldChange} 金币`);
+  
+  return parts.join('，') || '什么都没发生。';
 }
 ```
 
-`OverlaySystem` 会自动监听 `NOTIFICATION` 事件并显示对应的 UI。
-
 ---
 
-## 完整示例
-
-### 创建一个简单的 RPG 游戏
+## 🎮 完整示例
 
 ```typescript
-// 1. 定义类型
-type Stats = 'hp' | 'mp' | 'gold' | 'exp' | 'level';
-type Items = 'sword' | 'potion' | 'key';
-type Flags = 'tutorial_done' | 'boss_defeated';
-
-// 2. 创建初始状态
-const initialState: GameState<Stats, Items, Flags> = {
-  stats: { hp: 100, mp: 50, gold: 0, exp: 0, level: 1 },
-  inventory: ['potion'],
-  flags: { tutorial_done: false, boss_defeated: false },
-  world: { currentLocationId: 'town', day: 1, time: 0 },
-  logs: [],
-  extra: {},
-};
-
-// 3. 创建 Store
-export const useGameStore = createGameEngineStore(initialState, 'rpg-save');
-
-// 4. 定义动作
-const buyPotionAction: ActionDef<Stats, Items, Flags> = {
-  id: 'buy_potion',
-  label: '购买药水',
-  costs: { gold: 10 },
-  effects: {
-    itemsAdd: ['potion'],
-  },
-  resultText: '你购买了一瓶药水。',
-};
-
-const usePotionAction: ActionDef<Stats, Items, Flags> = {
-  id: 'use_potion',
-  label: '使用药水',
-  requirements: {
-    hasItems: ['potion'],
-    stats: { hp: { max: 99 } }, // 生命值未满
-  },
-  effects: {
-    statsChange: { hp: 30 },
-    itemsRemove: ['potion'],
+// 克苏鲁风格的仪式动作
+const performRitualAction: ActionDef<Stats, Items, Flags, Extra> = {
+  id: 'perform_ritual',
+  label: '进行禁忌仪式',
+  
+  costs: { 
+    action_point: 2,
+    sanity: 5 
   },
-  resultText: (state) => `你使用了药水，恢复了 30 点生命值。当前生命值: ${state.stats.hp + 30}`,
-};
-
-const attackBossAction: ActionDef<Stats, Items, Flags> = {
-  id: 'attack_boss',
-  label: '挑战 Boss',
+  
   requirements: {
-    hasItems: ['sword'],
-    stats: {
-      level: { min: 5 },
-      hp: { min: 50 },
+    hasItems: ['ancient_book'],
+    stats: { 
+      knowledge: { min: 10 },
+      sanity: { min: 20 }
     },
+    custom: (state) => {
+      const time = state.world.time;
+      if (time < 18 && time > 6) {
+        return {
+          passed: false,
+          reason: '禁忌仪式只能在夜晚进行'
+        };
+      }
+      return { passed: true };
+    }
   },
-  costs: {
-    mp: 20,
-  },
+  
   effects: {
-    statsChange: { exp: 100, gold: 50 },
-    flagsSet: { boss_defeated: true },
-    triggerEvent: 'boss_victory',
-  },
-  resultText: '你击败了 Boss！获得大量奖励！',
-};
-
-// 5. 设置事件监听
-function setupGameEvents() {
-  // 升级检查
-  gameEvents.on(EngineEvents.STAT_CHANGE, (data) => {
-    if (data.stat === 'exp') {
-      const store = useGameStore.getState();
-      const expNeeded = store.stats.level * 100;
-      
-      if (store.stats.exp >= expNeeded) {
-        store.updateStat('level', 1);
-        store.updateStat('exp', -expNeeded);
-        store.updateStat('hp', 20);
-        store.updateStat('mp', 10);
-        store.showModal('恭喜升级！', 'success');
+    // 动态属性变更
+    statsChange: (state) => ({
+      knowledge: state.world.time === 0 ? 5 : 3,
+      sanity: state.world.time === 0 ? -15 : -10
+    }),
+    
+    // 动态标记
+    flagsSet: (state) => ({
+      [`ritual_day_${state.world.day}`]: true,
+      'has_performed_ritual': true
+    }),
+    
+    // 条件效果
+    conditionalEffects: (state) => {
+      if (state.stats.sanity < 30) {
+        return {
+          statsChange: { sanity: -5 },
+          flagsSet: { 'going_mad': true },
+          itemsAdd: ['cursed_artifact']
+        };
+      }
+      return null;
+    },
+    
+    // 修改扩展数据
+    custom: (draft) => {
+      draft.lastActionTime = Date.now();
+      draft.reputation += 5;
+    },
+    
+    // 完整状态修改
+    customFull: (draft, original) => {
+      if (original.inventory.includes('protective_charm')) {
+        const sanityLoss = original.stats.sanity - draft.stats.sanity;
+        draft.stats.sanity = original.stats.sanity - Math.floor(sanityLoss * 0.5);
+        draft.inventory = draft.inventory.filter(i => i !== 'protective_charm');
+        draft.flags.charm_used = true;
       }
     }
-  });
-
-  // Boss 胜利
-  gameEvents.on(EngineEvents.CUSTOM, (data) => {
-    if (data.id === 'boss_victory') {
-      playSound('victory');
-      showCutscene('ending');
+  },
+  
+  afterEffects: (state, original, actions) => {
+    if (state.stats.knowledge >= 100 && !state.flags.master_scholar) {
+      actions.setFlag('master_scholar', true);
+      actions.showModal('成就解锁：博学大师！', 'success');
     }
-  });
-}
-
-// 6. UI 组件
-function GameUI() {
-  const stats = useGameStore((state) => state.stats);
-  const inventory = useGameStore((state) => state.inventory);
-  const flags = useGameStore((state) => state.flags);
-
-  const handleAction = (action: ActionDef) => {
-    const store = useGameStore.getState();
-    const success = FlowSystem.executeAction(store, action);
     
-    if (!success) {
-      store.showToast('无法执行该动作', 'warn');
+    if (state.flags.midnight_ritual) {
+      actions.saveNamedSnapshot('after_midnight_ritual', '午夜仪式后');
     }
-  };
-
-  return (
-    <div className="game-ui">
-      {/* 状态栏 */}
-      <div className="stats">
-        <div>等级: {stats.level}</div>
-        <div>生命值: {stats.hp}/100</div>
-        <div>魔法值: {stats.mp}/50</div>
-        <div>金币: {stats.gold}</div>
-        <div>经验值: {stats.exp}</div>
-      </div>
-
-      {/* 背包 */}
-      <div className="inventory">
-        <h3>背包</h3>
-        {inventory.map((item, i) => (
-          <div key={i}>{item}</div>
-        ))}
-      </div>
-
-      {/* 动作按钮 */}
-      <div className="actions">
-        <button onClick={() => handleAction(buyPotionAction)}>
-          购买药水 (10 金币)
-        </button>
-        <button onClick={() => handleAction(usePotionAction)}>
-          使用药水
-        </button>
-        {flags.tutorial_done && (
-          <button onClick={() => handleAction(attackBossAction)}>
-            挑战 Boss
-          </button>
-        )}
-      </div>
-
-      {/* 撤销按钮 */}
-      <button onClick={() => useGameStore.getState().undo()}>
-        撤销上一步
-      </button>
-    </div>
-  );
-}
-```
-
----
-
-## 最佳实践
-
-### 1. 类型定义
-
-```typescript
-// ✅ 好的做法：使用字符串字面量联合类型
-type Stats = 'hp' | 'mp' | 'gold';
-
-// ❌ 避免：使用 string 类型
-type Stats = string;
-```
-
-### 2. 动作设计
-
-```typescript
-// ✅ 好的做法：清晰的动作定义
-const action: ActionDef = {
-  id: 'buy_sword',
-  label: '购买剑',
-  costs: { gold: 100 },
-  effects: { itemsAdd: ['sword'] },
-  resultText: '你购买了一把剑。',
-};
-
-// ❌ 避免：过于复杂的动作
-const action: ActionDef = {
-  id: 'complex_action',
-  // 太多效果，应该拆分成多个动作
-  effects: {
-    statsChange: { hp: 10, mp: -5, gold: -50, exp: 20 },
-    itemsAdd: ['item1', 'item2', 'item3'],
-    flagsSet: { flag1: true, flag2: false, flag3: true },
   },
-};
-```
-
-### 3. 需求检查
-
-```typescript
-// ✅ 好的做法：使用 QuerySystem
-if (QuerySystem.canExecuteAction(store, action)) {
-  FlowSystem.executeAction(store, action);
-}
-
-// ❌ 避免：手动检查
-if (store.stats.gold >= 100 && store.inventory.includes('key')) {
-  FlowSystem.executeAction(store, action);
-}
-```
-
-### 4. 事件监听
-
-```typescript
-// ✅ 好的做法：在组件卸载时取消监听
-useEffect(() => {
-  const unsubscribe = gameEvents.on(EngineEvents.STAT_CHANGE, handler);
-  return unsubscribe; // 清理
-}, []);
-
-// ❌ 避免：忘记取消监听（内存泄漏）
-useEffect(() => {
-  gameEvents.on(EngineEvents.STAT_CHANGE, handler);
-}, []);
-```
-
-### 5. 状态更新
-
-```typescript
-// ✅ 好的做法：使用 Store 提供的方法
-store.updateStat('hp', -10);
-
-// ❌ 避免：直接修改状态（不会触发更新）
-store.stats.hp -= 10;
-```
-
-### 6. 消息使用
-
-```typescript
-// ✅ 好的做法：根据重要性选择合适的展示方式
-store.addLog('你走进了房间', 'info');           // 普通信息
-store.showToast('获得 10 金币', 'success');      // 轻量提示
-store.showModal('任务完成！', 'success');        // 重要信息
-
-// ❌ 避免：所有消息都用弹窗（打扰用户）
-store.showModal('你走了一步', 'info');
-```
-
-### 7. 扩展数据
-
-```typescript
-// ✅ 好的做法：定义明确的扩展数据类型
-interface ExtraData {
-  reputation: number;
-  guild: string;
-  achievements: string[];
-}
-
-// ❌ 避免：使用 any 或过于宽泛的类型
-type ExtraData = any;
-```
-
----
-
-## 常见问题
-
-### Q: 如何添加新的属性类型？
-
-A: 在类型定义中添加新的字符串字面量：
-
-```typescript
-// 添加 'stamina' 属性
-type Stats = 'hp' | 'mp' | 'gold' | 'stamina';
-```
-
-### Q: 如何实现复杂的条件判断？
-
-A: 使用 `custom` 函数：
-
-```typescript
-requirements: {
-  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;
-  }
-}
-```
-
-### Q: 如何保存多个存档？
-
-A: 使用不同的 `persistName`：
-
-```typescript
-const slot1 = createGameEngineStore(initialState, 'save-slot-1');
-const slot2 = createGameEngineStore(initialState, 'save-slot-2');
-const slot3 = createGameEngineStore(initialState, 'save-slot-3');
-```
-
-### Q: 如何实现自动保存？
-
-A: 监听关键事件并保存快照：
-
-```typescript
-gameEvents.on(EngineEvents.ACTION_EXECUTED, () => {
-  useGameStore.getState().saveSnapshot();
-});
-```
-
----
-
-## 进阶主题
-
-### 自定义系统扩展
-
-你可以创建自己的系统来扩展引擎功能：
-
-```typescript
-// src/game/systems/achievement.ts
-export class AchievementSystem {
-  static checkAchievements(store: GameStore) {
-    // 检查成就解锁条件
-    if (store.stats.gold >= 1000 && !store.flags.rich_achievement) {
-      store.setFlag('rich_achievement', true);
-      store.showModal('成就解锁：富豪', 'success');
+  
+  resultText: (state) => {
+    const parts = [];
+    if (state.flags.midnight_ritual) {
+      parts.push('午夜时分，仪式达到了高潮');
     }
+    if (state.stats.sanity < 20) {
+      parts.push('你的理智岌岌可危');
+    }
+    if (state.flags.charm_used) {
+      parts.push('护符保护了你，但它已经碎裂了');
+    }
+    return parts.join('，') + '。';
   }
-}
-
-// 在事件监听中使用
-gameEvents.on(EngineEvents.STAT_CHANGE, (data) => {
-  if (data.stat === 'gold') {
-    AchievementSystem.checkAchievements(useGameStore.getState());
-  }
-});
-```
-
-### 动态内容加载
-
-```typescript
-// 从 JSON 文件加载动作
-import actionsData from './data/actions.json';
-
-const actions: ActionDef[] = actionsData.map(data => ({
-  ...data,
-  // 转换 JSON 数据为 ActionDef
-}));
+};
 ```
 
 ---
 
-## 总结
-
-这个游戏引擎框架提供了：
-
-- 🎯 **类型安全** - 完整的 TypeScript 支持
-- 🔄 **状态管理** - 基于 Zustand 的响应式状态
-- 📡 **事件系统** - 解耦的发布-订阅模式
-- ⏮️ **历史管理** - 撤销/重做功能
-- 💬 **消息系统** - 多级消息通知
-- 🎮 **流程控制** - 完整的动作执行流程
-- 🔍 **查询系统** - 便捷的状态查询
-
-通过这些系统的组合，你可以快速构建各种类型的文字冒险和 RPG 游戏！
-
----
-
-## 迁移指南
-
-### 从旧版本迁移
+## 📝 总结
 
-如果你之前使用了错误的 `addLog` 设计（带 `display` 参数），需要进行以下修改：
+本引擎提供了以下增强功能：
 
-#### ❌ 旧的错误做法
-
-```typescript
-// 错误：将弹窗存入日志（会导致持久化问题）
-store.addLog('打开宝箱', 'info', 'modal');
-store.addLog('获得金币', 'success', 'toast');
-```
-
-**问题**：
-- 页面刷新后，弹窗会再次出现
-- 撤销操作后，弹窗记录仍然存在
-- 日志面板会显示不应该显示的内容
-
-#### ✅ 新的正确做法
-
-```typescript
-// 正确：分离记录和通知
-
-// 1. 添加历史记录（持久化）
-store.addLog('你打开了宝箱', 'result');
-
-// 2. 显示瞬时通知（不持久化）
-store.showModal('获得传说武器！', 'success');
-store.showToast('获得 10 金币', 'success');
-```
+1. ✅ **动态 Flag 支持** - flagsSet 支持函数形式
+2. ✅ **完整状态访问** - customFull 可修改所有状态
+3. ✅ **条件性效果** - conditionalEffects 根据状态决定效果
+4. ✅ **职责分离** - afterEffects 和 resultText 分离副作用和文本
+5. ✅ **动态 StatsChange** - statsChange 支持函数形式
+6. ✅ **批量 Flag 操作** - flagsBatch 支持正则、前缀、列表
+7. ✅ **时间推进副作用** - onTimeAdvance 自动处理每日重置
+8. ✅ **灵活的 Requirements** - custom 可返回失败原因
+9. ✅ **明确的执行顺序** - 5 个阶段，清晰的文档说明
+10. ✅ **命名快照系统** - 支持保存和恢复命名快照
+11. ✅ **ResultText 双参数** - 可以比较前后状态，无需 extra 传递
 
-#### 需要修改的地方
-
-1. **移除 `addLog` 的第三个参数**
-   ```typescript
-   // 旧代码
-   store.addLog('消息', 'info', 'toast');
-   
-   // 新代码
-   store.addLog('消息', 'info');  // 仅用于历史记录
-   store.showToast('消息', 'info'); // 用于通知
-   ```
-
-2. **添加 `OverlaySystem` 组件**
-   ```typescript
-   // src/App.tsx
-   import { OverlaySystem } from 'steamsheep-ts-game-engine/ui';
-   
-   function App() {
-     return (
-       <>
-         <OverlaySystem /> {/* 新增：处理飘字和弹窗 */}
-         <GameContent />
-       </>
-     );
-   }
-   ```
-
-3. **更新类型定义**
-   - `LogEntry` 不再有 `display` 字段
-   - 使用 `NotificationPayload` 处理通知
-   - 监听 `NOTIFICATION` 事件而不是 `MESSAGE` 事件
+所有功能都是类型安全的，并且完全向后兼容！
 
 ---
 
-## 相关文档
+## 📚 更多文档
 
+- [完整功能示例](./examples/complete-features-example.ts)
+- [动态 Flag 示例](./examples/dynamic-flags-example.ts)
 - [核心类型定义](./core/types.ts)
 - [状态管理](./state/store.ts)
-- [事件系统](./systems/events.ts)
 - [历史管理](./state/history.ts)
-- [流程系统](./systems/flow.ts)
-- [查询系统](./systems/query.ts)
-- [覆盖层系统](./ui/OverlaySystem.tsx)
 
-## 许可证
+## 📄 许可证
 
 MIT