魔兽地图工具
VS Code 扩展，面向 Warcraft III 1.27a 经典版地图资源工作流：定位并预览模型、贴图、声音，浏览 MPQ 资源，整理模型与贴图，检查资源引用，转换贴图格式。地图入口固定为 JASS/vJASS。
功能概览
| 功能 |
说明 |
| 资源路径悬停 |
在源文件的资源路径上查看图片或 BLP/TGA 贴图预览；模型显示基本摘要；声音提供预览入口。 |
| 路径跳转 |
Ctrl+单击（macOS：Cmd+单击）资源路径，打开对应的模型、贴图或声音预览。 |
| 模型预览 |
使用 WebGL 查看 MDX/MDL 模型，控制动画与视角，查看贴图和镜头，并编辑可写模型的缩放和镜头。 |
| 贴图与声音预览 |
贴图可平移、缩放、检查透明度和复制尺寸；声音可通过内置播放器试听。 |
| MPQ 浏览 |
浏览、搜索和收藏核心 MPQ 资源，复制路径/名称，打开预览或导出。 |
| 模型整理 |
将模型和其引用的本地贴图归档至指定目录，并改写模型中的贴图路径。 |
| 资源诊断 |
诊断缺失资源，或扫描未引用模型/贴图候选并统计体积；不自动删除。 |
| 贴图转换 |
在 BLP、TGA、PNG 之间单文件、多选或递归批量转换。 |
| 模型互转 |
MDX ⇄ MDL 单文件或批量转换，保留原始输入。 |
| 魔兽图标 |
从 PNG/JPEG/TGA/BLP 生成 64×64 BTN / DISBTN / PASBTN / DISPASBTN BLP。 |
支持的格式
| 类型 |
扩展名 |
支持的行为 |
| 常见图片 |
.png、.jpg、.jpeg、.gif、.webp、.svg、.bmp、.ico |
悬停预览、贴图预览面板 |
| Warcraft BLP |
.blp |
BLP1 解码、悬停/贴图预览、转换为 PNG/TGA |
| Targa |
.tga |
未压缩/RLE 真彩色解析、悬停/贴图预览、转换为 PNG/BLP |
| Warcraft 模型 |
.mdx、.mdl |
摘要、WebGL 预览、模型整理、资源诊断 |
| 声音 |
.mp3、.wav、.ogg、.aac、.m4a、.flac、.webm |
悬停入口、内置播放器预览 |
使用
资源路径悬停与跳转
在字符串中输入资源路径，鼠标悬停可查看预览。符合资源扩展名规则的路径会成为文档链接：按住 Ctrl（macOS 为 Cmd）并单击，可打开模型、贴图或声音预览。
路径解析顺序：绝对路径 → 当前源文件目录 → 魔兽目录 → 工作区根目录 → 核心 MPQ 归档 → 按文件名兜底搜索。悬停预览支持 %d 和 %0Nd 数字占位符，尝试编号 1 到 10。
预览编辑器
.mdx / .mdl 使用模型预览编辑器；BLP、TGA 和常见图片使用贴图预览编辑器；声音通过命令或 MPQ 浏览器预览。- 模型预览：左键旋转、右键平移、滚轮缩放；切换动画、调整速度；重置视角；查看序列、贴图、镜头；导出 PNG；调整缩放并保存；添加/重命名/删除镜头。MPQ 中的模型只读。底部“队伍色/发光”提供 24 色，同步切换
ReplaceableId 1/2。贴图列表支持“选择本地贴图”和“改路径并保存”。
- 贴图预览：平移、缩放、重置视图；查看并复制尺寸；切换透明网格/Alpha 灰度/底色。
- 声音预览：内置音频控件播放。
命令
命令面板搜索“魔兽地图工具”：模型预览、贴图预览、声音预览、贴图转换、模型互转、生成魔兽图标、整理模型、诊断缺失资源、未用资源检查、重复资源检测、模型健康检查、导出模型资源、地图引用检查、资源引用查询、贴图质量设置、搜索资源、刷新资源列表、打开资源、收藏/取消收藏、导出资源、复制路径/名称等。
模型整理
在资源管理器文件夹右键执行“整理模型”。递归查找 MDX/MDL，移动模型到目标目录，引用的本地贴图移动到贴图目录并更新路径。默认目标目录 model 和 textures。跳过 UI 目录模型和 UI 路径贴图；不移动 MPQ 贴图。同名同内容可覆盖，不同内容改用新文件名。结束后清理空目录并报告统计。
资源诊断
- 缺失资源：扫描当前文件或所选文件/目录，仅报告本地与 MPQ 均未找到的引用。
- 未引用资源：在工程根目录执行，扫描代码/配置/模型引用，列出候选及体积，不自动删除。
- 重复资源：按大小和 SHA-256 分组重复模型、贴图、声音。
- 模型健康：检查结构、索引、轨道、依赖，只读报告。
MPQ 浏览器
侧边栏 War3 → MPQ Explorer 浏览核心 MPQ，按目录展开，支持预览/打开、收藏、复制路径/名称、导出、搜索。
工程工作流
工程由根目录 war3-workflow.json 标识，地图源为 map/ 下的 w3x2lni LNI 工程。新建工程使用内置 resources/map/。活动栏 地图工程 侧栏管理工程；任务写入 .vscode/tasks.json（运行/打开WE/打开地图/加密地图）。打开WE 用 KKWE.exe，编辑地图用内置 YDWE.exe。侧栏仅配置 KKWE 测试路径。
已有任务缺失或损坏时，点击 生成任务 或执行 War3: 生成任务 重新生成。
AI 地图工具（MCP）
Windows x64、VS Code 1.102+ 通过官方 MCP provider 提供 war3_console、war3_press_key、war3_screenshot 三个工具，无需 Node/Bun 或修改 .vscode/mcp.json。不安装地图 Lua、不修改地图、不监听端口。
配置
| 设置 |
默认值 |
说明 |
war3ResourcePreview.war3RootPath |
空 |
魔兽目录；Windows 留空自动检测 |
war3ResourcePreview.textureMaxSize |
0 |
转换最长边，0 保留原尺寸 |
war3ResourcePreview.textureAlphaBits |
auto |
BLP1 Alpha 位数 |
war3ResourcePreview.texturePaletteSize |
256 |
BLP1 量化颜色数 |
war3ResourcePreview.textureMipmaps |
false |
生成多级贴图 |
war3ResourcePreview.texturePreviewBeforeConvert |
false |
转换前样本预览 |
war3ResourcePreview.organizeModelTargetDirectory |
model |
整理模型目标目录 |
war3ResourcePreview.batchTextureTargetDirectory |
textures |
整理贴图目标目录 |
资源路径补全
输入 model/、model\\ 等目录前缀，自动列出子目录及受支持资源。候选仅来自 resource/ 和 map/resource/ 两个资源根。
工程编辑辅助
- 物编语义辅助：LNI 对象表中文字段说明、类型、枚举、继承链。
- 保存诊断：保存后显示资源路径、对象 ID、WTS 断链问题。
- 环境检查：报告可预览/构建/脚本检查/测试的静态前提。
性能
MPQ 按位置读取，LRU 索引缓存（32 归档、32 MiB）。悬停支持取消与并发查找共享。同名资源优先当前工程与工作区。
限制
- 渲染后端为 WebGL，无 WebGPU。
- BLP 解析器支持 BLP1；输出调色板 BLP1。
- TGA 支持未压缩和 RLE 真彩色。
- MPQ 浏览依赖归档
(listfile)。
开发
npm install
npm run dev:extension # 另一终端 npm run dev:webview
脚本：npm run build / lint / test / package / package:check / toolchain:check。Node.js ≥20，npm ≥10。
目录结构
src/extension.ts 扩展入口
src/features/ 业务模块（audio/editors/models/mpq/resources/textures/workflows）
src/shared/ 公共配置、文件系统、缓存、日志
src/mdx/ MDX/MDL 与 WebGL 查看器
media/ Webview 资源
schemas/ 工程配置校验
resources/ 内置资源（map/lua/YDWE/w3x2lni）
tests/ 测试
docs/ 文档
依赖与致谢
许可证
MIT
