# OES-WEB 架构文档

## 系统架构图

```
┌─────────────────────────────────────────────────────┐
│                   UI Layer (HTML/CSS)                │
│  HUD │ Inventory │ Dialogue │ Skills │ Map │ Mods   │
└──────────────────────┬──────────────────────────────┘
                       │ EventBus
┌──────────────────────┴──────────────────────────────┐
│                Game Logic Layer (TypeScript)          │
│  Systems: Combat │ Magic │ Quest │ Alchemy │ ...     │
│  Components: Health │ Skills │ Inventory │ ...       │
│  Entities: Player │ NPC │ Enemy │ Corpse │ Item      │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────┴──────────────────────────────┐
│               Core Engine Layer (Phaser 3)           │
│  Rendering │ Physics │ Input │ Audio │ Scene Mgmt   │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────┴──────────────────────────────┐
│                Data Layer (JSON + IndexedDB)         │
│  Base Data │ DataRegistry │ Save Data │ Mod Data      │
└─────────────────────────────────────────────────────┘
```

## 核心模块

### GameManager (单例)
- 初始化 Phaser 游戏实例
- 注册和管理系统
- 管理主循环 tick 顺序

### EventBus (单例)
- 发布/订阅事件系统
- 系统间解耦通信
- 所有交互通过事件，不直接调用

### EntityManager (单例)
- 实体生命周期管理
- 组件存储和查询
- 实体工厂方法

## 系统执行顺序

每帧按以下顺序执行:

```
1.  InputSystem          ← 读取玩家输入
2.  AIControlSystem      ← NPC/敌人 AI 决策
3.  PhysicsSystem        ← 移动、碰撞检测
4.  CombatSystem         ← 伤害计算、命中检测
5.  MagicSystem          ← 法术施放、效果
6.  StealthSystem        ← 检测等级、潜行倍率
7.  StatusEffectSystem   ← Buff/Debuff/毒药
8.  InventorySystem      ← 重量、物品管理
9.  CorpseSystem         ← 尸体状态、搜刮
10. ItemInteractionSystem ← 物品拾取、容器
11. QuestSystem          ← 任务状态更新
12. DialogueSystem       ← NPC 对话
13. AnimationSystem      ← 精灵动画
14. SpawnSystem          ← 随机遭遇、刷新
15. ModHookSystem        ← Mod 事件钩子
16. SaveSystem           ← 自动存档
```

## 数据流

```
Player Input
    ↓
EventBus.emit('player:attack', { target, damage })
    ↓
CombatSystem 处理事件
    ↓
EventBus.emit('entity:damaged', { entity, amount })
    ↓
HealthSystem 更新生命值
    ↓
EventBus.emit('entity:died', { entity })
    ↓
CorpseSystem 生成尸体
LootSystem 生成掉落
QuestSystem 检查任务目标
```

## 组件设计

所有组件必须有 `type` 字段:

```typescript
interface Component {
  type: string;
  [key: string]: any;
}

// 示例
{ type: 'health', current: 100, max: 100 }
{ type: 'position', x: 100, y: 200 }
{ type: 'combat', attackPower: 10, defense: 5 }
```

## Mod 系统架构

```
Base Game Data (src/data/*.json)
    ↓
ModValidator (manifest + data schema guard)
    ↓
ModResolver (dependency order + priority merge + conflict report)
    ↓
Resolved Mod Data
    ↓
DataRegistry rebuilds runtime snapshot
    ↓
Game Systems read DataRegistry
```

### Mod v1 边界

- 当前只支持 JSON 数据 Mod: `manifest + data`
- 支持数据域: `items / enemies / npcs / quests / recipes / spells / skills / perks / zones`
- 禁止执行玩家导入脚本；旧脚本入口只保留为禁用兼容桩
- 加载顺序: 依赖先于依赖方，同层按 `priority` 从小到大合并，后合并者覆盖前者
- 冲突: 多个启用 Mod 修改同一 `domain.id` 时记录冲突，最终以后合并者为准
- 运行时数据入口: 新系统应通过 `DataRegistry` 读取物品、敌人、掉落、任务等内容，不再在系统内硬编码内容表

## 存档结构

```json
{
  "version": 1,
  "timestamp": 1234567890,
  "playTime": 3600,
  "character": { "name", "race", "level", "skills", "perks" },
  "inventory": { "items", "gold", "equipped" },
  "worldState": { "discoveredLocations", "clearedDungeons" },
  "quests": { "active", "completed", "failed" },
  "factions": { "factionId": "reputation" },
  "npcs": { "npcId": "state" },
  "mapStates": { "mapId": "entities" }
}
```