概述
插件开发 (SDK) 概述
Section titled “插件开发 (SDK) 概述”NP Editor 可以通过 C# 插件扩展功能。插件是一个包含一个 dll 和一个 plugin.json 的文件夹。插件只引用一个 SDK（NP.Editor.Sdk.dll），无需了解 Godot 或编辑器的内部代码。
本文档以 SDK 1.3.0 为准。当前编辑器的 SDK 版本显示在「工具 › 插件管理器…」窗口的顶部，形如 SDK 1.3.0。
插件可以添加的内容
Section titled “插件可以添加的内容”| 添加位置 | 编辑器界面 | 注册点 | SDK |
|---|---|---|---|
| 菜单项 | 菜单栏（文件 · 编辑 · 窗口 · 工具 · 构建 · 帮助，新名称 = 新菜单） | AddMenuItem | 1.0 |
| 快速添加 | 主工具栏「添加」（搜索 · 分类 · 图标） | AddQuickAddItem | 1.0 |
| 控制台命令 | 下方「控制台」面板 | AddCommand | 1.0 |
| 导入 · 导出 | 「文件 › 导入: …」 · 「构建 › 导出: …」 | AddImporter · AddExporter | 1.0 |
| 面板 | 下方区域的面板（从「窗口」菜单打开） | AddContentTab + NpUi | 1.0 |
| 模式 | 主工具栏的模式栏 + 工具面板 + 视口点击 | AddMode | 1.0 |
| Actor 类型 | 大纲「类型」列中的文字 · 颜色 | AddActorType | 1.0 |
| 格守卫 · 对称 | 介入所有方块编辑 | AddCellGuard · AddSymmetry | 1.0 |
| 画面验证场景 | --np-shot=<id> 自动截图 · 检查（编辑器开发用构建） | AddShotScenario | 1.0 |
| 快捷键 | 「工具 › 快捷键…」（用户可更改） | AddShortcut | 1.1 |
| 保存设置 | 每个插件一个 JSON 文件 | host.Settings | 1.1 |
| 3D 叠加绘制 | 视口上的线 · 框 · 文字 | host.Draw | 1.1 |
| 世界逻辑 type | 世界逻辑 · 逻辑图 · 检查 · MCP · 运行预览 | AddSceneEvent | 1.2 |
| 读取场景 Actor · 运行相机 | 场景 Actor 列表、运行中的相机 | host.Scene · host.View | 1.3 |
插件也可以读写世界（host.World）。方块状态字符串采用 Minecraft 格式（minecraft:oak_stairs[facing=east]）。一次 World.Edit 即为一步撤销。
外部插件与内置插件
Section titled “外部插件与内置插件”| 外部插件（本文档的对象） | 内置插件 | |
|---|---|---|
| 位置 | 插件文件夹中的一个文件夹 | 编辑器内部 |
| 引用 | 仅 NP.Editor.Sdk.dll | 编辑器内部代码 |
| 启用 · 禁用 | 在插件管理器中操作，无需关闭编辑器 | 始终启用 |
| 错误 | 仅隔离该插件，编辑器继续运行 | 随编辑器一同修复 |
| 兼容性 | 由 SDK 版本（semver）保证 | 与编辑器版本相同 |
编辑器的基本功能（方块笔刷 · 地形景观 · 世界逻辑等）也是采用相同注册结构的内置插件。内置插件还会使用不对外公开的注册点（视图模式 · 视口拖放 · 选择面板区域等）。本文档只讨论外部插件。
我的插件.dll ──引用──> NP.Editor.Sdk.dll (接口 · 数据类型) │ 插件宿主 (检查 plugin.json · 比较 SDK 版本 · 加载上下文 · 错误隔离) │ NP Editor (菜单 · 模式 · 面板 · 世界逻辑 · 视口)| 层 | 作用 |
|---|---|
| 我的插件 dll | 在 INpEditorPlugin.Register(host) 中调用注册点。 |
NP.Editor.Sdk.dll | 只包含接口和数据类型。编辑器已预先加载同一文件，并与插件共享。 |
| 插件宿主 | 检查 plugin.json 并比较 SDK 版本。为每个插件单独创建加载上下文，捕获插件代码中的异常并只禁用该插件。 |
| 编辑器 | 将注册的内容挂接到菜单 · 工具栏 · 面板 · 世界逻辑。禁用时全部移除。 |
注册的内容在编辑器内会加上 ext.<插件 id>. 前缀，因此不会与内置功能或其他插件重名。控制台命令名和世界逻辑 type 例外。详情见加载与生命周期。
| 项目 | 值 |
|---|---|
| 编辑器 | NP Editor 0.9.1 及以上（SDK 1.3）。若只使用到 SDK 1.2 的功能，0.9.0 也可以。 |
| .NET | .NET 8 SDK（dotnet --version 为 8. 及以上） |
| 语言 | C# 12（目标 net8.0） |
| 编辑工具 | 任意 C# 编辑工具（Visual Studio · Rider · VS Code） |
| SDK dll | 编辑器安装文件夹中的 data_NPEditor_windows_x86_64\NP.Editor.Sdk.dll |
编辑器的默认安装文件夹为 %LOCALAPPDATA%\Programs\NP Editor。
安全：插件是未经签名检查、以与编辑器相同权限运行的代码。请只放入自己制作或从可信来源获取的插件。详情见分发与版本。
| 想做的事 | 文档 |
|---|---|
| 10 分钟做出第一个插件 | 快速开始 |
了解 plugin.json 的字段 | plugin.json |
| 启用 · 禁用 · 错误隔离的工作方式 | 加载与生命周期 |
| 世界读写、事件、设置、3D 绘制 | 宿主 API |
| 菜单 · 模式 · 命令等全部注册点 | 注册点 |
| 制作面板 UI | 面板 UI (NpUi) |
| 为世界逻辑添加触发器 · 条件 · 动作 | 添加世界逻辑 type |
| 运行中的相机演出 | 场景读取与运行相机 |
| 测试 · 调试 | 测试与调试 |
| 分发给他人 | 分发与版本 |
| 出现错误时 | 故障排除 |
| 各 SDK 版本的变化 | SDK 更新日志 |
| 示例源码 | 示例: hello_tool · 示例: csv_export · 示例: event_example |