Installation

Installation, Upgrade and Removal

简体中文 | English

← Back to the index

This page covers three things only: how to get MobInteract onto your server, how to confirm it is actually working, and what it touches when you upgrade or remove it. For behaviour tuning and commands, see Related pages at the bottom.

• Current version 1.2.1, api-version: 1.21.8, folia-supported: true.
• The same jar loads on Paper / Purpur / Canvas / Folia 1.21.8 ~ 26.x.
• It only takes over mobs (zombies, skeletons, illagers, piglins, witches, ...). Boats, armour stands, dropped items and players are out of scope, and villagers / wandering traders are not taken over by default — test with a zombie, not with a villager.

1. Before You Install: Check Your Server Version

Item	Value
Supported servers	Paper / Purpur / Canvas / Folia
Supported server versions	1.21.8 ~ 26.x
api-version declared by the jar	1.21.8
folia-supported	true
Minimum supported version	1.21.8

api-version is the jar telling the server "I need at least this new an API". The server compares it exactly once, while scanning plugin metadata at startup:

• api-version not newer than the server → loads normally. One jar covers 1.21.8 ~ 26.x.
• api-version newer than the server → rejected at startup, the console throws InvalidPluginException: Unsupported API version X, and the plugin shows up red (not enabled) in /plugins; a later load through something like PlugMan does not help either and reports That file is not a valid plugin / Plugin didn't load any plugin providers?.

That is why the released jar always declares the oldest supported version, 1.21.8 — it can be dropped on old and new servers alike without being rejected.

1.1 Why It Cannot Go on an Older Server

MobInteract uses Paper pathfinding / scheduling APIs that only exist as of 1.21.8. Servers older than 1.21.8 do not have them, so the behaviours it attaches to mobs cannot run. 1.21.8 is the floor; upgrade the server first instead of trying to work around the check.

1.2 A Trap in 1.2.0 and Earlier

The 1.2.0 jar hard-coded api-version as 26.3, so it failed to load on first start on servers such as Paper / Purpur 26.2:

[ModernPluginLoadingStrategy] Could not load plugin ... InvalidPluginException: Unsupported API version 26.3

The plugin showed red in /plugins, and a later PlugMan load could not rescue it. If you see this error, switch to the 1.2.1 jar — no config change is needed.

2. Installing

1. Stop the server (at the very least, do not replace the jar while it is running).
2. Download the jar for your version from the project's Releases (current version 1.2.1, file name MobInteract-1.2.1.jar).
3. Drop the jar into the server's plugins/ directory.
4. Start the server.

The jar is a single self-contained file: no extra libraries to install, and no changes to the server core are required.

After startup the plugin registers the command /mobinteract (alias /mi), permission mobinteract.admin (op only by default).

BlockLocker is a soft dependency: if it is installed it is picked up automatically (mobs will not mine or blow up the chests, doors and trapdoors it protects); if it is absent nothing about this plugin changes.

3. What Gets Generated on First Start

The first start writes four yml files into plugins/MobInteract/, all with Chinese comments. You can run them untouched — the defaults are what they contain:

File	What it governs	A few key defaults
mining.yml	Mining: triggers, reach, duration, pickaxes, feedback	enabled: true, tool.require-pickaxe: true, break-time.multiplier: 4.0, break-time.hard-cap-seconds: 180.0, debug: false
placement.yml	Placement / path building + pickup	config-version: 2, enabled: true, placement.max-per-chase: 32, placement.block-lifetime-seconds: 15, backpack.chance: 0.65, pickup.enabled: true
equip.yml	Spawn-equipment master gate	chance: 0.10; worlds.<world name> overrides per world, world names are case-insensitive
message.yml	Every text sent to players (the output of /mobinteract status / inspect / reload)	Generated automatically; deleting a key falls back to the built-in default without affecting startup
update.yml	Update check: on/off, which repository to ask, how often, who gets told	enabled: true, repository: LiuyeStudio/MobInteract, first-delay-seconds: 60, interval-hours: 6, console: true, include-prerelease: false

Things worth knowing:

• mining.yml and placement.yml each have an enabled; the one in placement.yml also controls pickup.
• Turning off enabled in placement.yml stops path building and pickup together, while mining still follows mining.yml.
• equip.yml governs the spawn-equipment chance; worlds.whitelist / worlds.blacklist in mining.yml / placement.yml govern in which worlds the behaviours apply. They are two different things.
• All texts are configurable in colour and wording (& colour codes, {placeholders}, multi-line YAML lists); see Spawn Equipment and Messages.

1.2.x also ships targeting.yml (player chase priority), and /mobinteract reload re-reads it together with the four above. Its keys are enabled (default true), radius (default 16.0), interval-ticks (default 10), require-line-of-sight (default false) and keep-villager-target (default true).

4. Making Config Changes Take Effect

/mobinteract reload re-reads those six yml files: parsing runs on the global region thread and, once the new immutable snapshot exists, it is swapped in wholesale without interrupting mining or placement in progress. Behaviours already running keep the old values; newly started ones use the new values. The reply reports the number of messages currently in effect, which is how you confirm message.yml was actually read.

• Config-only changes → reload is enough, no restart needed.
• Replacing the jar, or changing api-version → a restart is required; reload cannot do it.
• reload requires the mobinteract.admin permission.

5. Upgrading from 1.1.0 to 1.2.0

The order: stop the server → swap the jar → start once (so the plugin writes the missing files) → check your old config against the two tables below.

The plugin never rewrites your files. Where an old file still holds an old value, the file wins — if you want the new defaults, change them yourself.

5.1 New Files and New Keys

Item	Notes
New equip.yml	Spawn-equipment master gate. Generated automatically on first start if missing; the plugin still runs without it, treating a missing key as chance: 0.10
New message.yml	Every text sent to players is now configurable. Generated automatically if missing; deleting a key falls back to the built-in default without affecting startup
debug	Per-candidate-block decision log, defaults to false when the key is missing
trigger.dig-below-self	Mines the block under itself when the target is below, defaults to true when the key is missing
break-time.hard-cap-seconds	Default 180.0; if an old file still says 45, the file wins (obsidian and the like are classed as "cannot be mined"), so raising it to 180 is recommended
placement.block-lifetime-seconds	Default 15; change the old value yourself if needed — the plugin never rewrites your config
placement.max-per-chase	With an old config-version: 1 and the old default value 10, it runs as 32 and warns in the console (the file is left untouched); raising it manually is recommended
config-version	Currently 2; the migration only covers max-per-chase, and every other key takes its value from the file
/mobinteract status	One extra line showing the spawn-equipment chance and the per-world override count

5.2 Default Value Changes

Config	New default	Notes
break-time.multiplier	4.0 (was 2.0)	Halves the mining speed
break-time.hard-cap-seconds	180.0 (was 45)	The old value classified hard blocks such as obsidian as "cannot be mined"; each skipped material produces one console notice
placement.block-lifetime-seconds	15 (was 60)	Meant to be used together with "renewed for a full cycle while a creature stands on it"
placement.max-per-chase	32 (was 10)	The old value made long bridges / tall pillars stop halfway; with config-version < 2 and a value of 10 it runs as 32 with a warning (file untouched)
Built-in fallbacks tool.give.chance / backpack.chance	0.8 / 0.65	Aligned with the bundled yml; only effective when a key is deleted

5.3 Three Things to Change by Hand After Upgrading

Old files do not change themselves, and these three are the easiest to trip over:

1. break-time.hard-cap-seconds: 45 → 180.0. Leave it and hard blocks such as obsidian stay "cannot be mined" forever (each skipped material produces one console notice, which is how you confirm this is the cause).
2. placement.max-per-chase: 10 → 32 (or larger). Leave it and long bridges / tall pillars stop halfway.
3. placement.block-lifetime-seconds: 60 → 15. The old value still works, the blocks mobs build just stay in the world longer.

Also note that the keys debug, dig-below-self, hard-cap-seconds, block-lifetime-seconds and max-per-chase all exist in the 1.2.0 mining.yml / placement.yml; after upgrading, check your files against the key tables in Mining / Placement to make sure no key is missing (a missing key falls back to its default).

6. Upgrading from 1.2.0 to 1.2.1

Swapping the jar is all it takes — 1.2.1 introduces no new config keys. This release fixes "will not install" and "installs but never takes over":

Symptom	Cause	What 1.2.1 does
First start fails on servers such as Paper / Purpur 26.2: [ModernPluginLoadingStrategy] Could not load plugin ... InvalidPluginException: Unsupported API version 26.3, red in /plugins, and a later PlugMan load reports That file is not a valid plugin / Plugin didn't load any plugin providers?	The jar hard-coded api-version: 26.3, so the server rejected a declaration newer than itself during the startup scan	Now api-version: 1.21.8: one jar loads on 1.21.8 ~ 26.x
After the first mob failed to be taken over, no mob was taken over for the rest of the run and only reloading the plugin restored it (typical symptom: it suddenly works after a reload)	A transient failure (chunk unloading, entity about to be removed, ...) was treated as "the server does not support this", and that flag was never reset	Only a genuine lack of support disables it; a transient failure warns once and keeps retrying for later mobs
The console keeps spewing diagnostic logs	[diag] output left over from 1.2.0 debugging	Removed

7. Confirming It Works After Installing

Go through these four steps in order; do not dig deeper until the current one passes.

7.1 It Is Green in /plugins

MobInteract shows green (enabled) in /plugins, not red. Red means it never loaded — go back to Section 1 and check the server version against api-version.

7.2 /mobinteract status Produces Output

/mobinteract status (or just /mobinteract, /mi) should print a configuration summary containing: world / mob filters, mining parameters, tools, placement limits, path-building strategy, pickup, spawn equipment, known mob count, number of mobs currently mining, temporary block count, BlockLocker integration state. As of 1.2.0 there is also a spawn-equipment line (chance plus the number of per-world overrides).

If this prints normally, config parsing, command registration and the filters are all working.

7.3 forceload + summon, Then Watch the Known Mob Count

This is the only check that separates "the plugin loaded" from "the plugin actually took over this mob" on a real server:

1. Use the vanilla forceload command to keep the target chunk loaded, so the mob is not unloaded right after spawning;
2. Use summon to create a zombie;
3. Run /mobinteract status again and see whether the known mob count went up.

Up = the behaviours are attached to that mob. If it does not go up, check in this order:

• whether the world / mob was filtered out: an empty worlds.whitelist means all worlds, and mob-blacklist always wins;
• whether you spawned a villager / wandering trader / iron golem — those are not taken over by default, so try a zombie;
• whether you are on the 1.2.0 jar (see the "first failure disables everything" issue in Section 6).

Before release, 1.2.1 was checked on three minimal servers — Folia 26.3, Canvas 26.3 and Purpur 26.2: /plugins green, status normal, and the count rising after forceload + summon.

7.4 Watch the Behaviour: Only ~9% of Mobs Carry Equipment by Default

If a summoned zombie does not mine or build, there is a good chance it simply did not roll any equipment. Spawning passes the master gate in equip.yml first, then splits:

passes the gate (chance in equip.yml, default 0.10)
├── pickaxe roll: mining.yml tool.give.chance (default 0.80)
└── backpack roll: placement.yml backpack.chance (default 0.65)

With the default configuration the share of mobs with "pickaxe ∪ blocks" is roughly 0.10 × (0.80 + 0.65 − 0.52) ≈ 9.3%. So when verifying:

• spawn several mobs; do not expect the first one to carry equipment;
• use /mobinteract inspect on the mob within 16 blocks of your crosshair (within about a 20° angle and with line of sight) to see its actual state: cooldowns, placements used in the current chase, main-hand pickaxe, most recent behaviour, pillar height, backpack contents;
• the gate is rolled once, at spawn, and the result is fixed. An already spawned mob never receives equipment later — to give it a pickaxe you must respawn it or hand it over manually.

The "most recent behaviour" line from /mobinteract inspect is the first-hand information for "why isn't it moving", for example 放置次数已用完（max-per-chase=32）, 放置失败 cobblestone @x,y,z, 挖掘停滞，已放弃.

7.5 When You Need Finer Logs

Set debug to true in mining.yml and the console prints the accept/reject reason for every candidate block (选中 … 耗时 … / 跳过 …：原因), plus the renewal decision when a temporary block expires. It floods the log — turn it off afterwards.

8. It Does Nothing? Check These First

The "no action" row of the behaviour overview is, in effect, a troubleshooting table:

Check	How to look at it
Server version	Is it ≥ 1.21.8 and not older than the jar's api-version
Master switches	enabled in mining.yml / placement.yml; the one in placement.yml also controls pickup
World filter	worlds.whitelist / worlds.blacklist, blacklist wins; an empty whitelist means all worlds
Mob filter	mob-whitelist / mob-blacklist; an empty whitelist means the default humanoid set, which excludes villagers / wandering traders; blacklist wins
Spawn equipment	chance in equip.yml, default 0.10; a mob that failed the gate never gets blocks / a pickaxe on any path
Has a pickaxe	With tool.require-pickaxe: true (default), no pickaxe in the main hand means no mining at all
Backpack / placements	No backpack, or placement.max-per-chase (default 32) used up
Has a target	No chase target means no path building
Cooldowns	cooldown-seconds: 8.0 after breaking a block; failures retry after retry-seconds: 1.5

9. Removing the Plugin

Deleting the jar removes the plugin. When it is disabled (server shutdown / jar removed) it does three things in order, all with one purpose: cleaning up the blocks it placed in your world.

1. Writes every currently registered "mob-placed block" into plugins/MobInteract/pending-blocks.txt;
2. Deletes them one by one directly (comparing the material first), and on failure dispatches that removal to the region owning the block;
3. Deletes the journal file once everything has been removed.

A few details worth knowing:

• If the plugin is still installed (a plain shutdown and restart), the next start deletes them again from pending-blocks.txt; entries whose chunks are not loaded stay in the journal until they load. This layer exists to cover a hard kill during shutdown, when region threads no longer execute tasks.
• The registry lives in memory only: a runtime kill -9 (never reaching the disable step) leaves no journal behind, so those temporary blocks stay in the world and can only be cleaned up by hand.
• The registry caps at 50,000 entries; beyond that the oldest records are evicted in insertion order, and evicted blocks are no longer protected and no longer expire automatically. Servers that set placement.block-lifetime-seconds: 0 (permanent) and accumulate blocks for a long time are the most likely to hit this cap.
• Permanent blocks from placement.block-lifetime-seconds: 0 are removed on shutdown too — setting them permanent does not keep them in the world.
• Removing the jar does not delete the config files in plugins/MobInteract/; delete that directory too if you want a clean slate (check pending-blocks.txt first in case it still lists blocks you want removed).
• Removing the plugin does not rewind the world: blocks that were mined stay gone, and only "blocks the mobs placed themselves" are in the cleanup scope.

Related pages

• Mining — the full mining.yml key table, trigger priority and duration maths
• Placement — placement.* in placement.yml and the three path-building actions
• Backpack and Pickup — backpack.*, entries, pickup.*
• Spawn Equipment and Messages — how to write equip.yml and message.yml
• Commands — the full output of /mobinteract status / inspect / reload, and permissions
• FAQ — why nothing happens after installing, why mobs do not mine or build
• Changelog — what changed in each version, including default value changes