# Creator 设备模板

此目录随启动器安装在 `UnrealHub.exe` 旁边，必须保留六个 JSON 文件。启动器只允许本地模板与平台分类交集内的设备创建：输电塔、负载建筑、电压互感器、电流互感器、避雷器、断路器。负载建筑的住宅、商业、工业、农业、市政为同一入口下的用途选项。

每个模板定义显示名称、说明、默认背包占地、设备级仿真参数、控件与挂点规则。第一步选择设备及用途后，第二步 Inspector 按模板生成参数面板。只有系统额定电压使用固定数值下拉，其他数值参数在安全范围内手动填写；准确级等文字分类及启用开关保留对应选择控件。挂点电压从设备级参数或用途自动派生，不能分别手填。

PT 二次额定电压可填写 1～400 V，CT 二次额定电流可填写 0.1～10 A；修改系统电压不会重置这些已填写数值。模板不再强制把 PT 二次电压与一次系统档位绑定。

## 选中部件与接线方式

先在场景中点击一个部件，再设置右侧“本部件角色”。未配置的部件默认是“本体”：不生成电气端口、不要求相别；它仍可独立编辑名称、变换和网格碰撞。“本体”不是“通用（0）”，后者已经是一个电气挂点。

模板合同 3 的所有设备、所有已绑定挂点均显示 `0=通用、1=A、2=B、3=C、4=N`，每个挂点独立选择，可重复选择通用 0。输电塔另有专用 `5=架空地线`，不等同于 N。通用 0 由游戏按实际导线识别；明确指定的相别不会被设备默认设置覆盖。N 不自动接地或产生电源，自由配置不代表电路必然正确，错相仍可能触发游戏故障。

| 设备 | 当前模板版本 | 单组挂点（single） | 三组挂点（three-phase） | 新项目默认 |
|---|---:|---|---|---|
| PT 电压互感器 | 3 | `line` 一个输入 | `lineA/lineB/lineC` 三个物理输入 | 三组 |
| CT 电流互感器 | 3 | `p1/p2` 输入、输出 | `p1A/p2A`、`p1B/p2B`、`p1C/p2C`，三组进出 | 三组 |
| 断路器 | 3 | `in/out` 输入、输出 | `inA/outA`、`inB/outB`、`inC/outC`，三组进出 | 三组 |
| 避雷器 | 3 | `line` 一个输入 | `line/lineB/lineC` 三个输入 | 单组 |

进出名称只区分物理接线位置，不把交流电路变成单向。三组布局须配齐物理槽位，但不强制 ABC 或进出同相；每个挂点绑定不同的真实节点。改相不移动槽位、不占用另一个部件。切换布局前先明确移除挂点 Box，并将相关部件改回本体。旧 PT 的 `lineOther` 仅为已保存配置的兼容端，不作为新 PT 默认项。旧模板 1/2 在读取、切选和未改变电气配置的保存时保持原版本；只有作者明确修改挂点且超出旧合同、完整通过合同 3 校验后才原子升级，失败不写文件。

PT/CT/断路器三相成套的一套仿真参数会分别应用到三个相对应的官方组件。额定电流、二次额定值、负担及损耗等应按**每相铭牌/每相损耗**填写，不把三相总损耗重复填到每一相。系统额定电压仍选设备所属的系统电压档位，不自行除以三或根号三；三相之间不同的铭牌参数不属于当前单模板配置能力。

### 三种身份不能混用

- `portKey`：固定电气槽位身份，例如 `inA`；用于端口和挂点 Box 引用，不是对象显示名称。
- `anchorPath`：该槽位绑定的原始 GLB 节点路径；改显示名不改路径，替换模型后须重新校验。
- 相别（保存为 `portKind`，运行时有 phase 语义）：独立电气属性，不是对象或端口的主键。合同 3 修改相别只改当前挂点的 `portKind` 和派生电压，不改 `portKey`、`anchorPath`、Box 或其它部件。

普通创作者按中文角色和相别操作即可，不需要手填这些内部键。

## 修改方式

- 修改 `label` / `description`：调整显示名称和帮助说明。
- 修改参数的 `default`：仅影响之后创建的项目；已有项目保持自己保存的值。
- 修改 `options`：用于额定电压档位与准确级等分类选项；不能把可填写的数值参数改为强制档位。值以字符串保存，并须符合 `type`。整数必须写作 `"5"`，不能写 `"5.0"` 或 `"5e0"`。
- 修改 `min` / `max`：可收窄本地填写范围；不能放宽到平台或游戏不支持的值。
- 修改 `category.variants`、参数键或类型、端口含义、组件 ID 等合同字段，需要同步平台与 Unity 的合同版本，不能仅修改本地 JSON 新增任意组件。

模板在读取时进行完整校验。缺失、重复或不合法模板会关闭创建功能并显示错误，不回退到不受限制的通用设备。修改模板后重新打开 Creator 项目或创建新项目即可重新读取；编辑过程中不周期性刷新、覆盖参数。

## 保存与发布

项目的 `devices/device.device.json` 保存 `templateId`、`templateVersion`、白名单 `simulationComponentId`，以及 `simulation` 中每项参数的 `key` / `value` / `type` 副本。发布源包包含该已保存的 Profile；不依赖创作者电脑上的模板路径。Unity 加载时按官方组件映射还原这些参数，平台和游戏仍独立校验。

六类新项目统一使用 `templateVersion=3`，旧 1/2 精确兼容。它与 `.dwdhmod` 外层格式 v2、Profile schema 2 不同，不改变加密方式。合同 2/3 最低游戏版本为 1.1.29，要求配套 Launcher、Hub 和游戏，不允许旧端猜测加载。建筑可整组不配置，配置时必须配齐对应用途的物理槽位；每个槽位都允许 0/A/B/C/N。输电塔需 3～16 个连续 `attachment01..N`，不再要求至少三个通用 0。N 和架空地线的端口额定电压派生为零，其它相别继承设备/用途电压，不手填。发布只写项目副本，不覆盖模板。

## 部件编辑与碰撞

新项目的 `defaults.collision` 为 `{ "shape": "selective", "version": 1, "meshNodes": [], "portBoxes": [] }`。物体本体只需在“场景节点”页勾选“生成网格碰撞”：路径加入 `meshNodes` 后，Unity 按该节点自己的网格创建 MeshCollider，不填写中心或大小；取消即不生成。最多 64 个路径且必须有自身网格，父分组不能隐式给所有子物体添加碰撞。勾选节点合计最多 128 个网格 Primitive、100000 个三角形实例；界面显示预算，发布与游戏端也独立验证，避免为高密度模型无限生成碰撞。移动、旋转、缩放仍作用于同一节点。

挂线点则在“电气挂点”页单独启用 Box，保存 `{portId, center[3], size[3]}`，最多 16 个。`portId` 对应当前已启用挂点，节点路径仍以挂点配置为唯一来源，不另写一份路径。中心各轴为 −256～256 米，大小各轴为 0.001～256 米，默认中心为零、大小为 0.15 米；参数与黄色 Box 实时联动，随所绑定节点变换。它与物体本体网格碰撞是两种独立用途。

旧 `shape: box` 和此前开发中的 `compound` 草稿按原值保留并提示兼容；需要改用新设置时，作者在“设备参数”页逐项明确移除旧盒，最后一个移除后进入空的 selective 配置，不静默丢弃旧值。替换模型后失效的网格或挂线点碰撞引用也必须明确移除，不能悄悄跳过。背包占地始终是整台设备的独立设置，绿色地面参考范围实时反馈，不由子节点碰撞倒推。

部件名称、位置、旋转与缩放在参数输入和视口操作柄间实时联动，保存到项目 `sceneNodeOverrides`，不重写作者源 GLB。点击底栏保存后随源包发布；Unity 按同一稳定节点路径恢复。编辑与可视化均由操作/状态变化驱动，不刷新网络、不周期重读模板。

## 模型单位

模板中的距离、挂点 Box 中心/尺寸和最终 GLB 均以米为单位。FBX 导入依据文件 `UnitScaleFactor`（每文件单位对应多少厘米）转换为米，即乘以 `UnitScaleFactor × 0.01`；几何与节点位移只换算一次，作者节点缩放保留。缺省单位按 FBX 标准厘米处理，非法单位拒绝，不按模型看起来大小猜测。直接 GLB 已按 glTF 米制，不再乘 0.01。

中文 3ds Max 的“自定义 → 单位设置 → 系统单位设置”若为“1 单位 = 1 厘米”，真实尺寸 100 × 100 厘米的模型导入后应是 1 × 1 米；显示单位 cm 不能代替系统单位。FBX 导出“高级选项 → 单位”可保留“自动”。完整操作见 Unity 工程 `Assets/Tools/SimSubModCreator/README.md` 的“3ds Max 中文单位与模型尺寸”。

此前因 FBX 单位遗漏导错的工作区不会自动缩小，应重新导入原 FBX。若之前用“统一缩放 = 0.01”手动补偿，请在重导入后核对并恢复需要的真实倍率，通常为 1；不能对所有已有 GLB/项目统一改倍率。源模型文件、已发布包和用户旧草稿都不会被此次修复直接改写。

高级 Unity AssetBundle Mod 的旧制作与加载链路独立保留，本目录仅控制启动器标准 GLB/JSON v2 Mod。
