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.

Platforms:

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.

• 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.

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

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.

• 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.

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.

Commands

Permission: modutils.admin (operators by default).

Setup

1. Drop the jar in plugins/ and start the server.
2. Edit plugins/ModUtils/config.yml, then /modutils reload.
3. Every message is in plugins/ModUtils/translations/en_US.yml (MiniMessage). Add other languages by adding more locale files.

Optional plugins: ViaVersion, Geyser, Floodgate, CraftEngine, ItemsAdder, Nexo and Oraxen are detected and used automatically if installed.

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.

TODO's

• Add older version support
• Create API for Jade & TheOneProbe for custom data to display
• Support Bukkit