Commands zh

命令、权限与行为总览

简体中文 | English

← 返回目录

这一页面向服主：怪物什么时候会动手、四条子命令各自能看出什么、权限怎么给、生物与世界怎么筛，以及同一份插件为什么能直接装在 Paper 和 Folia 上、和 BlockLocker 怎么共存。

行为总览

行为	触发	关键配置
挖掘	头顶被压 / 目标在下方 / 目标脚下 / 寻路被前方方块挡住 / 面前出现指定方块	mining.yml 全部
放置	追击目标与自身之间有高度差或沟壑，且背包里还有方块	placement.yml 的 placement.* + backpack.* + entries
拾取	半径内有“值得捡”的掉落物（方块 / 镐子）	placement.yml 的 pickup.*
不动作	没镐子（挖掘）、没背包 / 次数用完（放置）、没目标、世界或生物被筛掉、冷却中	enabled、worlds、mob-whitelist/blacklist、equip.yml

挖掘的触发条件

命中即返回，顺序如下（前面的先判定）：

顺序	触发	条件	配置键
1	挖头顶	目标比自己高 ≥1.5 格，且脚上方第 2 格被方块压着	trigger.ceiling-blocked
2	挖自己脚下	目标比自己低 ≥1.5 格、水平 3 格内、自己站在地上、脚下第二格不是液体	trigger.dig-below-self
3	挖目标脚下	目标比自己高 ≥0.5 格，且目标下方那一格可挖	trigger.dig-under-target
4	寻路受阻	先查正前方脚下 / 头顶那两格，再看“眼睛 → 目标”射线上的第一处实体方块	trigger.path-blocked
5	指定方块	面前 max-distance 范围内出现 trigger.configured-blocks.blocks 里的方块（不要求挡视线）	trigger.configured-blocks.enabled

• 前面还有一道工具门槛：tool.require-pickaxe: true（默认）时主手不是镐子，就完全不参与挖掘。
• 每个候选方块还要依次通过材料、安全、可及范围、保护区、耗时检查；射线不穿透，第一处不可通过方块挖不动就直接放弃，不会隔着一层基岩去挖后面的方块。
• 安全黑名单（基岩、屏障、命令方块、结构方块、传送门、移动活塞、刷怪笼等）、世界高度与世界边界之外一律不动；默认也不挖带方块实体的容器。
• require-adjacent: true（默认）时只挖紧贴身体的方块（水平 ±1、竖直 −1..+2）；设 false 退回按 max-distance（默认 4.5）判断。
• protect-mob-blocks: true（默认）不挖怪物自己或同伴放下的方块，刚搭好的桥不会被自己拆掉。

放置（搭路）的触发条件

• 有追击目标（placement.vertical-aggro: true 时可主动锁定上方 16 格内可见的生存 / 冒险玩家）；
• 背包非空（backpack.chance 抽中，或拾取攒下来的方块）；
• 本次追击放置次数未达 placement.max-per-chase（默认 32），且不在放置冷却中；
• 挑出的条目里如果有功能方块（TNT / 桶），special-only-under-target: true（默认）时只放在目标所在那一格，不参与搭路。

策略顺序是近战 → 上岸 → 抬高（楼梯 / 垫高）→ 搭桥 / 往下搭：

条件	动作
横向 < 1 格且目标不高出 2 格	不放置，交给原版近战
自己泡在水里（脚所在格或其下一格是液体）	先走到附近干燥落脚点，不消耗方块
高度差 ≥ 2 格且横向 ≥ stair-min-distance(4)、高度差 < pillar-far-height(8)	搭楼梯
高度差 ≥ pillar-far-height(8)，或横向 ≤ pillar-near-distance(2)	原地垫高
其余	先垫高到目标高度，再朝目标横向搭桥
目标明显更低（vertical-drop 默认 1.5）且前方是深沟	往下搭一格

不乱放的几条硬规则：前方本来就有台阶 / 实地就直接走上去；落差 ≤ 3 格直接走下去；前方或前方脚下是液体不铺；前方是两格以上的墙交给原版绕行或挖掘；落点那一格里有任何生物（含追击目标本身不算）就不放；被同伴挤住先让位。

拾取的触发条件

• pickup.enabled: true（默认）时，每只被接管且通过世界 / 生物筛选的怪物每秒检查一次半径内的掉落物；注意 placement.yml 的 enabled 是总开关，同时管放置与拾取；
• 搜索半径 pickup.radius 默认 8.0（水平 radius，竖直 max(2, radius × 0.5)），进入 pickup.reach（默认 1.8）才真正捡起；reach 必须小于 radius，否则自动下调为 radius / 2 并告警；
• 只捡“值得捡”的方块和镐子：不捡有重力的方块（沙子、沙砾），也不捡基岩、刷怪笼这类硬黑名单方块与非方块物品；
• 方块进方块背包，镐子进主手（pickup.blocks / pickup.pickaxes）；拿不住就丢回地上，不会凭空吞掉；
• 正在挖掘 / 放置的怪物不会被拾取打断。

什么时候什么都不做

症状	原因	去哪里看
完全不动手	没镐子（tool.require-pickaxe: true 且主手不是镐子）	equip.yml 的 chance、tool.give.chance
不搭路	没背包，或本次追击放置次数已用完（max-per-chase），或背包空了	backpack.chance、placement.max-per-chase
目标都没有	没有追击目标；targeting.yml 关掉后不会主动锁玩家	targeting.yml 的 enabled / radius
整片区域都不动	世界被筛掉：worlds.whitelist 非空且不含该世界，或该世界在 worlds.blacklist 里	mining.yml / placement.yml 的 worlds.*
只有某些怪不动	生物被筛掉：不在默认人形集合、被 mob-blacklist 命中，或 mob-whitelist 非空但没列它	mob-whitelist / mob-blacklist
动一下就停几秒	冷却中：挖掘成功 cooldown-seconds（默认 8 秒）、失败 retry-seconds（默认 1.5 秒）、功能方块放置 placement.cooldown-seconds（默认 3 秒）	mining.yml / placement.yml
对着方块干看	耗时超过 break-time.hard-cap-seconds，视为“挖不动”直接跳过（每种材质控制台提示一次）	break-time.hard-cap-seconds、materials.multiplier
什么都不生效	对应文件的 enabled 是 false	mining.yml / placement.yml 的 enabled

排查的顺序建议是：先 /mobinteract status 确认筛选和开关没把整片区域关掉，再用 /mobinteract inspect 看具体那只怪的“最近行为”，最后才开 debug 看候选方块取舍（会刷屏，排查完关掉）。

命令

命令是 /mobinteract，别名 /mi。不带参数等价于 status。

子命令	说明
/mobinteract reload	重载六份配置文件（mining.yml / placement.yml / equip.yml / targeting.yml / message.yml / update.yml），回话里带当前消息条数
/mobinteract status	配置摘要：世界 / 生物筛选、挖掘参数、工具、放置上限、搭路策略、拾取、出生装备、已知怪物数、正在挖掘数、临时方块数、BlockLocker 接入状态
/mobinteract inspect	只能玩家执行；看准星 16 格内（夹角约 20° 以内、有视线）的怪物：冷却、单次追击已放置数、主手镐子、最近行为、垫高格数、背包内容
/mobinteract update	去 GitHub Releases 查一次有没有新版本，结果只回给执行命令的人

/mobinteract reload

• 六份配置文件一起重读，message.yml 与 update.yml 也在其中：改提示文案、改概率、改筛选、改检查间隔都不需要重启服务器。
• 世界里已经生成的怪也会跟着变：档案会被重建，出生装备与背包按新配置重新掷骰。
• 热重载的边界：配置整体替换成新快照，正在进行的挖掘 / 放置不会被打断。已经在挖的那个方块继续按旧参数挖完，正在搭的那一段继续按旧参数搭；重载之后新启动的行为才用新值。
• 回话里带当前消息条数，用来确认 message.yml 确实被读到（条数对不上通常是文件没存盘或 YAML 缩进写坏了）。
• 某个键被删掉时会回退到内置默认值并在控制台告警一次，不会因此报错或让插件停摆。
• 想改这一条回话本身，改 message.yml 的 command.reload.success（带 {count} 占位符）再 reload 一次即可。

/mobinteract status

一次看全服的口径，适合“刚装好先确认配置对不对”：

• 世界筛选与生物筛选的当前结果（全部世界 / 全部生物 / 默认人形 / 白名单(n) / 黑名单(n)）；
• 挖掘参数（距离、邻接、冷却）、工具与发放概率；
• 放置上限与搭路策略、拾取开关；
• 出生装备概率；
• 运行时数字：已知怪物数、正在挖掘数、临时方块数；
• BlockLocker 接入状态，显示为“BlockLocker 保护：是/否”。

/mobinteract inspect

• 只能由玩家执行（控制台执行会得到“仅玩家可用”的通用提示）。
• 看的是准星 16 格内、夹角约 20° 以内、且有视线的怪物；准星偏了或隔着墙都取不到。
• 输出里有：冷却、单次追击已放置数、主手镐子、最近行为、垫高格数、背包内容（每个背包条目一行）。
• 「最近行为」是排查“为什么不动”的第一手信息，例如：

放置次数已用完（max-per-chase=32）
放置失败 cobblestone @x,y,z
挖掘停滞，已放弃

看到 放置次数已用完 就调 placement.max-per-chase；看到 放置失败 多半是落点被占或前方是液体；看到 挖掘停滞，已放弃 说明连续 3 秒没有进度（通常是目标方块被别的东西挡住或区域任务没提交成功）。

/mobinteract update

• 立刻查一次，不用等后台的定时检查；结果只回给执行命令的人（控制台或玩家）。
• 做的事：向 GitHub Releases 要最新的正式版（草稿不算），把它的版本号和当前运行的 jar 版本对比，然后回答四种结果之一 —— 已是最新；有新版本（附发布页链接）；update.yml 里关掉了检查；检查失败（通常是服务器连不上 api.github.com）。
• 结果会缓存成"最近一次结果"，控制台的提示和 OP 上线提醒都复用它，所以人多也不会反复打 GitHub。
• 不会自动下载安装，升级依旧是自己换 jar。
• 检查间隔、首次延迟、是否包含预发布版、三个提醒开关都在 update.yml；文案在 message.yml 的 update.* 与 command.update.* 下。

输出文案与权限提示

• 所有发给玩家的文本（status / inspect / reload 的输出，含筛选摘要、状态词、背包条目模板）都在 message.yml，首次启动自动生成。
• 通用片段是 command.common.no-permission / usage / player-only；状态词是“开启 / 关闭”“开 / 关”“是 / 否”“无”“永久”“不可挖掘”“已判定 / 未判定”。
• 颜色码用 &（如 &7、&f），占位符用 {名字}（已用到的有 {count}、{mob}、{worlds}、{percent}、{seconds}、{max}、{maxPerChase}、{kinds}、{total}、{id}、{type} 等）。
• 任何一条消息都可以写成 YAML 列表，按顺序逐行发送；想把 status 的某一行拆成两行时用这个。

权限

权限节点	默认	作用范围
mobinteract.admin	op	/mobinteract 及其别名 /mi 的全部子命令：reload、status、inspect、update

• 插件只为这个命令定义了一个节点，四条子命令都归它管：没有单独给 status 或 inspect 的只读节点。想让普通管理员只看状态，就把 mobinteract.admin 给对应的组，接受他们同时能用 reload。
• 默认只有 op 能用；用权限组插件授权时，节点名照抄 mobinteract.admin，不要带斜杠。
• 没权限时走 message.yml 的 command.common.no-permission，可以自己改文案。
• 命令本身不改任何游戏规则，reload 也只是重读配置，因此不需要额外的高权限节点。

生物与世界范围

只接管 Mob

插件只接管 Mob 子类（会自己走动、有 AI 的生物），不碰玩家、盔甲架、掉落物、船 / 矿车这类实体。默认接管的是这套人形集合：

• 僵尸（含溺尸 / 尸壳 / 僵尸村民 / 僵尸猪灵）
• 骷髅（含流浪者、凋灵骷髅等骨架类）
• 灾厄村民（卫道士、唤魔者、掠夺者）
• 猪灵
• 女巫

村民 / 流浪商人不在集合里；需要时写 mob-whitelist: [VILLAGER, WANDERING_TRADER] 显式加回。mob-whitelist: ["*"]（或 ALL / ANY）表示全部生物；mob-blacklist 永远优先——同时在两个名单里时按黑名单处理。

筛选对挖掘、放置、拾取三件事同时生效：被筛掉的怪物既不会挖、也不会搭、也不会捡。

两种“世界配置”是两件事

文件	键	管什么
equip.yml	chance、worlds.<世界名>	出生装备概率：这个世界的怪物出生时有多大机会带镐子 / 方块（世界名不区分大小写）
mining.yml / placement.yml	worlds.whitelist / worlds.blacklist	行为是否生效：白名单留空 = 所有世界；非空 = 只在这些世界；黑名单优先

• 世界名不区分大小写，world 与 World 是同一个世界；写错名字不会报错，只会表现为“这个世界里没反应”，所以填完用 /mobinteract status 确认筛选结果。
• 黑名单优先于白名单：同一个世界同时出现在两份名单里，视为关闭。
• 想让主世界和资源世界才有行为、小游戏世界完全不受影响：worlds.whitelist: [world, resource]，或反过来把 world_minigame 写进 worlds.blacklist。
• 出生装备闸门（equip.yml 的 chance，默认 0.10）与两道细分概率的关系：

通过闸门（equip.yml 的 chance，默认 0.10）
├── 抽镐子：mining.yml tool.give.chance（默认 0.80）
└── 抽背包：placement.yml backpack.chance（默认 0.65）

所以出生时“带镐子 ∪ 带方块”的比例不超过 chance（默认配置下约 9.3%）。闸门的结果对这只怪而言是终局：没通过闸门的怪物之后不会再补发背包或镐子，pickup.only-equipped（默认开启）也把“捡来的装备”挡在闸门之外。

Folia：同一份插件、区域线程与清除延迟

为什么一个 jar 通吃 Paper 和 Folia

• 插件没有假设“所有世界跑在同一个主线程上”。行为判定、冷却、背包、计数都在怪物自己所属的区域线程上完成；真正改方块（挖掉、放下、倒流体、点 TNT）则投递到目标方块所在的那条区域线程去执行。
• 需要抬高时用异步传送再切回怪物自己的线程放方块，不会在错误的线程上碰世界。
• 因此同一份 jar 直接丢进 plugins/ 即可：Paper 上照常跑，Folia 上也不会因为跨区域访问而报错或崩服。两种服务端不需要装不同版本。
• 行为是“加”上去的，不是“替换”原版 AI：只新增挖掘与搭路两条行为，激活时抢占移动与朝向，停下时把控制权还给原版。

区域线程对“到期方块清除”的影响

怪物放下的方块默认 15 秒后消失（placement.block-lifetime-seconds，0 = 永久，只做来源标记）。在 Folia 上这套清除不是“到点立刻删”：

• 清扫是定时批处理：全局每 20 tick（1 秒）扫一次到期表，再把同一区块的到期方块合并成一次区域任务，一次删一批。所以实际消失时间 = 到期时间 + 最多约 1 秒（再加该区域当时的排队）。
• 有生物站在上面会续期：到期时方块上方 1.2 格内有活着的生物（含正在过桥的怪物）→ 再延一个完整周期。所以桥上有怪时，桥不会塌在它脚下，你看到“方块活得更久”是设计行为。
• 删前再校验材质：玩家后来把那个位置换成了别的方块，只丢记录、不误删。
• 区块没加载就等：该条延后 5 秒重试，不丢记录；等区块被加载后照样清掉。这也是离线跑图时“回来发现旧桥还在、过一会儿才消失”的原因。
• 关服 / 卸载兜底：把所有登记过的方块（含设为永久的）写进 plugins/MobInteract/pending-blocks.txt，先直接删、删不掉再投递到方块所在区域；下次启动再按清单清一遍，覆盖“关服过程中被强杀”的情况。
• 登记表上限 5 万条，超出会按插入顺序淘汰最旧记录；怪物活动量特别大的服可以把 placement.block-lifetime-seconds 调小，减少同时在册的方块数。

区块未加载时的重试

• 要改的方块所在区块当时如果还没有就绪的任务队列，这一次提交会失败；插件把“没提交成功”当成一次失败处理，按 retry-seconds 进一次短冷却后重试，而不是留一个“已经开始但永远不会结束”的挖掘。
• 到期清除遇到区块未加载走的是另一条路径：延后 5 秒重试，记录保留，不当作删除成功。

与 BlockLocker 共存

• 这是软依赖：装了 BlockLocker 只影响加载顺序，没装时功能完全不受影响，也不会因为缺它而启动失败。
• 启动时会尝试接入 BlockLocker 的保护查询；接入成功后，挖掘、放置、炸方块三条路径都会跳过被它保护的方块——箱子、门、活板门、木桶等。
• /mobinteract status 里能看到当前是否接入（“BlockLocker 保护：是/否”），部署后先确认这一行。
• 查询失败按“不保护”处理（fail-open），每个实例只告警一次，避免 BlockLocker 自身出错把怪物行为整体卡死。也就是说：BlockLocker 坏掉时怪物会重新变得“会拆箱子”，这一点在排查 grief 投诉时要记得。
• 其它保护插件（WorldGuard、Residence 等）通过扩展点注册判定即可；注册多个时任意一个拒绝即视为受保护，不会有“后注册的覆盖前面的”的情况。
• 建议顺序：先只在一小块区域开 worlds.whitelist 观察，确认箱子 / 门没被动过，再放大到全服。

相关页面

• 安装、升级与卸载
• 挖掘
• 放置
• 背包与拾取
• 装备与消息
• 常见问题
• 变更记录