This is an old revision of the document!
Table of Contents
Fabric Loom
Fabric Loom, or just Loom for short, is a Gradle plugin for development of mods in the Fabric ecosystem. Loom provides utilities to install Minecraft and mods in a development environment so that you can link against them with respect to Minecraft obfuscation and its differences between distributions and versions. It also provides run configurations for use with Fabric Loader, Mixin compile processing and utilities for Fabric Loader's jar-in-jar system.
Dependency configurations
minecraft
: Defines the version of Minecraft to be used in the development environment.mappings
: Defines the mappings to be used in the development environment.modCompile
,modImplementation
,modApi
andmodRuntime
: Augmented variants ofcompile
,implementation
,api
andruntime
for mod dependencies. Will be remapped to match the mappings in the development environment and can optionally have nested JARs extracted and remapped.include
: Declares a dependency that should be included as a jar-in-jar in theremapJar
output. This dependency configuration is not transitive.
Default tasks
cleanLoomBinaries
: For the configured version of Minecraft and the configured mappings, deletes the merged Minecraft jar, the intermediary Minecraft jar and the mapped Minecraft jar from the user cache.cleanLoomMappings
: For the configured version of Minecraft and the configured mappings, deletes the mappings, the intermediary Minecraft jar and the mapped Minecraft jar from the user cache. Also clears the root project build cache.migrateMappings
: Migrates the current source to the specified mappings. See migratemappings.remapJar
: Produces a jar containing the remapped output of thejar
task. Also appends any included mods for jar-in-jar.genSources
: Delegates to two tasks.genSourcesDecompile
decompiles the mapped Minecraft jar using FernFlower to create a sources jar and additionally generates a linemap.genSourcesRemapLineNumbers
then applies the generated linemap to produce a linemapped jar which re-aligns line numbers in the binary and source jars. The linemapped jar replaces the mapped jar.downloadAssets
: Downloads the asset index and asset objects for the configured version of Minecraft into the user cache.genIdeaWorkspace
: Depends onidea
andgenSources
. Installs run configurations in the ItelliJ project of the root project and creates the run directory if it does not already exist.genEclipseRuns
: Depends ongenSources
. Installs Eclipse run configurations and creates the run directory if it does not already exist.vscode
: Depends ongenSources
. Generates or overwrites a Visual Studio Codelaunch.json
file with launch configurations in the.vscode
directory and creates the run directory if it does not already exist.remapSourcesJar
: Only exists if an AbstractArchiveTasksourcesJar
exists. Remaps the output of thesourcesJar
task in place.runClient
: A JavaExec task to launch Fabric Loader as a Minecraft client.runServer
: A JavaExec task to launch Fabric Loader as a Minecraft dedicated server.
Default configuration
- Applies the following plugins:
java
,eclipse
andidea
. - Adds the following Maven repositories: Fabric https://maven.fabricmc.net/, Mojang https://libraries.minecraft.net/, Maven Central and JCenter.
- Configures the
idea
extension to exclude directories.gradle
,build
,.idea
andout
, to download javadocs sources and to inherit output directories. - Configures the
idea
task to be finalized by thegenIdeaWorkspace
task. - Configures the
eclipse
task to be finalized by thegenEclipseRuns
task. - If an
.idea
folder exists in the root project, downloads assets (if not up-to-date) and installs run configurations in.idea/runConfigurations
. - Adds
net.fabricmc:fabric-mixin-compile-extensions
and its dependencies with theannotationProcessor
dependency configuration. - Configures all non-test JavaCompile tasks with configurations for the Mixin annotation processor.
- Configures the
remapJar
task to output a JAR with the same name as thejar
task output, then adds a “dev” classifier to thejar
task. - Adds the
remapJar
task and theremapSourcesJar
task as dependencies of thebuild
task. - Configures the
remapJar
task and theremapSourcesJar
task to add their outputs asarchives
artifacts when executed. - For each MavenPublication (from the
maven-publish
plugin):- Manually appends dependencies to the POM for mod-augmented dependency configurations, provided the dependency configuration has a Maven scope.
All run configurations are set with the run directory ${projectDir}/run
and the VM argument -Dfabric.development=true
. The main class for run configurations is usually defined by a fabric-installer.json
file in the root of Fabric Loader's JAR file when it is included as a mod dependency, but the file can be defined by any mod dependency. If no such file is found, the main class defaults to net.fabricmc.loader.launch.knot.KnotClient
and net.fabricmc.loader.launch.knot.KnotServer
.
Client run configurations are configured with –assetsIndex
and –assetsDir
program arguments pointing to the loom cache directory containing assets and the index file for the configured version of Minecraft. When running on OSX, the “-XstartOnFirstThread” VM argument is added.
Configuration
minecraft
extension properties:
runDir
(String): Default value is“run”
. Defines the run directory used by run configurations and therunServer
andrunClient
tasks.refmapName
(String): Default value is“${projectName}-refmap.json”
. Defines the name of the mixin refmap.loaderLaunchMethod
(String): Default value is“”
. Defines the method used to launch Fabric Loader in run configurations. The launch method used is Knot by default. If set to another valuemethod
, Loom will attempt to use readfabric-installer.${method}.json
for run configurations and fall back tofabric-installer.json
if none can be found. If set to“launchwrapper”
and no fabric installer definitions can be found, run configurations will use default LaunchWrapper run configuration for Fabric Loader.remapMod
(boolean): Default value istrue
. If false, disables the configuration of theremapJar
task, theremapSourcesJar
task and thejar
task.autoGenIDERuns
(boolean): Default value istrue
. If false, disables the automatic downloading of assets and generation of IntelliJ run configurations if an.idea
folder exists in the root project.extractJars
(boolean): Default value isfalse
. If true, Loom will recursively extract and remap nested JARs of mod dependencies.
Publishing
Useful task types
net.fabricmc.loom.task.RemapJarTask
: Takes an input JAR and outputs a JAR. Should be configured to depend on the task that produces the input JAR. This task is not an AbstractArchiveTask.net.fabricmc.loom.task.RemapSourcesJarTask
:
Development environment setup
Loom does quite a few things behind the scenes to create a development environment with Minecraft.
- Downloads the client and server jar from official channels for the configured version of Minecraft.
- Merges the client and server jar to produce a merged jar with
@Environment
and@EnvironmentInterface
annotations. - Downloads the configured mappings.
- Remaps the merged jar with intermediary mappings to produce an intermediary jar.
- Remaps the intermediary jar with yarn mappings to produce a mapped jar.
- Optional: Decompiles the mapped jar to produce a mapped sources jar and linemap, and applies the linemap to the mapped jar.
- Adds dependencies of Minecraft.
- Downloads Minecraft assets.
- Remaps mod-augmented dependencies (and optionally extracts and remaps nested JARs).
Caches
${GRADLE_HOME}/caches/fabric-loom
: The user cache, a cache shared by all Loom projects for a user. Used to cache Minecraft assets, jars, merged jars, intermediary jars and mapped jars..gradle/loom-cache
: The root project persistent cache, a cache shared by a project and its subprojects. Used to cache remapped mods as well as generated included mod jars.build/loom-cache
: The root project build cache.**/build/loom-cache
: The (sub)project build cache.