JassForge Helper Extend

专为 JassForge / Zinc / Jass / vJass 开发体验优化的 VS Code 扩展。

如果你在使用 JassForge 或 Zinc，本扩展会在补全、格式化、参数提示、索引和条件编译可视化方面提供直接帮助。

反馈

• BUG/意见反馈 QQ 群：663259255

功能总览

• 代码片段快捷插入
• 文档/选区格式化（zinc / j / zn）
• 闭包自动传参与句柄自动 set null
• 函数签名提示增强（含函数指针 evaluate）
• 索引过滤与快速重建索引
• 条件编译未生效分支暗淡显示
• 补全采纳排序记忆（重启后保留）
• 音频文件悬停预览与 Ctrl+Click 自动播放
• 图片文件悬停预览（支持 BLP / TGA / PNG / JPG 等格式）

安装

1. 打开扩展市场（Ctrl+Shift+X）
2. 搜索 JassForge Helper Extend
3. 点击安装并重启 VS Code

快速使用

1. 打开 zinc/j/zn 文件
2. 通过命令面板（Ctrl+Shift+P）调用功能
3. 常用快捷操作：
   • 全文格式化：Shift+Alt+F
   • 选区格式化：Ctrl+K Ctrl+F

闭包自动传参与自动 set null（默认关闭）

这两项功能都不会默认启用，需要你在工作区显式配置。

配置项

• zinc-helper.autoTrans.enabled
  • 是否启用自动传参与自动清理逻辑（默认 false）
• zinc-helper.autoTrans.handleTypes
  • 参与自动 set null 的句柄类型列表，例如 unit、timer、group
• zinc-helper.autoTrans.parameterMapping
  • 自动传参使用的类型映射表：{ "type": { "set": "SetXxx", "get": "GetXxx", "isHandle": true } }
• zinc-helper.autoTrans.timerHandleSymbol
  • 计时器上下文符号（默认 THISTIMER）
• zinc-helper.autoTrans.triggerHandleSymbol
  • 触发器上下文符号（默认 THISTRIGGER）

说明：

• 自动传参依赖 parameterMapping
• 自动 set null 依赖 handleTypes，或者 parameterMapping 里标记了 isHandle=true 的类型
• 如果你只想要自动 set null，可以只开 enabled 并配置 handleTypes，不需要配置 SetXxx/GetXxx
• parameterMapping 非法时会停用自动传参，但不会再连带禁用已正确配置的自动 set null

推荐 settings 示例

将以下内容放到工作区 .vscode/settings.json：

{
  "zinc-helper.autoTrans.enabled": true,
  "zinc-helper.autoTrans.handleTypes": ["unit", "timer", "group", "force", "location"],
  "zinc-helper.autoTrans.timerHandleSymbol": "THISTIMER",
  "zinc-helper.autoTrans.triggerHandleSymbol": "THISTRIGGER",
  "zinc-helper.autoTrans.parameterMapping": {
    "unit": { "set": "SetUnit", "get": "GetUnit", "isHandle": true },
    "timer": { "set": "SetTime", "get": "GetTime", "isHandle": true },
    "integer": { "set": "SetInt", "get": "GetInt", "isHandle": false },
    "string": { "set": "SetString", "get": "GetString", "isHandle": false }
  }
}

如果你只需要自动 set null，最小配置可以是：

{
  "zinc-helper.autoTrans.enabled": true,
  "zinc-helper.autoTrans.handleTypes": ["unit", "timer", "group", "force", "location"]
}

自动传参效果示例

输入前：

timer time = CreateTimer();
integer unitID = 0;

TimerStart(time, 0.1, false, function() {
    // 闭包内默认访问不到此变量
    unitID = 0;
});

触发后（示意）：

timer time = CreateTimer();
integer unitID = 0;

SetInt(time, "unitID", unitID);
TimerStart(time, 0.1, false, function() {
    integer unitID = GetInt(THISTIMER, "unitID");
    unitID = 0;
});

time = null;

说明：SetInt/GetInt 需要你在项目内自行封装（例如基于 hashtable）。

代码格式化

• 支持 zinc / j / zn 文档与选区格式化
• 规则要点：
  • 统一 4 空格缩进
  • 统一常见运算符与逗号空格
  • 保留字符串内部内容
  • 连续空行压缩为单空行（全文模式）
  • 预处理行（如 #define）不会被错误改写为函数调用形式

签名提示增强

• 参数提示展示完整参数列表并高亮当前参数
• 光标停留在参数区时可持续刷新
• 可调设置：
  • zinc-helper.signatureHints.persistent（默认 true）
  • zinc-helper.signatureHints.retriggerDelayMs（默认 90，范围 30-500）

函数指针 evaluate 提示示例

public type GetItemCount_Func extends function(integer, integer) -> integer;
GetItemCount_Func getItemCount_Func = GetItemCount;
getItemCount_Func.evaluate(1, 2);

说明：当前解析以单行声明为主，复杂换行写法可能无法完全识别。

索引过滤

你可以通过过滤规则减少无关文件干扰跳转/引用/补全。

• zinc-helper.indexing.includeGlob（默认 **/*.{j,zn,zinc}）
• zinc-helper.indexing.excludeGlob（默认 **/{node_modules,dist,build,out,.git}/**）
• zinc-helper.indexing.excludePathPatterns（路径模式）
• zinc-helper.indexing.excludeFileNamePatterns（文件名模式）

示例：

{
  "zinc-helper.indexing.excludePathPatterns": [
    "legacy/**",
    "test/**",
    "**/backup/**",
    "./import/**",
    "./include/**"
  ],
  "zinc-helper.indexing.excludeFileNamePatterns": [
    "*_generated.j",
    "*_backup.j",
    "*_old.j",
    "war3map.j"
  ]
}

修改后会自动重建索引，也可以手动执行命令：JassForge Helper: Rebuild Index。

条件编译暗淡显示

• 支持 #ifdef / #ifndef / #else / #endif（含嵌套）
• 根据工作区宏定义判断未生效分支并暗淡显示
• 指令行本身保持正常显示，仅代码内容变暗
• 可调设置：
  • zinc-helper.conditionalCompilation.enabled（默认 true）
  • zinc-helper.conditionalCompilation.opacity（默认 0.45，范围 0.15-0.9）

媒体文件预览

在代码中悬停在音频或图片路径字符串上时，会自动展示预览信息。

音频预览（mp3 / wav / ogg / flac / aac / m4a / wma）

• 悬停：展示文件名、路径、大小与修改时间
• Ctrl+Click：直接在侧边拆分窗格打开播放器并自动开始播放

图片预览（png / jpg / bmp / gif / tga / blp）

• 悬停：直接在悬停框内内嵌显示图片（支持 TGA 内置解码）
• Ctrl+Click：在侧边面板内打开独立图片预览（支持 BLP 格式）

路径解析依赖配置项 zinc-helper.war3RootPath，找不到文件时展示提示而非报错。

备注

• 跨文件签名与索引依赖已保存文件内容，建议编辑后及时保存
• 本扩展优先服务 JassForge/Zinc，同时兼容 Jass/vJass 常见场景

感谢使用 JassForge Helper Extend，欢迎反馈与建议。