User Tools

Site Tools


Sidebar

Setup

Basics

Advanced

Items

Blocks and Block Entities

Fluids

Entities

World Generation

Recipe Types

Miscellaneous

Events

Mixins

Dynamic Data Generation

Tutorials for Minecraft 1.15

Tutorials for Minecraft 1.14

Documentation

tutorial:setup

Setting up a mod development environment

Prerequisites

  • A Java Development Kit (JDK) for Java 16 (recommended) or newer. Visit https://adoptopenjdk.net/ for installers.
    • If you are professional, you can obtain a JDK from http://jdk.java.net/, which needs to be extracted and have system variables set up manually.
  • Any Java IDE, for example Intellij IDEA and Eclipse. You may also use any other code editors, such as Visual Studio Code.
    • If you are not familiar with any of these, we recommend to use Intellij IDEA as that is what most people choose for modding.

Minecraft Development (mcdev) IntelliJ IDEA Plugin

If you are using IntelliJ IDEA you can use the MinecraftDev plugin. This plugin adds support for automatically generating Fabric projects as well as some mixin related features like inspections, generating accessors/shadow fields, and copying Mixin Target References (JVM Descriptors). You can install it using IntelliJ's internal plugin browser by navigating to File → Settings → Plugins, then clicking the Marketplace tab and searching for Minecraft.

Mod Startup

There are two main ways to make a new mod for Minecraft based on Fabric. You can either manually download fabric-example-mod and setup by yourself, or use automatic tools for you.

NOTE: The default template in the mcdev plugin blindly uses the latest unstable version of the loom. Use with caution.

Manual Steps

  1. Copy the starting files from fabric-example-mod (or from the Kotlin version, if you wish to use Kotlin,) excluding the LICENSE and README.md files - as those apply to the template itself, not necessarily to your mod.
  2. Edit gradle.properties:
    • Make sure to set archives_base_name and maven_group to your preferred values.
    • Make sure to update the versions of Minecraft, the mappings, the loader and the loom - all of which can be queried through https://fabricmc.net/versions.html - to match the versions you wish to target.
    • Add any other dependencies you plan to use in build.gradle.
  3. Import the build.gradle file to your IDE. You may refer to the next section for specific IDE's.
  4. Happy modding!

If you are unable to use the mc plugin or the fabric-example-mod, you may also use GeneratorFabricMod by ExtraCrafTX, a convenient tool to automatically generate new fabric mods from template. Follow these steps:

  1. Download latest release of GeneratorFabricMod here and extract them.
  2. Make a new directory, then run a command shell there and type path/to/GeneratorFabricMod/bin/GeneratorFabricMod.
  3. After letting it get its dependencies, follow the instructions and input required information.
  4. You're now done, just open the project folder with in your IDE.

IntelliJ IDEA

If you are using IntelliJ IDEA by JetBrains, please follow these steps:

  1. In the IDEA main menu, select 'Import Project' (or File → Open… if you already have a project open).
  2. Select the project's build.gradle file to import the project.
  3. After Gradle is done setting up, close (File → Close Project) and re-open the project to fix run configurations not displaying correctly.
  4. (If the run configurations still don't show up, try reimporting the Gradle project from the Gradle tab in IDEA.)

Optional, but recommended: By default, IntelliJ delegates to Gradle to build the project. This is unnecessary for Fabric and causes longer build times and hotswapping related weirdness, among other problems. To make it use the builtin compiler:

  1. Open the 'Gradle Settings' dialog from the Gradle tab.
  2. Change the 'Build and run using' and 'Run tests using' fields to 'IntelliJ IDEA'.
  3. Go to File → Project Structure → Project and set 'Project compiler output' to $PROJECT_DIR$/out.

Unfortunately, it is currently impossible to set an IDE-wide default for the 'Build and run using' and 'Run tests using' options, so these steps have to be repeated for every new project.

NOTE: Don't run the idea gradle task. It is known to break development environment.

Eclipse

If you are using Eclipse and you would like to have the IDE run configs you can run gradlew eclipse. The project can then be imported as a normal (non-gradle) Eclipse project into your workspace using the 'File' - 'Import…' menu, then 'General' → 'Existing Projects into Workspace'.

Visual Studio Code

If you are using VSCode, please follow these instructions.

Generating Minecraft Sources

Reading the Minecraft source is an essential part of modding. Unfortunately, we can't publish the Minecraft source because it violates the Minecraft EULA. You need to generate the Minecraft source yourself.

To generate the Minecraft source. run the genSources gradle task. If your IDE doesn't have gradle integration, run the following command in the terminal: gradlew genSources (or ./gradlew genSources on Linux/MacOS). It can take a while depending on your computer power. You may need to refresh gradle after running the task.

See Reading the Minecraft source for how to read the source.

Getting started

Try adding an item or a block. It's also a good idea to visit Applying changes without restarting Minecraft.

Advice

  • While Fabric API is not strictly necessary for developing mods, its primary goal is to provide cross-compatibility and hooks where the game engine does not, and as such it is highly recommended! Even some of the tutorials on the wiki implicitly require Fabric API.
  • Occasionally, with development of fabric-loom (our Gradle build plugin) issues may crop up which require resetting the cache files. This can be done by running gradlew cleanloom. Running gradlew --stop can also help with a few rare issues.
  • Don't hesitate to ask questions! We're here to help you and work with you to make your dream mod a reality.

Troubleshooting

Missing sounds

Sometimes, when importing the Gradle project into an IDE, the assets might not download correctly. In this case, run the downloadAssets task manually - either using IDE's built-in menu or by simply running gradlew downloadAssets.

tutorial/setup.txt · Last modified: 2021/09/26 08:02 by siglong