Fabric Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
~~REDIRECT>https://docs.fabricmc.net/develop/getting-started/setting-up~~

====== Setting up a mod development environment ======

===== Prerequisites =====

==== Installing JDK ====
To develop mods, a Java Development Kit (JDK) is required. Visit [[https://adoptium.net/en-GB/temurin/releases]] for installers.
  * Since 1.20.5, Java 21 or newer is required.
  * Since 1.18, Java 17 or newer is required.
  * Since 1.17, Java 16 or newer is required.
  * For older Minecraft versions, Java 8 or newer is required.

More information about installing Java can be found:
  * Fabric Wiki's player tutorial of installing Java for [[player:tutorials:java:windows|Windows]], [[player:tutorials:java:mac|MacOS]] or [[player:tutorials:java:linux|Linux]]
  * Fabric Documentation's player tutorial of installing Java for [[https://docs.fabricmc.net/zh_cn/players/installing-java/windows|Windows]], [[https://fabricmc.net/wiki/player:tutorials:java:mac|MacOS]] or [[https://docs.fabricmc.net/zh_cn/players/installing-java/linux|Linux]]

==== Installing an IDE ====

Before writing your code, you should have a Java IDE (Integrated Development Environment) installed. Such as [[https://www.jetbrains.com/idea/download/?section=windows#community-edition|Intellij IDEA Community Edition]] (recommended) or [[https://www.eclipse.org/downloads/|Eclipse]]. You may also use any other code editors, such as [[https://code.visualstudio.com/|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.

===== Creating the project =====
> Detailed tutorial can be found on [[https://docs.fabricmc.net/develop/getting-started/creating-a-project|Fabric Documentation]]

There are multiple ways to create a project:
  * copy template project from [[https://github.com/FabricMC/fabric-example-mod/|fabric-example-mod]], excluding the ''LICENSE'' and ''README.md'' file
  * use template generator at [[https://fabricmc.net/develop/template/|the template generator]]
  * use Intellij IDEA's generator, which requires installing Intellij IDEA's Minecraft Development plugin.

After creating a project, please edit some key files as you wish:
  * 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/develop/ - to match the versions you wish to target.
       * Add any other dependencies you plan to use in ''build.gradle''.
  * Edit ''fabric.mod.json'':
       * Change the versions your mod is compatible, and mods your mod will depend on, as well as some other information like mod id. For information, see [[documentation:fabric_mod_json|usage of the file]].

> :!: As of Minecraft 1.19.2, Fabric API's mod ID has changed from ''fabric'' to ''fabric-api''. When backporting from 1.19.2 to earlier versions, you must alter the ''depends'' section of your ''fabric.mod.json'' to expect ''fabric''.

===== Configuring the project =====

==== IntelliJ IDEA ====
If you are using IntelliJ IDEA by JetBrains, please follow these steps:
    - In the IDEA main menu, select 'Import Project' (or File -> Open... if you already have a project open).
    - Select the project's "build.gradle" file to import the project.
    - After Gradle is done setting up, close (File -> Close Project) and re-open the project to fix run configurations not displaying correctly. If the run configurations still don't show up, try reimporting the Gradle project from the Gradle tab in IDEA. You can also manually run ''ideaSyncTask'' gradle task to generate run configurations.

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

=== Minecraft Development plugin ===
If you are using IntelliJ IDEA, it is highly recommended to install [[https://plugins.jetbrains.com/plugin/8327|Minecraft Development plugin]], which support 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.

For launching Minecraft and start debugging, see [[https://docs.fabricmc.net/develop/getting-started/launching-the-game|Fabric Documentations]].

==== 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 [[tutorial:setup:vscode|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 [[tutorial:reading_mc_code|Reading the Minecraft source]] for how to read the source.

===== 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.
  * Keep up with the latest Loom version (which is defined in ''build.gradle'') and the Fabric Loader and Fabric API version for your mod (which is defined in ''build.gradle'' or ''gradle.properties''). Latest version can be found in [[https://fabricmc.net/develop/]]. Even the old version Minecraft is supported by latest Loom and latest Fabric Loader.
  * Keep up with the latest Gradle version, which can be defined in ''gradle/wrapper/gradle-wrapper.properties''. Old version Minecraft is supported by latest Gradle.
    * Different Gradle versions require different Java versions.
  * If you're developing mods for old version Minecraft, besides changing ''gradle.properties'', you may also need to change the Java compatibility version in ''build.gradle'' and the mixin config.
  * Don't hesitate to ask questions! We're here to help you and work with you to make your dream mod a reality.

===== Troubleshooting =====

==== "no usages" on every method ====
After running the ''genSources'' gradle task in IntelliJ IDEA, check if the sources are attached properly. Open a Minecraft .class file and click on the "Choose Sources..." button on the top right of the screen. Select the jar with "-sources" at the end (e.g. ''.gradle\loom-cache\1.20.1\net.fabricmc.yarn.1_20_1.1.20.1+build.10-v2\minecraft-project-@-merged-named-sources.jar'')

==== 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''.

==== Could not find or load class / no JDK module specified  ====
Sometimes the run config may be invalid, reporting errors such as:
  * ''Could not find or load class net.fabricmc.devlaunchinjector.Main: java.lang.ClassNotFoundException''
  * "no JDK module specified" in the run config

There are several fixes, among which one may be a potential fix:
  * If you're using Intellij IDEA, go to "project strcture" and then select "Modules" tab, then clear all modules. Then reload your gradle project.
  * It seems to be a bug of Intellij IDEA since a recent update 2023.2. To fix, just delete the ''.idea'' folder entirely and then restart Intellij IDEA. The module will be reconstructed. You may need to specify Java versions again. If after restarting there is no run config, you can run ''gradle ideaSyncTask'' then check it again.
  * If you have subprojects, please ensure your subprojects are configured correctly. If the ''build.gradle'' of your subproject exists, check whether the gradle plugin ''maven-publish'' is enabled or applied to it. Try adding ''apply plugin: maven-publush'' in the ''build.gradle'' file, if it is not declared at all.
  * If the issue still happens, edit the run config, and try modifying the module (the value for parameter ''-cp'') to other values.

==== Minecraft game provider couldn't locate the game ====
Sometimes you may come with some error like:
  * ''java.lang.ClassNotFoundException: net.fabricmc.loader.impl.launch.knot.KnotClient''
  * ''java.lang.TypeNotPresentException: Type net/minecraft/util/Identifier not present''
  * ''java.lang.RuntimeException: Minecraft game provider couldn't locate the game! The game may be absent from the class path, lacks some expected files, suffers from jar corruption or is of an unsupported variety/version.''

This may be because the project path contains non-ASCII characters that may cause incompatibility. Try move the project to paths without non-ASCII characters, or in the run config of "Minecraft Client" and "Minecraft Server", set "Shorten Command Line" from "@argfile (Java 9+)" to "none". This also applies to the [[tutorial:datagen_setup|Data Generation]] run config.

Another potential fix, is to go to Region Settings in the Settings or Contral Panel of Windows, go to Region Settings, and enable "Beta: Use Unicode UTF-8 for worldwide language support", and then reboot.
==== "processResources" not run ====

That may be because you're using Intellij IDEA to build and run. If issue happens, try open the 'Gradle Settings' dialog from the Gradle tab, and then change the 'Build and run using' and 'Run tests using' fields from 'IntelliJ IDEA' to 'Gradle (default)'.

===== What's Next?  =====
Try [[items|adding an item]] or [[blocks|a block]]. It's also a good idea to visit [[tutorial:hotswapping|Applying changes without restarting Minecraft]].