八、MOD 语法校验规则
重要：MOD 加载器现在会进行严格语法校验。加载时检查每个文件的语法，遇到错误语法或无法解读的内容，会报告详细问题并停止加载该 MOD（不生效），而不是静默跳过或部分加载。本页完整说明校验规则。
8.1 校验流程（三阶段）
启用 / 启动加载一个 MOD 时，按以下三个阶段依次校验，任一致命错误 → 整个 MOD 停止加载：
| 阶段 | 检查对象 | 检查内容 |
|---|---|---|
| A | mod.ini | [mod] 节存在、name 非空、引用文件路径合法 |
| B | units / buildings / weapons / factions / art / campaigns | 结构级（合法节/字段）+ 类型级（数字/布尔/数组/JSON/枚举） |
| B′ | eva.ini（可选，mod.ini 的 eva= 引用） | 存在 [eva] 节；事件值格式为 vo:合成音 / file:外部语音；file: 路径无非法字符（../、\、绝对路径、空格） |
| C | res/*.r | 指令合法、必填字段、数值类型 |
停止加载策略：先完整校验所有文件，全部通过才真正合并。若有致命错误，该 MOD 的任何内容都不会生效（包括此前可能已合并的部分），数据表保持原样。仅「警告」级别问题不阻止加载。
8.2 错误级别
| 级别 | 含义 | 处理 |
|---|---|---|
| 致命 | 结构错误、类型错误、必填缺失、无法解读 | 停止加载该 MOD |
| 警告 | 未知字段等非致命问题 | 继续加载，但列出提示 |
8.2 各表合法字段
units.ini（单位）
[Unit]>kind= — 必填，枚举：infantry / vehicle / air / naval非法值（如
[Unit]>armor= — 枚举：infantry / light / heavy / building / air / naval / sub
tank）→ 致命错误。非法值 → 致命错误。
[Unit]>hp / cost / build / speed / rad / sight / turn / turretTurn / secondaryEvery — 必须是数字
如
[Unit]>crush / engineer / canGarrison — 必须是 true / false
hp=abc → 致命错误。如
[Unit]>req / forbidFactions — 数组（逗号分隔 或 JSON 数组）
crush=yes → 致命错误。注意：单值也会被解析为数组（兼容逗号语法）。
[Unit]>harvester — JSON 对象，如 harvester={"capacity":700,"rate":210}
JSON 解析失败 → 致命错误。
其它合法字段：name / desc / weapon / secondary / secondaryWeapon / secondaryMode / vet2Weapon / from / tab / art / key / faction / garrisonWeapon / 'art.png' / 'PNG.se'
未列出的字段名 → 警告（不阻止加载）。
buildings.ini（建筑）
[Building]>size= — 必须 WxH 格式，如 1x1 / 2x2 / 3x3如
[Building]>hp / cost / build / power / sight / tech / techLevel / garrisonMax — 数字
size=大 或 size=2 → 致命错误。类型错误 → 致命错误。
[Building]>buildable / neutral / garrisonable / isFlag / invincible / harvesterDock — 布尔
类型错误 → 致命错误。
其它合法字段：name / desc / weapon / tab / art / faction / req / superweapon / superweaponUnlock / exit / 'art.png' / 'PNG.se'
未列出的字段名 → 警告。
weapons.ini（武器）
[Weapon]>proj= — 枚举：bullet / shell / rocket / arc / flame / beam / tesla非法值 → 致命错误。
[Weapon]>prefer= — 枚举：air / infantry / light / heavy / naval / sub / building
非法值 → 致命错误。
[Weapon]>dmg / cd / range / splash / burst / burstGap / minRange — 数字
类型错误 → 致命错误。
[Weapon]>air / airOnly / waterOnly / needStop / underwater — 布尔
类型错误 → 致命错误。
[Weapon]>vs= — JSON 对象，如 vs={"infantry":1.6,"heavy":0.3}
JSON 解析失败 → 致命错误。
其它合法字段：name / sfx / color / prism / tesla
未列出的字段名 → 警告。
factions.ini（国家）
[Faction]>unique / excludeUnits — 必须数组强烈建议用 JSON 数组语法
其它合法字段：name / short / color / color2 / dark / desc / tint（字符串）
unique=["sniper","grizzly"]。若写成单值字符串（无逗号），解析结果不是数组 → 致命错误。未列出的字段名 → 警告。
art.ini（美术）
[artKey]>use_png / overflow — 布尔类型错误 → 致命错误。
[artKey]>facing= — 枚举：none / flip / rotate
非法值 → 致命错误。
[artKey]>file / icon_file — 非空字符串（文件路径）
file 在 MOD 内可省略——只要该文件名已列入 mod.ini 的 res=，引擎自动按 ROOT:/res/文件名 注册，此节只补 se/facing 等属性。显式写则用 ROOT:/res/文件名.png 指向包内（ROOT 指模组根目录）。类型错误 → 致命错误。
campaigns.ini（战役）
[MapId]>file= — 必填，指向 map/ 内的 .json缺失 → 致命错误。
其它合法字段：name / mission / difficulty / recommendedPlayers / faction
未列出的字段名 → 警告。
8.3 .r 素材指令必填字段
| 指令 | 必填字段 | 说明 |
|---|---|---|
rect | x y w h | 矩形 |
ellipse | cx cy rx ry | 椭圆 |
circle | cx cy r | 圆 |
line | x1 y1 x2 y2 | 线段（建议带 stroke） |
triangle | x1 y1 x2 y2 x3 y3 | 三角形 |
poly | pts（≥3 个点） | 多边形 pts="x,y;x,y;x,y" |
未知指令（如 star）、缺必填字段、数值非数字 → 均致命错误。size= 必须是 WxH 格式。
8.4 错误报告与修复
加载失败时，MOD 管理器列表会显示红色「语法错误」标签。点击会弹出详细错误面板，每行包含：
| 列 | 说明 | 示例 |
|---|---|---|
| 级别 | 致命 / 警告 | 致命 |
| 表 | 数据表 | units |
| 文件 | 包内文件 | units.ini |
| 节 | [节名] | [cz_flameTank] |
| 字段 | 字段名 | kind |
| 行 | 行号 | 12 |
| 原因 | 问题描述与期望 | kind 必须是 infantry/vehicle/air/naval，收到 "tank" |
常见致命错误与修复
| 错误提示 | 原因 / 修复 |
|---|---|
| mod.ini 缺少 [mod] 节 / name | 必须有 [mod] 和 name= |
| kind 必须是 infantry/vehicle/air/naval | 单位类型写错，修正枚举值 |
| size 必须是 WxH 格式 | 建筑占地写错，改为如 size=2x2 |
| proj 必须是 bullet/shell/rocket/… | 武器弹道类型写错 |
| 字段 xxx 必须是数组 | unique/excludeUnits/req 用逗号或 JSON 数组 |
| 字段 xxx 的 JSON 解析失败 | vs/harvester 的 { } 花括号或引号不配对 |
| 指令 rect 缺少必填字段 x | .r 素材少了坐标/尺寸参数 |
| 未知绘制指令 "star" | .r 里用了不存在的指令 |
修复后：改正
.gsdzmod 重新导入，或直接停用再启用该 MOD，即可重新触发校验加载。