From 374bf2fff6633f6f27416431a4aa87fc74e1b163 Mon Sep 17 00:00:00 2001
From: troytt <47798984@qq.com>
Date: Thu, 17 Sep 2026 10:51:10 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AE=B0=E5=BD=95=E6=9C=AC=E6=9C=BA?=
 =?UTF-8?q?=E5=8E=9F=E7=89=88=20MPQ=20/=20DLL=20=E7=9A=84=E6=8C=81?=
 =?UTF-8?q?=E4=B9=85=E5=AD=98=E6=94=BE=E4=BD=8D=E7=BD=AE=E4=B8=8E=20/tmp?=
 =?UTF-8?q?=20=E4=B8=A2=E5=A4=B1=E6=95=99=E8=AE=AD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

把原版数据的权威路径固定为 /usr/local/google/home/taodao/d2-data，
由各工作树的 samples/d2 软链引用，避免十几个 worktree 各存一份 1.9 GB。

同时记下 2026-09-16 那次事故：数据原先放在 tmpfs 的 /tmp 下，机器重启后
被清空，samples/d2 变死链，角色与怪物立绘全部退化为占位方块。

顺带留档 22 个原版 DLL 的逆向参考价值，其中 D2Common.dll（DRLG 地图生成）
与 D2Game.dll（怪物惰性填充 / 视距休眠唤醒）是后续修野外悬崖拼接和接入
流式刷怪时的对照基准。
---
 README.md          |  4 ++
 docs/LOCAL_DATA.md | 93 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 97 insertions(+)
 create mode 100644 docs/LOCAL_DATA.md

diff --git a/README.md b/README.md
index 5a7544a..ee16384 100644
--- a/README.md
+++ b/README.md
@@ -46,6 +46,10 @@ scripts/       资源包烘焙、格式/数据/部署校验、无头浏览器检
 `samples/d2-packs/`——它不在 Git 里（63 MB 的索引 PNG 每次重烘都会让仓库再长一份），
 按下面的「资源包从哪来」下载解包后，**没有原版数据也能看地图**。
 
+`samples/d2/` 通常做成软链接，指向一个**磁盘上的持久目录**。切勿链到 `/tmp`——它是内存盘，
+重启即清空，链接会变死链而角色/怪物退化成占位方块。本机的实际摆放、清单与逆向参考用的原版
+DLL 见 [`docs/LOCAL_DATA.md`](docs/LOCAL_DATA.md)。
+
 ### 2. 资源包从哪来（不在 Git 里）
 
 图集包（62 个地图块 / 35 关，索引色 PNG + `scene.json`）**不在本仓库里**——它是 ~66 MB 的索引色
diff --git a/docs/LOCAL_DATA.md b/docs/LOCAL_DATA.md
new file mode 100644
index 0000000..7f32bc6
--- /dev/null
+++ b/docs/LOCAL_DATA.md
@@ -0,0 +1,93 @@
+# 本机游戏数据位置（原版 MPQ 与 DLL）
+
+> 本文件只记录**本机开发环境**的数据摆放约定。仓库本身不含任何暴雪资源，
+> 见 [`THIRD_PARTY_NOTICES.md`](../THIRD_PARTY_NOTICES.md) 与 `.gitignore`。
+
+## 1. 权威路径
+
+原版《暗黑破坏神 II》1.13c 的全部数据（MPQ 归档 + 原版 DLL）统一存放在**磁盘持久目录**：
+
+```
+/usr/local/google/home/taodao/d2-data/
+```
+
+仓库通过软链接引用它（`samples/d2` 是引擎 `DEFAULT_BASES` 的第一顺位）：
+
+```bash
+ln -s /usr/local/google/home/taodao/d2-data \
+      /usr/local/google/home/taodao/d2w-wg1-main/samples/d2
+```
+
+验证链接生效：
+
+```bash
+ls -la samples/d2/ | head
+curl -s -o /dev/null -w '%{http_code}\n' -r 0-1023 http://localhost:8080/samples/d2/Patch_D2.mpq
+# 期望输出 206（Range 生效，?live=1 直读归档才能工作）
+```
+
+> [!CAUTION]
+> **绝对不要把数据放在 `/tmp`。**
+> 这台 Cloudtop 的 `/tmp` 是 48 GB 的 **tmpfs（内存盘）**，每次重启全部清空。
+> 历史教训：2026-09-14 曾把数据放在 `/tmp/diablo2-web/Diablo II V1.13C/` 并软链到
+> `samples/d2`，机器在 2026-09-16 15:35 重启后数据全丢，`samples/d2` 变成死链，
+> 导致角色与怪物立绘全部退化为占位方块。
+
+## 2. 目录内容清单
+
+共 **1.9 GB**：11 个 MPQ + 22 个 DLL（录入时间 2026-09-17 10:41~10:47）。
+
+### 2.1 引擎必需的 MPQ（`DATA_ARCHIVES` + `CHARACTER_ARCHIVE`）
+
+挂载顺序即覆盖优先级，`Patch_D2.mpq` 最高。
+
+| 文件 | 大小 | 用途 |
+| --- | ---: | --- |
+| `d2data.mpq` | 268 MB | 地图 DS1/DT1、`Levels.txt` / `MonStats.txt` / `LvlPrest.txt` 等全部表格、调色板 |
+| `d2char.mpq` | 270 MB | **角色立绘**（女法师 DCC + COF 逐层合成）——缺它角色就是方块 |
+| `d2exp.mpq` | 250 MB | 资料片（第五幕、扩展怪物与地块） |
+| `Patch_D2.mpq` | 3.9 MB | 1.13c 补丁，覆盖前三者 |
+
+### 2.2 其余 MPQ（当前引擎暂未消费，音频解码链路已具备）
+
+`d2music.mpq`(348 MB)、`d2sfx.mpq`(55 MB)、`d2speech.mpq`(163 MB)、`d2xtalk.mpq`(60 MB)、
+`D2xMusic.mpq`(55 MB)、`d2video.mpq`(442 MB)、`D2xVideo.mpq`(111 MB)。
+
+### 2.3 原版 DLL（**参考资料，不参与运行**）
+
+22 个原版 DLL 一并留存，作为逆向比对的**权威事实来源**，尤其是：
+
+| DLL | 为什么留着 |
+| --- | --- |
+| `D2Common.dll` | **DRLG 地图生成**全在这里：`DRLGOUTDOORS_GenerateLevel`、`DRLGOUTPLACE_PlaceAct1245OutdoorBorders`、`DRLGTILESUB_DoSubstitutions`。修野外悬崖拼接、迷宫房间生长时的对照基准 |
+| `D2Game.dll` | **怪物惰性填充与视距休眠/唤醒**（`bPopulated`、Active/Sleeping Room Streaming）、怪物 AI、战斗数值公式 |
+| `D2Client.dll` | 渲染与画家序、屏幕坐标换算 |
+| `D2CMP.dll` | DCC / DC6 解压参考 |
+| `Storm.dll` | MPQ 容器与 PKWARE implode 参考 |
+
+其余（`D2Win`/`D2gfx`/`D2Direct3D`/`D2Glide`/`D2DDraw`/`D2Gdi`/`D2Lang`/`D2Launch`/`D2Multi`/
+`D2Net`/`D2MCPClient`/`D2sound`/`Bnclient`/`Fog`/`binkw32`/`SmackW32`/`ijl11`）暂无直接用途，
+一并保留以免再次缺失。
+
+## 3. 多 worktree 共享
+
+本机同时存在十几个 `d2w-issue-*` / `d2w-monster-*` 工作树。**不要各拷一份**（一份 1.9 GB），
+每个工作树各自软链到同一目录即可：
+
+```bash
+for d in ~/d2w-issue-* ~/d2w-monster-* ~/d2w-wg1-main; do
+  rm -rf "$d/samples/d2"
+  ln -s /usr/local/google/home/taodao/d2-data "$d/samples/d2"
+done
+```
+
+`.gitignore` 已有 `samples/*` 与 `*.mpq` 规则，软链与数据都不会误入库。
+
+## 4. 数据到位后可解锁的流程
+
+| 命令 | 产出 | 解决的问题 |
+| --- | --- | --- |
+| `npx tsx scripts/pack-entity-assets.ts` | `samples/d2-packs/entities/`（`char-so.r8`、`monster-*.r8`） | 角色 / 怪物从占位方块变成真实 8 向立绘 |
+| `npm run pack:data` | 重烘 365 张地图到 `samples/d2-packs/` | 修正野外悬崖断层等地形问题（需先修 `wilderness.ts` 生成算法） |
+| `npm run verify:d2` | 端到端解码自检 | 确认归档可读、表格可解析 |
+| `?live=1` | 浏览器按 HTTP Range 直读归档 | 免烘焙查看任意关卡（慢，作为回退路径） |