魔兽地图制作助手（wc3-map-assistant）
不依赖魔兽争霸3地图编辑器（World Editor），用脚本直接产出可玩的 .w3x 地图文件，
并能解包 / 修改 / 重打包已有地图、对成品做多级校验。
什么时候用
- 用户要"做一张魔兽争霸3（War3/WC3）地图"，或要 RPG / 防守 / 生存 / 塔防 / 对抗图
- 用户拿到
.w3x/.w3m，要改、要看内部、要重新打包 - 地图打不开 / 报错，需要排查格式问题
- 需要 MPQ 归档读写（魔兽地图、暴雪老游戏资源包）
快速流程（新做一张图）
- 问清两件事：① 玩法类型（防守/塔防/RPG/对抗）；② 游戏版本——
1.27 经典版 →war3map.w3i格式版本 25、.w3x、.doo用 v8/subversion 11；
重制版 1.31+ → 版本 28/31+。不确定就写 25（Reforged 向下兼容老格式）。 - 搭工程目录（make_map.py 按此布局找文件，产物输出到工程目录的上一级）：
我的地图/ └── wc3map/ ← 工程目录 ├── mpq_pack.py ← 从 scripts/ 复制 ├── make_map.py ← 从 scripts/ 复制（地形/信息/单位参数都在这里面改） ├── verify.py ← 从 scripts/ 复制 ├── jass_lint.py ← 从 scripts/ 复制 └── war3map.j ← 玩法脚本：从 assets/survival-defense-war3map.j.txt 复制后改名为 war3map.j，再按需求改 - 先写
war3map.j（全部玩法逻辑：刷怪、波次、胜负、奖励），
再改make_map.py顶部的地形/地图信息参数（尺寸、地表、出生点、每波怪物表）。
地图内文本一律用 ASCII（1.27 中文客户端对地图内文本编码处理不一致，中文易乱码）。 - 依次执行并全部通过：
python jass_lint.py # 需官方 common.j / Blizzard.j，见 references/checklist.md python make_map.py # 产出 ../xxx.w3x python verify.py # 独立校验（需 pip install mpyq） - 交付
.w3x，提醒用户放到文档\Warcraft III\Maps\，单人游戏 → 自定义游戏 选择。
改已有地图 / 只想解包
python mpq_pack.py unpack 地图.w3x 输出目录/ # 解包全部内部文件
python mpq_pack.py pack 输出目录/ 新地图.w3x # 改完重新打包
python mpq_pack.py list 地图.w3x # 只看里面有什么
深度规格（按需加载，不要一次全读）
| 需要什么 | 读哪个 |
|---|---|
| MPQ 容器格式、表加密算法、读写的坑 | references/mpq-container.md |
| w3e/w3i/wpm/shd/doo/Units.doo/mmp/Preview 字节级规格 | references/war3map-formats.md |
| JASS 骨架顺序、玩家常量、常用函数、硬性规则 | references/jass-guide.md |
| 校验清单、参考样本下载地址、交付提醒 | references/checklist.md |
五条最容易翻车的红线
- MPQ 的哈希表/块表是加密存储的，密钥用 hash type 3（不是算槽位的 type 0），
且加密/解密推进密钥流都用明文值——按同一循环写会导致读回来全是乱码。 w3etilepoint 平地基准：高度0x2000、水0x2000、无悬崖0xF、层高 2 → 尾字节F2。- 出生点是一个
sloc单位，必须写进war3mapUnits.doo（不是只写在 w3i 里）。 - JASS：
local必须在函数体最前；函数必须先定义后引用；块结构必须配平。 - 用 World Editor 保存地图会按触发器树重写
war3map.j，把你的脚本覆盖掉——
先备份脚本，或把 WE 只当地形编辑器用，改完重新跑生成器。
校验（无法真机启动游戏时必做）
- 第三方库
mpyq回读成品，与 build 目录逐字节比对——对 MPQ 写入最强的外部验证。 - 自己的解析器把
war3map.w3i按对应格式版本解析，断言恰好消耗到文件末尾。 jass_lint.py用官方common.j/Blizzard.j核对每个函数名、块配平、local 位置。- 结构对表：w3e =
头 + (格数+1)²×7；shd =16×格数²；wpm =16+16×格数²。
详细步骤与样本地址见references/checklist.md。
交付时一定要提醒用户
.w3x= 冰封王座，.w3m= 混乱之治；放到Documents\Warcraft III\Maps\。- 本技能生成的是原创数据，不包含任何暴雪游戏素材；请配合正版/自有的游戏客户端使用。
- 若用户要"保护"地图：可去掉
(listfile)并压缩内部文件，但请仅用于自己的作品。
