分发与版本

插件以一个文件夹的形式分发。接收者将该文件夹放入插件文件夹，并在插件管理器中启用。

应包含的文件

文件	是否包含	说明
plugin.json	是	位于文件夹根目录
自己的 dll	是	plugin.json 中 dll 的路径
自己使用的其他 dll（NuGet 包等）	是	放在自己的 dll 旁。构建输出中的 .deps.json 也一并放入。
.pdb	可选	日志中会显示错误位置（行号）。
NP.Editor.Sdk.dll	否	使用编辑器自带的。在 csproj 中用 Private=false 排除。
较大的数据	可选	放在文件夹内，通过 host.PluginDir 查找。

road_tools\
├─ plugin.json
├─ RoadTools.dll
├─ RoadTools.deps.json
├─ RoadTools.pdb
└─ data\
   └─ presets.json

从 dotnet build -c Release 的输出文件夹中挑出上述文件并压缩。告知接收者以下步骤。

1. 解压后，将 road_tools 文件夹放入插件文件夹（工具 › 打开插件文件夹）。
2. 在「工具 › 插件管理器…」中点击「重新扫描」。
3. 若是首次，在安全警告中点击「可信 — 加载」。

放入编辑器安装文件夹下的 plugins\ 文件夹，编辑器也会读取。

自己的版本号（version）

plugin.json 的 version 按 semver（major.minor.patch）递增。显示在插件管理器的「版本」列中。

更改内容	递增位	例
只修复了 bug	patch	1.2.0 → 1.2.1
添加了功能（保存格式 · 命令不变）	minor	1.2.1 → 1.3.0
更改了命令名 · 世界逻辑 type · 设置键 · 保存格式	major	1.3.0 → 2.0.0

• 世界逻辑的 Type 和字段的 Name 会保存在地图文件（scene.json）中。更改后，旧地图中的规则会变为「未知 type」。
• 不要更改 id。设置文件 · 用户更改的快捷键都以 id 保存。

sdk 范围

sdk 写实际所用功能的最低版本。

使用的内容	sdk	可运行的编辑器
仅 SDK 1.0 功能	^1.0	SDK 1.0 ~ 1.x 全部
Settings · Draw · AddShortcut	^1.1	SDK 1.1 ~ 1.x
AddSceneEvent	^1.2	SDK 1.2 ~ 1.x（编辑器 0.9.0 及以上）
Scene · View · ActorList	^1.3	SDK 1.3 ~ 1.x（编辑器 0.9.1 及以上）

• 写得过高，旧版编辑器的用户将无法使用。
• 写得过低，在旧版编辑器中加载时会因缺少成员而失败（「版本不匹配」）。
• 不要使用没有上限的范围（>=1.0）。在下一个 major 版本中可能会在不兼容的状态下被加载。

SDK 兼容承诺

承诺	内容
同一 major 内	类型 · 成员只增不减。不会更改或删除名称。
新字段	作为带默认值的末尾字段添加。旧代码可原样编译。
破坏性变更	提升 major 版本（2.0）。^1.x 插件会以「版本不匹配」安全停止，编辑器继续运行。
行为	在同一 major 内不改变注册点的含义。

各版本的变更见 SDK 更新日志。

安全

插件是未经签名检查、在这台计算机上以与编辑器相同权限运行的代码。

能阻止的	无法阻止的
插件代码的异常 → 只禁用该插件（隔离）	无限循环 · 栈溢出 · 进程终止
清理已禁用插件的注册 · 绘制 · 相机	文件的读取 · 写入 · 删除
	网络访问

• 编辑器首次发现插件时会弹出一次警告。
• 请只放入自己制作或从可信来源获取的插件。
• 分发时一并告知源码或出处。
• 不要在插件中放入密钥 · 令牌。dll 很容易被反编译。

发布前确认

• 已提升 plugin.json 的 version。
• sdk 为所用功能的最低版本。
• 文件夹中没有 NP.Editor.Sdk.dll。
• 放入新的用户文件夹后，通过「重新扫描」可以启用。
• 启用 → 禁用 → 启用后，菜单 · 面板不会重复或残留。

详细清单见故障排除中的「发布前确认」。

相关文档

• plugin.json
• 加载与生命周期
• SDK 更新日志
• 故障排除