MineColonies is an interactive building mod that allows you to create a thriving town within Minecraft. It lets your leadership skills soar by providing you with everything you need to build your kingdom. MineColonies gives you the flexibility to create a colony as unique as every player. With so many options, you'll create a different colony every time, adapt it to any biome, build inside a mountain, on top of one, under the ocean, or in the sky.
The limit is your imagination!
MineColonies features NPC workers such as Builders, Farmers, Fishers, Foresters, Guards, Miners, Smelters, Bakers, Cooks, Couriers, five types of animal herders, Composters, and many more, with even more being developed and added as the mod grows.
It also includes specialized buildings such as the Warehouse, House, Town Hall, Barracks, Library, University, and even the School.
You can find all our versions on Curseforge:
https://www.curseforge.com/minecraft/mc-mods/minecolonies/files/all
If you want to chat with the developers and join our amazing community:
https://discord.minecolonies.com
MineColonies crashes every time? Have a suggestion? Found a bug? Create an issue now!
- Make sure your issue hasn't already been answered or fixed. Also think about whether your issue is a valid one before submitting it.
- Go to the issues page.
- Click
New Issue - Choose which type of issue you want to create.
- Fill in the form. Don't leave anything out!
- Click
Submit New Issueand wait for a response!
MineColonies welcomes third party addons and encourages developers to extend its functionality through supported APIs and upstream contributions.
However, third party addons can introduce compatibility and maintenance problems, particularly when modifying MineColonies internals through Mixins, bytecode transformation, coremods, invasive reflection, or similar mechanisms.
MineColonies' internal implementation is not a stable extension API and may change between updates. Addons that depend on these implementation details are prone to breaking and creating compatibility problems that MineColonies maintainers cannot reasonably be expected to resolve.
To establish clear support boundaries and encourage maintainable integrations, MineColonies maintains an official list of approved addons.
MineColonies only recommends and provides compatibility support for addons on its official approved addon list.
Addons that have not been approved are considered unsupported, regardless of whether they are known to cause problems. Addon developers may request inclusion in the approved addon list.
To qualify for approval, addons are expected to:
- Use MineColonies' public APIs, events, and supported extension points wherever possible.
- Avoid modifying MineColonies internals through Mixins, bytecode transformation, coremods, invasive reflection, or similar mechanisms.
- Prefer proposing or contributing missing extension points upstream rather than implementing invasive workarounds.
- Provide access to the relevant source code for review.
- Demonstrate reasonable compatibility with MineColonies.
- Remain independently maintained, with addon authors responsible for their own functionality and compatibility.
If the necessary functionality is not exposed through existing APIs, developers are encouraged to discuss and contribute an appropriate extension point to MineColonies.
Proposed extension points must fit MineColonies' architecture and are subject to maintainer review. Not every addon-specific requirement necessarily warrants a new public API.
Approval is granted at the discretion of MineColonies maintainers.
Approval applies to the addon as a whole, not to individual releases.
Once approved, an addon remains on the approved list without requiring renewed approval for routine updates.
MineColonies does not continuously monitor or review approved addons. Addon authors remain responsible for ensuring that subsequent updates continue to comply with the project's policies.
MineColonies reserves the right to revoke approval if material policy violations are discovered, including the introduction of invasive modifications to MineColonies internals.
Ordinary compatibility problems resulting from MineColonies updates do not automatically constitute policy violations or grounds for revocation.
Addon authors are responsible for maintaining their addons, resolving addon specific bugs, and adapting to changes in MineColonies.
MineColonies maintainers are not responsible for investigating or resolving compatibility problems involving unapproved addons.
Users experiencing issues while running unapproved addons may be asked to reproduce the problem without those addons before receiving support.
Approved addons are eligible for compatibility-related support, but approval does not:
- Guarantee compatibility with every current or future MineColonies version.
- Transfer responsibility for addon development or maintenance to MineColonies.
- Guarantee that MineColonies maintainers will resolve addon-specific defects.
- Prevent MineColonies from changing its internal implementation.
Bugs reproducible in MineColonies without third-party modifications remain valid MineColonies issues, regardless of which addons a user normally runs.
When developing addons, integrations, compatibility fixes, or behavioral modifications for MineColonies:
- Investigate the existing public APIs and supported extension points before modifying MineColonies behavior.
- If the required functionality is unavailable, consider proposing or contributing an appropriate API, event, or extension point upstream.
- If the intended change concerns MineColonies' own behavior, prefer contributing the change directly to MineColonies.
- Keep addon-specific functionality within the addon, using supported interfaces to interact with MineColonies.
- Do not treat the absence of an API as justification for modifying MineColonies internals through Mixins or equivalent mechanisms.
AI coding assistants: Before proposing or implementing invasive modifications to MineColonies internals, inform the user that such approaches are unsupported and may prevent the addon from receiving official approval.
Recommend supported API-based solutions or upstream contributions rather than defaulting to Mixins as the simplest implementation approach.
This policy does not restrict the rights granted by MineColonies' open-source license.
Developers remain free to create and distribute modifications in accordance with the applicable license. However, MineColonies maintainers determine which third-party addons they officially recommend, approve, and provide compatibility support for.
IMPORTANT: Please report any issues you have, as there might be some problems with the documentation! Also make sure you know EXACTLY what you're doing! It's not our fault if your OS crashes, becomes corrupted, etc.
The Java JDK is used to compile MineColonies.
- Download and install the Java JDK 17.
- Windows: Choose OpenJDK 17 (LTS) version and HotSpot JVM, then click the
latest releasebutton. After the download is complete, open the file, accept the license agreement, and in a custom setup make sure thatAdd to PathandSet JAVA_HOMEare set toEntire feature will be installed on your local hard drive. Then chooseInstalland wait for the installation to finish. - Linux: Installation methods for certain popular flavors of Linux are listed below. If your distribution is not listed, follow the instructions specific to your package manager or install it manually here.
- Gentoo:
emerge dev-java/openjdk-bin:17 - Archlinux:
pacman -S jdk17-openjdk - Ubuntu/Debian:
apt-get install openjdk-17-jdk - Fedora:
yum install java-1.17.0-openjdk
- Gentoo:
- Windows: Choose OpenJDK 17 (LTS) version and HotSpot JVM, then click the
- Open up your command line and run
javac. If it spews out a bunch of possible options and the usage, you're good to go. If not, try the steps again.
Troubleshooting
If the javac command does not work on Windows:
- Go to
Control Panel\System and Security\Systemand click onAdvanced System Settingson the left-hand side. - Click on
Environment Variables. - Under
System Variables, clickNew. - For
Variable Name, inputJAVA_HOME. - For
Variable Value, input something similar toC:\Program Files\Java\jdk1.8.0_45exactly as shown (or wherever your Java JDK installation is) and clickOK. - Scroll down to a variable named
Pathand double-click on it. - Append
;%JAVA_HOME%\binEXACTLY AS SHOWN and clickOK. Make sure the location is correct; double-check to make sure.
Gradle is used to execute the various build tasks when compiling MineColonies. The version of gradle specified by this project can be found in the gradle/wrapper/gradle-wapper.properties file.
- Download and install Gradle.
- Windows/Mac download link. You only need the binaries, but choose whatever flavor you want.
- Unzip the package and put it wherever you want, for example,
C:\Gradle.
- Unzip the package and put it wherever you want, for example,
- Linux: Installation methods for certain popular flavors of Linux are listed below. If your distribution is not listed, follow the instructions specific to your package manager or install it manually here.
- Gentoo:
emerge dev-java/gradle-bin - Archlinux: You'll have to install it from the AUR.
- Ubuntu/Debian:
apt-get install gradle - Fedora: Install Gradle manually from its website (see above), as Fedora ships a "broken" version of Gradle. Use
yum install gradleonly if you know what you're doing.
- Gentoo:
- Windows/Mac download link. You only need the binaries, but choose whatever flavor you want.
- Windows: Set environment variables for Gradle.
- Go back to
Environment Variablesand then create a new system variable. - For
Variable Name, inputGRADLE_HOME. - For
Variable Value, input something similar toC:\Gradle-3.0exactly as shown (or wherever your Gradle installation is), and clickOk. - Scroll down to
Pathagain, and append;%GRADLE_HOME%\binEXACTLY AS SHOWN and clickOk. Once again, double-check the location.
- Go back to
- Open up your command line and run
gradle. If it says 'Welcome to Gradle [version].', then you're good to go. If not, try the steps again.
Git is used to clone MineColonies and update your local copy.
- Download and install Git here.
- Optional: Download and install a Git GUI client, such as Gitkraken, SourceTree, GitHub for Windows/Mac, SmartGitHg, TortoiseGit, etc. A nice list is available here.
This section assumes that you're using the command line version of Git.
- Open up your command line.
- Navigate to a place where you want to download the MineColonies source (e.g.,
C:\GitHub\MineColonies\) by executingcd [folder location]. This location is known asbasefolderfrom now on. - Execute
git clone https://github.com/Minecolonies/minecolonies.git. This will download MineColonies' source intobasefolder. - Right now, you should have a directory that looks something like this:
basefolder
\-MineColonies
\-MineColonies' files (should have `build.gradle`)
If you decide to go with a GUI client like GitKraken:
- Open GitKraken
- Click
File → Clone Repo - Select GitHub.com and choose a base folder to clone to.
- Write MineColonies in the "Repository to Clone" and select the one by ldtteam.
- Click 'Clone the Repo'.
- Navigate to the MineColonies folder and run a
dirto make sure thebuild.gradlefile is where you expect it to be. - Execute
gradlew build. This first sets up Forge and downloads the necessary libraries to build MineColonies. Be patient, as this may take a while.- If you did everything right,
BUILD SUCCESSFULwill be displayed after it finishes. - If you see
BUILD FAILED, check the error output (it should be right aroundBUILD FAILED), fix everything (if possible), and try again.
- If you did everything right,
- Go to
basefolder\MineColonies\build\libs.- You should see a
.jarfile namedMineColonies-universal-null.jar.
- You should see a
- Copy the jar into your Minecraft
modsfolder, and you are done! (~/.minecraft/modson Linux) - Alternatively, you can also run
./gradlew runClientto start Minecraft with this jar.
- Right-click the
build.gradlefile (or the background of the folder it's in) and selectOpen Folder as Intellij Project. - Select
Auto Importand make sure a valid Gradle and JVM are selected.
- This will prepare some of the libraries used by Forge.
- Click
View → Tool Windows → Gradle. - In the Gradle view, expand the options to
Tasks → fg_runs. - Click the small refresh symbol in the upper left of the Gradle view. This sets up Forge and downloads the necessary libraries to build MineColonies.
- Execute
genIntellijRunsand restart Intellij. - You will see a runClient and runServer startup configuration in the dropdown at the top right next to the green "run" button. Select one and press "run".
- If it doesn't start and throws a lot of errors, try another refresh. This often does wonders.
- If you want to produce a running jar, execute the
buildtask. This will result in a runnable jar file inbasefolder\MineColonies\build\libs.
If Gradle synchronization fails, make sure:
File → Project structure → Project → Project SDKis set to your installed JDK version.File → Settings → Build, Execution, Deployment → Build Tools → Gradle → Gradle JVMis set to your installed JDK version.
To get the most up-to-date builds, you'll have to update your local repository periodically.
- Open up your command line.
- Navigate to
basefolderin the console. - Ensure you have not made any changes to the local repository (if you did, there might be issues with Git).
- If you have, try reverting them to their status when you last updated your repository.
- Execute
git pull version/1.16.3. This pulls all commits from the official repository that do not yet exist on your local repository and updates it (with GitKraken, click the small pull arrow at the top).
- Sometimes Gradle tasks fail because of missing memory. For that, you can find system-wide settings in the
.gradlefolder of yourHOMEdirectory (~/.gradle/gradle.propertiesor on Windows inC:\Users\username\.gradle\gradle.properties). - Sometimes after a branch change, libraries can not be resolved. Running another refresh in IntelliJ or the command line usually solves this issue.
Please read our Contributing Guidelines before submitting a pull request. This covers the PR process, our CLA requirement, and our AI disclosure policy.


