chore:首次提交

2026-05-11 17:39:31 +08:00
parent 906f1cf468
commit 83e99a7ef8
109 changed files with 19558 additions and 0 deletions
@@ -0,0 +1,33 @@
+# ADR-001: 使用 Entity-Component 模式
+
+## Status
+Accepted
+
+## Date
+2026-05-10
+
+## Context
+需要一个管理游戏对象的架构，要求:
+- 支持 50+ 个并发实体
+- 轻松添加新实体类型，无需修改核心系统
+- 高效查询特定组件组合的实体
+- 解耦物理、渲染和 AI 逻辑
+
+## Decision
+使用 Entity-Component (EC) 模式，不用完整 ECS 框架。
+
+- 实体是唯一 ID (字符串)
+- 组件是纯数据对象，必须有 `type` 字段
+- 系统遍历组件数组操作匹配的实体
+- EventBus 处理系统间通信
+
+选择此方案而非:
+- 继承层次 (太僵化，钻石问题)
+- 完整 ECS 库 (增加依赖，复杂度超出需求)
+- 扁平对象数组 (大数据量缓存不友好)
+
+## Consequences
+- 添加新实体类型只需定义组件 (无需修改类)
+- 系统可以独立开发和测试
+- 需要自己编写组件存储和查询逻辑
+- 实体数量在 200+ 时可能需要优化
@@ -0,0 +1,33 @@
+# ADR-002: 使用 2D 俯视角渲染
+
+## Status
+Accepted
+
+## Date
+2026-05-10
+
+## Context
+需要选择渲染方式，要求:
+- 浏览器原生支持
+- AI 工具可以生成素材
+- 开发速度快
+- 能展示所有 RPG 系统
+
+## Decision
+使用 2D 俯视角 (类经典塞尔达/早期最终幻想)。
+
+- Phaser 3 + Arcade Physics
+- 32x32 像素 tile 地图
+- 极简色块/简单像素美术
+- HTML/CSS 覆盖层处理 UI
+
+选择此方案而非:
+- 3D WebGL (开发周期太长，AI 难以生成 3D 模型)
+- 2D 横版 (不适合开放世界探索)
+- 纯 HTML UI (失去游戏世界沉浸感)
+
+## Consequences
+- 开发速度快，可以专注系统完整性
+- AI 可以生成 2D 像素美术
+- 性能良好，中端硬件可达 60fps
+- 视觉表现简单，后期可美化
@@ -0,0 +1,34 @@
+# ADR-003: 使用 JSON 数据的 Mod 系统
+
+## Status
+Accepted
+
+## Date
+2026-05-10
+
+## Context
+需要实现 Mod 生态系统，要求:
+- 玩家可以制作和分享 Mod
+- Mod 可以添加新内容和修改现有内容
+- 加载顺序可控制
+- 冲突可以检测和解决
+
+## Decision
+使用 JSON 数据文件作为 Mod 格式。
+
+- Mod 格式: JSON 数据 + manifest.json 清单
+- 加载方式: 深度合并，后加载覆盖先加载
+- 优先级: 数字越小越先加载
+- 事件钩子: GameEvents.on() 让 Mod 响应游戏事件
+- 验证: JSON Schema 确保数据结构合规
+
+选择此方案而非:
+- 二进制格式 (不可读，难以调试)
+- 脚本语言 (安全风险，性能问题)
+- 文件系统覆盖 (浏览器限制)
+
+## Consequences
+- Mod 格式简单易懂，玩家容易上手
+- JSON 可以被任何文本编辑器修改
+- 深度合并可能产生意外覆盖，需要冲突检测
+- 运行时加载性能良好
@@ -0,0 +1,27 @@
+# ADR-004: Mod v1 采用 JSON-only 数据运行时
+
+## Status
+Accepted
+
+## Date
+2026-05-10
+
+## Context
+OES-WEB 的目标是让 Mod 成为核心能力，但浏览器内执行玩家导入的脚本会带来注入、数据窃取、无限循环和调试成本风险。当前阶段更需要先把基础内容扩展、覆盖、加载顺序、冲突报告和游戏系统接入跑稳。
+
+## Decision
+Mod v1 只支持 JSON 数据 Mod，不执行任意 JavaScript。
+
+- Mod 包结构: `{ manifest, data }`
+- `manifest` 声明 id/name/version/priority/dependencies
+- `data` 支持 items/enemies/npcs/quests/recipes/spells/skills/perks/zones
+- `ModValidator` 校验清单、数据域、内容 id 和危险 key
+- `ModResolver` 按依赖和优先级合并启用 Mod，并报告冲突
+- `DataRegistry` 使用 Base Data + Resolved Mod Data 重建运行时数据快照
+- 旧脚本入口保留为禁用桩，任何执行请求都会失败并发出 `script:error`
+
+## Consequences
+- 武器、敌人、掉落、任务和地图可以先通过 JSON 稳定扩展
+- 安全边界清晰，避免 `new Function`/eval 类执行入口进入主包
+- 脚本 Mod 暂时不能实现复杂行为，后续如需要应单独设计 Worker 沙箱和权限 API
+- 系统必须逐步改为只读 `DataRegistry`，减少硬编码内容