Getting Started with Mindustry Modding

This guide takes you from a fresh Mindustry install to your first running content mod, covering the in-game browser, manual GitHub installs, and a one-block "hello world" you write yourself. It assumes you're comfortable editing text files but new to Mindustry's mod system.

Finding the mods folder

The mods folder is created on first launch. Its location depends on the OS:

Windows: %appdata%/Mindustry/mods/ (paste into Explorer's address bar; resolves to C:/Users/<you>/AppData/Roaming/Mindustry/mods/).
Linux: ~/.config/Mindustry/mods/.
macOS: ~/Library/Application Support/Mindustry/mods/.
Android: /storage/emulated/0/Android/data/io.anuke.mindustry/files/mods/. Android 10+ needs a file manager that can reach app-private storage (Material Files works).
Steam (Anuken Edition): same as the OS path above. Steam does not reroute the mods folder, so installs and saves are shared across the Steam build and the free build.

Inside that folder, each mod is either a .jar (compiled Java), a directory, or a .zip containing the same layout as a directory. The game scans this folder at startup and surfaces results under Mods in the main menu.

Path A: Install from the in-game browser

This is the smoothest first install:

Main menu, Mods, Browse.
The browser lists everything from the official github.com/Anuken/MindustryMods index. Each entry shows the latest released tag.
Tap Download on the one you want. The game pulls the release asset, drops it into your mods folder, and prompts to restart.

If the browser is empty or stuck, you're being rate-limited by GitHub (unauthenticated API calls cap at 60/hour per IP). Wait an hour or switch networks.

Path B: Install from a GitHub release directly

Useful for mods that are not on the official index yet, or for pre-release builds:

Open the mod's GitHub page, then Releases.
Download the .jar for Java mods or the .zip for content mods.
Drop the file into the mods folder. Do not unzip content-mod zips; Mindustry reads them as-is.
Restart Mindustry. Mods should now list your install with the mod's icon and version.

If a mod's release page has multiple zips per platform (MyMod-android.zip vs MyMod-desktop.jar), grab the one matching your build.

Path C: Write your first content mod

A minimal "hello world" mod adds one block. No compilation, no Gradle.

Create this structure inside mods/HelloMod/:

mods/HelloMod/
├── mod.hjson
├── content/blocks/hello-router.hjson
└── sprites/blocks/hello-router.png

mod.hjson:

name: hello-mod
displayName: "Hello Mod"
author: "you"
description: "My first Mindustry mod."
version: "0.1"
minGameVersion: "146"

content/blocks/hello-router.hjson (extends vanilla Router, just changes health and cost):

type: Router
health: 200
buildCostMultiplier: 1.0
requirements: [
  copper/10
]

sprites/blocks/hello-router.png: a 32x32 PNG with a transparent background. Any image editor works; even MS Paint output loads if you save as 32-bit PNG.

Restart Mindustry. In a sandbox map's build menu, your new router shows up as "Hello Router". If it does not appear, open Settings, Game Data, Open Mod Log Folder and read the most recent log. Parse errors land there with the file path and line number that caused the failure.

Common gotchas

Sprites belong in sprites/<category>/, not nested further. The folder name doubles as the content category, so a block sprite at sprites/units/hello-router.png will be ignored by the block loader.
minGameVersion is a hard gate by build number, not semver. v7 lives roughly around build 136, v8 around build 146. Set it too low and the game refuses to load your mod on newer builds.
HJSON is JSON's looser cousin. Trailing commas are fine and quotes around string keys are optional, but indentation inside arrays still matters. Validate with any HJSON-aware editor before launching.
Java mods need android: true in mod.hjson to load on mobile, and the jar must be Dexed (the d8 step in the Anuken template's Gradle build handles this).
Server multiplayer requires the mod on both sides. Pure content mods sync from the host on join in recent versions; Java mods do not, and a missing server mod will refuse the connection.
The mod browser caches. If you publish a new release and the in-game browser still shows the old version, restart the game or hit Refresh at the top of the browse list.

Where to next

Once the one-block mod loads cleanly, move on to a multi-block content pack (add a unit, an item, and a planet sector) before reaching for Java. The vanilla content under the game's core/assets/content/ directory on the public GitHub repo is the best reference; every block in the base game is declared the same way yours is.

For game-specific context (version cadence, what's on the official index, how the Steam build relates to the free build), see the Mindustry modding overview.