diablo2-web/AGENTS.md

Diablo II Web 逆向与工程保真度开发铁律 (D2 Parity Rules)

[!IMPORTANT] 本项目为暗黑破坏神 2（Diablo II v1.13c）Web 端移植与高保真复刻项目。 在任何开发、重构、修复与测试过程中，必须严格遵守 Diablo II 1.13c 原版底层二进制（DLL 汇编与 C 逻辑）及 MPQ 官方数据表规范。 严禁凭空发明伪规则，严禁通过“静默容错”掩盖管线断层。

---

1. 原版权威与反伪逻辑准则 (Ground Truth Priority)

1. 原版逻辑为唯一最高准则：
   • 遇到地图生成（DRLG）、掉落（TC / Drop Pipeline）、怪物属性与随从（MonStats / SuperUniques）、物理碰撞（Collision）等机制疑问时，必须严格以 1.13c 逆向工程反汇编及官方数据表（LvlTypes.txt, LvlPrest.txt, Levels.txt, SuperUniques.txt, TreasureClassEx.txt）为唯一事实来源。
2. 严禁凭个别样本盲目类推：
   • 暗黑2共有 136 个 Level ID，包含预置建筑、迷宫拼接、野外生成等截然不同的 DRLG 范式。
   • 严禁仅测试 Act 1 鲜血荒地或罗格营地即假定全图可用。任何地图算法改动必须经受全 136 关卡全量场景普查。
3. 杜绝“自创”Style / Sequence 编号：
   • 程序化地貌贴图、路网、围墙、水系过渡所使用的 style 与 sequence 必须来自该关卡绑定的 DT1 库实际导出定义，严禁跨章节挪用（例如严禁在沙漠、高地、雪山中使用 Act 1 的 Style 0 泥路或 Style 2 水面）。

---

2. 地图与瓦片渲染铁律 (DRLG & Tile Invariants)

1. 三通用 DT1 常驻加载机制（1.13c DRLGROOM_LoadDt1Files）：
   • 依据 1.13c 汇编逻辑（D2Common.dll @ 0x6fdb8400），任何关卡在解析完其 LvlTypes.txt 声明的 DT1 后，必须无条件追加加载 3 个全局通用 DT1 库：
     • data\global\tiles\Act1\Outdoors\Blank.dt1
     • data\global\tiles\Act1\Barracks\InvisWal.dt1
     • data\global\tiles\Act1\Barracks\Warp.dt1
   • 其中 InvisWal.dt1 包含 style=49 sequence=7 的地面瓦片（用于行走阻挡的隐形碰撞墙，见于 Act 5 混沌避难所、地狱、世界之石等处），严禁将其作为缺少贴图（missingTile）跳过。
2. 空单元格阻挡掩码与玩家出生点定位：
   • 地图未放置有效地面瓦片的纯黑虚空区域，必须在子网格（Sub-tile）上严格打满 blocked = 1 与 COLLIDE_MASK_INVALID（包含 COLLIDE_BLANK = 0x0001 与 COLLIDE_WALL = 0x0004）。
   • 玩家出生点搜寻（findIsoSpawn）绝对严禁直接取地图几何中心点 (width/2, height/2)。在非矩形或中空地图（如遗忘之塔外景、皇宫、秘密避难所等），中心点极可能是纯黑虚空。
   • 出生点必须严格落在“物理连通、有非隐藏有效地面瓦片且 blocked === 0”的最大可行走连通分量上，优先靠近传送门（Warp）或小站（Waypoint）。
3. 消除平铺条纹：严禁在空间离散中使用简单线性算术：
   • 地块变体选择（pickVariant）严禁使用 ((x * A) ^ (y * B)) % count 这类简单线性同余公式。在二维离散规则网格上，线性乘积会导致明显的 45 度斜向周期性机械几何平铺条纹。
   • 变体散列必须使用高熵伪随机空间哈希（如 SplitMix64 坐标散列），并通过空间方差统计单测确保视觉离散度。

---

3. 严禁以“防御性编程”掩盖系统性缺陷 (Anti-Silent Failures)

1. 严禁宽容吞错的伪 Fallback：
   • 严禁编写类似 if (availableTiles.size === 0) return true; 这类无原则放行逻辑。核心参数（如 DT1 库、关卡配置）漏传时，必须显式抛出异常或严格判定不可用，决不能让缺失数据伪装成“全量支持”。
2. 杜绝越界贴图跨章节污染：
   • 自动贴图 LUT（Auto-tiling LUT）必须在每次应用贴图更新前，严格执行 isTileAvailable(style, sequence) 校验，未声明的贴图一律禁止写入渲染管线。

---

4. 资产管线与数据保真度 (Data & Pipeline Fidelity)

1. 离线烘焙预打包（Pack）与运行时必须全链路对齐：
   • 严禁预打包脚本维护一套写死的窄白名单，而运行时又依赖动态未打包资产。
   • 所有暗金怪（SuperUniques）必须自动推导并解析其随从（Minions）所依赖的全部 DCC/DC6 动画与材质资源，一并纳入离线打包构建。
2. 原版文本数据转录不得篡改或简化：
   • SuperUniques.txt、MonStats.txt 等元数据必须严格保留原版 Class 标识（如 scarab2, zombie5, fetishshaman4, nihlathakboss 等具体变体），禁止粗暴截断变体数字后缀或自编别名。
3. 技能与投射物美术资源必须采用原版资源并离线烘焙 (Missile & Spell FX Parity)：
   • 严禁长期使用由代码绘制的方块、纯几何色块或纯程序化简易图形作为技能投射物/特效替代品。
   • 所有技能投射物（Missiles）、次生爆炸（Explosions）、状态光环与法术特效，必须严格以 1.13c 原版 MPQ（d2data.mpq / d2exp.mpq / Patch_D2.mpq）中由 Missiles.txt 的 CelFile 字段所引用的原版 DCC / DC6 动画文件为准（例如 Firebolt.dcc, Fireball.dcc, FireArrowExplode2.dcc 等）。
   • 必须通过离线解包烘焙脚本（如 scripts/pack-missiles.ts）结合章节调色板（ACT1/pal.pl2），将原版 DCC/DC6 的全部朝向（如 16 方向）与全帧序列预打包烘焙为 Web 原生 Sprite Atlas（图集）及对应元数据，供前端 WebGL 运行时直接高效索引与渲染。
   • 音效接入解耦：现阶段音效系统（Sounds.txt / WAV 音频资源）允许暂缓接入，但视觉动画必须具备 100% 像素级原版 DCC 贴图资产与帧率对齐。

---

5. 质量验证与门禁标准 (Verification Standards)

任何涉及地图、物品、怪物及战斗核心机制的代码提交，必须通过以下铁门禁：

1. 全量无头自动化实机走查：涉及渲染和地图变动，必须执行全 136 个关卡的自动化走查截图或状态检验，杜绝抽检盲区。
2. 严苛静态类型与全量单测：
   • npm run typecheck 必须保持 0 errors。
   • npx vitest run 必须保持全量套件 100% 通过（包括 global-dt1-load.test.ts, iso-spawn-void-guard.test.ts, variant-distribution.test.ts, superuniques-fidelity.test.ts 等防退化单测）。