From 2a93677e5274a28c998d54a61d38bdc5d2890473 Mon Sep 17 00:00:00 2001 From: troytt <47798984@qq.com> Date: Mon, 28 Sep 2026 01:49:31 +0000 Subject: [PATCH] docs(readme): update README with latest 1.13c features, assets, pages, and controls --- README.md | 217 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 128 insertions(+), 89 deletions(-) diff --git a/README.md b/README.md index 30d741d..384a4bc 100644 --- a/README.md +++ b/README.md @@ -1,72 +1,80 @@ # d2web -从零实现的**暗黑破坏神 II 引擎**（纯 TypeScript + Vite + WebGL2，**零运行时依赖**），在浏览器里读取 -用户自备的经典版 D2 归档（MPQ），渲染等距地图、驱动角色走动、释放 221 个原版技能，并支持把地图与模型离线烘焙成 web 原生格式。 +从零实现的**暗黑破坏神 II（v1.13c）Web 引擎**（纯 TypeScript + Vite + WebGL2，**零运行时依赖**），在浏览器里读取 +用户自备的经典版 D2 归档（MPQ）或离线烘焙包，完整还原等距地图与 Glide 动态光影、原版等距精灵自动地图（Automap / Minimap）、七大职业 16 层角色合成、221 个原版技能、流式怪物生态、1.13c 宝藏等级（TC）掉落与未鉴定辨识系统、以及城镇 NPC 交易/赌博/修理交互。 -- **仓库不含任何暴雪资源**：没有 `.mpq` / `.dc6` / `.dt1` / 图集 PNG；原版数据要自己放进 `samples/d2/`。 -- **代码可复现一切**：格式解码、地图构建、资源包烘焙、角色合成都在这份代码里，脚本可重跑。 +- **仓库不含任何暴雪资源**：没有 `.mpq` / `.dc6` / `.dt1` / 地图图集 PNG；原版数据要自己放进 `samples/d2/`。 +- **代码可复现一切**：格式解码、DRLG 地图构建、资源包烘焙、角色与特效合成都在这份代码里，脚本可重跑。 - 路线图、实现细节、验证方法论与未完成项在 [`ROADMAP.md`](ROADMAP.md)（README 只做总览与部署使用）。 ## 总览 | 能力 | 说明 | | --- | --- | -| **等距地图渲染** | DS1 + DT1 投影（2:1 dimetric，格 80×40 px），地板 / 墙 / **屋顶** 三层分别绘制；逐格按 `RarityFrameIndex` 加权随机选瓦片变体；画家序排序 | -| **碰撞系统** | 每格 5×5 个 sub-tile 标志位（一层内所有层做 OR 合并，含 `type 13` 影子层），角色按 sub-tile 判定走位，支持沿梯度脱困 | -| **真实关卡** | 已烘焙 **365 张地图**，覆盖 5 个 act：35 个预置关卡（罗格营地、修道院、大教堂、地下墓穴、鲁高因、库拉斯特码头、哈洛加斯…）+ **70 个随机迷宫 + 31 个野外关卡**（生成逻辑移植自 D2MOO，按官方参数表复现） | -| **七大职业与角色合成** | 完整支持亚马逊（Amazon）、刺客（Assassin）、野蛮人（Barbarian）、德鲁伊（Druid）、死灵法师（Necromancer）、圣骑士（Paladin）、女巫（Sorceress）七大职业的 DCC + COF 16 层组件装配与 8 方向动画，支持游戏中实时切换职业与初始专属装备 | -| **全技能系统（221 技能）** | 210 个各职业技能（每职业 3 系 × 10 技能）与 11 个通用玩家技能（普攻/踢击/投掷/反召唤/辨识/回城等），严格复现 1.13c 公式、协同加成（Synergies）、投射物引擎、光环扫描与延迟机制 | -| **完整 UI / HUD 交互** | 800×600 原版底栏控制台（红蓝血球与中毒覆盖、技能快捷槽、腰带）、左/右宽屏 400px 停靠面板（背包、纸娃娃、属性面板、技能树、储物箱、方块、任务日志、传送点菜单）、动态鼠标指针、Alt 物品高亮等 | -| **资源包（离线烘焙）** | 索引色 PNG 图集页（≤2048²，PLTE + tRNS 取自该 act 的 `pal.pl2`）+ `scene.json`（绘制列表、碰撞 RLE、出生点、对象元数据）+ `manifest.json` | +| **等距地图与动态光影** | 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`，慢，作为回退路径） | -| **三级关卡选择器** | 章节 → 场景 → 细分场景（如 第一章 / 罗格营地 / 北）；中文场景名见 `src/game/level-names-zh.ts` | +| **多维场景与调试选择器** | 顶部工具栏支持实时切换：职业 → 章节 → 场景 → 细分场景 → 光照预设（9 档） → 怪物密度（`0.5x~8x`） → 精英倍率（`0.5x~All Elite`）；中文场景名见 `src/game/level-names-zh.ts` | -**开发进展**：当前底层引擎、七大职业表现、221 技能完整实现与全套 UI 面板已全面打通。下一步将深入完善野外怪物密度与 AI 行为、装备词缀掉落平衡与 `.d2s` 官方存档双向互通，详见 [`ROADMAP.md`](ROADMAP.md)。 +**开发进展**：当前底层引擎、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、Range 读取 -src/formats/ dc6 / ds1 / dt1 / pal / pl2 / cel / pcx / tbl / sprite / dcc / cof / bitstream -src/game/ 等距场景与碰撞、关卡表解析、DCC+COF 角色合成、对象与物品解析、确定性 RNG - engine/ 1.13c 真实战斗引擎、AST 公式求值器、状态机、投射物调度、光环与召唤物管理 - skills/ 221 个技能的具体实现模块（uni / ama / sor / nec / pal / bar / dru / ass） -src/ui/ 完整 UI / HUD 模块：背包、属性面板、技能树、控制底栏、传送点、储物箱、任务日志、字体、鼠标指针 -src/render/ WebGL2 渲染器（多图集；纹理切换时 flush 以保画家序） -src/scene/ 页面级装配（资源包优先，失败回退到直读归档） -src/data/ 技能目录、Gitea 跟踪 Issue 数据库、掉落表与任务官方文本数据 -scripts/ 资源包烘焙、格式/数据/部署校验、无头浏览器检查、夹具生成 -*.html 主入口页面：acts.html（游戏全功能主页面）、arena.html（数值与技能验证竞技场） +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/`) +### 1. UI 界面图集、自动地图图集与面板切片 (`public/ui/` & `public/assets/ui/automap/`) - **综合图集 (Atlases)**： - - `items-atlas.png`：装备与物品大图集，覆盖所有武器、防具、饰品（戒指、护身符、珠宝）、符文、药水等，完整支持大/中/小护身符与首饰的原版 `VarInvGfx` 多视觉外观变体。 + - `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`：装备纸娃娃界面与 10×4 背包网格、主副手武器切换 Tab。 + - `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`：营地私人储物箱面板（6×8 格子）。 - - `cube-bg.png`：赫拉迪克方块（3×4 合成面板）。 - - `vendor-bg.png` / `buysellbtn.png`：NPC 商人交易界面与买卖交互按钮。 + - `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`：硬件感暗黑手套鼠标指针（支持空闲状态机与点击动作动画）。 + - `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`：菜单微型按钮、升级提示羽毛球、跑步状态切换钮等。 + - `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/ui/`) +### 2. 技能树背景、技能图标与法术投射物/叠加特效图集 (`public/skills/`、`public/missiles/`、`public/overlays/`) - **全职业技能树背景切片 (`public/skills/bg__.png`)**： - 共 21 张 256×432 px 原版复古羊皮纸技能树背景原画，覆盖 7 大职业各自的 3 大技能分支： @@ -81,44 +89,50 @@ scripts/ 资源包烘焙、格式/数据/部署校验、无头浏览器检 - 包含 221 个技能的 48×48 px 原版技能图标，细分为普通态（`icon_.png`）与激活/按下高光态（`icon__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 个装备图层复合装配，解包出行走、跑动、各种武器攻击、施法、受击、死亡等 8 方向完整序列。 + - 由 16 个装备图层复合装配，解包出行走（`wl`）、跑动（`rn`）、待机（`nu`）、近战/远程攻击（`a1`/`a2`）、施法（`sc`）、受击（`gh`）、死亡（`dt`/`dd`）等 8 方向完整序列。 - 伴随同名 `.r8` 紧凑二进制像素包，用于在 WebGL/Canvas 中零拷贝极速解码渲染。 -- **怪物实体模型**： - - 包含沉沦魔（Fallen）、骷髅（Skeleton）、僵尸（Zombie）、血鸟（Blood Raven）、督瑞尔（Duriel）、安达利尔（Andariel）、墨菲斯托（Mephisto）、暗黑破坏神（Diablo）、巴尔（Baal）等数十种怪物的完整动画包与 `.r8` 调色板像素数据。 +- **怪物与召唤物实体模型（共 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 个地图场景分块切片图集，每个图集包含 ≤2048² 尺寸的索引色 PNG 瓦片页（地板层、墙体层、屋顶层），附带 PLTE 调色板与透明度表。 +- 365 个地图场景（65 个预置场景、210 个随机迷宫变体、90 个野外场景变体）分块切片图集，每个图集包含 ≤2048² 尺寸的索引色 PNG 瓦片页（地板层、阴影层、墙体层、屋顶层与场景物件层），附带 PLTE 调色板与透明度表。 ## 结构化数据与 JSON 规范（Data & JSON） -引擎采用结构化 JSON 数据来驱动界面排版、图集映射、场景还原与游戏逻辑： +引擎采用结构化 JSON 与内嵌权威数据表来驱动界面排版、图集映射、场景还原与游戏逻辑： -### 1. `public/ui/manifest.json`（UI 资源与图集总清单） -由 `scripts/pack-ui.ts` 自动烘焙生成，为 UI 系统提供像素级定位映射： -- `atlasWidth` / `atlasHeight`：`items-atlas.png` 装备图集的分辨率规格。 +### 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`：物品 3 字母代码（如 `rin`、`amu`、`cm1`、`hpot`）到原版 MPQ 图像文件名的映射表。 -- `itemRects`：所有物品及装备的 UV 矩形坐标表（`{ x, y, w, h }`），针对戒指、项链、珠宝和护身符支持 `VarInvGfx` 多图集变体定位。 -- `questRects`：1–5 幕任务日志在图集中的坐标切片。 -- `images`：各种独立 UI 面板背景、边框、按键在 `public/ui/` 下的文件索引。 +- `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、装备描述和任务日志提供完全原版的排版效果。 +- 包含每个 ASCII 字符在字体图集上的矩形包围盒、字宽（`charWidths`）、字符高度、基线偏移与字间距（Kerning），为游戏内悬浮 Tooltip、装备描述、小地图标签和任务日志提供完全原版的排版效果。 ### 3. `samples/d2-packs/index.json`（全关卡全局场景目录） - 记录全游戏 5 幕 365 个地图块的元数据。 -- 包含字段：章节编号（Act 1..5）、关卡 ID（Level ID）、内部场景标识、关卡类型（预置场景 Preset / 随机迷宫 Maze / 野外关卡 Wilderness）、网格尺寸（Grid Bounds）、可用变体数（Variants）与对应的烘焙目录相对路径。 +- 包含字段：章节编号（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），支撑小地图与跨关卡传送切换。 +- 记录场景之间的连通边（Edges）、传送点（Waypoints）分布、楼梯/洞穴出入口（Warps）、野外边界开放开口（Perimeter Openings），支撑自动地图标注与跨关卡无缝切换。 ### 5. `samples/d2-packs/anim/animdata.json`（动画关键帧事件权威表） 由 `scripts/pack-animdata.ts` 直接解析 1.13c `AnimData.d2` 二进制文件（570,304 字节，3,558 条记录）生成： @@ -130,15 +144,18 @@ scripts/ 资源包烘焙、格式/数据/部署校验、无头浏览器检 - 记录所有怪物的身体构成组件、图层合成规则、各武器模式下的动作代码映射（如 `hth`、`1hs`、`2ht`、`bow`）。 ### 7. `samples/d2-packs/entities/char-*.json` 与 `monster-*.json`（实体模型定义） -- 描述 7 大角色职业与数十种怪物的骨骼装配结构。 +- 描述 7 大角色职业与 71 种怪物/召唤物的骨骼装配结构。 - 包含复合图层映射、8 方向动作切片元数据、每帧中心偏移（Pivot），搭配同名 `.r8` 文件在渲染管线中执行高效逐像素着色。 ### 8. `samples/d2-packs/act//scene.json` & `manifest.json`（单场景规格） - `manifest.json`：当前场景所需的瓦片图集页清单与调色板信息。 -- `scene.json`：记录等距地图的地板（Floor）、墙体（Wall）、屋顶（Roof）多层瓦片绘制列表与深度排序，采用 RLE 压缩的 5×5 子格碰撞阻挡网格（Collision Grid），以及预置对象（储物箱、石碑、传送门、出生点）。 +- `scene.json`：记录等距地图的地板（`floors`）、阴影（`shadows`，`type 13`）、墙体（`walls`）、屋顶（`roofs`）与场景物件（`objectDrawables`）绘制列表、经 `Automap.txt` 规则预映射的自动地图四层单元格数据（`automap`）、采用 RLE 压缩的 5×5 子格碰撞阻挡网格（`grid`），以及出生点、小站、跨图入口与预设怪物群（`monsterPacks`）。 -### 9. `src/data/gitea-skill-issues.json`（技能跟踪数据库） -- 建立 221 个技能与开发追踪系统的双向索引映射，包含 Skill ID、英文名称、职业缩写、Slug 标识与对应的 Issue/Milestone 编号。 +### 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`：投射物、爆炸、施法叠加层与光环图集的帧序列及锚点注册表。 ## 部署与使用 @@ -146,7 +163,7 @@ scripts/ 资源包烘焙、格式/数据/部署校验、无头浏览器检 把你自己合法拥有的**经典版暗黑破坏神 II（1.13c）** 数据放进 `samples/d2/`，至少需要 `d2data.mpq`、`d2char.mpq`、`d2exp.mpq`、`Patch_D2.mpq`。资源包模式（页面默认）只需要 -`samples/d2-packs/`——它不在 Git 里，按下面的「资源包从哪来」下载解包后，**没有原版数据也能看地图**。 +`samples/d2-packs/`——它不在 Git 里，按下面的「资源包从哪来」下载解包后，**没有原版数据也能直接运行全部烘焙地图与角色战斗**。 `samples/d2/` 通常做成软链接，指向一个**磁盘上的持久目录**。切勿链到 `/tmp`——它是内存盘， 重启即清空，链接会变死链而角色/怪物退化成占位方块。本机的实际摆放、清单与逆向参考用的原版 @@ -154,10 +171,7 @@ DLL 见 [`docs/LOCAL_DATA.md`](docs/LOCAL_DATA.md)。 ### 2. 资源包从哪来（不在 Git 里） -图集包（62 个地图块 / 35 关，索引色 PNG + `scene.json`）**不在本仓库里**——它是 ~66 MB 的索引色 -PNG，每次重烘几乎全部文件都变，而 PNG 无法被 git 的 delta 压缩，随仓库分发会让每烘焙一次仓库再长 -~60 MB。它放在**图库仓库**，那里刻意**只保留一个提交**（每次重烘 orphan 提交 + force push）， -体积恒定在「一份快照」： +烘焙资源包（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 @@ -171,66 +185,84 @@ sha256sum d2-packs-2026-09-14.tar.xz # 应为 9cdfd0c19ac68de842c6725070b65d05 tar xJf d2-packs-2026-09-14.tar.xz # 解出 samples/d2-packs/ ``` -仓库里只保留 `.gitignore` 规则与本文档；要自己生成包就照第 3 步 `npm run pack:data` 从原版 MPQ -烘焙，再用 `npm run publish:packs` 发布到图库仓库（脚本会重建单提交历史）。 +仓库里只保留 `.gitignore` 规则与本文档；要自己生成包就照第 3 步从原版 MPQ +烘焙，再用 `npm run publish:packs` 发布到图库仓库（脚本会自动打包地图、动画、实体、投射物、叠加层与世界图并重建单提交历史）。 ### 3. 本地跑起来 ```bash -npm install # 仅 vite / typescript / @types/node +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 场景图集 → samples/d2-packs -npm run pack:ui # 烘焙 UI 综合图集与 manifest.json +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 大职业模型与怪物实体动画包 +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:data` 需要原版 MPQ（约 2 分钟）；只用上面下载来的 `samples/d2-packs/` 可以跳过它， +`pack:*` 系列脚本需要原版 MPQ；只用上面下载来的 `samples/d2-packs/` 可以跳过烘焙步骤直接 `npm run dev`， 代价是 `?live=1` 与重新烘焙不可用。 ### 4. 页面与操作 | 页面 | 用途 | | --- | --- | -| `/acts.html`（或访问根路径 `/`） | **主游戏页面**：全屏 WebGL2 画布 + HUD 控制条 + 左右停靠全套功能面板 + 7 职业漫步战斗 | +| `/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`） ``` -?act=1..5 章节 -?level=<地图块 label> 直接指定细分场景，如 33-act-1-cathedral-cathy3 -?quadrant= 直读归档模式下指定该关卡的某个 DS1 -?live=1 不走资源包，直接按 HTTP Range 读 MPQ 解码（慢） -?pack=<目录> 换一个资源包目录 ?base=<目录> 换一个归档目录 +?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 +?live=1 不走资源包，直接按 HTTP Range 读 MPQ 解码（慢） +?pack=<目录> 换一个资源包目录 ?base=<目录> 换一个归档目录 ?arena=1&class=&skill=&slvl=&autocast=1 启动竞技场自动验证模式 ``` #### 完整操作快捷键 -- **移动与视口**： - - `WASD` / 方向键：移动角色（按等距屏幕方向） +- **移动、交互与视口**： + - **鼠标左键点击**：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`：开启 / 关闭技能树面板（右停靠，3 系垂直选项卡切换与加点） + - `T` / `S`：开启 / 关闭技能树面板（右停靠，3 系垂直选项卡切换与加点） - `Q`：开启 / 关闭任务日志面板（左停靠，按幕查看真实任务状态） - - `V`：开启 / 关闭传送点网络菜单（左停靠，各幕传送点导航） - - `Esc`：关闭当前开启的所有停靠面板与弹出层 + - `P`：快捷施放双向回城传送门（Town Portal） + - `Esc` / `Space`：关闭当前开启的所有停靠面板、商人界面与弹出层 - **战斗与技能快捷栏**： - - 鼠标左键 / 右键：施放当前选中的左 / 右手技能 - - `S` 或点击底栏技能图标：打开 Speedbar 技能选择菜单 - - 鼠标悬浮在 Speedbar 技能上按 `F1` ~ `F8`：绑定快捷键；在游戏过程中按 `F1` ~ `F8`：即时切换技能 - - `1` ~ `4`：快捷使用腰带对应列药水；`~`：展开 / 折叠腰带 - - `Alt`（按住）：高亮显示地面掉落物品标签 + - 点击底栏左 / 右技能槽图标：打开向上展开的 Speedbar 技能选择弹窗（按技能树行序排列） + - 鼠标悬浮在 Speedbar 技能上按 `F1` ~ `F8`：绑定技能快捷键；在游戏过程中按 `F1` ~ `F8`：即时切换对应技能 + - `Shift`（按住）：强制原地站立攻击 / 施法（Force Stand Still） + - `1` ~ `4`：快捷饮用腰带第 1 ~ 4 列药水；`~` / `` ` ``：展开 / 折叠 4×4 腰带弹窗 + - `Alt`（按住）或鼠标悬浮地面物品：高亮显示地面掉落物品名称标签（带防重叠阶梯排布） - `R`：切换跑步 / 走路模式 - `W`：主副手武器切换（`I` / `II` 套） -- **测试与调试功能**： - - 键盘数字 `1` ~ `7`：一键热切换 7 大职业（亚马逊、刺客、野蛮人、德鲁伊、死灵法师、圣骑士、女巫）并自动装配初始专属套装与储物箱 - - `K` / `L`：快速保存 / 读取角色快照存档 +- **控制台与调试功能**： + - `Enter`：打开游戏内聊天/控制台输入框，支持输入 `/players 1` ~ `/players 8` 动态调整游戏人数难度与掉落率 + - 顶部工具栏下拉菜单：实时热切换 **7 大职业（`#hero`）**、**章节与细分场景**、**9 档场景光照预设（`#lighting`）**、**怪物密度（`#density`）** 与 **精英倍率（`#elite`）** + - `K` / `L`：快速保存 / 读取 `localStorage` 角色快照存档 ### 5. 部署到服务器 @@ -269,14 +301,21 @@ location ~ ^/diablo2/data/(?[A-Za-z0-9_.-]+\.mpq)$ { # 只暴露 .mpq ```bash npm run verify:deploy # 线上：页面 / 资源包索引 / 图集 / Range 206 / 旧入口 410 -npm run verify:packs # 资源包与"现读现解"逐项比对（绘制序、碰撞栅格逐字节、每帧像素哈希） +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 typecheck # tsc --noEmit +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 完整测试套件 ``` @@ -286,5 +325,5 @@ npm test # 运行 Vitest 完整测试套件 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)）；`samples/fixtures/`（本项目自产）与 `samples/d2-packs/`（派生数据）只作为 `/diablo2/assets/` 下的归档发布，不进 Git 历史。 图集包每次重烘都会让 Git 仓库再长 ~60 MB（PNG 无法 delta 压缩），所以不再入库。 -- 使用本引擎需要你自己合法拥有的游戏数据。将来落地的生成类关卡（迷宫 / 野外）会在页面与文档中标注为 - **"按官方参数表复现，非引擎原版布局"**（生成逻辑移植自 D2MOO）。 +- 使用本引擎需要你自己合法拥有的游戏数据。生成类关卡（70 个随机迷宫 + 31 个野外关卡）严格移植自 D2MOO / 1.13c `D2Common.dll` 官方参数表与 DRLG 算法复现。 +