How to Install Mods on a Mindustry Dedicated Server

1. Understanding Mindustry Mod Types

Before installing anything, it is crucial to understand the difference between the two primary types of Mindustry modifications, as they behave fundamentally differently on a server:

• Content / Logic Mods: These mods introduce new turrets, units, environmental blocks, resources, or altered logic processors. Because they change the rules and assets of the game, both the server and every connecting client must have these mods installed to play together without syncing errors.
• Server-Side Plugins: These are `.jar` or `.js` script files that only run on the host server. They do not add visible blocks or units to the client game. Instead, they provide administration tools (kick/ban), chat censorship, advanced logging, economy tracking, or Discord webhook integrations. Connecting players do not need to download these.

2. Downloading Mods Repositories

Unlike Steam Workshop, where integration handles synchronization natively, you must manually acquire server mods from authorized sources.

The best and safest locations to acquire Mindustry mods and plugins are:

• The Official Mindustry Discord Server: The #mods and #servers channels contain direct links by authors to verified plugins and enormous asset packs.
• GitHub: Most prominent plugin developers host their `.jar` releases and documentation here. Search for "Mindustry Plugins" on GitHub.
• The In-Game Mod Browser: If you are looking for asset mods (like 'Exogenesis' or 'Fading Revelations'), you can browse and download them through the Mindustry client, then transfer those files to the server.

3. Installing Server-Side Plugins (Java & JS)

Plugins are the backbone of a successful public Mindustry server network. They grant your server the tooling required to mitigate griefing automatically and link your server chat to Discord.

Step 1: Locate the config/mods/ Directory

When you executed the vanilla server initially, a directory structure was created. Navigate to your Mindustry server's installation path:

cd ~/server/config/mods/

Step 2: Upload the Plugin

If you downloaded a `.jar` or `.js` file from a reputable developer on GitHub, transfer it to this directory using an SFTP client like FileZilla or WinSCP, or download it directly using `wget`:

wget https://github.com/ExampleDev/AdminPlugin/releases/latest/download/admin-plugin.jar

Step 3: Restart the Server

Mindustry plugins are loaded when the JVM initializes. Therefore, a server reboot is strictly required to hook the plugin into the game's event listeners.

sudo systemctl restart mindustry.service

Step 4: Verify Plugin Execution

Monitor your server console or check your logs. The startup sequence will explicitly print lines such as [Info] Loaded plugin: AdminPlugin v1.0. If it prints a stack trace error, the plugin may be outdated or incompatible with your current Mindustry version (e.g., trying to use a v135 plugin on v146).

4. Installing Content Mods (Units, Turrets, Blocks)

Adding new content to the game involves transferring `.zip` or `.jar` mod files directly into the same config/mods/ directory.

However, managing content mods poses a unique challenge: synchronization. When a player attempts to connect to your IP, the server will broadcast a list of required mods. If the player does not have these exact mods enabled (or if the server has mismatched versions), they will be disconnected with a "Mod Mismatch" or "Version Mismatch" error.

Step-by-Step Installation:

1. Launch your local Mindustry game client on your PC.
2. Navigate to Mods -> Mod Browser and install the desired overhauls (e.g., scheme size extenders, new planets).
3. Ensure they are enabled, then locate the physical `.zip` files on your local desktop (usually found in `%AppData%\Mindustry\mods` on Windows, or `~/.local/share/Mindustry/mods` on Linux).
4. Upload these exact `.zip` files via SFTP to your server's config/mods/ directory.
5. Restart the server. The headless server processes these zip bundles, registers the new JSON block definitions and logic circuits, and mandates them for joining players.

Pro Tip: Frequently advertise the exact modpack your server requires in your server's MOTD (Message of the Day) or a Discord `#announcements` channel to prevent player frustration from constant disconnects.

5. Configuring Plugins

Most sophisticated server plugins do not run optimally out of the box; they require precise JSON configuration tuning parameters like discord token keys, swearing blacklists, or economy multipliers.

When you restart the server after initially installing a new plugin, it will typically generate its own sub-folder or a `.json` configuration file inside the `config/` or `config/mods/` directory.

For example, a Discord verification plugin might produce `config/discord-plugin-settings.json`. Open this via terminal (nano config/discord-plugin-settings.json) or SFTP, insert your bot's token string, set the relay channel ID, and save. Always use a JSON validator online to ensure you haven't accidentally missed a comma or quotation mark before restarting.

6. Updating and Removing Mods

If an update drops for either the base Mindustry game or a pivotal overhaul mod installed on your server, you must update the files immediately, or your player base will quickly dwindle due to incompatibility errors.

To Update: Down the server, delete the old `.jar` or `.zip` file from `config/mods/`, and upload the new identical replacement file. Do not leave both versions in the directory, as the JVM will likely crash trying to register duplicate identical IDs or classes.

To Remove: Simply delete the file from the directory. Warning: If you remove a content mod that added specific blocks to a map, loading that existing `.msav` save file may corrupt it, or instantly delete thousands of hours of building where the modded blocks used to reside. Always backup your `saves/` folder before stripping mods away from a live campaign!

7. Troubleshooting Mod Errors

When dealing with Java plugins or massive asset tweaks, errors are expected. Here are the most common mod-related crash conditions and how to recover from them quickly:

• Server Crashes Immediately on Startup: Run the server manually via terminal without `systemd` to witness the console readout. Look for `java.lang.NoClassDefFoundError` or `java.lang.NoSuchMethodError`. This unequivocally means the plugin is entirely incompatible with the exact version of the `server.jar` you are executing. You must downgrade the server or wait for the plugin dev to update.
• Out of Memory (OOM) Errors: Asset mods containing hundreds of high-res sprite sheets consume intense amounts of RAM during the initialization phase. If the server aborts with an OutOfMemory exception, edit your systemd startup script and increase the `-Xmx` flag from `1024M` to `2048M` or `4096M`.
• Players Unable to Connect (Mismatch): If you recently updated a mod, remember that players typically wait for the in-game browser to push an update. A player on `SuperMod v1.4` cannot join a server running `SuperMod v1.5`. Keep a firm, well-communicated update schedule.