Repository navigation
Installation zh
简体中文 | English
本页只讲三件事：怎么把 MobInteract 装进服务端、装完怎么确认它真的在干活、升级和卸载时它会动到什么。行为怎么调、命令怎么用，见文末的相关页面。
- 当前版本 1.2.1，
api-version: 1.21.8，folia-supported: true。 - 同一个 jar 可在 Paper / Purpur / Canvas / Folia 1.21.8 ~ 26.x 上加载。
- 它只接管怪物（僵尸、骷髅、灾厄村民、猪灵、女巫等）；船、盔甲架、掉落物、玩家这类实体不在范围内，村民 / 流浪商人默认也不接管 —— 验证时请拿僵尸试，别拿村民试。
| 项目 | 值 |
|---|---|
| 支持的服务端 | Paper / Purpur / Canvas / Folia |
| 支持的服务端版本 | 1.21.8 ~ 26.x |
jar 里声明的 api-version
|
1.21.8 |
folia-supported |
true |
| 最低支持版本 | 1.21.8 |
api-version 是 jar 向服务端声明的"我至少要这么新的接口"。服务端只在开机扫描插件元数据那一步比一次，规则很简单：
-
api-version不高于服务端版本 → 正常加载。1.21.8 ~ 26.x 一个 jar 通吃。 -
api-version高于服务端版本 → 开机就被拒，控制台抛InvalidPluginException: Unsupported API version X，/plugins里这一项显示红色（未启用）；事后用 PlugMan 之类的工具补一次load也没用，会报That file is not a valid plugin/Plugin didn't load any plugin providers?。
所以正式发布的 jar 一律按最旧受支持版本 1.21.8 声明，装到新服旧服都不会被拒。
MobInteract 用到了 1.21.8 才有的 Paper 寻路 / 调度接口。比 1.21.8 更旧的服务端没有这些接口，插件挂到怪物身上的行为跑不起来。1.21.8 就是下限，更旧的版本请先升级服务端，不要试图绕过这个检查。
1.2.0 的 jar 把 api-version 写死成了 26.3，于是在 Paper / Purpur 26.2 这类服务端上首次启动就加载失败：
[ModernPluginLoadingStrategy] Could not load plugin ... InvalidPluginException: Unsupported API version 26.3
/plugins 里显示红色，PlugMan 事后 load 也救不回来。遇到这个报错，换 1.2.1 的 jar 即可，不需要改任何配置。
- 停服（至少要保证 jar 不是在运行中被替换）。
- 从项目的 Releases 下载对应版本的 jar（当前版本 1.2.1，文件名为
MobInteract-1.2.1.jar）。 - 把 jar 放进服务端的
plugins/目录。 - 启动服务端。
jar 是自带全部内容的单个文件，不需要额外装任何依赖库，也不要求改服务端核心。
启动后插件会注册命令 /mobinteract（别名 /mi），权限 mobinteract.admin（默认只给 op）。
BlockLocker 是软依赖：装了就自动生效（怪物不会去挖 / 炸它保护的箱子、门、活板门），没装也完全不影响本插件的功能。
首次启动会在 plugins/MobInteract/ 下生成四个 yml，全部带中文注释。不改任何一行也能直接跑，跑的就是默认值：
| 文件 | 管什么 | 几个关键默认值 |
|---|---|---|
mining.yml |
挖掘：触发条件、可及范围、耗时、镐子、反馈 |
enabled: true、tool.require-pickaxe: true、break-time.multiplier: 4.0、break-time.hard-cap-seconds: 180.0、debug: false
|
placement.yml |
放置搭路 + 拾取 |
config-version: 2、enabled: true、placement.max-per-chase: 32、placement.block-lifetime-seconds: 15、backpack.chance: 0.65、pickup.enabled: true
|
equip.yml |
出生装备总闸门 |
chance: 0.10；worlds.<世界名> 可按世界覆盖，世界名不区分大小写 |
message.yml |
所有发给玩家的文本（/mobinteract status / inspect / reload 的输出） |
首次启动自动生成；某个键被删掉会回退内置默认值，不影响启动 |
update.yml |
检查更新：开关、查哪个仓库、多久查一次、谁能收到提醒 |
enabled: true、repository: LiuyeStudio/MobInteract、first-delay-seconds: 60、interval-hours: 6、console: true、include-prerelease: false
|
几点必须知道的：
-
mining.yml和placement.yml各有一个enabled；placement.yml的那个同时控制拾取。 -
placement.yml的enabled关掉后，搭路和拾取一起停，但挖掘仍然按mining.yml走。 -
equip.yml管的是出生装备概率，mining.yml/placement.yml里的worlds.whitelist/worlds.blacklist管的是行为在哪些世界生效，两件事别混。 - 所有文本都能改颜色和措辞（
&颜色码、{占位符}、YAML 列表多行），写法见出生装备与玩家文本。
1.2.x 里还有一份
targeting.yml（优先追杀玩家），/mobinteract reload会把它和前四份一起重读。它的键是enabled（默认true）、radius（默认16.0）、interval-ticks（默认10）、require-line-of-sight（默认false）、keep-villager-target（默认true）。
/mobinteract reload 会重读这六份 yml：解析在全局区域线程完成，产出新的不可变快照后整体替换，不打断正在进行的挖掘 / 放置。进行中的行为继续用旧值，新起的行为用新值。回话里会带上当前生效的消息条数，可以用它确认 message.yml 真的被读进去了。
- 只改配置 →
reload就够，不需要重启。 - 换 jar、换
api-version→ 必须重启，reload办不到。 -
reload需要mobinteract.admin权限。
顺序是：停服 → 换 jar → 启动一次（让插件把缺的文件补出来）→ 对照下面两张表核对自己的旧配置。
插件不会改写你的文件。 旧文件里还写着旧值的键，一律以文件为准 —— 想用新默认值就得自己动手改。
| 项目 | 说明 |
|---|---|
新增 equip.yml
|
出生装备总闸门。缺失时首次启动自动生成；不生成也能跑，缺键按 chance: 0.10 处理 |
新增 message.yml
|
所有发给玩家的文本改为可配置。缺失时首次启动自动生成；某个键被删掉会回退内置默认值，不影响启动 |
debug |
逐候选方块的取舍日志，缺键默认 false
|
trigger.dig-below-self |
目标在下方时挖自己脚下那一格，缺键默认 true
|
break-time.hard-cap-seconds |
默认 180.0；旧文件里若仍写着 45，以文件为准（黑曜石等会被判"挖不动"），建议改成 180 |
placement.block-lifetime-seconds |
默认 15；旧值请按需手动改，插件不会改写你的配置 |
placement.max-per-chase |
旧版 config-version: 1 且值为旧默认 10 时，自动按 32 运行并在控制台告警（文件不改动）；建议手动改大 |
config-version |
当前为 2；迁移只做 max-per-chase 这一项，其它键的值一律以文件为准 |
/mobinteract status |
多一行「出生装备」概率与按世界覆盖数量 |
| 配置 | 新默认 | 说明 |
|---|---|---|
break-time.multiplier |
4.0（旧 2.0） | 挖掘速度减半 |
break-time.hard-cap-seconds |
180.0（旧 45） | 旧值会把黑曜石等硬方块判成"挖不动"，跳过的材质会在控制台提示一次 |
placement.block-lifetime-seconds |
15（旧 60） | 配合"到期时上方站着生物就再延一个完整周期"使用 |
placement.max-per-chase |
32（旧 10） | 旧值会让长桥 / 高柱搭到一半停手；config-version < 2 且值为 10 时按 32 运行并告警（文件不改） |
内置兜底的 tool.give.chance / backpack.chance
|
0.8 / 0.65 | 与内置 yml 对齐，只在键被删掉时生效 |
旧文件不会自己变，下面三处最容易踩：
-
break-time.hard-cap-seconds：45→180.0。不改的话黑曜石这类硬方块永远"挖不动"（被跳过的材质每种会在控制台提示一次，方便你确认是这里的问题）。 -
placement.max-per-chase：10→32（或更大）。不改的话长桥、高柱搭到一半就收手。 -
placement.block-lifetime-seconds：60→15。不改也能用，只是怪物搭出来的方块在地图上留得更久。
另外，debug、dig-below-self、hard-cap-seconds、block-lifetime-seconds、max-per-chase 这几个键在 1.2.0 的 mining.yml / placement.yml 里都存在；升级后请对照挖掘 / 放置与搭路 的键表，确认自己的文件没漏键（漏键时按默认值运行）。
只换 jar 就行，1.2.1 没有引入新的配置键。这一版修的是"装不上"和"装上了却不接管"两件事：
| 症状 | 原因 | 1.2.1 的处理 |
|---|---|---|
在 Paper / Purpur 26.2 等服务端上首次启动就加载失败：[ModernPluginLoadingStrategy] Could not load plugin ... InvalidPluginException: Unsupported API version 26.3，/plugins 显示红色，PlugMan 事后 load 还报 That file is not a valid plugin / Plugin didn't load any plugin providers?
|
jar 把 api-version 写死成 26.3，服务端在开机扫描阶段就拒绝了比自己新的声明 |
改为 api-version: 1.21.8，一个 jar 在 1.21.8 ~ 26.x 都能加载 |
| 第一只怪物接管失败后，整场运行期所有怪物都不再被接管，只有重载插件才恢复（典型症状：reload 之后突然就好了） | 把一次暂时性失败（区块卸载中、实体正要移除等）当成了"服务端不支持"，且这个判断置位后不再复位 | 只有真正不支持时才停用；暂时性失败只提示一次，并继续对后续怪物重试 |
| 控制台一直刷诊断日志 | 1.2.0 调试期留下的 [diag] 输出 |
删除 |
按顺序走这四步，前一步不通过就别往下查。
/plugins 里 MobInteract 显示绿色（已启用）而不是红色。红色说明根本没加载成功，回去看第 1 节的服务端版本和 api-version。
/mobinteract status（或直接 /mobinteract、/mi）应该打印一份配置摘要，包含：世界 / 生物筛选、挖掘参数、工具、放置上限、搭路策略、拾取、出生装备、已知怪物数、正在挖掘数、临时方块数、BlockLocker 接入状态。1.2.0 起还多一行「出生装备」（概率 + 按世界覆盖数量）。
这一步能正常输出，说明配置解析、命令注册、筛选条件都通了。
这是在真实服务端上唯一能区分"插件加载了"和"插件真的接管了这只怪物"的检查：
- 用原版命令
forceload让目标区块常驻，避免怪物刚生成就被卸载； - 用
summon生成一只僵尸； - 再执行一次
/mobinteract status，看「已知怪物数」是否上涨。
上涨 = 行为已经挂到这只怪物身上了。不涨的话按这个顺序查：
- 世界 / 生物有没有被筛选掉：
worlds.whitelist留空 = 所有世界，mob-blacklist永远优先； - 生成的是不是村民 / 流浪商人 / 铁傀儡 —— 这些默认不接管，换成僵尸试；
- 是不是 1.2.0 的 jar（见第 6 节那个"第一只失败后全部不接管"的问题）。
1.2.1 发布前在 Folia 26.3、Canvas 26.3、Purpur 26.2 三个最小服上都跑过这套检查：/plugins 绿色、status 正常、forceload + summon 后计数上涨。
summon 一只僵尸看不到它挖方块 / 搭路，非常可能只是因为它没抽到装备。出生时先过 equip.yml 的总闸门，再细分：
通过闸门（equip.yml 的 chance，默认 0.10）
├── 抽镐子：mining.yml tool.give.chance（默认 0.80）
└── 抽背包：placement.yml backpack.chance（默认 0.65）
默认配置下"带镐子 ∪ 带方块"的比例约 0.10 × (0.80 + 0.65 − 0.52) ≈ 9.3%。所以验证时：
- 多生成几只，别指望第一只就带装备；
- 用
/mobinteract inspect看准星 16 格内（夹角约 20° 以内、有视线）那只怪物的实际状态：冷却、单次追击已放置数、主手镐子、最近行为、垫高格数、背包内容； - 闸门只在出生那一刻掷一次，结果是固定的。已经生成的怪物不会补装备，想让它带镐子只能重新生成或手动给。
/mobinteract inspect 里的「最近行为」是排查"为什么不动"的第一手信息，例如 放置次数已用完（max-per-chase=32）、放置失败 cobblestone @x,y,z、挖掘停滞，已放弃。
把 mining.yml 的 debug 改成 true，控制台会打印每个候选方块的取舍原因（选中 … 耗时 … / 跳过 …：原因），以及临时方块到期时的续期判定。会刷屏，排查完记得关掉。
行为总览里那个"不动作"的行，其实就是一张排查表：
| 检查项 | 怎么看 |
|---|---|
| 服务端版本 | 是否 ≥ 1.21.8，且不低于 jar 的 api-version
|
| 总开关 |
mining.yml / placement.yml 的 enabled；placement.yml 的那个同时控制拾取 |
| 世界筛选 |
worlds.whitelist / worlds.blacklist，黑名单优先；白名单留空 = 所有世界 |
| 生物筛选 |
mob-whitelist / mob-blacklist；白名单留空 = 默认人形集合，村民 / 流浪商人不在集合里；黑名单优先 |
| 出生装备 |
equip.yml 的 chance，默认 0.10；没通过闸门的怪物在任何路径上都拿不到方块 / 镐子 |
| 有没有镐子 |
tool.require-pickaxe: true（默认）时，主手不是镐子就完全不挖 |
| 背包 / 次数 | 没背包，或 placement.max-per-chase（默认 32）已经用完 |
| 有没有目标 | 没有追击目标就不会搭路 |
| 冷却 | 挖断一个方块后有 cooldown-seconds: 8.0 冷却；失败重试是 retry-seconds: 1.5
|
删除 jar 就算卸载。 插件被停用（关服 / 移除 jar）时会按顺序做三件事，目的只有一个：把它自己在世界里放过的方块清干净。
- 把当前登记的所有"怪物放的方块"写进
plugins/MobInteract/pending-blocks.txt； - 逐个直接删除（先比对材质），失败则把这次删除投递到该方块所在的区域；
- 全部删干净就删掉清单文件。
几个细节值得知道：
- 如果插件还在（只是关服重启），下次启动时会按
pending-blocks.txt再删一遍；区块没加载的条目留在清单里，等区块加载后再删。这一层专门用来覆盖"关服过程中被强杀、区域线程已不再执行任务"的情况。 - 登记表是内存态：运行期直接被
kill -9（没走到停用流程）不会留下清单，那些临时方块会留在世界里，只能手动清理。 - 登记表上限 5 万条，超出后按插入顺序淘汰最旧记录；被淘汰的方块不再受保护、也不再自动到期。把
placement.block-lifetime-seconds设成0（永久）的服务器长期累积时更容易碰到这个上限。 -
placement.block-lifetime-seconds: 0的永久方块也会在卸载时被清掉，不会因为设成永久就留在世界里。 - jar 删掉后，
plugins/MobInteract/里的配置文件不会自动删除；想彻底清干净就自己把这个目录也删掉（删之前确认pending-blocks.txt里没有你还想清掉的方块）。 - 卸载不会让世界复原：已经挖掉的方块不会长回来，只有"怪物自己放的方块"才在清理范围内。
MobInteract · QQ 群 995974858 · Repository · Releases · Issues · English | 简体中文