186 lines
5.8 KiB
Markdown
186 lines
5.8 KiB
Markdown
# 08 技术架构与代码导读
|
||
|
||
本文档定义“新项目重制版”的目标技术架构，并说明为何要从旧版的全局脚本结构迁移到现代工程化。该文档同时作为程序端的模块边界约定，避免后期职责混乱与重复实现。
|
||
|
||
## 8.1 技术目标
|
||
|
||
- 现代工程化：TypeScript、模块化、自动化测试、CI
|
||
- 数据驱动：内容配置可热更新（至少开发期热更新），线上可增量发布内容包
|
||
- 可重放：随机数与模拟可注入 seed，便于复现与平衡
|
||
- 可观测：结构化日志与埋点，便于 QA/分析
|
||
- 可扩展：系统之间低耦合，内容扩展不引发代码级联改动
|
||
|
||
## 8.2 总体架构（客户端）
|
||
|
||
推荐架构分层：
|
||
|
||
- Presentation（UI 层）：界面渲染与交互
|
||
- Application（应用层）：用例编排（例如“执行一次采集”）
|
||
- Domain（领域层）：规则与模型（状态、战斗、事件、任务、时间推进）
|
||
- Data（数据层）：内容配置加载、存档读写、远端 API
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
UI[UI: React/Canvas/纯DOM均可] --> APP[Application: 用例与指令]
|
||
APP --> DOM[Domain: 规则引擎与模型]
|
||
DOM --> RNG[RNG: 可注入种子]
|
||
APP --> DATA[Data: 配置/存档/API]
|
||
DATA --> CT[Content: 表与包]
|
||
DATA --> SAV[Save: 本地/云端]
|
||
DATA --> NET[Net: 后端API]
|
||
```
|
||
|
||
对应源文件：[architecture-client.mmd](./diagrams/architecture-client.mmd)
|
||
|
||
## 8.3 关键模块与职责边界
|
||
|
||
### 8.3.1 Simulation（时间推进）
|
||
|
||
职责：
|
||
|
||
- `advanceTime(Δt)`：统一时间推进管线
|
||
- 结算状态消耗、Buff tick、资源刷新、灾害计时
|
||
- 对外暴露“结算结果摘要”用于 UI 提示（不直接操作 UI）
|
||
|
||
边界：
|
||
|
||
- 不负责事件抽取（由 EventEngine 负责）
|
||
- 不直接读写存档（由 SaveService 负责）
|
||
|
||
### 8.3.2 Inventory（背包与容器）
|
||
|
||
职责：
|
||
|
||
- 容量计算（体积/堆叠）
|
||
- 移入移出、消耗、掉落
|
||
- 装备槽与耐久更新
|
||
|
||
边界：
|
||
|
||
- 不负责“物品效果执行”（由 EffectEngine 执行）
|
||
|
||
### 8.3.3 EffectEngine（效果执行器）
|
||
|
||
职责：
|
||
|
||
- 执行配置化效果链：AddItem、AddStatus、AddBuff、SetFlag、StartCombat 等
|
||
- 保障效果执行顺序与事务性（可选：失败回滚）
|
||
|
||
边界：
|
||
|
||
- 不包含具体内容逻辑；内容差异通过配置表达
|
||
|
||
### 8.3.4 EventEngine（事件引擎）
|
||
|
||
职责：
|
||
|
||
- 事件池管理（全局/区域/地点/任务）
|
||
- 条件过滤、权重抽取
|
||
- 选项检定（属性/资源/标记）
|
||
- 返回事件给 UI；结果通过 EffectEngine 执行
|
||
|
||
### 8.3.5 CombatEngine（战斗引擎）
|
||
|
||
职责：
|
||
|
||
- 依据双方数据初始化战斗场景（距离、回合）
|
||
- 执行玩家动作与敌人 AI
|
||
- 输出结构化战斗日志
|
||
|
||
边界：
|
||
|
||
- 不直接改变全局状态；通过 EffectEngine 或 CombatResult 由上层应用写回
|
||
|
||
### 8.3.6 QuestEngine（任务引擎）
|
||
|
||
职责：
|
||
|
||
- 任务状态机（NotStarted/Active/Completed）
|
||
- 监听世界事件（到达地点、获得物品、完成战斗等）
|
||
- 驱动任务事件池与奖励发放
|
||
|
||
### 8.3.7 ContentService（内容服务）
|
||
|
||
职责：
|
||
|
||
- 加载基础包与扩展包（版本、依赖、覆盖策略）
|
||
- 提供按 ID 与按标签检索能力
|
||
- 提供校验：唯一性、引用完整性、字段类型、循环依赖检查
|
||
|
||
## 8.4 数据与配置组织（建议）
|
||
|
||
### 8.4.1 文件结构建议
|
||
|
||
- `content/base/*.json`：基础内容
|
||
- `content/packs/<packId>/*.json`：扩展包
|
||
- `content/locales/zh-CN.json`：文本本地化
|
||
- `content/schema/*.json`：JSON Schema（用于校验）
|
||
|
||
### 8.4.2 依赖与覆盖策略
|
||
|
||
- 包必须声明：
|
||
- `packId`
|
||
- `version`
|
||
- `dependsOn`（可选）
|
||
- `overrides`（可选，覆盖的目标与字段）
|
||
- 默认策略：追加；只有明确声明 overrides 才允许覆盖
|
||
|
||
## 8.5 随机与可重放
|
||
|
||
### 8.5.1 RNG 注入原则
|
||
|
||
- 任何概率行为必须来自同一个 RNG 实例（或可追踪的子 RNG）
|
||
- 每次行动生成子种子，保证“局部随机独立、整体可重放”
|
||
|
||
### 8.5.2 重放数据
|
||
|
||
为了复现 bug：
|
||
|
||
- 记录：初始 seed、玩家输入序列（动作与选项）、版本号、内容包版本
|
||
- 可导出一份 replay 文件给 QA
|
||
|
||
## 8.6 存档体系（概览）
|
||
|
||
存档应分层：
|
||
|
||
- `PlayerState`：状态、背包、装备、位置、任务进度
|
||
- `WorldState`：时间、地点资源存量、世界标记、灾害状态
|
||
- `ContentVersion`：内容包版本（用于兼容与迁移）
|
||
|
||
存档详细见：[09-存档与后端.md](./09-%E5%AD%98%E6%A1%A3%E4%B8%8E%E5%90%8E%E7%AB%AF.md)
|
||
|
||
## 8.7 旧版 TinyWaste 代码结构速览（用于迁移参考）
|
||
|
||
旧版项目（当前仓库）具备典型特点：
|
||
|
||
- 入口由 [loader.js](file:///Users/virtheart/Documents/CloneProjects/TinyWaste/data/loader.js) 动态加载多个 `data/*.min.js`
|
||
- 大量全局变量保存游戏状态（例如 `PLAYER_STATUS/BAG_DATA/MAP_DATA` 等）
|
||
- 时间推进由 [updateSysClock](file:///Users/virtheart/Documents/CloneProjects/TinyWaste/data/lib.js#L460-L510) 驱动，依赖 `setTimeout` 递归
|
||
- 快进逻辑在 [costTimeFunc](file:///Users/virtheart/Documents/CloneProjects/TinyWaste/data/action.js#L587-L682) 内实现，快进过程中暂停计时器
|
||
- 战斗 UI 与逻辑混在一起（见 [battleObj](file:///Users/virtheart/Documents/CloneProjects/TinyWaste/data/action.js#L2486-L2605)）
|
||
|
||
迁移目标：
|
||
|
||
- 将“全局状态 + DOM 操作”拆解为“领域模型 + 纯逻辑结算 + UI 渲染”
|
||
- 保留数据驱动思想，但用 Schema 与工具链保障质量
|
||
|
||
## 8.8 安全与反作弊（基础）
|
||
|
||
即使是单人游戏，也建议做到：
|
||
|
||
- 云端存档接口鉴权（token）
|
||
- 存档校验与限流，避免被滥用
|
||
- 客户端不保存敏感密钥
|
||
|
||
## 8.9 工程化与质量
|
||
|
||
- TypeScript 全覆盖
|
||
- 单元测试：
|
||
- 时间推进管线
|
||
- 事件抽取
|
||
- 战斗计算
|
||
- 存档迁移
|
||
- 内容校验：
|
||
- CI 中运行 Schema 校验与引用完整性检查
|
||
|