Zinc J

---
name: zinc-j
description: 本项目 .j 文件中的 Zinc（//! zinc ... //! endzinc）语法与约定：库/结构体写法、匿名函数（无闭包）最佳实践、回调参数传递、资源释放/置空、以及 JASS->Zinc 迁移要点。
---

# Zinc（本项目）语法与约定

## 必须遵守

- 用 `//! zinc` / `//! endzinc` 包裹 Zinc 代码块。
- 禁用 `++/--`；用 `+= 1` / `-= 1`。
- 禁用 `break/continue`；用 `if` 分支或布尔开关改写。
- 数组声明一律用 `type name[];`，不要写大小（例如 `integer a[10]` 是错的）。
- 返回类型用 `-> type` 写在参数列表后；无返回可省略。
- 局部变量统一在函数/匿名函数开头声明：先基础类型，后句柄类型。
- 函数定义顺序按“自上而下可见”处理：下方函数可以直接调用上方函数；上方函数不能直接调用下方函数。
- 上方若必须调用下方逻辑：优先把下方逻辑封装到 `struct` 静态方法后再调用；或使用 `xxxx.execute(...)` / `xxxx.evaluate(...)` 间接调用。
- 本地场景（例如 UI 本地执行）禁止 `execute`，只能用 `evaluate`，否则有 OOS 风险。

## 匿名函数（无闭包）

- 匿名函数内不能直接访问外层局部变量；需要显式传参。
- 传参优先用结构体/库的 `static` 成员变量，并在回调结束后立刻清理为默认值（`null/0/""`）。
- 临时触发器回调用 `CreateTrigger` + `TriggerAddCondition` + `TriggerEvaluate`，随后 `DestroyTrigger` 并置 `null`。

## 句柄生命周期（资源释放）

- 创建出来的句柄资源（`timer/trigger/group/effect/location/...`）：按对应 `Destroy*` / `Remove*` API 释放，并在作用域末尾 `= null`。
- 结构体析构只写 `method onDestroy()`；不要自定义 `destroy()`。

## 结构体/方法写法

- 静态方法：`static method foo(...) -> type { ... }`
- 实例方法：`method foo(...) -> type { ... }`
- 纯静态“管理器”可用 `struct X [] { ... }`（避免 `create/destroy`）。

## 跨位置调用与性能约束

- `execute`：不带返回值（底层是 `TriggerExecute` 触发 action）。
- `evaluate`：可用于需要返回值或不需要返回值的调用场景。
- 非必要不要做“上方间接调下方”；编译后会为这类调用生成额外 trigger/condition 包装，有额外资源开销。
- 仅在必要情形（例如循环调用链 `A -> B -> A`）才设计成上方间接调下方。

## JASS -> Zinc 迁移要点

- JASS 默认 `public`；Zinc 默认 `private`：需要对外可见的函数/全局变量要显式 `public`。
- `loop/exitwhen/endloop` 优先改写为 Zinc 的范围 `for (a <= i <= b)` 或常规 for。
- timer/trigger 的一次性逻辑优先改成匿名回调。

## References（按需加载）

- `references/jass-to-zinc.md`
- `references/anonymous-functions.md`
- `references/callback-params.md`
- `references/method-syntax.md`
- `references/function-order-and-indirect-call.md`