====== Маппинги ======

==== Вступление ====

Маппинги определяют имена классов, полей и методов. В обычной среде Fabric, [[https://github.com/FabricMC/yarn/Yarn]] маппинги используются, чтобы предоставить значимые имена для кодовой базы Minecraft в соответствии с решением сообщества. [[https://github.com/FabricMC/intermediary/Intermediary]] также является важным типом маппингов, используемым Fabric. Необходимость в маппингах возникает из-за запутывания версий Minecraft, что создает множество проблем. Ремаппинг - это процесс применения сопоставлений к скомпилированным классам или исходным файлам.

==== Использование маппингов ====

В Loom маппинги определяют имена классов, полей и методов Minecraft, используемых в вашей среде разработки. Эти имена могут варьироваться от одной среды разработки к другой в зависимости от установленных маппингов.

Yarn - это маппинг по умолчанию, используемый Loom. Yarn постепенно совершенствуется и получает новые версии по мере принятия вкладов. Маппинги в Loom задаются с помощью конфигурации зависимостей ''mappings'' в buildscript и могут быть обновлены путем обновления зависимости. Minecraft, а также зависимости, включенные в конфигурации зависимостей, дополненные модами, такие как ''modCompile'', ремаппятся с помощью маппингов. Классам, полям и методам, которые не отображаются в Yarn, присваиваются промежуточные имена, такие как ''class_1234'', ''method_1234'' и ''field_1234''.

<code>
dependencies {
    [...]
    mappings "net.fabricmc:yarn:${project.yarn_mappings}"
}
</code>

Изменяя маппинги в вашей среде разработки, вы можете ожидать, что имена классов, методов и полей в Minecraft и любых включенных модах изменились, и что ваш код, возможно, придется обновить, чтобы ссылаться на измененные имена. [[ru:tutorial:migratemappings|Этот процесс может быть частично автоматизирован]]. Вам также придется запустить ''genSources'', чтобы получить доступ к источникам Minecraft с обновленными маппингами.

Задача "remapJar" Loom'а создаст основной артефакт мода, который представляет собой встроенный jar с использованием промежуточных имен. Однако он не выполняет тестирование или проверку, ''build'' всегда должен использоваться для создания jar для использования конечным пользователем. Кроме того, если присутствует задача "sourcesJar", "remapSourcesJar" создаст jar-файл источников с использованием промежуточных имен. Эти jar-файлы могут быть установлены как моды или включены в среду разработки с конфигурацией зависимостей "modCompile".

  * ** Jar '-dev' (вывод задачи ''jar'') не использует промежуточные имена и поэтому бесполезен.** Он не может быть установлен как мод вне среды разработки и будет работать только в среде разработки с соответствующими маппингами. Вместо этого следует использовать обычный jar (вывод задачи ''remapJar'') и устанавливать его в средах разработки с использованием конфигураций зависимостей, дополненных модулями, таких как ''modCompile''.
  * ** Имена Yarn применяются только в среде разработки **. Вне среды разработки существуют только промежуточные имена, что означает, что код не будет точно соответствовать тому, что вы видите и написали. Loom прозрачно обрабатывает этот переход для вас, но будьте осторожны при использовании отражения.

=== Маппинги Mojang ===

Начиная с версии Loom 0.5, вы также можете использовать официальные маппинги Mojang вместо Yarn, например:

<code>
dependencies {
    [...]
    mappings loom.officialMojangMappings()
}
</code>

Маппинги Mojang поставляются с удобной, но более строгой лицензией, чем Yarn. Используйте их на свой страх и риск.


=== Свои маппинги ===

Вы можете использовать свои небольшие маппинги для Fabric Loom для настройки вашего проекта Gradle.

Например, если у вас есть пользовательская ветвь Yarn, которую вы хотите использовать для маппингов, вы можете скомпилировать Yarn с помощью команды "./gradlew build", извлечь файл jar из каталога "build/libs" и переместить его в папку "mapping" в вашем проекте Gradle. Затем измените запись зависимости маппингов на:

<code>
dependencies {
    mappings fileTree(dir: "mapping", include: "**.jar")
}
</code>

Вы можете изменить каталог, в который вы помещаете маппинги, на любое пользовательское имя; просто измените имя в приведенном выше аргументе "dir". Обратите внимание, что сборка Gradle завершится ошибкой, если в каталоге маппингов у вас есть какой-либо другой файл, кроме jar-файла маппинга!

==== Ремаппинг ====

Ремаппинг - это процесс применения маппингов в коде, преобразования из одного набора имен в другой. Как исходный код Java, так и скомпилированный Java-код могут быть ремаппнуты. Это включает в себя изменение имен ссылок в соответствии с маппингами, а также тщательное переименование методов для сохранения переопределений. Это не меняет того, что делает код, хотя и повлияет на имена, используемые в [[ru:tutorial:reflection|отражении]].

[[https://github.com/FabricMC/tiny-remapper|Tiny Remapper]] это инструмент, который может переназначать скомпилированный Java-код. Он имеет интерфейс командной строки, а также программируемый интерфейс. Loom использует Tiny Remapper для ряда задач, а Fabric Loader использует Tiny Remapper для ремаппинга кода Minecraft в промежуточный. Loom также способен ремаппнуть исходный код Java.

==== Запутывание и распутывание ====

Выпуски Minecraft Java Edition представляют собой запутанные jar-файлы, что означает, что они представляют собой скомпилированные двоичные файлы, лишенные какой-либо значимой информации об именовании, оставляя только голую логику. Мотивация, лежащая в основе запутывания, заключается в предотвращении обратного проектирования и уменьшении размеров файлов. Java-программы, такие как Minecraft, довольно просты в декомпиляции, но запутывание удаляет много информации, которая была бы полезна для целей моддинга. Можно было бы задаться вопросом, как вообще возможно разрабатывать для Minecraft.

Маппинги, подобные Yarn, предоставляют значимые имена для разработки. Используя маппинги, можно разобраться в коде Minecraft и создать для него моды. Маппинг может предоставлять имена для классов, полей, методов, параметров и локальных переменных. Должно быть очевидно, что эти маппинги не идеальны. Маппинг всего Minecraft включает в себя множество догадок от нескольких участников. Маппинги могут быть неполными и иногда изменяться по мере нахождения более точных имен.

==== Посредники (промежутки) ====

Свойство запутывания Minecraft заключается в том, что оно не всегда согласуется между версиями Minecraft. Класс может называться ''abc'' в одной версии Minecraft и ''abd'' в другой. Такая же несогласованность применима к полям и методам. Несоответствие создает двоичную несовместимость между версиями Minecraft.

Код Java может быть скомпилирован для одной версии библиотеки и при этом работать с другой, что делает две версии библиотеки совместимыми в двоичном формате. Проще говоря, двоичная совместимость достигается, если библиотека предоставляет по крайней мере одни и те же классы с одинаковыми методами и полями с одинаковыми именами. Несоответствие в запутывании Minecraft представляет проблему при использовании Minecraft в качестве библиотеки для модов из-за отсутствия двоичной совместимости.

Посредник определяет стабильные имена для внутренних компонентов Minecraft в разных версиях Minecraft. Назначение промежуточного имени состоит в том, что оно всегда будет ссылаться на один и тот же класс, поле или метод. В отличие от имен Yarn, промежуточные имена не имеют смысла и вместо этого следуют числовому шаблону, такому как ''class_1234'', ''method_1234'' и ''field_1234''.

Будучи стабильным маппинг, Посредник может сделать бинарный файл Minecraft совместимым с несколькими версиями (например, версиями снапшотов)! Совместимость гарантируется только для тех частей игры, которые не меняются между версиями. При установке вне среды разработки Fabric Loader предоставляет среду с промежуточными именами, переназначая Minecraft (и клиент Realms) перед запуском игры. Это можно увидеть, просмотрев краш-репорт из производственной среды с установленным загрузчиком Fabric, который будет содержать промежуточные имена. Моды, скомпилированные с промежуточными именами, применяемыми Loom, естественно, совместимы с этой средой.