Preloading Tricks

Мод Preloading Tricks для Minecraft — ранний доступ к загрузчику

Preloading Tricks — это утилита исключительно для разработчиков, позволяющая выполнять продвинутые операции на самых ранних этапах инициализации загрузчика модов. Проект предоставляет доступ к ранним хукам, трансформацию классов с помощью Java Instrumentation и callback-функции, управляемые SPI. Инструмент поддерживает три основные платформы: Fabric (с версии 1.20.1), Forge (LexForge, 1.20.1) и NeoForge (с версии 1.20.6). Благодаря зависимости от версии загрузчика, а не только версии игры, мод можно тестировать на широком спектре обновлений.

Ранний доступ к загрузчику и трансформация классов

Preloading Tricks — это инструмент исключительно для разработчиков, предоставляющий доступ к самым ранним стадиям инициализации загрузчика модов. В отличие от стандартных модов, работающих после полной загрузки системы, этот проект позволяет выполнять продвинутые операции на этапе, когда загрузчик только начинает свою работу. Ключевые возможности включают ранние хуки (early hooks), трансформацию классов через Java Instrumentation и обратные вызовы, управляемые SPI.

Центральной функцией является инструмент ClassTransform, способный трансформировать уже загруженные классы, включая классы ядра Java и самого загрузчика. Это открывает возможности для глубокой интеграции с внутренними механизмами платформы, недоступными для обычных модов. Настройка трансформации осуществляется через файл MANIFEST.MF, где указываются пути к конфигурационным файлам трансформации. Если требуется применить несколько конфигураций, их можно перечислить через запятую в атрибуте ClassTransformConfig.

Настройка конфигурации трансформации

Для активации функций трансформации классов на всех поддерживаемых платформах необходимо добавить соответствующий атрибут в файл `MANIFEST.MF` вашего проекта. Формат атрибута выглядит следующим образом:

```
ClassTransformConfig: xxxx.classtransform.json
```

Если требуется загрузить несколько конфигураций, их можно указать через запятую:

```
ClassTransformConfig: first.classtransform.json,second.classtransform.json
```

Пример содержимого конфигурационного файла (`xxxx.classtransform.json`):

```json
{
  "package": "settingdust.preloading_tricks.neoforge.transformer",
  "transformers": [
    "mod_setup_hook.FMLLoaderTransformer"
  ]
}
```

Этот механизм позволяет разработчикам гибко управлять тем, какие классы и как будут трансформироваться в процессе загрузки.

События и обратные вызовы через SPI

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

• SETUP_LANGUAGE_ADAPTER — ранняя настройка адаптера языков, позволяющая вмешиваться в локализацию до её полной инициализации.
• COLLECT_MOD_CANDIDATES — динамическое добавление путей к модификам перед их обнаружением системой, что позволяет включать или исключать моды на этапе сканирования.
• SETUP_MODS — модификация списка установленных модов с использованием API ModManager, включая добавление, удаление или запрос информации о модах.

Также доступна ранняя точка входа через PreloadingEntrypoint, основанная на SPI, что обеспечивает выполнение кода раньше, чем это возможно для стандартных модов.

Интеграция в Gradle (Kotlin DSL)

Для использования Preloading Tricks в проектах на базе Gradle необходимо добавить соответствующий репозиторий Maven и зависимость в файл сборки. При использовании Kotlin DSL это выглядит следующим образом:

```kotlin
repositories {
    maven("https://raw.githubusercontent.com/settingdust/maven/main/repository/")
}

dependencies {
    // Рекомендуемый вариант: использование базового артефакта без классификатора.
    // Gradle variant matching / cloche автоматически выберут правильный артефакт для платформы.
    implementation("settingdust.preloading_tricks:PreloadingTricks:VERSION")

    // Опционально: привязка к конкретному классификатору для предотвращения случайного использования
    // API из других платформ.
    // implementation("settingdust.preloading_tricks:PreloadingTricks:VERSION:fabric")
    // implementation("settingdust.preloading_tricks:PreloadingTricks:VERSION:forge-service")
    // implementation("settingdust.preloading_tricks:PreloadingTricks:VERSION:neoforge-modlauncher")
    // implementation("settingdust.preloading_tricks:PreloadingTricks:VERSION:neoforge-fancy-mod-loader")
}
```

Вместо `VERSION` следует указать последнюю версию релиза (например, `3.5.9`). Если используется cloche, соответствующий вариант будет выбран автоматически на основе атрибутов загрузчика и Minecraft. Для точного выбора версии библиотеки можно использовать специфичные классификаторы для каждой платформы, что полезно при разработке мультиплатформенных модов, чтобы избежать конфликтов API.

Обнаружение вариантов Forge и совместимость

Функция обнаружения вариантов (Forge variant detection) доступна только для загрузчиков, похожих на Forge (LexForge и NeoForge). Она позволяет моду загружаться только на конкретной версии загрузчика, что критически важно для безопасного сосуществования реализаций. Это позволяет объединять JAR-файлы для LexForge и NeoForge в одном файле мода с помощью техники jar-in-jar.

Конфигурация:
Укажите целевой вариант вашего мода в файле MANIFEST.MF:

`
ForgeVariant: LexForge
`

или

`
ForgeVariant: NeoForge
`

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

Связанные материалы

• Cloth Config API — похожий мод
• YetAnotherConfigLib (YACL) — похожий мод
• Architectury API — похожий мод
• Just Enough Items (JEI) — похожий мод

Автор: settingdust · Лицензия: Apache-2.0