Installing Mods on a Mindustry Server

Mindustry Server Mods

Mindustry has two distinct types of server mods — they work differently and have different requirements for players.

Type 1: Server-Side Plugins

File format: .jar (compiled Java) or .js (JavaScript)

How they work: Run entirely on the server. Players don't need anything installed. Invisible to clients.

Common uses: Admin tools, Discord bots, automated announcements, logging, custom commands.

Installation:

1. Download the plugin .jar or .js file
2. Upload to config/mods/:

   scp MyPlugin.jar user@YOUR_IP:~/mindustry-server/config/mods/
   

3. Restart the server

Verify it loaded:

Check the console output on startup for:

[INFO] Loaded plugin: MyPlugin

Plugin sources:

• GitHub: mindustry-plugin topic
• Popular examples: Essentials, ServerPackets

Type 2: Content Mods

File format: .zip

How they work: Add new game content — blocks, units, planets, items. The server broadcasts its mod list to connecting players. Both the server AND all clients must have identical mod versions — a mismatch causes an immediate disconnect with "Mod Mismatch" error.

Installation:

1. Install the mod in your local Mindustry client first (Mods → Mod Browser)
2. Find the installed .zip file on your PC:
   • Windows: %AppData%\Mindustry\mods\
   • Linux: ~/.local/share/Mindustry/mods/
   • macOS: ~/Library/Application Support/Mindustry/mods/
3. Upload the .zip to config/mods/:

   scp ContentMod.zip user@YOUR_IP:~/mindustry-server/config/mods/
   

4. Restart the server

Tell your players to install the same mod version from the in-game Mod Browser before joining.

Mod Directory Structure

config/
└── mods/
    ├── EssentialsPlugin.jar    ← server-side plugin
    ├── MyScript.js             ← server-side plugin
    ├── ContentMod-v1.2.zip     ← content mod (clients need this too)
    └── AnotherMod-v3.0.zip     ← content mod

Troubleshooting

"Mod Mismatch" on connect: Server and client mod versions differ. Ensure both have the exact same .zip file (same version number).

Plugin not loading:

• Confirm the file is in config/mods/ (not a subdirectory)
• Check console for error stack traces on startup
• Plugin may be built for a different Mindustry API version — check the plugin's GitHub for version compatibility

Server crashes on startup after adding a mod: Remove the mod file and restart to confirm it's the cause. Check the plugin's issue tracker for known crash bugs.