steamsheep-ts-game-engine 1.0.0

package/README.md

@@ -0,0 +1,1087 @@
+# 游戏引擎框架使用指南
+
+## 📋 更新日志
+
+### 最新更新 (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)
+- [消息通知系统](#消息通知系统)
+- [完整示例](#完整示例)
+- [最佳实践](#最佳实践)
+
+---
+
+## 概述
+
+这是一个基于 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)│              │
+│  └──────────┘  └──────────┘  └──────────—┘              │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 核心概念
+
+### 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)
+
+动作是玩家可以执行的操作：
+
+```typescript
+interface ActionDef<S, I, F, X> {
+  id: string;                     // 唯一标识
+  label: string;                  // 显示名称
+  costs?: Partial<Record<S, number>>;      // 执行成本
+  requirements?: RequirementDef;  // 执行条件
+  effects?: EffectDef;            // 执行效果
+  resultText: string;             // 结果文本
+}
+```
+
+### 3. 事件 (Event)
+
+事件用于系统间通信，解耦组件：
+
+```typescript
+// 发射事件
+gameEvents.emit(EngineEvents.STAT_CHANGE, { stat: 'hp', delta: -10 });
+
+// 监听事件
+gameEvents.on(EngineEvents.STAT_CHANGE, (data) => {
+  console.log(`${data.stat} 变化了 ${data.delta}`);
+});
+```
+
+---
+
+## 快速开始
+
+### 步骤 1: 定义游戏类型
+
+```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;
+}
+```
+
+### 步骤 2: 创建初始状态
+
+```typescript
+// src/game/config/init.ts
+import type { GameState } from '@/engine/core/types';
+
+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',
+  },
+};
+```
+
+### 步骤 3: 创建 Store
+
+```typescript
+// src/game/store.ts
+import { createGameEngineStore } from '@/engine/state/store';
+import { initialState } from './config/init';
+
+export const useGameStore = createGameEngineStore(
+  initialState,
+  'my-game-save' // localStorage 键名
+);
+
+export type GameStore = ReturnType<typeof useGameStore>;
+```
+
+### 步骤 4: 定义动作
+
+```typescript
+// src/game/content/actions.ts
+import type { ActionDef } from '@/engine/core/types';
+
+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', // 触发自定义事件
+  },
+  
+  resultText: '你击败了哥布林！获得 10 经验和 5 金币。',
+};
+```
+
+### 步骤 5: 在 UI 中使用
+
+```typescript
+// src/components/GameUI.tsx
+import { useGameStore } from '@/game/store';
+import { FlowSystem } from '@/engine/systems/flow';
+import { QuerySystem } from '@/engine/systems/query';
+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');
+    }
+  };
+  
+  return (
+    <div>
+      <div>生命值: {hp}</div>
+      <div>金币: {gold}</div>
+      <div>背包: {inventory.join(', ')}</div>
+      <button onClick={handleAttack}>攻击哥布林</button>
+    </div>
+  );
+}
+```
+
+---
+
+## 核心系统
+
+### 状态管理 (Store)
+
+Store 是游戏状态的中心，提供所有状态操作方法。
+
+#### 基本操作
+
+```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,
+}));
+```
+
+#### 历史记录操作
+
+```typescript
+// 保存快照
+store.saveSnapshot();
+
+// 撤销到上一个状态
+const success = store.undo();
+if (success) {
+  console.log('撤销成功');
+}
+```
+
+---
+
+### 事件系统 (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',        // 自定义事件
+};
+```
+
+#### 监听事件
+
+```typescript
+import { gameEvents, EngineEvents } from '@/engine/systems/events';
+
+// 监听属性变化
+const unsubscribe = gameEvents.on(EngineEvents.STAT_CHANGE, (data) => {
+  console.log(`${data.stat} 变化了 ${data.delta}，当前值: ${data.current}`);
+  
+  // 生命值过低警告
+  if (data.stat === 'hp' && data.current < 20) {
+    playSound('warning');
+  }
+});
+
+// 取消监听
+unsubscribe();
+```
+
+#### 自定义事件
+
+```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');
+  }
+});
+```
+
+---
+
+### 历史管理 (History)
+
+历史管理器提供撤销/重做功能。
+
+#### 基本用法
+
+```typescript
+// 在重要操作前保存快照
+store.saveSnapshot();
+
+// 执行操作
+store.updateStat('hp', -50);
+store.addItem('cursed_item');
+
+// 撤销操作
+if (store.undo()) {
+  console.log('已撤销');
+}
+```
+
+#### 自动快照
+
+可以在 `flow.ts` 中启用自动快照：
+
+```typescript
+// src/engine/systems/flow.ts
+static executeAction(...) {
+  // 取消注释以启用自动快照
+  store.saveSnapshot();
+  
+  // ... 执行动作
+}
+```
+
+---
+
+### 流程系统 (Flow)
+
+流程系统负责执行动作的完整流程。
+
+#### 执行流程
+
+1. **验证条件** - 检查需求和成本
+2. **扣除成本** - 消耗资源
+3. **应用效果** - 修改游戏状态
+4. **记录日志** - 反馈给玩家
+5. **发射事件** - 通知其他系统
+
+#### 使用方法
+
+```typescript
+import { FlowSystem } from '@/engine/systems/flow';
+
+const success = FlowSystem.executeAction(store, action);
+
+if (success) {
+  console.log('动作执行成功');
+} else {
+  console.log('动作执行失败');
+}
+```
+
+---
+
+### 查询系统 (Query)
+
+查询系统提供各种状态查询方法。
+
+#### 常用查询
+
+```typescript
+import { QuerySystem } from '@/engine/systems/query';
+
+// 检查是否有物品
+const hasKey = QuerySystem.hasItem(state, 'key');
+
+// 检查是否有足够的资源
+const canAfford = QuerySystem.canAfford(state, { gold: 100 });
+
+// 检查需求
+const meetsRequirements = QuerySystem.checkRequirements(state, {
+  hasItems: ['sword'],
+  stats: { hp: { min: 20 } },
+});
+
+// 检查是否可以执行动作
+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)
+
+**瞬时通知**，不会被持久化：
+
+```typescript
+// 轻量级反馈
+store.showToast('获得 10 经验值', 'success');
+store.showToast('体力不足', 'warn');
+
+// 飘字会：
+// - 显示 3 秒后自动消失
+// - 不保存到 localStorage
+// - 页面刷新后不会重新出现
+// - 不阻塞用户操作
+```
+
+### 3. 弹窗 (Modals)
+
+**瞬时通知**，不会被持久化：
+
+```typescript
+// 重要信息
+store.showModal('恭喜！你升级了！', 'success');
+store.showModal('警告：此操作不可撤销', 'warn');
+
+// 弹窗会：
+// - 需要用户点击确认
+// - 不保存到 localStorage
+// - 页面刷新后不会重新出现
+// - 阻塞用户操作
+```
+
+### UI 层实现
+
+使用 `OverlaySystem` 组件处理瞬时通知：
+
+```typescript
+// src/App.tsx
+import { OverlaySystem } from '@/engine/ui/OverlaySystem';
+import { LogStream } from '@/engine/ui/LogStream';
+
+function App() {
+  return (
+    <div className="app">
+      {/* 日志面板（持久化） */}
+      <LogStream />
+      
+      {/* 覆盖层系统（瞬时通知） */}
+      <OverlaySystem />
+      
+      {/* 游戏内容 */}
+      <GameContent />
+    </div>
+  );
+}
+```
+
+`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'],
+  },
+  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 },
+    },
+  },
+  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');
+      }
+    }
+  });
+
+  // Boss 胜利
+  gameEvents.on(EngineEvents.CUSTOM, (data) => {
+    if (data.id === 'boss_victory') {
+      playSound('victory');
+      showCutscene('ending');
+    }
+  });
+}
+
+// 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');
+    }
+  };
+
+  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');
+    }
+  }
+}
+
+// 在事件监听中使用
+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. **移除 `addLog` 的第三个参数**
+   ```typescript
+   // 旧代码
+   store.addLog('消息', 'info', 'toast');
+   
+   // 新代码
+   store.addLog('消息', 'info');  // 仅用于历史记录
+   store.showToast('消息', 'info'); // 用于通知
+   ```
+
+2. **添加 `OverlaySystem` 组件**
+   ```typescript
+   // src/App.tsx
+   import { OverlaySystem } from '@/engine/ui/OverlaySystem';
+   
+   function App() {
+     return (
+       <>
+         <OverlaySystem /> {/* 新增：处理飘字和弹窗 */}
+         <GameContent />
+       </>
+     );
+   }
+   ```
+
+3. **更新类型定义**
+   - `LogEntry` 不再有 `display` 字段
+   - 使用 `NotificationPayload` 处理通知
+   - 监听 `NOTIFICATION` 事件而不是 `MESSAGE` 事件
+
+---
+
+## 相关文档
+
+- [核心类型定义](./core/types.ts)
+- [状态管理](./state/store.ts)
+- [事件系统](./systems/events.ts)
+- [历史管理](./state/history.ts)
+- [流程系统](./systems/flow.ts)
+- [查询系统](./systems/query.ts)
+- [覆盖层系统](./ui/OverlaySystem.tsx)
+
+## 许可证
+
+MIT