diablo2-web/src/baker/README.md

src/baker — 离线 MPQ 美术资产与数据表烘焙管线

src/baker 是运行在 Node.js 环境下的离线资产烘焙（Baking）工具链，负责将原版 Diablo II: Lord of Destruction (v1.13c) 的 MPQ 归档文件（d2data.mpq、d2char.mpq、d2exp.mpq、Patch_D2.mpq 等）解码、调色板转换、合批打包并生成供浏览器客户端零 MPQ 开销直接消费的静态资产包（输出至 public/）。

1. 模块职责与架构边界

• TypeScript 工程约束（tsconfig.baker.json）：
  • lib: ["ES2022"], types: ["node"] —— 纯 Node.js CLI 模块，严禁包含任何浏览器 DOM API。
  • 仅依赖 src/common（共享 MPQ 读取器、二进制格式解析器与 pack-contract 校验契约），严禁导入 src/client、src/server 或 src/netproto。
• 统一 CLI 入口：src/baker/cli.ts（通过 npm run bake -- <target> 调用）。

---

2. 目录结构

src/baker/
├── cli.ts           # 统一命令行入口，支持分项烘焙、全量烘焙 (all) 与契约校验 (verify)
├── packers/         # 核心美术与数据打包器 (瓦片、实体、投射物、覆盖层、UI、前置界面、动画表、字体等)
├── extract/         # 1.13c 权威 TXT/BIN 数据表与 D2Net/D2MOO 常量提取脚本
├── io/              # PNG/WebP 图像编码、SHA-256 资产清单生成 (asset-manifest.ts) 与发布辅助工具
└── audit/           # Fail-Fast 烘焙产物完整性校验器 (verify-packs, verify-tiles, verify-entity-packs)

---

3. 烘焙目标与产物对照表

运行 npm run bake -- <target>（或对应 npm run pack:* 快捷命令）将从 samples/d2/ 下的 MPQ 文件提取并生成以下静态资产：

烘焙子命令 (cli.ts)	对应 npm run 快捷脚本	核心实现文件	输出目录 / 产物 (public/)	说明
tiles	npm run pack:tiles	packers/pack-tiles.ts	public/act-packs/tiles/	烘焙全部 5 幕共 233 个关卡 DT1 + 3 个通用 DT1 (Blank.dt1, InvisWal.dt1, Warp.dt1) 瓦片图集及 drlg-bundle.{json,bin}
ui	npm run pack:ui	packers/pack-ui.ts	public/act-packs/ui/	烘焙游戏内 HUD 底栏、面板背景、按钮、7 职业技能图标、鼠标指针与物品栏网格 DC6 精灵图
frontend	npm run pack:frontend	packers/pack-frontend-ui.ts	public/act-packs/frontend/	烘焙战网登录界面、角色选择营火背景、7 职业创建角色动画与大厅 UI 资源
animdata	npm run pack:animdata	packers/pack-animdata.ts	public/act-packs/animdata.json	提取 data/global/AnimData.d2 全量 COF 动画帧数、速度与关键帧触发事件表
entities	npm run pack:entities	packers/pack-entity-assets.ts	public/act-packs/entities/	烘焙全部怪物、SuperUniques（自动捆绑其随从 Minions）、NPC 与场景交互 Object 的 DCC/DC6/COF 图集
missiles	npm run pack:missiles	packers/pack-missiles.ts	public/act-packs/missiles/	烘焙 Missiles.txt 全部投射物 DCC 图集与发光混合模式元数据
overlays	npm run pack:overlays	packers/pack-overlays.ts	public/act-packs/overlays/	烘焙 Overlays.txt 全部光环、诅咒、Buff、命中特效与升级光柱 DCC 图集
acts	npm run pack:acts	packers/pack-act-assets.ts	public/act-packs/act1..act5/	按幕聚合关卡音频、环境调色板 (PL2)、物品掉落图标与角色纸娃娃分层 (pack-char-so-layers.ts)
manifest	npm run pack:manifest	io/asset-manifest.ts	public/asset-manifest.json	递归扫描 public/ 计算所有资产的字节大小与 SHA-256 哈希，供客户端 Service Worker 增量更新使用
verify	npm run bake:verify	audit/verify-packs.ts	(控制台校验报告)	执行 src/common/pack-contract 严格校验，确保零缺失文件 (missingFiles === 0) 且通用 DT1 完整

---

4. 使用方法

4.1 准备原版 1.13c MPQ 文件

在执行烘焙前，请将原版 Diablo II: Lord of Destruction v1.13c 的 MPQ 文件放置在仓库根目录下的 samples/d2/ 目录中（支持软链接）：

samples/d2/
├── d2data.mpq       # 必需：基础数据、Act 1-4 瓦片、怪物、UI、音效
├── d2char.mpq       # 必需：角色纸娃娃分层 DCC/COF 动画
├── d2exp.mpq        # 必需：毁灭之王资料片 (Act 5、德鲁伊/刺客、扩展暗金/符文)
├── Patch_D2.mpq     # 必需：1.13c 最终补丁数据表 (Levels.txt, Skills.txt, SuperUniques.txt 等)
├── d2sfx.mpq        # 可选：音效资源
├── d2music.mpq      # 可选：Act 1-4 背景音乐
└── d2xmusic.mpq     # 可选：Act 5 背景音乐

4.2 执行全量或分项烘焙

# 一键执行全量离线资产烘焙 (tiles -> ui -> frontend -> animdata -> entities -> missiles -> overlays -> acts -> manifest)
npm run bake -- all

# 或者按需单独烘焙某一类资源（例如仅重打包瓦片或前端 UI）：
npm run pack:tiles
npm run pack:frontend
npm run pack:entities
npm run pack:manifest

# 烘焙完成后执行严格完整性校验（Fail-Fast 契约检查）
npm run bake:verify