fabric.mod.json 26.1.2

Руководству по структуре fabric.mod.json.

WARNING

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

Файл fabric.mod.json это файл с метаданными, который использует загрузчик Fabric для загрузки мода. Он должен находиться в главной папке JAR файла мода, что бы мод смог загрузиться.

Обычно файл fabric.mod.json включен с шаблоном мода, или его можно сгенерировать с помощью Fabric Loom.

Также можно обратиться к исходному коду структуры fabric.mod.json. Вы найдёте файл fabric.mod.json используемый этим примером мода ниже.

fabric.mod.json из примера мода

{
  "schemaVersion": 1,
  "id": "example-mod",
  "version": "1.0.0",
  "name": "Example Mod",
  "icon": "assets/example-mod/icon.png",
  "environment": "*",
  "entrypoints": {
    "main": [
      "com.example.docs.ExampleMod",
      "com.example.docs.event.ExampleModEvents",
      "com.example.docs.command.ExampleModCommands",
      "com.example.docs.effect.ExampleModEffects",
      "com.example.docs.potion.ExampleModPotions",
      "com.example.docs.sound.ExampleModSounds",
      "com.example.docs.damage.ExampleModDamageTypes",
      "com.example.docs.item.ExampleModItems",
      "com.example.docs.enchantment.ExampleModEnchantments",
      "com.example.docs.block.ExampleModBlocks",
      "com.example.docs.block.entity.ExampleModBlockEntities",
      "com.example.docs.menu.ExampleModMenuType",
      "com.example.docs.component.ExampleModComponents",
      "com.example.docs.advancement.ExampleModDatagenAdvancement",
      "com.example.docs.networking.ExampleModNetworking",
      "com.example.docs.networking.basic.ExampleModNetworkingBasic",
      "com.example.docs.debug.ExampleModDebug",
      "com.example.docs.saveddata.ExampleModSavedData",
      "com.example.docs.entity.attribute.ExampleModAttributes",
      "com.example.docs.recipe.ExampleModRecipes",
      "com.example.docs.entity.ExampleModEntity",
      "com.example.docs.gamerule.ExampleModGameRules",
      "com.example.docs.conditions.ExampleModResourceConditions",
      "com.example.docs.stats.ExampleModStats"
    ],
    "client": [
      "com.example.docs.client.command.ExampleModClientCommands",
      "com.example.docs.ExampleModBlockEntityRenderer",
      "com.example.docs.ExampleModDynamicSound",
      "com.example.docs.ExampleModClient",
      "com.example.docs.ExampleModScreens",
      "com.example.docs.rendering.CustomRenderPipeline",
      "com.example.docs.rendering.HudRenderingEntrypoint",
      "com.example.docs.rendering.RenderingConceptsEntrypoint",
      "com.example.docs.network.basic.ExampleModNetworkingBasicClient",
      "com.example.docs.appearance.ExampleModAppearanceClient",
      "com.example.docs.keymapping.ExampleModKeyMappingsClient",
      "com.example.docs.ExampleModRecipesClient",
      "com.example.docs.entity.ExampleModCustomEntityClient"
    ],
    "fabric-datagen": ["com.example.docs.datagen.ExampleModDataGenerator"]
  },
  "mixins": [
    "example-mod.mixins.json",
    {
      "config": "example-mod.client.mixins.json",
      "environment": "client"
    }
  ],
  "depends": {
    "fabricloader": ">=0.19.0",
    "minecraft": "~26.1",
    "java": ">=25",
    "fabric-api": "*"
  },
  "accessWidener": "example-mod.classtweaker"
}

Обязательные поля

Следующие поля являются обязательными, что бы Fabric загрузил ваш мод.

• schemaVersion Должно быть первым элементом, и значение всегда должно быть 1. Необходимо, что бы Fabric Loader правильно прочитал файл.
• id Значение типа string, определяющее идентификатор мода. Должно начинаться с буквы. Может содержать только символы ASCIII, цифры, нижние подчёркивания или дефисы. От 2 до 64 символов.
• версия строковое значение, которое определяет версию мода; оно должно предпочтительно совпадать со структурой суперсета Сематического Версионирования 2.0.0, поддерживая любое число компонентов и произвольных build метаданных. Если совпадение отсутствует, оно рассматривается как обычная строка, без поддержки диапазонов версий.

"schemaVersion": 1,
"id": "example-mod",
"version": "1.0.0"

Метаданные

• name: Строка, определяющая название мода, для пользователя. Если не указано, то является id.
• description: Строка, определяющая описание мода. Если не указано, то является пустой строкой.

"name": "Example Mod",
"description": "This is an example description! Tell everyone what your mod is about!",

Контакты

contact: Словарь, определяющий всю контактную информацию проекта. Содержит немного общих полей:

• email: Строка, определяющая электронную почту, для связи с разработчиком мода. Электронная почта должна быть действительной.
• homepage: Строка, определяющая страницу проекта или разработчика. Адрес HTTP/HTTPS должен быть действительным.
• irc: Строка, определяющая канал общения, относящийся к моду. Должно быть в правильном формате URL - например: irc://irc.esper.net:6667/charset для #charset в EsperNet - этот порт необязательный, и если неуказан то будет 6667.
• issues: Строка, определяющая портал, относящийся к ошибкам проекта. Адрес HTTP/HTTPS должен быть действительным.
• sources: Строка, определяющая репозиторий исходного кода проекта. Должно быть действительным URL - он может быть специализированным для разных систем контроля версий (как Git или Mercurial).

Список может быть больше - моды так же могут добавлять необычные ключи, как discord, telegram, twitter... Если возможно, так же должно быть действительным URL.

"contact": {
    "homepage": "https://fabricmc.net",
    "sources": "https://github.com/FabricMC/fabric-example-mod"
}

Авторы и Помощники

• authors Массив авторов мода. Элементы могут быть строкой или объектом с полями перечисленными ниже.
• contributors Массив помощников мода. Элементы могут быть строкой или объектом с полями перечисленными ниже.

Поля:

• name Обязательная строка с настоящим именем человека, или его ника.
• contact Необязательный объект с контактной информацией человека. То же самое, как и обычный contact.

"authors": [
    "Me!",
    {
        "name": "Tiny Potato",
        "contact": {
          "homepage": "https://fabricmc.net",
          "sources": "https://github.com/FabricMC/fabric-example-mod"
        }
    }
]

Лицензия

• license Строка или массив, который определяет лицензионную информацию. Можно использовать Идентификаторы лицензий SPDX для автоматического поиска открытых исходных лицензий.

Это должно проводить минимальное количество лицензий, которые удовлетворяют пакет модов. То есть, те кто хотят использовать или распространять ваш мод, всего лишь то надо соблюдать перечисленные здесь лицензии. Если ваши части кода имеют две лицензии, выберите более важную лицензию. Этот список не обязательно запрещает вам предоставлять дополнительные права или применять разные лицензии для определённых людей в каждом случае.

"license": "CC0-1.0"

Иконка

• icon Строка или словарь, которые определяют иконку вашего мода. Иконки это квадратные картинки PNG формата. Наборы ресурсов майнкрафта используют разрешение 128x128, но это не жёсткое требование, но желательно соблюдать. Может быть предоставлено в двух формах:
  • Путь к одному PNG файлу.
  • Словарь ширины изображений к их файловым путям.

"icon": "assets/example-mod/icon.png"

Загрузка мода

Среда

• environment: Значение типа string, которое определяет в какой среде мод должен запущен:
  • *: Запускается во всех средах. Стоит по умолчанию.
  • client: Запускается на физической клиентской стороне. Если установить, то мод не будет загружен на выделенных серверах.
  • server: Запускается на физической серверной стороне. Если установить, то мод не будет загружен на клиентах, включая одиночную игру и игру по сети.

"environment": "*"

Точки входа

• entrypoints Объект, определяющий основные классы, из которых ваш мод будет загружен.
  • main String массив имен, которые имплементируют ModInitializer.
  • client String массив имен, которые имплементируют ClientModInitializer. Данная точка входа запускается после основной, и только на физической клиентской стороне.
  • server String массив имен, которые имплементируют DedicatedServerModInitializer. Данная точка входа запускается после основной, и только на физической серверной стороне.

Загрузчик Fabric поставляет эти три основных точки входа, но остальные моды могут добавлять свои. Например, Fabric API поставляет fabric-datagen для точек входа генератора данных.

Каждая точка входа может загружать множество классов, методов или статических полей. Например:

"main": [
    "net.fabricmc.example.ExampleMod",
    "net.fabricmc.example.ExampleMod::handle"
]

TIP

Если вы не используете Java, то можете обратиться к документации адаптера языка. Для Kotlin находится в README файл в Fabric Language Kotlin.

JAR файлы

• jars: Массив JAR файлов находящиеся внутри твоего мода. Используя include в блоке зависимостей, Loom автоматические заполнит это. Каждый элемент это объект содержащий ключ file, с путём к включённому JAR файлу в вашем моде. Например:

"jars": [
   {
      "file": "nested/vendor/dependency.jar"
   }
]

Адаптеры языков

• languageAdapters: Словарь классов, которые имплементируют LanguageAdapter.

"languageAdapters": {
   "kotlin": "net.fabricmc.language.kotlin.KotlinAdapter"
}

Миксины

• mixins: Список файлов с конфигом миксина. Каждый элемент это путь к файлу конфига миксина в JAR файле вашего мода или объект содержащий следующие поля:
  • config: Путь к файлу конфига миксина внутри JAR файла вашего мода.
  • environment: То же самое, что и поле environment* выше. Например:

"mixins": [
   "example-mod.mixins.json",
   {
      "config": "example-mod.client-mixins.json",
      "environment": "client"
   }
]

Расширители Доступа

• accessWidener: Строка идентифицирующая как файл расширителя доступа или модификатора класса.

"accessWidener": "example-mod.classtweaker"

Обеспечивает

• provides： Массив идентификаторов модов, которые будут псевдонимами для этого мода. Загрузчик Fabric рассмотрит данные идентификатора, будто эти моды есть. Если другой мод использует какой-либо из них, то он не загрузится.

"provides": [
   "example_mod"
]

Разрешения Зависимостей

Эти ключи будут принимать словарь зависимостей. Для больших деталей структуры словаря смотрите ниже:

• depends: Зависимости обязательные для запуска. Если какого либо не будет, то Загрузчик Fabric вызовет краш.
• recommends: Зависимости необязательные для запуска. Для каждой отсутствующей зависимости, Загрузчик Fabric предупредит в логах.
• suggests: Зависимости необязательные для запуска. Используйте это как метаданные.
• breaks: Для модов, которые вместе с вашим, будут вызывать краш игры. Если какой-либо будет, то Загрузчик Fabric вызовет краш.
• conflicts: Для модов, которые вместе с вашим, могут вызывать баги и прочее. Для каждого представленного конфликтующего мода, Загрузчик Fabric предупредит в логах.

Семантическое Версионирование

Ключ каждого элемента - это идентификатор мода зависимости.

Значения каждого ключа - это строка или массив строк, говорящих поддерживаемый диапазон версий зависимостей. Если это массив, для выполнения ограничения должен совпадать только один диапазон.

Fabric использует суперсет Сематического Версионирования, чтобы поддерживать любое число компонентов, например, поддерживаются версии как 1.2.3.4. Когда сравниваются версии с разным числом компонентов, к ним добавляется 0 справа, например, 26.1 = 26.1.0

Чтобы сопоставить все компоненты предрелизов в диапазоне, добавьте к диапазону суффикс -; например, чтобы получить только снимки версии 26.2, используйте диапазон >26.2- <26.2.

Метаданные сборки, то есть все, что следует за символом «+» в обозначении версии, игнорируются при сравнении версий. К примеру 0.154+26.3 и 0.154+26.2 равны.

Здесь есть немного примеров диапазонов и что они показывают. Попытайтесь использовать Верификацию загрузчика Fabric от Outlet, чтобы протестировать, какие значения будут удовлетворять константу.

Примеры Семантического Версионирования

Заметка: Майнкрафт не следует семантическому версионированию. Если надо, Fabric переведёт версию Майнкрафта в эквивалент в виде семантического версионирования. Примеры включают 26.1->26.1.0, 26.1-snapshot-1->26.1-alpha.1, 26w14a->26.1.1-alpha.26.14.a. Этот паттерн изменился с релизом версии 1.16-rc1. Раньше Fabric нормализовал пререлизы как 1.16-pre1 в 1.16-rc.1, что теперь конфликтует. Начиная с загрузчика 0.8.8, 1.16-rc1 нормализовано в 1.16-rc.9 и будущие пререлизы нормализованы в -beta.n.

Диапазон	Описание	Совпадения	Конфликты
*	Любая версия (не рекомендуется)	26.1.2, 24w14potato...	нету
26.1.2	Только одна версия	26.1.2	26.1, 26.1.1, 26.2...
>26	Версии выше (исключительно)	26.1.2, 26.2...	26, 25.x...
>=26.1	Эта версия или выше (включающее)	26.1, 26.1.2, 26.2`...	26.0, 25.x...
<=26.1	Эта версия или ниже (включающее)	26.1, 26.0, 25.x...	26.1.2, 26.2...
>26 <26.2	Между двумя версиями (оба исключительные)	26.1, 26.1.2, снапшоты...	26, 26.2...
>=26.1 <26.2	Между двумя версиями (включающее нижнюю границу)	26.1, 26.1.2, снапшоты...	26.0, 26.2...
~26.1-rc.2	То же самое относится и к следующей минорной версии, за исключением более ранних версий (эквивалентно >=26.1-rc.2 <26.2-). Проверяет только мажорные и минорные компоненты.	26.1-rc.2, 26.1, 26.1.2, снэпшоты...	26.1-rc.1, 26.2, 27.x...
^26.2	То же самое относится и к следующей основной версии, за исключением более ранних версий (эквивалентно >=26.2 <27-). Проверяет только мажорный компонент.	26.2, 26.3...	26.1, 25.x, 27.x...
26.1.x	Эквивалентно ~26.1-.	26.1-rc-3, 26.1, 26.1.2, снэпшоты...	26.2, 27.x`...
1.x	Эквивалентно ^1-.	1.0.0-beta.4, 1.0.0, снэпшоты...	26.x
>26.2- <26.2	Все снэпшоты 26.2, включая 26.2	26.2-pre-1, 26.2-rc-1	26.2

Примечание: Оператор .x не работает, если включен компонент пререлиз версии (например, 26.1.x-rc.1); вместо этого диапазон обрабатывается как обычная строка (смотрите другие форматы версий ниже). .*, .x, или .X могут быть использованы взаимозаменяемо. В загрузчике Fabric'а 0.19.3 есть баг из-за которого оператор .x не работает корректно для версий с более тремя компонентами. Оно будет исправлено в будущей версии.

Другие форматы версий

Если версия не соответствует расширенному SemVer, поддерживаемому Fabric, она рассматривается как строка и сравнивается лексикографически в соответствии с Java String#compareTo для целей сортировки, например, во время загрузки модулей, когда Fabric должен решить, какую версию загрузить.

В этом режиме операторы < и> диапазона не разрешены. Другие операторы диапазона работают как =, кроме *, который будет продолжать соответствовать любой версии.

Посмотрите экземпляр строковой версии.

Примечание: Рекомендуется по возможности использовать расширенный SemVer для поддержки сравнения версий и диапазонов!

"depends": {
    "example-mod": "*",
    "minecraft": [
        "26.1",
        "26.1.1"
    ]
}
"suggests": {
    "another-mod": ">1.0.0"
}

Пользовательские Поля

Вы можете добавить любое поле внутри как кастомное поле. Загрузчик проигнорирует их. Однако, рекомендуется использовать пространство имен ваших полей, что бы избежать конфликты с другими модами.