首先在「工具 › 插件管理器…」中查看状态列和下方的详细行。然后在输出日志中查找 [插件 <id>] 行。各状态的含义见加载与生命周期。
| 症状 | 原因 | 解决 |
|---|
| 管理器列表中没有 | plugin.json 不在文件夹根目录（多嵌套了一层） | 移动为 plugins\<文件夹>\plugin.json 的形式。 |
| 管理器列表中没有 | 放入文件夹后没有重新扫描 | 点击「重新扫描」。 |
| 管理器列表中没有 | 放到了其他文件夹 | 放入通过「工具 › 打开插件文件夹」打开的文件夹。管理器窗口顶部会列出所有读取的文件夹。 |
| 一直停在「等待」 | 在首次运行警告中点击了「本次不加载」 | 取消「启用」勾选后再重新勾选，警告会再次出现。重启编辑器也会出现。点击「可信 — 加载」。 |
「错误 (文件)」 id 格式错误 | 含大写字母 · - · 以数字开头 | 以小写字母开头，只使用小写字母 · 数字 · _ · .。 |
「错误 (文件)」 version 格式错误 | 像 1.0 这样只有两段 | 像 1.0.0 这样写成三段。 |
「错误 (文件)」 缺少 sdk … · sdk 版本错误 | 没有 sdk 字段或写法有误 | 写成 "^1.0" 的形式。 |
「错误 (文件)」 dll 必须位于 plugin.json 旁… | dll 中含 .. 或绝对路径 | 写成相对于 plugin.json 的相对路径。 |
「错误 (文件)」 找不到 dll | 没有构建，或名称不同 | 使构建输出的 dll 名称与 dll 字段一致。 |
「错误 (已隔离)」 加载失败: … 找不到 entry 类型 | entry 的命名空间 · 类名有误 | 写出 命名空间.类 的完整名称，大小写也要一致。 |
「错误 (已隔离)」 加载失败: … 没有 INpEditorPlugin 实现 | 没有入口类，或入口类为 abstract · 没有无参数的 public 构造函数 | 在 public sealed class Plugin : INpEditorPlugin 中提供无参数构造函数。 |
「错误 (已隔离)」 加载失败: … 不是 INpEditorPlugin (无参构造函数) | entry 类未实现 INpEditorPlugin，或没有无参数的 public 构造函数 | 确认实现和构造函数。 |
「错误 (文件)」 相同 id … 已存在 | 其他文件夹中有相同的 id | 删除其中一个或更改 id。 |
「版本不匹配」 需要 SDK ^1.3 — 本编辑器为 1.2.0 | sdk 范围高于编辑器的 SDK | 更新编辑器，或根据所用功能降低 sdk。 |
「版本不匹配」 加载失败: MissingMethodException 等 | 用新 SDK 构建，但 sdk 写得过低 | 将 sdk 提高到实际所用功能的版本。 |
「错误 (已隔离)」 加载失败: … | Register 中发生异常 | 修正输出日志中的异常。参见下方「注册」表。 |
| 症状 | 原因 | 解决 |
|---|
刚启用就「错误 (已隔离)」 … 为空 | Id · Name · Kind · 快捷键名称 · 键为空字符串 | 填写空字段。 |
「错误 (已隔离)」 无法解析快捷键按键 | "1~8" · "W/E/R" · "Ctrl++" 之类的键字符串 | 写成 "Ctrl+Alt+H" 的形式。参见注册点中的键表。 |
| 「错误 (已隔离)」 与场景事件 type 有关 | 同一角色中已存在相同 Type（内置 cinematic 等） | 在 Type 前加上自己的名称。 |
| 控制台命令未生成 | 已存在同名命令 · 名称中含空格 | 在名称前加上自己的名称并去掉空格。 |
| 菜单出现在意外的位置 | Menu 名称拼写错误（生成了新菜单） | 使用 "파일" · "편집" · "창" · "도구" · "빌드" · "도움말" 之一。 |
| 看不到面板 | 面板以关闭状态生成 | 在「窗口」菜单中打开该面板。 |
| 模式栏中看不到模式 | 前 8 个之后的模式位于「更多」中 | 打开模式栏末尾的「更多」。 |
| 菜单 · 标签页名称中的符号消失 | 图形字符会在界面上被去除 | 只写文字，图标通过 Icon 字段以图标名称指定。 |
| 症状 | 原因 | 解决 |
|---|
| 使用中变为「错误 (已隔离)」 | 回调（菜单 · 命令 · 事件 · 面板文字 · Simulate）中发生异常 | 查看输出日志中的 错误 → 已隔离 — <位置>: … 并修正，然后点击「重新加载 (所选)」 |
World.Edit 中出现 InvalidOperationException | 其他大型编辑任务（填充 · 地形）正在进行 | 任务结束后重试。捕获异常并改为通知。 |
| 方块未更改 · 返回值偏少 | 锁定的格（协作建造锁定 · 已锁定的 Actor · 格守卫） | 通过返回值（更改的格数）确认。 |
| 方块显示为紫黑棋盘格 | 方块状态字符串拼写错误 · 缺少命名空间 | 准确地写成 minecraft:stone_bricks 这样的形式。 |
| 需要按多次 Ctrl+Z 才能恢复 | 多次调用了 Edit | 将一个操作合并到一次 Edit 中。 |
| 新世界中残留了前一个世界的绘制 · 状态 | 未在 WorldChanged 中清空 | host.WorldChanged += _ => { …Clear(); host.Draw.Clear(); }; |
| 编辑时编辑器卡顿 | Committed 处理器过重 | 只做计数，繁重的工作稍后再做。 |
| 打开面板后编辑器卡顿 | 动态文字（Label(() => …)）扫描了世界 | 把值存在字段中，文字中只读取。 |
| 面板数字字段与保存值不同 | 面板在启用时只创建一次 | 在 Register 开头先读取 Settings。 |
SetCamera 返回 false | 未在运行中 · 值为 NaN | 先检查 host.View.Playing。 |
host.WorldChanged -= … 不起作用 | 宿主事件不支持 -= | 在处理器内用标志过滤。 |
| 设置丢失 | 设置文件损坏，以空设置启动 | 检查 plugin_settings\<id>.json.bad。 |
| 症状 | 原因 | 解决 |
|---|
| 重新构建的内容未生效 | 插件文件夹中残留旧 dll · 未重新加载 | 覆盖新的 dll 并点击「重新加载 (所选)」 |
| 「重新扫描」后未生效 | 已启用的插件不会重新加载 | 使用「重新加载 (所选)」。 |
| 禁用后仍未从内存中卸载 | 静态事件 · 计时器 · 线程中残留了自己的对象 | 在 IDisposable.Dispose 中解除。 |
| 禁用后后台任务仍在运行 | 未停止 Task.Run 任务 | 在 Dispose 中用 CancellationToken 停止。 |