MineColonies: a town-building Minecraft mod with a real workforce

A colony with professions, buildings and a place to put them

MineColonies is described as an interactive building mod that allows you to create a thriving town within Minecraft, and the README's pitch is about leadership: it lets your leadership skills soar by providing you with everything you need to build your kingdom.

The mechanics that make it more than a building mod are the NPC workers. The feature list names Builders, Farmers, Fishers, Foresters, Guards, Miners, Smelters, Bakers, Cooks, Couriers, five types of animal herders and Composters, with more being developed as the mod grows. That list is the game's progression system in miniature: a builder needs stone and timber, a smelter needs ore, a baker needs a farm, and a courier moves goods between them. Each profession is a different production chain that a player has to satisfy.

The buildings come in the same style. The Warehouse, House, Town Hall, Barracks, Library, University and School are named, and they cover storage, housing, administration, military, and two levels of education. A school and a university in a Minecraft mod is a design statement, since each one implies a chain of unlocks rather than a craft recipe.

The other promise is placement. The README says you can build inside a mountain, on top of one, under the ocean or in the sky, and adapt the colony to any biome, and that you will create a different colony every time because of so many options. Whether that holds in practice is a question about the mod's building system rather than about the documentation, but it is the ambition the README sets out.

The licence is GPL-3.0, the primary language is Java, and the default branch is version/main.

Releases are versioned per Minecraft version, with snapshots

The release list shows the versioning scheme, which is the first thing to understand about the project.

The three most recent releases are v1.21.1-1.1.1403-snapshot on 2026-10-01, v1.21.1-1.1.1403 on 2026-10-04, and v1.20.1-1.1.1302-snapshot on 2026-10-06. The pattern is a Minecraft version first and the mod's own version second, so 1.21.1 is the Minecraft release and 1.1.1403 is the build of the mod for it, while the 1.20.1 line is still being built as a snapshot for the older Minecraft release.

That structure has consequences. The mod is not released once, it is released per Minecraft version, and a player on 1.20.1 and a player on 1.21.1 are on different builds. The trailing -snapshot marks a build made from the development branch rather than a tagged release, and the project publishes both, so the two kinds of artefact are on the same download list.

Players do not compile this. The README points users to CurseForge for all the versions, and that is where the releases land, with the mod page listed under the Minecraft mods files. The community lives on a Discord server at discord.minecolonies.com, and the README's issue instructions are detailed to the point of telling you to search for an existing answer first and to think about whether the issue is valid before submitting it.

For a user, that means the practical questions are about Minecraft and Forge versions rather than about the build, and for a developer it means the first thing to check is which Minecraft version your changes target.

Compiling from source starts with JDK 17

The developer section of the README is the longest part of the document, and it opens with a warning that has a distinct tone: please report any issues you have, as there might be some problems with the documentation, also make sure you know exactly what you are doing, and it is not our fault if your OS crashes, becomes corrupted, and so on.

The requirement is the Java JDK, version 17, with per-distribution instructions that are old enough to show their age. On Gentoo it is emerge dev-java/openjdk-bin:17, on Arch Linux pacman -S jdk17-openjdk, on Ubuntu and Debian apt-get install openjdk-17-jdk, and on Fedora yum install java-1.17.0-openjdk. The Windows path points at an AdoptOpenJDK download, with a custom setup step that asks you to set Add to Path and Set JAVA_HOME.

The verification step is a good one, and worth copying into your own notes: open a command line and run javac. If it prints a list of options and the usage, your installation works. If it does not, the README walks through Control Panel, System and Security, System, Advanced System Settings, Environment Variables, and adding a JAVA_HOME system variable, then appending ;%JAVA_HOME%\bin to the Path variable, with an instruction to check the location twice.

That much prose about environment variables is a symptom of a project whose audience includes a lot of people who have never compiled a Java project, which fits a Minecraft mod. The mod itself is a Gradle build, so the toolchain is old and widely available, and the JDK is the only hard requirement.

Gradle is optional in the guide and present in the tree

The Gradle section is marked optional, which is confusing until you look at the repository, because the tree contains gradlew, gradlew.bat, a gradle/ directory, gradle.properties, build.gradle and settings.gradle. The wrapper is in the repository, so a build does not need a system Gradle at all, and the README's Gradle install instructions are really about the case where you want to run Gradle yourself.

The README says the version of Gradle specified by the project can be found in the gradle/wrapper/gradle-wapper.properties file, and it is spelled wapper rather than wrapper in that sentence. That is a small typo in the documentation rather than a broken file, but it is the kind of thing that makes a newcomer doubt they are in the right directory.

The installation instructions have the same vintage. Windows and Mac get a zip from gradle.org, and the Linux instructions are emerge dev-java/gradle-bin on Gentoo, the AUR on Arch Linux, apt-get install gradle on Ubuntu and Debian, and a manual install on Fedora with a note that Fedora ships a broken version of Gradle and that yum install gradle should be used only if you know what you are doing. The Windows part asks for a GRADLE_HOME system variable and the same Path edit as for Java, and the verification step is to run gradle and look for a Welcome to Gradle message.

The build status badge in the README header points at buildsystem.ldtteam.com with a TeamCity-style rest path, so there is a continuous integration server behind the project, and the tree also carries a .travis.yml and a travis/ directory from the earlier generation of CI.

The clone URL points at a different organisation

The setup instructions tell you to clone the repository with:

git clone https://github.com/Minecolonies/minecolonies.git

The repository you are reading lives under the ldtteam organisation, and the README's URL points at Minecolonies. Those may be the same project with a moved home, an old organisation, or two related repositories, and the README does not say which. Anyone following the instructions verbatim will clone a different path than the one they came from, and it is the kind of detail that costs an afternoon when the build then fails on a file that is not where the documentation said it would be.

The rest of the layout instructions are clear. You move to a folder where you want the source, which the README calls the basefolder from then on, and after the clone you should have a directory tree of basefolder, then MineColonies inside it, and then the project's files including build.gradle.

There is also a separate path for people who prefer a graphical Git client, the Setup MineColonies with GitKraken section, and the README points out that the command line version of Git is assumed by the earlier section. The Git setup step itself is short: install Git, and optionally install a GUI client, with a list of examples from GitKraken and SourceTree to TortoiseGit.

So the toolchain story is: JDK 17, optionally a system Gradle, and Git. Everything else is in the repository.

Localisation, code quality and community process are all in the tree

The top-level listing of the repository shows a project with a real process behind it, not just source code.

There is crowdin.yml and a Crowdin badge, plus a .phraseapp.yml, so the project has used two translation platforms and the strings are managed as a workflow rather than edited in place. The documentation/ directory is where the in-game documentation lives, and config/ holds the mod's configuration resources, which for a mod this size is a large amount of JSON describing blocks, professions and buildings.

Quality tooling is present too. sonar.json for SonarCloud analysis, .pullapprove.yml for review approvals on pull requests, and a CLA.md alongside a Contributor Licence Assistant badge, which means contributors are asked to sign a licence agreement before their code is merged. That is a notable practice for a Minecraft mod.

The build files are the standard Gradle pair, build.gradle and settings.gradle, with gradle.properties for the project properties, and there are scripts/, tools/ and travis/ directories for the build helpers and the CI configuration. The unusedAssets/ directory is a curious inclusion, and a useful one, because it keeps files that are no longer referenced rather than deleting them outright, which makes it easy to see what a past version used.

Release and community channels are in the README as well: CurseForge for the files, the Discord server for chat, the issue tracker for bugs, and the project website at minecolonies.com, with the build badge pointing at the team's own build server.

What to check before you build or extend it

Three things decide whether this project fits your setup, and the README answers all of them if you read past the badges.

The first is the Minecraft version. Because releases are cut per Minecraft version, you are choosing between the 1.21.1 line and the 1.20.1 line, and the 1.20.1 line is still on snapshot builds in the release list. For a server, that is the difference between two artefact families to track.

The second is the toolchain, which is JDK 17 with Gradle. The wrapper is in the tree, so the system Gradle instructions are optional in practice, and the JDK is the part that has to be right, since the README asks for version 17 specifically rather than a range.

The third is the organisation of the source, and the mismatch between the clone URL in the README and the repository this document lives in is the concrete example. If you plan to contribute, the CONTRIBUTING.md file is there, and the CLA requirement is the thing to read first, because it is a condition on a pull request being merged rather than a guideline.

What the README does not tell you is worth naming too. There is no architecture overview, no description of how professions are implemented, and no API documentation for anyone who wants to write an add-on. For a mod of this size, the source is the documentation, and the ABOUT.md and documentation/ directories are where to start looking.

Editorial conclusion

Adopt MineColonies if you want a Minecraft world with an economy of workers and specialist buildings rather than a solo building sandbox, because the professions, the building tiers and the placement flexibility are the whole design, and the CurseForge distribution means players do not need to compile anything. Do not adopt it as a dependency for your own code, because the repository is a mod and not a library, and expect to track a Minecraft version at a time, since releases are cut per Minecraft version and the default branch is version/main. Before you build it from source, install JDK 17 and check the Gradle version in the wrapper properties, and note that the clone URL in the README points at the Minecolonies organisation rather than the ldtteam one this repository lives under, so fix the URL before you start.

Frequently asked questions

Official sources

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