oes-web/docs/ARCHITECTURE.md

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 字段:

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 读取物品、敌人、掉落、任务等内容，不再在系统内硬编码内容表

存档结构

{
  "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" }
}