Preloading Tricks

概述

预加载技巧 (Preloading Tricks) 是一个仅限开发者的模组，可在模组加载器的极早期阶段实现高级操作。 它提供了早期钩子、基于 Java Instrumentation 的类转换，以及用于加载器扩展的 SPI 驱动回调。

支持的环境：

• Fabric – 1.20.1、1.21+
• Forge (LexForge) – 1.20.1
• NeoForge – 1.20.6、1.21+

由于它依赖于加载器版本而非 Minecraft 版本，你可以在更多版本上进行测试。

---

特性

• 早期加载器入口点，通过 PreloadingEntrypoint（基于 SPI）实现

  • 使用 PreloadingTricksCallbacks 事件注册回调：
    • SETUP_LANGUAGE_ADAPTER – 早期语言适配器设置阶段
    • COLLECT_MOD_CANDIDATES – 在发现之前动态添加模组候选路径
    • SETUP_MODS – 修改模组列表（通过 ModManager API 添加/移除/查询）

• 基于 Instrumentation 的 ClassTransform 可以转换已加载的类，包括 Java 核心类和类加载器类。 在所有平台上通过 MANIFEST.MF 配置（见下文）。

• Forge 变体检测（仅限 Forge 类加载器）

  • 访问 ForgeVariants 以在运行时检测特定的 Forge/NeoForge 版本

---

使用方法 (Gradle)

将 Maven 仓库和依赖添加到你的构建中：

Kotlin DSL：

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

dependencies {
  // 推荐：使用基础构件（无分类器）。
  // Gradle 变体匹配 / 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 属性自动选择对应的变体。

---

ClassTransform 配置

在所有平台上，将以下属性添加到你的 MANIFEST.MF 中：

ClassTransformConfig: xxxx.classtransform.json

可以通过逗号分隔值指定多个配置：

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

配置示例 (xxxx.classtransform.json)：

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

---

Forge 变体检测（仅限 Forge 类加载器）

允许模组仅在特定 Forge 类加载器变体上加载。这使得可以通过 jar-in-jar 将 LexForge 和 NeoForge 的 JAR 打包在单个模组文件中。

配置：

在 MANIFEST.MF 中指定模组的目标变体：

ForgeVariant: LexForge

或

ForgeVariant: NeoForge

指定了 ForgeVariant 的模组只会在匹配的加载器变体上加载，从而允许不同变体的实现安全共存。

---

为那些需要触及 Minecraft 加载过程最早期阶段的开发者而设计。