# d2web

从零实现的**暗黑破坏神 II（v1.13c）Web 引擎**（纯 TypeScript + Vite + WebGL2，**零运行时依赖**），在浏览器里读取
用户自备的经典版 D2 归档（MPQ）或离线烘焙包，完整还原等距地图与 Glide 动态光影、原版等距精灵自动地图（Automap / Minimap）、七大职业 16 层角色合成、221 个原版技能、流式怪物生态、1.13c 宝藏等级（TC）掉落与未鉴定辨识系统、以及城镇 NPC 交易/赌博/修理交互。

- **仓库不含任何暴雪资源**：没有 `.mpq` / `.dc6` / `.dt1` / 地图图集 PNG；原版数据要自己放进 `samples/d2/`。
- **代码可复现一切**：格式解码、DRLG 地图构建、资源包烘焙、角色与特效合成都在这份代码里，脚本可重跑。
- 路线图、实现细节、验证方法论与未完成项在 [`ROADMAP.md`](ROADMAP.md)（README 只做总览与部署使用）。

## 总览

| 能力 | 说明 |
| --- | --- |
| **等距地图与动态光影** | DS1 + DT1 投影（2:1 dimetric，格 80×40 px），地板 / **阴影层（`type 13`）** / 墙体与场景物件（按画家序交错深度排序） / **屋顶**（进屋自动渐隐）多层绘制；SplitMix64 空间哈希 + `RarityFrameIndex` 加权选瓦片变体；**1.13c 原版 Glide 动态光照系统**（子格视线遮挡、玩家火炬、飞行投射物/爆炸动态光源、火把/火盆/小站/神殿环境光源、昼夜流转与顶部 9 档光照预设切换）；动态瓦片序列与错峰物件动画 |
| **碰撞与 A* 寻路系统** | 每格 5×5 个 sub-tile（16×8 px 各向异性）标志位（全层 OR 合并，含 `type 13` 阴影层及通用 `Blank.dt1` / `InvisWal.dt1` / `Warp.dt1` 阻挡规则），虚空越界格子全封闭保护；角色与怪物按真实阻挡子格计数梯度脱困；支持鼠标点击 A* 自动寻路移动、攻击、拾取掉落、NPC 交谈与跨图 |
| **真实关卡与世界连通** | 已烘焙 **365 张地图**，覆盖 5 幕全部 **136 个关卡 ID**（35 个预置关卡 `65` 变体 + **70 个随机迷宫 `210` 变体 + 31 个野外关卡 `90` 变体**，1:1 移植自 D2MOO / `D2Common.dll` DRLG 算法）；支持鼠标点击楼梯/洞穴入口（Warp / Entrance）切图、野外边界无缝跨越、**双向回城传送门（Town Portal，精确对齐 DS1 Object #33 城镇落点）**与跨幕**小站（Waypoint）传送网络** |
| **七大职业与角色合成** | 完整支持亚马逊（Amazon）、刺客（Assassin）、野蛮人（Barbarian）、德鲁伊（Druid）、死灵法师（Necromancer）、圣骑士（Paladin）、女巫（Sorceress）七大职业的 DCC + COF 16 层组件装配与 8 方向动画，支持顶部工具栏实时热切换职业并自动装配初始专属套装与储物箱 |
| **全技能系统（221 技能）** | 210 个各职业技能（7 职业 × 3 系 × 10 技能，已全部通过 M1–M30 全职业终极质量门禁）与 11 个通用技能（普攻/踢击/投掷/反召唤/辨识与回城卷轴和书等），严格复现 1.13c 汇编公式、协同加成（Synergies）、`AnimData.d2` 关键帧事件、149 项原版投射物/爆炸图集（零黑边加法混合）、558+ 项施法/状态/光环（含 33 个圣骑士光环）叠加特效、死灵/德鲁伊召唤物与刺客陷阱系统 |
| **怪物生态、掉落鉴定与商人交易** | 基于 `Levels.txt` / `MonStats.txt` / `SuperUniques.txt` 流式房间激活（`MonsterStreamingManager`），还原普通怪、头目（Champion `[2,4]`）、金怪（Unique `[3,6]` 随从）及全幕固定暗金 Boss（含秘密母牛关地狱母牛等 78 套实体动画包），支持实时调节怪物密度与精英倍率；完整实现 1.13c 多难度宝藏等级（TC）递归掉落、16×8 子格防卡死扇形散落、原版 `flp*.dc6` 抛物线弹跳与星光闪烁、魔法/稀有/套装/暗金**未鉴定（Unidentified）掉落与卷轴/书辨识**、以及城镇 NPC 原版对话菜单与**商人买卖/赌博/修理（`buysell.dc6`）**完整闭环 |
| **原版等距自动地图（Automap & Minimap）** | 基于 `D2Client.dll` (`0x6fb0f080..0x6fb12c28`) 逆向复现，烘焙 8 张原版 DC6 自动地图图集（`MaxiMap` / `Act2Map` / `Act4Map` / `ExTnMap` 全尺寸与半尺寸），按 `floors -> walls -> objects -> extras` 四层等距投影渲染；支持**右上角缩略小地图（`nDivisor=20`）**与**全屏自动地图（`nDivisor=10`）**双模式（面板开启自动避让/偏移）、八向距离迷雾揭露、12 段闭合多边形方向十字标（玩家/NPC/召唤物/Boss）、双向传送门与出口 `Font6` 标签及 `F9` 透明度 / `F10` 标签开关 |
| **完整 UI / HUD 交互** | 800×600 原版底栏控制台（流体红蓝血球与中毒覆盖、按技能树行序排列的 Speedbar 技能弹窗与 `F1~F8` 绑定、可展开腰带）、左/右宽屏 400px 停靠面板（背包与装备纸娃娃、角色属性面板、3 系技能树、私人储物箱、赫拉迪克方块及合成按钮、商人/赌博面板、羊皮纸任务日志、小站传送菜单）、严格对齐 `.tbl` 的中英双语词缀 Tooltip、动态手套/交易/修理/辨识专属鼠标光标、鼠标悬浮与 `Alt` 地面物品高亮标签、以及 `/players 1-8` 控制台指令 |
| **资源包（离线烘焙）** | 索引色与 32-bit RGBA PNG 图集页（≤2048²，PLTE + tRNS 取自各幕 `pal.pl2`）+ `.r8` 紧凑像素包 + `scene.json`（绘制列表、阴影层、Automap 层、碰撞 RLE、出生点、怪物与对象元数据）+ `manifest.json` |
| **按需读归档** | 也可不烘焙，直接用 HTTP Range 只拉需要的 MPQ 字节当场解码（`?live=1`，慢，作为回退路径） |
| **多维场景与调试选择器** | 顶部工具栏支持实时切换：职业 → 章节 → 场景 → 细分场景 → 光照预设（9 档） → 怪物密度（`0.5x~8x`） → 精英倍率（`0.5x~All Elite`）；中文场景名见 `src/game/level-names-zh.ts` |

**开发进展**：当前底层引擎、1:1 D2MOO DRLG 迷宫与野外地图生成、Glide 动态光影、1.13c 原版等距精灵自动地图/小地图、七大职业 221 技能、流式怪物与精英群生态、1.13c 掉落/未鉴定辨识/城镇商人交易以及全套 UI 面板已全面打通。下一步将继续推进 `.d2s` 官方二进制存档双向互通与可破坏场景物件深入演进，详见 [`ROADMAP.md`](ROADMAP.md)。

### 代码结构

```
src/mpq/       MPQ v1 容器：hash/block 表、Storm 加密、分扇区编解码、PKWARE implode/explode、ADPCM/Huffman 音频、Range 读取
src/formats/   dc6 / ds1 / dt1 / pal / pl2 / cel / pcx / tbl / sprite / dcc / cof / animdata / automap-table / bitstream
src/game/      等距场景与碰撞、关卡拓扑与跨图、DCC+COF 角色合成、怪物流式生成、1.13c 掉落/鉴定/商人系统、确定性 RNG
  drlg/        1:1 移植自 D2MOO / D2Common.dll 的 DRLG 地图生成管线（迷宫 drlg-maze、野外 drlg-outdoors/outplace/outwild、预置房间与瓦片替换）
  engine/      1.13c 真实战斗管线、AST 公式求值器、Glide 动态光照栅格（light-grid / environment）、投射物引擎、光环扫描与召唤物管理
  skills/      221 个技能的具体实现模块与注册表（uni / ama / sor / nec / pal / bar / dru / ass）
src/ui/        完整 UI / HUD 模块：原版等距自动地图与小地图（minimap）、背包、属性面板、技能树、控制底栏、小站、储物箱、方块、商人面板、任务日志、字体、鼠标指针
src/render/    WebGL2 渲染器（多图集、动态光照着色、加法/常规混合、视口裁剪；含 missiles-meta 与 overlays-meta）
src/scene/     页面级装配（act-scene 主游戏循环、A* 鼠标控制器、跨图过渡；资源包优先，失败回退到直读归档）
src/data/      1.13c 权威内嵌数据表（canonical-drop-data / canonical-tbl-strings / canonical-vendor-data / canonical-quest-data / skills-catalog / gitea-skill-issues.json）
scripts/       资源包多进程烘焙（地图/UI/动画/实体/投射物/叠加特效）、格式/数据/部署校验、无头浏览器全量走查、夹具生成
*.html         入口页面：acts.html（游戏主页面）、arena.html（战斗数值与技能竞技场）、skills.html（技能加点模拟器）、loot.html（掉落模拟器）、boss.html（幕首领战利品模拟器）
```

## 美术资源与图集资产（Assets）

项目在离线烘焙和客户端运行时划分了清晰的美术资产目录结构，所有视觉素材均可从 1.13c 原版 MPQ 自动导出与打包：

### 1. UI 界面图集、自动地图图集与面板切片 (`public/ui/` & `public/assets/ui/automap/`)

- **综合图集 (Atlases)**：
  - `items-atlas.png`：装备与物品大图集，同时包含背包/储物箱物品图标（`invfile`）与地面 2:1 等距掉落精灵（`flippyfile` / `flp*.dc6`），覆盖所有武器、防具、饰品（戒指、护身符、珠宝）、符文、药水、卷轴与金币堆，完整支持大/中/小护身符与首饰的原版 `VarInvGfx` 多视觉外观变体。
  - `quests-atlas.png`：1–5 幕全部任务状态图标图集（未触发、进行中、已完成）。
  - `skill-tree-tabs.png`：七大职业技能树的 3 系专属垂直选项卡图集（激活/未激活切片）。
- **1.13c 原版等距自动地图精灵图集 (`public/ui/automap-*.png` & `public/assets/ui/automap/`)**：
  - 完整烘焙原版 `data\global\ui\AUTOMAP\` 下的 8 张 DC6 精灵表：
    - 全屏自动地图（`nDivisor = 10`）：`MaxiMap.png`（Slot 0 基础图集）、`Act2Map.png`（Slot 1 第二幕）、`Act4Map.png`（Slot 2 第四幕）、`ExTnMap.png`（Slot 3 资料片第五幕）。
    - 右上角缩略小地图（`nDivisor = 20`）：`MaxiMapS.png`、`Act2MapS.png`、`Act4MapS.png`、`ExTnMapS.png`。
- **经典功能面板背景与控件**：
  - `ctrlpnl-800.png`：800×600 原版底栏控制台面板（包含左右技能槽底框、经验槽、腰带槽）。
  - `inv-sheet.png` / `inv-tab-0.png` / `inv-tab-1.png` / `goldcoinbtn.png`：装备纸娃娃界面与 10×4 背包网格、主副手武器切换 Tab、金币丢弃按钮。
  - `char-sheet.png`：角色属性与抗性详情面板。
  - `stash-bg.png`：营地私人储物箱面板（`TradeStash.dc6`，含顶部标题凹槽与金币槽）。
  - `cube-bg.png` / `miniconvert.png`：赫拉迪克方块（3×4 合成面板）与原版转化（Transmute）按钮。
  - `vendor-bg.png` / `vendor-tabs.png` / `buysellbtn.png`：原版 `buysell.dc6` NPC 商人交易/赌博界面、分类选项卡与买/卖/修理交互按钮。
  - `boxpieces.png` / `focus16.png`：原版 1.13c NPC 对话弹出菜单边框切片与焦点指示动画。
  - `quest-bg.png` / `quest-tabs.png`：羊皮纸任务日志背景与 1–5 幕选项卡。
  - `waypoint-bg.png` / `waypoint-tabs.png` / `waypoint-icons.png`：传送点菜单、各幕选项卡与石碑传送状态图标。
- **指示器与动态视觉元素**：
  - `globe-life.png` / `globe-mana.png` / `globe-poison.png`：经典流体红蓝血球与中毒、法力燃烧覆盖层。
  - `cursor.png` / `cursor-hand.png`：暗黑手套鼠标指针图集（包含空闲/点击状态机、商人买/卖/修理专用交易光标与辨识卷轴目标十字光标）。
  - `border-left.png` / `border-right.png` / `overlap-left.png` / `overlap-right.png`：宽屏自适应下的左右面板停靠石柱边框与过渡阴影。
  - `minipanel.png` / `minipanel-btns.png` / `popbelt.png` / `runbutton.png` / `menubutton.png` / `level-btn.png` / `skillpoints.png`：菜单微型按钮、升级加点按钮、跑步状态切换钮等。
- **原版位图字体 (`public/ui/fonts/`)**：
  - 提供 6 套暗黑 II 经典字体纹理：`font6.png`、`font8.png`、`font16.png`、`font30.png`、`fontexocet10.png`、`fontformal12.png`。

### 2. 技能树背景、技能图标与法术投射物/叠加特效图集 (`public/skills/`、`public/missiles/`、`public/overlays/`)

- **全职业技能树背景切片 (`public/skills/bg_<cls>_<tab>.png`)**：
  - 共 21 张 256×432 px 原版复古羊皮纸技能树背景原画，覆盖 7 大职业各自的 3 大技能分支：
    - 亚马逊：`bg_ama_0.png`（标枪与长矛）、`bg_ama_1.png`（被动与魔法）、`bg_ama_2.png`（弓与十字弓）
    - 刺客：`bg_ass_0.png`（武学艺术）、`bg_ass_1.png`（影子训练）、`bg_ass_2.png`（陷阱）
    - 野蛮人：`bg_bar_0.png`（战吼）、`bg_bar_1.png`（战斗专家）、`bg_bar_2.png`（战斗技能）
    - 德鲁伊：`bg_dru_0.png`（元素）、`bg_dru_1.png`（变形）、`bg_dru_2.png`（召唤）
    - 死灵法师：`bg_nec_0.png`（召唤术）、`bg_nec_1.png`（毒素与白骨）、`bg_nec_2.png`（诅咒）
    - 圣骑士：`bg_pal_0.png`（战斗技能）、`bg_pal_1.png`（攻击灵气）、`bg_pal_2.png`（防御灵气）
    - 女巫：`bg_sor_0.png`（火焰法术）、`bg_sor_1.png`（闪电法术）、`bg_sor_2.png`（冰冷法术）
- **技能图标资产 (`public/skills/icon_*.png` 与 `public/ui/`)**：
  - 包含 221 个技能的 48×48 px 原版技能图标，细分为普通态（`icon_<id>.png`）与激活/按下高光态（`icon_<id>_active.png`）。
  - 涵盖七大职业全部 210 个技能，以及 11 个通用技能（普通攻击、踢击、投掷、反召唤、辨识/回城卷轴与书、迪勒瑞姆变身等）。
  - 动态普通攻击图标：根据当前主手装备自动切换拳头图标（`icon_0_fist.png`）或武器剑图标（`icon_0_sword.png`），并具备投掷（`icon_2.png`）与反召唤（`icon_3.png`）专用图标。
- **法术投射物与爆炸图集 (`public/missiles/` & `samples/d2-packs/missiles/`)**：
  - 由 `scripts/pack-missiles.ts` 结合 `Missiles.txt` 的 `CelFile` 字段从原版 DCC 解包烘焙的 **149 套** 32-bit RGBA PNG 精灵图集与同名 `.json` 帧锚点元数据。
  - 对魔法投射物（`Trans: 1`）严格执行暗部底色零黑边过滤并在 WebGL 中以加法混合（`blendMode: 'additive'`）渲染，覆盖火焰弹/火球/陨石/九头蛇、冰弹/冰风暴/暴风雪/冰封球、充能弹/闪电链、牙齿/骨矛/骨灵、祝福之锤、标枪/箭矢与全部次生爆炸特效。
- **施法叠加层、光环与传送门特效图集 (`public/overlays/` & `samples/d2-packs/overlays/`)**：
  - 由 `scripts/pack-overlays.ts` 结合 `Overlays.txt` 从原版 DCC 解包烘焙的 **558+ 套**特效图集。
  - 涵盖各系施法前摇光效（Cast Overlays）、全部 33 个圣骑士进攻/防御光环与通用光环脚底环绕特效、死灵法师诅咒与野蛮人战吼头顶标记、德鲁伊变形/充能球、刺客聚气球，以及双向回城传送门的开启（`OP` 15 帧）与常驻（`ON` 15 帧）双层混合动画。

### 3. 角色与怪物实体动画包 (`samples/d2-packs/entities/`)

- **七大职业模型**：
  - 亚马逊（`char-am`）、刺客（`char-ai`）、野蛮人（`char-ba`）、德鲁伊（`char-dz`）、死灵法师（`char-ne`）、圣骑士（`char-pa`）、女巫（`char-so`）。
  - 由 16 个装备图层复合装配，解包出行走（`wl`）、跑动（`rn`）、待机（`nu`）、近战/远程攻击（`a1`/`a2`）、施法（`sc`）、受击（`gh`）、死亡（`dt`/`dd`）等 8 方向完整序列。
  - 伴随同名 `.r8` 紧凑二进制像素包，用于在 WebGL/Canvas 中零拷贝极速解码渲染。
- **怪物与召唤物实体模型（共 78 套实体包）**：
  - 包含沉沦魔（Fallen）、骷髅（Skeleton）、僵尸（Zombie）、血鸟（Blood Raven）、格瑞斯华尔德（Griswold）、安达利尔（Andariel）、督瑞尔（Duriel）、墨菲斯托（Mephisto）、暗黑破坏神（Diablo）、巴尔（Baal）、秘密母牛关地狱母牛（Hell Bovine，`hellbovine`）等各幕常规怪物、固定暗金头目（SuperUniques）及其随从、死灵/德鲁伊/亚马逊/刺客召唤物的完整动画包与 `.r8` 调色板像素数据。

### 4. 场景瓦片图集 (`samples/d2-packs/act[1-5]/`)

- 365 个地图场景（65 个预置场景、210 个随机迷宫变体、90 个野外场景变体）分块切片图集，每个图集包含 ≤2048² 尺寸的索引色 PNG 瓦片页（地板层、阴影层、墙体层、屋顶层与场景物件层），附带 PLTE 调色板与透明度表。

## 结构化数据与 JSON 规范（Data & JSON）

引擎采用结构化 JSON 与内嵌权威数据表来驱动界面排版、图集映射、场景还原与游戏逻辑：

### 1. `public/ui/manifest.json` & `src/ui/baked-ui-meta.ts`（UI 与自动地图图集总清单）
由 `scripts/pack-ui.ts` 自动烘焙生成，为 UI 与自动地图系统提供像素级定位映射：
- `atlasWidth` / `atlasHeight`：`items-atlas.png` 装备与地面物品图集的分辨率规格。
- `questsAtlasWidth` / `questsAtlasHeight`：`quests-atlas.png` 任务图集的分辨率规格。
- `codeToInvFile` / `itemRects`：物品 3 字母代码到背包图标文件名的映射与 UV 矩形坐标表（`{ x, y, w, h }`），支持戒指、项链、珠宝和护身符的 `VarInvGfx` 多变体定位。
- `codeToFlippyFile` / `flippyRects`：物品代码到地面掉落精灵（`flp*.dc6`）的映射与 UV 坐标表，支撑地面真实 2:1 等距物品渲染。
- `automapAtlases`：8 张原版自动地图精灵表（`MaxiMap` / `MaxiMapS` / `Act2Map` / `Act2MapS` / `Act4Map` / `Act4MapS` / `ExTnMap` / `ExTnMapS`）的全部帧 UV 与 DC6 基线锚点偏移（`offsetX` / `offsetY`）。
- `questRects` & `images`：1–5 幕任务日志切片与各独立 UI 面板背景、边框、按键在 `public/ui/` 下的文件索引。

### 2. `public/ui/fonts/metrics.json`（位图字体排版度量）
- 记录 6 套经典字体（Exocet、Formal、Font6/8/16/30）的字形度量参数。
- 包含每个 ASCII 字符在字体图集上的矩形包围盒、字宽（`charWidths`）、字符高度、基线偏移与字间距（Kerning），为游戏内悬浮 Tooltip、装备描述、小地图标签和任务日志提供完全原版的排版效果。

### 3. `samples/d2-packs/index.json`（全关卡全局场景目录）
- 记录全游戏 5 幕 365 个地图块的元数据。
- 包含字段：章节编号（Act 1..5）、关卡 ID（Level ID 1..136）、内部场景标识、关卡类型（预置场景 `preset` / 随机迷宫 `maze` / 野外关卡 `wilderness`）、网格尺寸（Grid Bounds）、可用变体数（Variants）与对应的烘焙目录相对路径。

### 4. `samples/d2-packs/world-graph.json`（世界拓扑连通网络图）
- 从 `Levels.txt` 的连接参数（`Vis0..7`、`Warp0..7`）生成的全局世界拓扑图。
- 记录场景之间的连通边（Edges）、传送点（Waypoints）分布、楼梯/洞穴出入口（Warps）、野外边界开放开口（Perimeter Openings），支撑自动地图标注与跨关卡无缝切换。

### 5. `samples/d2-packs/anim/animdata.json`（动画关键帧事件权威表）
由 `scripts/pack-animdata.ts` 直接解析 1.13c `AnimData.d2` 二进制文件（570,304 字节，3,558 条记录）生成：
- 记录每个动作 Hash 的播放帧率（Frame Speed）、总帧数（Total Frames）。
- 精确解析动作事件标志位：`0x01` 判定为近战命中/施法触发判定帧，`0x02` 判定为投射物（Missile）发射事件帧，确保 25Hz 动作逻辑与原版单机完全一致。

### 6. `samples/d2-packs/anim/monstats2.json`（怪物组件与动画模式配置）
- 结构化提取自 `MonStats2.txt`。
- 记录所有怪物的身体构成组件、图层合成规则、各武器模式下的动作代码映射（如 `hth`、`1hs`、`2ht`、`bow`）。

### 7. `samples/d2-packs/entities/char-*.json` 与 `monster-*.json`（实体模型定义）
- 描述 7 大角色职业与 71 种怪物/召唤物的骨骼装配结构。
- 包含复合图层映射、8 方向动作切片元数据、每帧中心偏移（Pivot），搭配同名 `.r8` 文件在渲染管线中执行高效逐像素着色。

### 8. `samples/d2-packs/act<N>/<level>/scene.json` & `manifest.json`（单场景规格）
- `manifest.json`：当前场景所需的瓦片图集页清单与调色板信息。
- `scene.json`：记录等距地图的地板（`floors`）、阴影（`shadows`，`type 13`）、墙体（`walls`）、屋顶（`roofs`）与场景物件（`objectDrawables`）绘制列表、经 `Automap.txt` 规则预映射的自动地图四层单元格数据（`automap`）、采用 RLE 压缩的 5×5 子格碰撞阻挡网格（`grid`），以及出生点、小站、跨图入口与预设怪物群（`monsterPacks`）。

### 9. `src/data/canonical-*.ts` & `src/render/*-meta.ts`（1.13c 权威内嵌数据表）
- `canonical-drop-data.ts`：完整内嵌 `Weapons.txt`、`Armor.txt`、`Misc.txt`、`TreasureClassEx.txt`、`ItemRatio.txt`、`UniqueItems.txt`、`SetItems.txt`、`MagicPrefix/Suffix.txt`、`MonStats.txt` 与 `SuperUniques.txt` 多难度掉落与属性表。
- `canonical-tbl-strings.ts`：从原版 `string.tbl`、`expansionstring.tbl`、`patchstring.tbl` 提取的官方物品、词缀、怪物与技能名称字典。
- `canonical-vendor-data.ts` & `canonical-quest-data.ts`：各幕城镇 NPC 商人库存生成规则与 1–5 幕任务文本数据。
- `missiles-meta.ts` & `overlays-meta.ts`：投射物、爆炸、施法叠加层与光环图集的帧序列及锚点注册表。

## 部署与使用

### 1. 前置：自备游戏数据

把你自己合法拥有的**经典版暗黑破坏神 II（1.13c）** 数据放进 `samples/d2/`，至少需要
`d2data.mpq`、`d2char.mpq`、`d2exp.mpq`、`Patch_D2.mpq`。资源包模式（页面默认）只需要
`samples/d2-packs/`——它不在 Git 里，按下面的「资源包从哪来」下载解包后，**没有原版数据也能直接运行全部烘焙地图与角色战斗**。

`samples/d2/` 通常做成软链接，指向一个**磁盘上的持久目录**。切勿链到 `/tmp`——它是内存盘，
重启即清空，链接会变死链而角色/怪物退化成占位方块。本机的实际摆放、清单与逆向参考用的原版
DLL 见 [`docs/LOCAL_DATA.md`](docs/LOCAL_DATA.md)。

### 2. 资源包从哪来（不在 Git 里）

烘焙资源包（365 个地图块 / 136 关、78 套角色与怪物实体、投射物与叠加特效图集、动画表与世界拓扑图）**不在本仓库里**——因为索引色与 RGBA PNG 无法被 git 的 delta 压缩，随代码仓库分发会让每次重烘都使仓库体积暴涨。它放在独立的**图库仓库**，那里刻意**只保留一个提交**（每次重烘 orphan 提交 + force push），体积恒定在「一份快照」：

```bash
git clone https://git.projectdiablo2.cn/troytt/diablo2-web-assets.git samples/d2-packs
```

只想要一份压缩包（不需要 git）：

```bash
curl -O https://www.laiseek.xyz/diablo2/assets/d2-packs-2026-09-14.tar.xz
sha256sum d2-packs-2026-09-14.tar.xz   # 应为 9cdfd0c19ac68de842c6725070b65d056e25f5bcc77f36d6d9a29cd9f1b431e8
tar xJf d2-packs-2026-09-14.tar.xz     # 解出 samples/d2-packs/
```

仓库里只保留 `.gitignore` 规则与本文档；要自己生成包就照第 3 步从原版 MPQ
烘焙，再用 `npm run publish:packs` 发布到图库仓库（脚本会自动打包地图、动画、实体、投射物、叠加层与世界图并重建单提交历史）。

### 3. 本地跑起来

```bash
npm install                                          # 仅 vite / typescript / tsx / vitest / @types/node
tsx scripts/make-fixtures.ts     samples/fixtures    # 夹具：DC6 + 调色板 + 文本表
tsx scripts/make-map-fixtures.ts samples/fixtures    # 夹具：DT1 + DS1 + 夹具 MPQ
npm run pack:data                                    # 从 samples/d2/ 烘焙 365 场景图集与 Automap 层 → samples/d2-packs
npm run pack:ui                                      # 烘焙 UI 综合图集、地面物品图集、8 张 Automap 图集与 manifest.json
npm run pack:animdata                                # 烘焙 AnimData.d2 与 monstats2.json
npm run pack:entities                                # 多进程并发烘焙 7 大职业模型与 71 套怪物/召唤物实体动画包
npm run pack:missiles                                # 烘焙 149 套法术投射物与爆炸 RGBA 图集及 missiles-meta.ts
npm run pack:overlays                                # 烘焙 558+ 套施法叠加层、光环与传送门图集及 overlays-meta.ts
npm run dev                                          # 启动 Vite：http://127.0.0.1:5173/acts.html
```

`pack:*` 系列脚本需要原版 MPQ；只用上面下载来的 `samples/d2-packs/` 可以跳过烘焙步骤直接 `npm run dev`，
代价是 `?live=1` 与重新烘焙不可用。

### 4. 页面与操作

| 页面 | 用途 |
| --- | --- |
| `/acts.html`（或访问根路径 `/`） | **主游戏页面**：全屏 WebGL2 画布 + Glide 动态光影 + 等距精灵自动地图/小地图 + HUD 控制底栏 + 左右停靠全套功能面板 + 7 职业漫步战斗与打宝交易 |
| `/arena.html` | **战斗数值与技能测试竞技场**：攻防数值数学模型、技能加成、伤害计算器（1.13c 原版公式验证） |
| `/skills.html` | **全职业技能加点模拟器**：7 大职业 210 个技能树加点、协同加成与 1.13c 技能数值实时预览 |
| `/loot.html` | **掉落模拟器与精确概率计算器**：Maxroll 风格宝藏等级（TC）掉落模拟、MF 收益曲线与物品概率查询 |
| `/boss.html` | **幕首领击杀与战利品属性模拟器**：五幕首领击杀掉落模拟与暗金/套装/词缀属性检视 |

#### 页面查询参数（`/acts.html`）

```
?hero=so|am|ne|pa|ba|dz|ai   指定初始职业（女巫/亚马逊/死灵/圣骑/野蛮人/德鲁伊/刺客）
?act=1..5                    指定章节（1..5）
?level=<地图块 label>         直接指定细分场景，如 33-act-1-cathedral-cathy3
?lighting=auto|noon|morning|sunset|night|cave|hell|eclipse|off   指定场景光照预设
?density=0.5|1|2|4|8         指定怪物密度倍率（默认 1，即 1.13c 原版密度）
?elite=0.5|1|2|4|all         指定精英怪（头目/金怪）生成倍率
?quadrant=<DS1 名>           直读归档模式下指定该关卡的某个 DS1
?live=1                      不走资源包，直接按 HTTP Range 读 MPQ 解码（慢）
?pack=<目录>                 换一个资源包目录      ?base=<目录>   换一个归档目录
?arena=1&class=<cls>&skill=<id>&slvl=<lvl>&autocast=1   启动竞技场自动验证模式
```

#### 完整操作快捷键

- **移动、交互与视口**：
  - **鼠标左键点击**：A* 自动寻路移动、近战/左键技能攻击怪物、拾取地面掉落物品/金币、点击城镇 NPC 弹出对话菜单（交谈/交易/赌博/修理）、点击储物箱/小站/双向传送门交互、**点击楼梯/洞穴口（Warp / Entrance）切换关卡**
  - **鼠标右键点击**：向鼠标方向施放当前选中的右手技能；在背包中**右击回城之书/卷轴**开启双向回城传送门，**右击辨识之书/卷轴**切换为辨识十字光标后左击未鉴定装备完成鉴定，**右击药水**直接饮用
  - 方向键（当全屏自动地图未开启时）：按等距屏幕方向移动角色
  - 鼠标滚轮 或 `+` / `-`：视口无级缩放；`0`：缩放复位
- **自动地图与小地图（Automap & Minimap）**：
  - `Tab` / `M`：开启 / 关闭自动地图（默认开启右上角缩略小地图）
  - `V`：在**右上角缩略小地图（Corner Minimap，`nDivisor=20`）**与**全屏自动地图（Full-Screen Automap，`nDivisor=10`）**之间切换
  - `F9`：循环切换自动地图 3 档透明度（`100%` → `75%` → `50%`）
  - `F10`：开启 / 关闭自动地图上的友方名称与出口目的地文字标签
  - 方向键（全屏自动地图开启时）：平移全屏自动地图视口（每步 `±8px`）；`Home`：重置自动地图平移偏移
- **功能面板（宽屏左右停靠）**：
  - `I` / `B`：开启 / 关闭背包与装备纸娃娃面板（右停靠）
  - `A` / `C`：开启 / 关闭角色属性面板（左停靠）
  - `T` / `S`：开启 / 关闭技能树面板（右停靠，3 系垂直选项卡切换与加点）
  - `Q`：开启 / 关闭任务日志面板（左停靠，按幕查看真实任务状态）
  - `P`：快捷施放双向回城传送门（Town Portal）
  - `Esc` / `Space`：关闭当前开启的所有停靠面板、商人界面与弹出层
- **战斗与技能快捷栏**：
  - 点击底栏左 / 右技能槽图标：打开向上展开的 Speedbar 技能选择弹窗（按技能树行序排列）
  - 鼠标悬浮在 Speedbar 技能上按 `F1` ~ `F8`：绑定技能快捷键；在游戏过程中按 `F1` ~ `F8`：即时切换对应技能
  - `Shift`（按住）：强制原地站立攻击 / 施法（Force Stand Still）
  - `1` ~ `4`：快捷饮用腰带第 1 ~ 4 列药水；`~` / `` ` ``：展开 / 折叠 4×4 腰带弹窗
  - `Alt`（按住）或鼠标悬浮地面物品：高亮显示地面掉落物品名称标签（带防重叠阶梯排布）
  - `R`：切换跑步 / 走路模式
  - `W`：主副手武器切换（`I` / `II` 套）
- **控制台与调试功能**：
  - `Enter`：打开游戏内聊天/控制台输入框，支持输入 `/players 1` ~ `/players 8` 动态调整游戏人数难度与掉落率
  - 顶部工具栏下拉菜单：实时热切换 **7 大职业（`#hero`）**、**章节与细分场景**、**9 档场景光照预设（`#lighting`）**、**怪物密度（`#density`）** 与 **精英倍率（`#elite`）**
  - `K` / `L`：快速保存 / 读取 `localStorage` 角色快照存档

### 5. 部署到服务器

```bash
npm run build:game                # → dist-game/（base=/diablo2/）
rm -rf /var/www/d2web   && mkdir -p /var/www/d2web   && cp -r dist-game/.       /var/www/d2web/
rm -rf /var/www/d2packs && mkdir -p /var/www/d2packs && cp -r samples/d2-packs/. /var/www/d2packs/
mkdir -p /var/www/d2data && ln -f samples/d2/*.mpq /var/www/d2data/     # 只有 ?live=1 用得到
```

nginx（`/etc/nginx/sites-enabled/default`）：

```nginx
location = /diablo2  { return 301 /diablo2/; }
location = /diablo2/ { rewrite ^ /diablo2/acts.html last; }
location /diablo2/   { alias /var/www/d2web/; autoindex off; add_header Cache-Control 'no-store'; }

location /diablo2/packs/ {                       # 资源包：可缓存
    alias /var/www/d2packs/;
    autoindex off;
    add_header Cache-Control 'public, max-age=3600';
}

location ~ ^/diablo2/data/(?<d2file>[A-Za-z0-9_.-]+\.mpq)$ {   # 只暴露 .mpq，不列目录
    alias /var/www/d2data/$d2file;
    autoindex off;
    add_header Accept-Ranges bytes;
    add_header Cache-Control 'public, max-age=3600';
}
```

要点：归档必须支持 **Range**（否则页面会退化成整文件下载）；`/root` 是 0700，所以用硬链接暴露给 nginx。
部署后跑 `npm run verify:deploy` 自检。

### 6. 自检命令

```bash
npm run verify:deploy         # 线上：页面 / 资源包索引 / 图集 / Range 206 / 旧入口 410
npm run verify:packs          # 资源包与"现读现解"逐项比对（绘制序、阴影层、碰撞栅格逐字节、每帧像素哈希）
npm run verify:entity-packs   # 校验 7 大职业与全部怪物实体动画包及 .r8 像素数据完整性
npm run verify:generators     # 校验 1:1 D2MOO DRLG 迷宫与野外地图生成器（缺瓦片率 0.00%，连通可达率 100%）
npm run verify:world-graph    # 校验全 5 幕世界拓扑连通图（Vis0..7 / Warp0..7 / 小站与边界开口）
npm run verify:world-walk     # 校验跨关卡行走、楼梯切图、双向回城传送门与小站传送网络
npm run verify:monsters       # 校验 Levels.txt 怪物群生成、头目/金怪精英配比与 SuperUniques 固定头目
npm run verify:tiles          # 每个槽位画的是不是该有的瓦片类型（地面=type 0）+ 位置公式
npm run verify:alignment      # 墙 / 地面基线、屋顶偏移与引擎公式一致
npm run verify:object-lookup  # DS1 对象 id → token/mode 与 Objects.txt 交叉核对
npm run verify:acts           # 关卡表 → DS1 → DT1 → 等距场景 + 碰撞
npm run verify:d2             # 真 MPQ 数据端到端解码
npm run verify:implode        # PKWARE implode 解码器（全成员）
npm run verify:all            # 综合校验：战斗 / 物品 / 任务 / 存档 / 网络 / 碰撞方向 / TBL / 音频 / 格式
tsx scripts/verify-automap.ts # 校验 1.13c 等距精灵自动地图（Automap.txt 映射、8 图集烘焙、双模式渲染与交互）
npm run typecheck             # tsc --noEmit（0 errors 门禁）
npm test                      # 运行 Vitest 完整测试套件
```

## 数据与许可

- 仓库**不含**暴雪美术：原版 MPQ、`reference/` 下的第三方参考源码都不入库（规则写在 `.gitignore` 与
  [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)）；`samples/fixtures/`（本项目自产）与
  `samples/d2-packs/`（派生数据）只作为 `/diablo2/assets/` 下的归档发布，不进 Git 历史。
  图集包每次重烘都会让 Git 仓库再长 ~60 MB（PNG 无法 delta 压缩），所以不再入库。
- 使用本引擎需要你自己合法拥有的游戏数据。生成类关卡（70 个随机迷宫 + 31 个野外关卡）严格移植自 D2MOO / 1.13c `D2Common.dll` 官方参数表与 DRLG 算法复现。