Mod Utils

Server-side support for client mods on Paper, plus a way to keep unwanted mods out.

Mod Utils lets players with popular client mods get the full experience on a plain Paper server, with support for clients on Fabric or NeoForge. It also has a mod blocker that kicks players whose client has mods you don't allow.

---

⚠️ Active Development & Testing Notice

Mod Utils is currently under active development.

• Work in Progress: Configs, permissions, commands, and features are not final and are subject to change.
• I would love your feedback! Please test the plugin on your server and report any bugs, performance issues, or feature requests.
• Version Rule of Thumb: All features are guaranteed to work flawlessly when both the client and the server are running on the exact same Minecraft version. Some features do not fully work cross-version yet.

---

Platforms:

!Supported Paper Logo !Supported Purpur Logo !Supported Spigot Logo

---

Version compatibility

One jar runs on Paper 1.20.6 up to 26.3. With ViaVersion, server and client versions can be mixed freely, as long as both are in the supported range for the mod.

Cross-Version Support Status

Mod	Server version	Client version
AppleSkin	1.20.5 or newer	1.20.5 or newer
TrashSlot	1.20.5 or newer	1.20.6 or newer
Shulker Box Tooltip	1.20.5 or newer	1.20.6 or newer
Jade🔍	1.20.5 or newer	1.20.5 or newer
The One Probe	1.20.5 or newer	1.20.5 or newer
JEI	1.21.3 or newer	1.21.3 or newer
Polymer	1.21.3 or newer	1.21.3 or newer

• JEI and Polymer work together. With Polymer on the client, custom items from your server show correctly in JEI recipes.
• JEI without Polymer on the client: JEI still gets your server's recipes. Recipes that use custom items are shown with a stand-in item (a dragon egg by default, and you can change it in config.yml). The recipe works, but custom ingredients don't render properly and show as that stand-in item.
• Without ViaVersion, clients must be on the same version as the server.
• Clients older than the server also need ViaBackwards.

---

Mod Compat

Each mod below can be switched on or off in config.yml, and only does something for players who have that mod installed.

Mod	Needs	What the server adds
Jade🔍	Server 1.20.5+	Furnace and brewing progress, beehives, jukeboxes, chest, barrel and shulker contents, mob growth and breeding timers, pet owners, custom block names
The One Probe	Server 1.20.5+	Crop growth, furnaces, brewing stands, storage contents, mob health, pet owners
AppleSkin	Server 1.20.5+	Accurate saturation and exhaustion in the hunger overlay
TrashSlot	Server 1.20.5+	Items in the trash slot can be taken back, and deleting works on the server
Shulker Box Tooltip	Server 1.20.5+	The preview of a player's ender chest (shulker boxes work without the server)
JEI	Server 1.21.3+	The + button recipe transfer, and sending your server's recipes, custom ones included
Polymer	Server 1.21.3+	Custom items show properly in JEI recipes, and operators see them in the creative tab

• Individual features can be switched off, such as furnace, itemStorage or mobHealth.
• Per-player rate limits protect the server from request spam.

---

Mod Block

Kicks players whose client has mods you don't want, and lists everything it found.

• Channel detection: blocks mods that use networking, by mod id.
• Translation detection: finds client-only mods that have no networking, by checking whether one of their language keys exists on the client.
• A fully customisable kick message.
• Permission modutils.modblock.bypass skips the check.
• Off by default.

---

Plugin Hooks

Mod Utils hooks into other plugins when they are installed, and does nothing for the ones that aren't. /modutils status lists the hooks that are active, and a hoverable button shows the ones that aren't installed.

Plugin	What it is used for
ViaVersion	Supports players on other client versions by translating item and component data for their version
ViaBackwards	Works alongside ViaVersion to translate item and registry data backwards for players on older client versions
Geyser / Floodgate	Detects Bedrock players, who are skipped by every compat
CraftEngine (26.5+)	Shows the custom items in CraftEngine recipes correctly in JEI, with no config needed
ItemsAdder (Not Tested)	Looks up ItemsAdder items by id for the ingredients setting
Nexo (Not Tested)	Looks up Nexo items by id for the ingredients setting
Oraxen	Looks up Oraxen items by id for the ingredients setting

• ViaVersion: players on other client versions are supported. Item and component data is translated for their version.
• Bedrock players (Geyser or Floodgate) are skipped.
• CraftEngine: CraftEngine builds some recipes out of plain stand-in items, so JEI would show a plain item. Mod Utils asks CraftEngine's API which custom items a recipe really takes.
• Other plugins: if a recipe from another plugin shows a plain item in JEI, add a rule under modCompat.polymer.ingredients in config.yml. Its like setting takes a custom item id from any hooked plugin. A plugin prefix picks which one to look from: craftengine:default:topaz, itemsadder:namespace:id, nexo:ruby, oraxen:ruby. Without a prefix, every installed plugin is asked (Less Efficient).
• Safe fallback: if a plugin's API isn't a version Mod Utils knows, the hook turns itself off and logs a warning, and items show as plain items.

---

Commands

Command	Does
/modutils status	Supported versions, which compats are on, blocked mods, and the plugin hooks that are active (hover the button for those not installed)
/modutils players [name]	Each player's client, version and which client mods they have
/modutils set <setting> <value>	Changes a setting live, saves it to config.yml (comments stay) and restarts only that feature
/modutils reload	Reloads the config and restarts every feature

Permissions:

• modutils.admin: use /modutils (operators by default)
• modutils.update: get told about new versions (operators by default)
• modutils.modblock.bypass: skip the Mod Block check

---

Update Checker

Checks Modrinth for a newer version of Mod Utils and tells you about it.

• The console is told when a newer version is found.
• Players with the permission modutils.update (operators by default) are told when they join, with a clickable message that opens the page of the new version.
• On by default. Turn it off with updateChecker.enabled: false in config.yml.

---

Notes

• Supports Paper and its forks, including Folia.
• The server never needs the client mods installed.
• Licensed CC BY-NC-SA 4.0. See the project's third-party notices for the mods it talks to. None are bundled.

---

Metrics

---

TODO's

• Test Items Adder (Don't Own)
• Test Nexo (Don't Own)
• Add older version support
• Create API for Jade & TheOneProbe for custom data to display (currently not public or complete)