Mindustry: Building the Java Tower Defense RTS from Source

What Mindustry Actually Is and Who It Is For

Mindustry describes itself as "the automation tower defense RTS, written in Java." The combination matters: it is not a pure tower defense game where you place turrets and wait, and it is not a pure factory builder where combat is incidental. You build conveyor and production chains to feed defensive structures while waves of enemies arrive on a schedule. The repository topics list android, desktop, game, java, mindustry, mobile-game, multiplatform, rts, sandbox-game and tower-defense, which matches the scope of the project.

The audience splits into two groups. The first is players who want a sandbox strategy game they can run on desktop, Android, iOS or a dedicated server. The second is developers. Because the whole thing is Java and GPL-3.0, the source is readable end to end, and the project documents a contribution path through CONTRIBUTING.md and a set of issues tagged 'candidate' in the Mindustry-Suggestions repository. If you have ever wanted to see how a shipped game handles entity component systems, generated networking code and multi-platform Gradle builds, this is a large, real example.

One thing the README does not do is explain the game loop or the content pipeline in prose. It links to a Trello board, a wiki and Javadoc, and then goes straight to build instructions. That tells you something about the intended reader of the README: it is written for people who already know what Mindustry is and want to compile it.

The Build System: Gradle, JDK 17 and the mindustry.gen Package

The build is a multi-module Gradle project. The top level contains android/, annotations/, core/, desktop/, ios/, server/, tests/ and tools/, plus build.gradle, settings.gradle, gradle.properties and the Gradle wrapper scripts. Each platform target is its own module, which is why the same commands work with a different module prefix.

The README is explicit about the toolchain: JDK 17 is required, and "Other JDK versions will not work." That is a hard constraint, not a suggestion. If your machine defaults to a newer JDK, Gradle will pick it up and the build will fail. The README points to Adoptium Temurin 17 as the download source.

The most interesting design decision is the generated code. The README states that the mindustry.gen package is generated at build time and does not exist in the repository, and that it should not be edited by hand. Three sources feed it. Classes named Call and the various *Packet classes come from methods marked with @Remote. Entity classes such as Unit, EffectState and Posc are generated from component classes in mindustry.entities.comp and combined using definitions in mindustry.content.UnitTypes. Asset-derived classes such as Sounds, Musics, Tex and Icon are generated from files in the respective asset folders. This is a code-generation-heavy architecture: the networking layer and the entity composition model are both derived from annotations and component definitions rather than written out. If you plan to modify gameplay systems, you need to understand that you are often editing inputs to a generator, not the final classes.

Gradle may take several minutes to download dependencies on the first run. The README says so directly, which is a useful warning if you are wiring this into CI.

Installing Mindustry and Running It for the First Time

There are two paths. If you just want to play, the README's Downloads table links to itch.io, Google Play, F-Droid and Flathub. There is no source build required for any of those.

If you want to build from source, install JDK 17 first. On Linux or macOS, open a terminal in the Mindustry directory and run the Gradle wrapper. The README gives these exact commands:

./gradlew desktop:run
./gradlew desktop:dist
./gradlew tools:pack

The first command runs the desktop build directly. The second produces a distributable JAR, which the README says lands in /desktop/build/libs/Mindustry.jar. The third repacks sprites, which you would run after changing assets.

On Windows the same tasks run through the batch wrapper:

gradlew desktop:run
gradlew desktop:dist
gradlew tools:pack

If the terminal returns Permission denied or Command not found on Mac or Linux, the README says to run chmod +x ./gradlew once:

chmod +x ./gradlew

For a headless server, swap the module name. The README states that server builds are bundled with each released build, and that compiling your own uses the same pattern with 'server' in place of 'desktop', for example gradlew server:dist. The output is /server/build/libs/server-release.jar.

Android is the longest path. You install the Android SDK command line tools only, move the contents of cmdline-tools into a new latest folder inside it, run sdkmanager --licenses, set the ANDROID_HOME environment variable to the unzipped SDK directory, enable developer mode on the device or emulator, and then build:

gradlew android:assembleDebug

The README says this creates an unsigned APK in android/build/outputs/apk. To debug on a connected device, the documented command is gradlew android:installDebug android:run.

What you should see: a Gradle build that resolves dependencies for several minutes, then either a running game window or a JAR in the build/libs directory of the module you targeted.

Where the Project Leaves You on Your Own

The README is a build document, not an operations manual. It does not document how to configure a dedicated server beyond telling you that server builds exist and where the JAR lands. There is no section on ports, no environment variable reference for server deployment, and no rollback procedure if a build fails partway. For a project with a live multiplayer community, that gap is notable. You are expected to find that information elsewhere, likely on the wiki.

The JDK 17 requirement is the sharpest practical limitation. Projects that track a newer LTS release will find this build does not move with them. If you are adding Mindustry as a dependency or vendoring parts of it into another project, you inherit that constraint.

The generated code is the second limitation, and it is more subtle. Because mindustry.gen does not exist in the repository, IDE navigation into those classes requires a completed build first. A fresh clone will show unresolved references until Gradle has run. Contributors who expect to read Call or the packet classes directly from the source tree will not find them. The README is clear that the package "should not be edited by hand," so any fix has to go into the annotation or component source that generates it.

Finally, the README does not describe the game's data formats, save file compatibility between versions, or mod API stability. The release history shows frequent point releases within the v160 line, which suggests that anything you build against a specific build number should be pinned.

How Mindustry Differs from Factorio and Other Automation Games

The most common comparison is Factorio, and the search data shows people ask directly whether Mindustry is a copy. It is not, and the difference is structural rather than cosmetic. Factorio is a commercial, closed-source game built in C++ with a Lua modding layer. Mindustry is GPL-3.0 Java with the entire source available, including the Android and iOS targets. That means the modding story is different: instead of scripting against a fixed API, you can change engine-level code and rebuild.

The second difference is the defense loop. In Factorio, combat is a pressure on your factory. In Mindustry, the tower defense framing is primary, and the automation exists to feed your defenses. The project's own one-line description puts automation first in the name, but the topics list includes both sandbox-game and tower-defense, and the gameplay ties production directly to survival.

The third difference is platform reach. Mindustry ships on desktop, Android, iOS, F-Droid and Flathub, and the repository contains modules for android/, ios/, desktop/ and server/ at the top level. A single Java codebase covering that range is unusual, and it is the main reason the code is worth reading even if you never play the game.

If you want a commercial licence without copyleft obligations, or if you want a game with a first-class scripting mod API rather than source-level modification, Mindustry is the wrong tool. GPL-3.0 is a deliberate choice here, and it shapes what you can do with derivative work.

Licence, Maintenance and Upgrade Cost

Mindustry is licensed under GPL-3.0, and the LICENSE file sits at the top level of the repository. That means derivative works distributed to others must be released under the same licence. If you are embedding Mindustry code into a closed product, this is a blocker, not a detail. The README itself does not discuss licensing implications, and the repository does not appear to publish a separate commercial licence option. For anything beyond personal use, read the LICENSE file in full; this article is not legal advice.

The repository is not archived, and the last push was on 2026-09-20. Releases are frequent: v160.4 on 2026-09-14, v160.3 on 2026-09-13 and v160.2 on 2026-09-12. That cadence matters for upgrade cost. If you fork or vendor the code, you should expect to rebase against a moving master branch. The generated-code architecture helps here in one way: because mindustry.gen is produced at build time, merge conflicts in generated classes do not exist. The conflicts land in the component and annotation sources instead, which are smaller and more stable.

The practical upgrade cost is dominated by the JDK 17 pin and by asset changes. The tools:pack task exists precisely because sprite assets are repacked into the build, so any asset change is a build step rather than a runtime load. Budget for a full Gradle cycle whenever you pull.

Editorial conclusion

Mindustry is worth adopting for players who want a moddable, cross-platform tower defense RTS and for Java developers who want a production-scale codebase to study or extend. Skip it if you need a commercial licence without GPL-3.0 obligations, or if you only want a prebuilt binary and no build toolchain. Before committing, verify that your JDK is exactly 17, check the LICENSE file for the full GPL-3.0 terms, and confirm which assets and translations carry separate licensing.

Frequently asked questions

Official sources

1. Anuken/Mindustry on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases