oes-web/CLAUDE.md

# OES-WEB - 上古卷轴 Web 版

## Overview
用 AI 工具开发的 Web 版《上古卷轴》风格 RPG 游戏。2D 俯视角，极简像素/色块美术，重点是系统完整性和 Mod 生态。
当前阶段: Phase 3 完成，进入 Phase 4 内容扩展。

## Tech Stack
- Language: TypeScript 5.x (strict mode)
- Framework: Phaser 3.8x (2D game framework)
- Build: Vite 6
- Testing: Vitest
- Persistence: Dexie.js (IndexedDB) + fflate 压缩
- Audio: Howler.js
- UI: HTML/CSS overlay on Phaser canvas

## Commands
- `npm run dev` -- 启动开发服务器 (localhost:5173, 热重载)
- `npm run build` -- 生产构建到 dist/
- `npm run test` -- 运行测试
- `npx tsc --noEmit` -- TypeScript 类型检查

## Project Structure
```
src/
├── core/           # GameManager, EventBus, EntityManager (核心单例)
├── components/     # 数据组件 (Health, Combat, Skills...)
├── systems/        # 游戏系统 (Combat, Magic, Quest...)
├── scenes/         # Phaser 场景 (GameScene, MenuScene...)
├── entities/       # 实体工厂 (Player, NPC, Enemy...)
├── ai/             # AI 控制器和行为树
├── ui/             # HTML/CSS UI 组件
│   └── components/ # HUD, Inventory, DialogueUI...
├── data/           # JSON 游戏数据 (物品/法术/任务/NPC)
├── mechanics/      # 计算公式 (伤害/技能/炼金...)
├── save/           # 存档系统 (Dexie.js)
├── maps/           # 地图管理
├── mods/           # Mod 系统 (ModLoader, ModManager)
└── utils/          # 工具函数
```

## Architecture
- **Entity-Component 模式**: 实体是 ID，组件是数据，系统操作组件
- **EventBus 事件总线**: 系统间解耦通信，不直接调用
- **GameManager 单例**: 初始化所有系统，管理主循环
- **DataRegistry 数据注册表**: 所有游戏数据通过 DataRegistry 加载，支持 Mod 覆盖
- **系统执行顺序**: Input → AI → Physics → Combat → Magic → Stealth → StatusEffect → Inventory → Corpse → ItemInteraction → Quest → Dialogue → Animation → Spawn → ModHook → Save

## Data Architecture (全部可 Mod 覆盖)
所有游戏数据通过 `DataRegistry` 统一加载和管理。Mod 可覆盖任何数据类型:
- **DataRegistry**: 中央数据注册表，加载 24 个 JSON 文件，监听 `mod:dataResolved` 事件
- **19 个数据域**: items, armor, enemies, races, skills, perkTrees, spells, shouts, standingStones, quests, recipes, enchantments, soulGems, smithing, cooking, dialogue, transforms, vampireStages, gameConfig
- **JSON 数据文件** (24 个):
  - `src/data/items/` — items.json, weapons.json, armor.json, enchantments.json, soul-gems.json
  - `src/data/spells/` — spells.json, shouts.json
  - `src/data/enemies/` — enemies.json
  - `src/data/quests/` — quests.json
  - `src/data/races/` — races.json
  - `src/data/skills/` — skills.json, perks.json, werewolf-perks.json, vampire-perks.json
  - `src/data/world/` — standing-stones.json
  - `src/data/alchemy/` — ingredients.json, potions.json
  - `src/data/crafting/` — smithing.json, cooking.json
  - `src/data/dialogue/` — trees.json
  - `src/data/transforms.json`, `vampire-stages.json`, `game-config.json`
- **系统数据驱动化**: 11 个游戏系统全部从 DataRegistry 读取数据，不再硬编码:
  - MagicSystem, CombatSystem, LevelingSystem, RegenSystem
  - EnchantingSystem, SmithingSystem, AlchemySystem, CookingSystem
  - TransformationSystem, VampireSystem, DialogueSystem
- **循环依赖解决**: CombatSystem/MagicSystem/QuestSystem/DialogueSystem 通过 `globalThis` 注册，ScriptContext lazy 访问
- **地图数据**: 由 MapManager 从 `zones.json` 加载，支持 Mod 覆盖
- **UI 组件**: CharacterCreationUI/SkillTreeUI 从 DataRegistry 读取数据，不再直接导入 JSON

## Conventions
- TypeScript strict mode，不用 `any`，用 `unknown` 然后窄化
- 组件必须有 `type` 字段作为标识
- 所有时间值用毫秒，delta-time 从游戏时钟获取
- 实体位置用浮点数，渲染时四舍五入
- 文件命名: 组件 PascalCase，工具 camelCase，资源 kebab-case
- 测试文件: `*.test.ts` 或 `*.spec.ts`

## Do Not
- 不要修改 `src/core/` 下的核心模块除非运行完整测试
- 不要添加外部依赖未经讨论
- 不要硬编码屏幕尺寸
- 不要直接 fetch 资源，通过 AssetManager
- 不要在游戏循环中产生不必要的对象分配
- 不要跳过 TypeScript 类型检查直接提交

## Development Progress

### Phase 0: 项目脚手架 ✅
- Vite + TypeScript + Phaser 3 配置
- GameManager, EventBus, EntityManager 核心模块
- 基础游戏场景和 UI 覆盖层
- IndexedDB 存档系统骨架

### Phase 1: 核心角色系统 ✅
- 10 个可玩种族 (Nord, Dunmer, Altmer, Argonian, Khajiit, Breton, Imperial, Redguard, Orc, Bosmer)
- 角色创建界面 (选种族、命名)
- 生命/魔力/耐力三大属性系统
- 18 项技能和 XP 追踪
- 升级系统 (每 10 级技能 = 1 角色等级)
- **18 棵完整天赋树** (251 个天赋)
- 种族能力和被动
- 13 个站立之石
- 存档/读档角色数据

### Phase 2: 基础战斗系统 ✅
- 实时动作战斗 (鼠标左键攻击)
- 单手/双手武器系统
- 盾牌格挡 (右键按住)
- 强力攻击 (Shift)
- 暴击系统 (10% 基础 + 潜行加成)
- 5 种敌人类型 (强盗/狼/骷髅/熊/蜘蛛) + 7 种新敌人 (尸鬼/尸鬼亡灵/洞穴熊/冰霜蜘蛛/强盗逃犯/强盗暴徒/死灵法师)
- 敌人 AI (追逐/攻击)
- 玩家死亡和复活
- 战斗音效和视觉反馈
- 状态效果系统
- 回血/回魔/回耐力系统

### Phase 3: 探索与世界 ✅
- 地图系统 (7 个区域)
  - 白漫城 (城市)
  - 白漫城外 (平原)
  - 荒瀑古坟 (地牢)
  - 溪木镇 (村庄)
  - 暗光洞穴 (地牢)
  - 古代遗迹 (地牢)
  - 天际省荒野 (世界地图)
- 门和区域过渡
- 宝箱容器系统
- 地面物品拾取
- 快速旅行
- 世界地图 UI
- 昼夜循环系统
- 物品交互 (悬停提示/使用/装备)
- 收藏/快捷栏系统

### Phase 4: NPC 与对话 ✅ (基础)
- NPC 实体和闲置行为
- 分支对话系统
- 商人买卖界面
- 每个城市的 NPC
- Speech 技能检定
- 随从招募系统

### Phase 5: 扩展战斗与魔法 ✅ (基础)
- 5 大魔法学派基础法术
- 法术施放 UI
- 潜行攻击倍率
- 完整潜行/检测系统
- 龙吼系统
- 尸体系统 (状态机/搜刮/复生)

### Phase 6: 制作系统 ✅ (基础)
- 炼金系统 (材料效果/组合/药水/毒药)
- 附魔系统 (分解/附魔/灵魂石)
- 锻造系统 (锻造台/砂轮)
- 烹饪系统

### Phase 7: 任务系统 ✅ (基础)
- 任务状态机 (开始/目标/完成/失败)
- 任务日志 UI
- 主线任务 (3 个)
- 公会任务线 (战士/盗贼)
- 魔神任务 (1 个)
- 辐射任务 (3 个)

### Phase 8: 高级系统 🔄
- **狼人变形** ✅:
  - TransformationSystem: form 组件管理变形状态
  - T 键切换狼人/吸血鬼领主形态
  - 形态加成: 生命+100, 耐力+50, 护甲+10, 移速+60, 爪击伤害 20
  - 变形时替换武器为形态武器，修改精灵外观
  - 形态有时限 (120s) + 冷却 (30s)
  - 狼人专属天赋树 (6 个天赋: 野兽之力/厚皮毛/疾跑/恐惧嚎叫/野性恢复/月圆之夜)
- **吸血鬼系统** ✅:
  - VampireSystem: 4 阶段感染进度
  - 白天惩罚 (阳光伤害) + 夜间增益 (属性加成)
  - 吸血回复机制
  - 吸血鬼专属天赋树 (6 个天赋: 暗夜视觉/冰霜亲和/生命虹吸/暗夜潜行/血魔法/远古血脉)
- **传奇技能** ✅:
  - LegendarySystem: 技能 100 后可传奇重置
  - 归零 + 获得 1 天赋点 + 传奇次数 +1
  - 每次传奇该技能获得 +10% XP 加成
- 阵营声望 (数据已定义)
- 结婚系统 (待实现)

### Phase 8.5: Mod 系统 ✅
- JSON 数据覆盖加载器
- 加载优先级系统
- 插件清单格式 (manifest.json)
- 事件钩子 API
- Mod 管理器 UI
- 依赖检查和冲突检测
- 示例 Mod (武器/任务)
- **实体脚本系统** (与原版上古卷轴一致):
  - 脚本定义: properties (持久化变量) + handlers (JS 代码字符串)
  - 生命周期事件: OnLoad, OnUpdate, OnHit, OnDeath, OnActivate, OnUnload, OnEquip, OnUse, OnZoneEnter, OnZoneLeave
  - 沙箱化上下文 API: entity, inventory, combat, magic, dialogue, quest, effects, prop, time, entities, events, data, log
  - ScriptSystem 集成到游戏循环，自动调用 OnUpdate 和事件转发
  - 实体通过 `data.script` 字段挂载脚本

### Phase 9: 内容与打磨 🔄
- 30+ 种敌人 (已完成)
- 7 个区域 (已完成)
- 18 棵天赋树 (已完成)
- 11 个任务 (已完成)
- 昼夜循环 (已完成)
- 待完成: 更多地图、更多任务、UI 打磨、音频集成

### Phase 10: 最终集成 ⏳
- 端到端测试
- 平衡调整
- 构建优化

## Game Content Summary
- **种族**: 10 个
- **敌人**: 12 种 (强盗/狼/骷髅/尸鬼/尸鬼亡灵/熊/洞穴熊/蜘蛛/冰霜蜘蛛/强盗逃犯/强盗暴徒/死灵法师)
- **区域**: 7 个 (白漫城/白漫城外/荒瀑古坟/溪木镇/暗光洞穴/古代遗迹/天际省荒野)
- **天赋树**: 20 棵 (18 技能 + 狼人 + 吸血鬼, 263 个天赋)
- **任务**: 11 个 (3 主线/2 战士公会/1 盗贼公会/1 魔神/3 辐射/1 采药)
- **武器**: 15 种 (铁/钢各 tier)
- **护甲**: 27 件 (铁/钢/皮革/精灵/兽人/乌木/魔族/龙)
- **物品**: 28 种 (消耗品/材料/杂物)
- **法术**: 多种 (毁灭/恢复/召唤/变化)
- **站立之石**: 13 个
- **变形形态**: 2 种 (狼人/吸血鬼领主)
- **高级系统**: 狼人变形 + 吸血鬼感染 + 传奇技能

## Mod 生态
- Mod 格式: `ModPackage` (manifest + data + scripts)，通过 `modLoader.loadMod()` 加载
- 加载方式: 深度合并，按 priority 排序后加载，后加载覆盖先加载
- 依赖检查: `manifest.dependencies` 声明前置依赖，未满足则拒绝加载
- 冲突检测: 同域同 ID 多个 Mod 声明冲突，最后一个赢
- 事件钩子: `mod:loaded`, `mod:dataResolved` 事件
- Mod 管理器: 启用/禁用/排序/冲突检测
- **19 个数据域全部可覆盖**: items, armor, enemies, races, skills, perkTrees, spells, shouts, standingStones, quests, recipes, enchantments, soulGems, smithing, cooking, dialogue, transforms, vampireStages, gameConfig
- **E2E 测试验证**: `src/mods/ModE2E.test.ts` — 10 个测试覆盖数据覆盖、新数据添加、优先级排序、依赖检查、系统热重载

## Mod 脚本系统
Mod 可为游戏实体附加自定义脚本逻辑，与原版上古卷轴的脚本系统一致。

### 脚本定义格式 (Mod JSON)
```json
{
  "manifest": { "id": "my-mod", "name": "我的 Mod", "version": "1.0.0" },
  "scripts": {
    "guard_patrol": {
      "properties": { "alertLevel": 0, "homeX": 0 },
      "handlers": {
        "OnLoad": "ctx.log('守卫上线');",
        "OnHit": "ctx.prop('alertLevel', ctx.prop('alertLevel') + 1);",
        "OnDeath": "ctx.log('守卫阵亡');"
      }
    }
  }
}
```

### 实体挂载
Zone 数据中的实体通过 `data.script` 字段挂载脚本:
```json
{ "type": "npc", "data": { "name": "守卫", "script": "my-mod:guard_patrol" } }
```

### 生命周期事件
| 事件 | 触发时机 | 参数 |
|------|---------|------|
| `OnLoad` | 实体创建时 | 无 |
| `OnUpdate` | 每帧 | `delta` (ms) |
| `OnHit` | 被攻击时 | `{ attacker, damage, isCritical }` |
| `OnDeath` | 死亡时 | `{ killer }` |
| `OnActivate` | 玩家交互时 | `{ player }` |
| `OnUnload` | 实体销毁时 | 无 |
| `OnEquip` | 被装备时 | `{ item, slot }` |
| `OnUse` | 被使用时 | `{ item }` |
| `OnZoneEnter` | 区域加载时 | `{ zoneId }` |

### 沙箱化上下文 API (`ctx`)
脚本执行时获得 `ctx` 对象，包含:
- `entity` — 读写生命/魔力/耐力/位置/技能/等级
- `inventory` — 增删查物品/金币
- `combat` — 伤害/治疗/击杀
- `magic` — 施法/学习/查询法术
- `dialogue` — 启动对话树 (待实现)
- `quest` — 任务操作 (待实现)
- `effects` — 应用/移除状态效果
- `prop` — 持久化自定义变量
- `time` — 游戏时间查询
- `entities` — 查询周围实体
- `events` — 自定义事件监听/触发
- `data` — 只读查询游戏数据
- `log` — 调试日志

### 关键文件
- `src/mods/ModTypes.ts` — ScriptDefinition, ScriptInstance 类型
- `src/mods/ScriptContext.ts` — 沙箱化 API 实现
- `src/mods/ModScriptEngine.ts` — 脚本编译和实例管理
- `src/systems/ScriptSystem.ts` — 游戏循环集成
- `src/mods/ModLoader.ts` — Mod 加载时注册脚本定义