5.8 KiB
5.8 KiB
08 技术架构与代码导读
本文档定义“新项目重制版”的目标技术架构，并说明为何要从旧版的全局脚本结构迁移到现代工程化。该文档同时作为程序端的模块边界约定，避免后期职责混乱与重复实现。
8.1 技术目标
- 现代工程化：TypeScript、模块化、自动化测试、CI
- 数据驱动：内容配置可热更新（至少开发期热更新），线上可增量发布内容包
- 可重放：随机数与模拟可注入 seed，便于复现与平衡
- 可观测：结构化日志与埋点，便于 QA/分析
- 可扩展：系统之间低耦合，内容扩展不引发代码级联改动
8.2 总体架构（客户端）
推荐架构分层：
- Presentation（UI 层）：界面渲染与交互
- Application（应用层）：用例编排（例如“执行一次采集”）
- Domain（领域层）：规则与模型（状态、战斗、事件、任务、时间推进）
- Data（数据层）：内容配置加载、存档读写、远端 API
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
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 依赖与覆盖策略
- 包必须声明：
packIdversiondependsOn（可选）overrides（可选，覆盖的目标与字段）
- 默认策略：追加；只有明确声明 overrides 才允许覆盖
8.5 随机与可重放
8.5.1 RNG 注入原则
- 任何概率行为必须来自同一个 RNG 实例（或可追踪的子 RNG）
- 每次行动生成子种子，保证“局部随机独立、整体可重放”
8.5.2 重放数据
为了复现 bug：
- 记录：初始 seed、玩家输入序列（动作与选项）、版本号、内容包版本
- 可导出一份 replay 文件给 QA
8.6 存档体系（概览）
存档应分层：
PlayerState：状态、背包、装备、位置、任务进度WorldState：时间、地点资源存量、世界标记、灾害状态ContentVersion：内容包版本（用于兼容与迁移）
存档详细见：09-存档与后端.md
8.7 旧版 TinyWaste 代码结构速览（用于迁移参考）
旧版项目（当前仓库）具备典型特点：
- 入口由 loader.js 动态加载多个
data/*.min.js - 大量全局变量保存游戏状态（例如
PLAYER_STATUS/BAG_DATA/MAP_DATA等） - 时间推进由 updateSysClock 驱动，依赖
setTimeout递归 - 快进逻辑在 costTimeFunc 内实现，快进过程中暂停计时器
- 战斗 UI 与逻辑混在一起（见 battleObj）
迁移目标：
- 将“全局状态 + DOM 操作”拆解为“领域模型 + 纯逻辑结算 + UI 渲染”
- 保留数据驱动思想，但用 Schema 与工具链保障质量
8.8 安全与反作弊（基础）
即使是单人游戏，也建议做到：
- 云端存档接口鉴权（token）
- 存档校验与限流，避免被滥用
- 客户端不保存敏感密钥
8.9 工程化与质量
- TypeScript 全覆盖
- 单元测试：
- 时间推进管线
- 事件抽取
- 战斗计算
- 存档迁移
- 内容校验：
- CI 中运行 Schema 校验与引用完整性检查