JassForge Helper Extend

BUG/意见反馈 Q群:663259255

本扩展本质上是为了我JassForge编译器的开发,顺便方便Zinc的使用者,如果你在写Jass/vJass,那本人建议你改用Zinc,尽管此扩展也支持

JassForge Helper Extend 是无聊写的一个专为 JassForge/Zinc/Jass/vJass 打造的扩展工具，旨在提高开发效率并为用户提供更便捷的代码辅助功能。

目前版本默认已关闭闭包自动传参功能 如要开启 请配置

闭包自动传参配置 / Auto-trans Mapping

• 闭包自动传参检测默认关闭，需要显式开启：
  • zinc-helper.autoTrans.enabled: true | false（默认 false）。
• 传参映射改为 settings.json 外置配置，不再写死在扩展代码中：
  • zinc-helper.autoTrans.parameterMapping: { "type": { "set": "SetXxx", "get": "GetXxx", "isHandle": true } }。
• 闭包上下文符号也支持配置（避免项目间宏名不同）：
  • zinc-helper.autoTrans.timerHandleSymbol: 计时器上下文符号（默认 THISTIMER）。
  • zinc-helper.autoTrans.triggerHandleSymbol: 触发器上下文符号（默认 THISTRIGGER）。
• 当 enabled=true 且 parameterMapping 缺失/格式错误时：
  • 扩展会提示错误，自动补全逻辑会停用（不会继续按旧映射兜底）。

示例（放到工作区 .vscode/settings.json）：

{
  "zinc-helper.autoTrans.enabled": true,
  "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 }
  }
}

此功能可以默认将Zinc的TimerStart/timer->code之类闭包函数自动进行Set/Get操作,具体的传参函数需要你自己封装(直接写哈希表不是个很好的做法)

示例代码

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需要你自己封装,比如SetInt=SaveInteger(table, time, StringHash("unitID"), unitId) THISTIMER = GetExpiredTimer()

功能特性

• 代码片段快捷插入：提供常用代码片段的快捷键和模板，轻松插入。
• 代码格式化：自动格式化代码，提升代码可读性。
• 自定义命令支持：允许用户定义和执行自定义命令。
• 补全采纳排序记忆：当你采纳函数/变量/结构体补全项后，该项会自动上浮到更靠前位置，并在下次重启 VS Code 后保持顺序。
• 代码提供输入;时自动将句柄变量自动set null(仅支持JassForge/Zinc)以免忘记

安装步骤

1. 打开 VSCode，进入扩展商店（快捷键：Ctrl+Shift+X 或 Cmd+Shift+X）。
2. 搜索 JassForge Helper Extend。
3. 点击 安装 按钮。
4. 安装完成后，重启 VSCode 以确保扩展加载成功。

使用指南

1. 打开任意代码文件。
2. 通过快捷键或命令面板 (Ctrl+Shift+P) 调用扩展功能。
3. 根据提示完成代码插入、格式化或其他操作。

• 说明（中文）：

  • 第一行为函数指针类型声明：type <TypeName> extends function(<params>) -> <ReturnType>;。
  • 第二行为将变量声明为该函数指针类型并赋值为已有函数名（单行声明）。
  • 第三行为对 evaluate 的调用 —— 在编辑器中光标置于 evaluate( 时，扩展会尝试显示该函数指针类型的参数签名。

• Notes (English):

  • The extension recognizes single-line declarations of the form type X extends function(...) -> R; and single-line variable declarations like X name = FunctionName;.
  • When you call name.evaluate(...), the signature help provider will try to resolve name's type (local → current file → workspace) and show the parameter list.

• 注意事项 / Caveats：

  • 当前解析基于单行正则：多行或复杂换行格式可能无法识别，建议使用示例中的单行写法。
  • 跨文件的类型/变量索引依赖已保存的解析结果 —— 保存文件会触发扩展重新解析并更新工作区索引，从而使跨文件的签名提示生效。

• 验证步骤 / Quick verification:

  1. 在项目中打开或新建一个文件，粘贴上面的示例三行。
  2. 保存文件（若类型放在另一个文件，请确保也保存该文件）。
  3. 在 getItemCount_Func.evaluate( 处触发签名提示（在 VSCode 中输入 ( 或使用快捷键）。

settings

过滤文件夹

"zinc-helper.indexing.excludePathPatterns": [ "legacy/", "test/", "/backup/", "./import/", "./include/" ],

过滤文件

"zinc-helper.indexing.excludeFileNamePatterns": [ "_generated.j", "_backup.j", "*_old.j", "war3map.j" ]

示例

• 插入代码片段：
  • 输入 zinc-snippet 并选择需要的片段。
• 格式化代码：
  • 整个文档：使用 VS Code 默认快捷键 Shift+Alt+F。
  • 仅格式化选区：先选中文本，再使用 Ctrl+K Ctrl+F。

代码格式化 / Formatting

• 已支持 zinc / j / zn 的文档格式化与选区格式化。
• 采用严格格式规则：
  • 统一 4 空格缩进。
  • 统一常见运算符与逗号周围空格。
  • 保留字符串内容，不对字符串内部做空白改写。
  • 连续空行会压缩为单空行（文档格式化模式下）。

参数提示增强 / Signature-help enhancements

• 参数提示会一次展示完整参数列表，并高亮当前参数位。
• 当光标停留在函数参数括号内时，提示会持续刷新（输入字符或移动光标都会更新）。
• 可在 VS Code 设置中调整：
  • zinc-helper.signatureHints.persistent：是否启用参数列表内常驻提示（默认 true）。
  • zinc-helper.signatureHints.retriggerDelayMs：重触发延迟（默认 90 ms，范围 30-500）。

索引过滤 / Index filtering

• 你可以通过设置排除不需要解析的文件，避免跳转、引用、补全被无关文件干扰。
• 可用设置：
  • zinc-helper.indexing.includeGlob：索引包含规则（默认 **/*.{j,zn,zinc}）。
  • zinc-helper.indexing.excludeGlob：索引排除规则（默认 **/{node_modules,dist,build,out,.git}/**）。
  • zinc-helper.indexing.excludePathPatterns：额外按相对路径排除（例如 legacy/**、test/**）。
  • zinc-helper.indexing.excludeFileNamePatterns：按文件名模式排除（例如 *_generated.j、*_backup.j）。
• 修改这些设置后会自动重建索引，也可以手动执行命令 JassForge Helper: Rebuild Index。

条件编译暗淡显示 / Conditional Compilation Dimming

• 支持 #ifdef / #ifndef / #else / #endif（含嵌套）未生效分支自动暗淡显示。
• 宏来源为工作区内 #define，并会结合当前文档实时内容进行判断。
• 指令行本身（如 #ifdef、#endif）保持正常显示，仅代码内容变暗。
• 可用设置：
  • zinc-helper.conditionalCompilation.enabled：是否启用条件编译暗淡显示（默认 true）。
  • zinc-helper.conditionalCompilation.opacity：未生效代码透明度（默认 0.45，范围 0.15-0.9，值越小越暗）。

感谢使用 JassForge Helper Extend！期待您的反馈与支持！