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（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。

代码结构

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。

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

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

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

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

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. 本地跑起来

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. 部署到服务器

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）：

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. 自检命令

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）；samples/fixtures/（本项目自产）与 samples/d2-packs/（派生数据）只作为 /diablo2/assets/ 下的归档发布，不进 Git 历史。 图集包每次重烘都会让 Git 仓库再长 ~60 MB（PNG 无法 delta 压缩），所以不再入库。
• 使用本引擎需要你自己合法拥有的游戏数据。生成类关卡（70 个随机迷宫 + 31 个野外关卡）严格移植自 D2MOO / 1.13c D2Common.dll 官方参数表与 DRLG 算法复现。