Loom 26.1.2

Документация по плагину Fabric Loom Gradle.

WARNING

Эта страница написана для версии 26.1.2. Документация для более старых версий может быть неполной.

Fabric Loom, или просто Loom, это Gradle плагин для разработки модов в экосистеме Fabric.

Loom предоставляет утилиты для установки Minecraft и модов в среде разработки, чтобы вы могли использовать их в отношении запутывания Minecraft и его различий между дистрибутивами и версиями. Он также предоставляет конфигурации запуска для использования с Fabric Loader, обработку компиляции Mixin и утилиты для системы jar-in-jar Fabric Loader.

Loom поддерживает все версии Minecraft, даже те, которые официально не поддерживаются Fabric API, потому что он не зависит от версии.

ВАЖНО

Эта страница является справочником всех опций и возможностей Loom. Если вы только начинаете, прочитайте Введение в Fabric.

Идентификатор плагина

Loom использует различные идентификаторы плагина:

• net.fabricmc.fabric-loom, для версии без обфускация (Minecraft 26.1 или новее)
• net.fabricmc.fabric-loom-remap, для обфусцированных версий (Minecraft 1.21.11 или раньше)
• fabric-loom (легаси), поддерживается только для обратной совместимости с обфусцированными версиями. Вместо этого используйте net.fabricmc.fabric-loom-remap
• net.fabricmc.fabric-loom-companion, в сложных многопроектных конфигурациях. Подробнее о подпроектах

Подпроекты

При настройке мультипроектной сборки, которая зависит от другого проекта Loom, вы должны использовать конфигурацию namedElements, когда зависите от другого проекта. По умолчанию "выходы" проекта переименовываются в промежуточные имена. Конфигурация namedElements содержит выходы проекта, которые не были ремаппированы.

dependencies {
 implementation project(path: ":name", configuration: "namedElements")
}

Если вы используете разделенные наборы исходных текстов в мультипроектной сборке, вам также нужно будет добавить зависимость для клиентского набора исходных текстов другого проекта.

dependencies {
 clientImplementation this.project(":name").sourceSets.client.output
}

Разделение клиента & Общего кода

В течение многих лет распространенным источником падения серверов были моды, случайно вызывающие код, предназначенный только для клиента, при установке на сервер. Новые версии Loom и Loader предоставляют возможность требовать переноса всего клиентского кода в собственный набор исходных текстов. Это делается для того, чтобы остановить проблему во время компиляции, но в результате сборки все равно получится один jar-файл, который будет работать с любой стороны.

Следующий фрагмент из файла build.gradle показывает, как вы можете включить это для вашего мода. Поскольку теперь ваш мод будет разделен на два набора источников, вам нужно будет использовать новый DSL для определения наборов источников вашего мода. Это позволит Fabric Loader сгруппировать классы вашего мода. Это также полезно для некоторых других сложных многопроектных настроек.

Для разделения клиента и общего кода требуется Minecraft 1.18 (рекомендуется 1.19), Loader 0.14 и Loom 1.0 или более поздняя версия.

loom {
	splitEnvironmentSourceSets()

	mods {
		"example-mod" {
			sourceSet sourceSets.main
			sourceSet sourceSets.client
		}
	}
}

Решение проблем

Иногда Loom и/или Gradle могут не работать из-за поврежденных файлов кэша. Выполнение команды ./gradlew build --refresh-dependencies заставит Gradle и Loom заново загрузить и создать все файлы. Это может занять несколько минут, но обычно этого достаточно, чтобы решить проблемы, связанные с кэшем.

Настройка среды разработки

Loom разработан для работы "из коробки", просто установив рабочую область в вашей IDE. Он делает довольно много вещей за кулисами, чтобы создать среду разработки с Minecraft:

• Загрузите клиент и серверный jar с официальных каналов для настроенной версии Minecraft
• Объединяет клиентский и серверный jar для создания объединенного jar с аннотациями @Environment и @EnvironmentInterface
• Загрузка настроенных отображений
• Изменяет объединенный jar с промежуточными отображениями, чтобы создать промежуточный jar
• Перерисовывает объединенный jar с помощью сопоставлений Yarn, чтобы получить сопоставленный jar
• Необязательно: Декомпилирует сопоставленный jar, чтобы получить сопоставленный исходный jar и linemap, и применяет linemap к сопоставленному jar
• Добавляет зависимости для Minecraft
• Скачивание папки для клиентских ресурсов (assets) Minecraft
• Обрабатывает и включает дополненные модом зависимости

Кеши

• ${GRADLE_HOME}/caches/fabric-loom: Пользовательский кэш - кэш, общий для всех проектов Loom для данного пользователя. Используется для кэширования активов Minecraft, jars, объединенных jars, промежуточных jars и сопоставленных jars
• .gradle/loom-cache: Постоянный кэш корневого проекта, кэш, общий для проекта и его подпроектов. Используется для кэширования ремаппированных модов, а также сгенерированных jars с модами
• **/build/loom-cache: Кэш сборки (под)проектов

Конфигурации зависимостей

• minecraft: Определяет версию Minecraft, которая будет использоваться в среде разработки
• mappings: Определяет сопоставления, которые будут использоваться в среде разработки
• modImplementation, modApi и modRuntime: Дополненные варианты implementation, api и runtime для зависимостей от модов. Будет изменено отображение в соответствии с отображениями в среде разработки и удалены все вложенные jars
• include: Объявляет зависимость, которая должна быть включена как jar-in-jar в финальный файл мода. Эта конфигурация зависимости не является переходной. Для немодовых зависимостей Loom сгенерирует mod jar с fabric.mod.json, используя ID мода для имени, и ту же версию

INFO

Зависимости, объявленные с помощью include, добавляются в remapJar в Loom с переотображением или в jar в Loom без переотображения соответственно. Из-за этого задачи jar из других плагинов (например, shadowJar) по умолчанию не будут включать эти зависимости.

Конфигурация (по умолчанию)

• Применяет следующие плагины: java, eclipse
• Добавляет следующие репозитории Maven: Fabric, Mojang и Maven Central
• Настраивает задачу eclipse, которая будет завершена задачей genEclipseRuns
• Если в корневом проекте существует папка .idea, загружает assets (если они не обновлены) и устанавливает конфигурации запуска в .idea/runConfigurations
• Добавляет net.fabricmc:fabric-mixin-compile-extensions и его зависимости в конфигурацию зависимостей annotationProcessor
• Настраивает все нетестовые задачи JavaCompile с конфигурациями для процессора аннотаций Mixin
• Настраивает задачу remapJar на вывод JAR с тем же именем, что и у задачи jar, затем добавляет классификатор "dev" к задаче jar
• Настраивает задачу remapSourcesJar на обработку вывода задачи sourcesJar, если такая задача существует
• Добавляет задачу remapJar и задачу remapSourcesJar в качестве зависимостей задачи build
• Настраивает задачу remapJar и задачу remapSourcesJar на добавление их результатов в качестве артефактов archives при выполнении
• Для каждой публикации MavenPublication (из плагина maven-publish) вручную добавляет зависимости в POM для конфигураций зависимостей, дополненных модом, при условии, что конфигурация зависимостей имеет область видимости Maven

Все конфигурации запуска имеют каталог запуска ${projectDir}/run и аргумент VM -Dfabric.development=true. Основные классы для конфигураций запуска обычно определяются файлом fabric-installer.json в корне JAR-файла Fabric Loader, когда он включается в качестве зависимости от мода, но этот файл может быть определен любой зависимостью от мода. Если такой файл не найден, основными классами по умолчанию будут net.fabricmc.loader.launch.knot.KnotClient и net.fabricmc.loader.launch.knot.KnotServer.