AlternationsLib — 面向 Fabric 的高级依赖驱动入口点加载器
AlternationsLib 是专为 Fabric 模组开发者设计的专用初始化 API。它通过引入直接由模组元数据驱动的多阶段、依赖感知加载序列,彻底重新定义了跨模组集成工作的方式。
它允许你安全地使用第三方模组中的物品、方块和机制,而无需担心因这些模组缺失而导致 ClassNotFoundException 或初始化崩溃。
⚙️ 配置结构 (fabric.mod.json)
要注册你的钩子(hooks),需在模组的元数据文件的 AlternationsLib 块中以布局样式声明它们。
? 旧版格式(支持所有版本,包括 1.0-BETA-2 及更高版本):
{
"AlternationsLib": {
"entrypoint": "org.example.mod.integration.MyModHook",
"depends": [
"example_depend_id"
]
}
}
? 新版格式(支持 1.0-BETA-2 及更高版本):
{
"custom": {
"AlternationsLib": {
"entrypoint": "org.example.mod.integration.MyModHook",
"depends": [
"example_depend_id"
]
}
}
}
? 元数据字段详解:
AlternationsLib: 核心配置注册表对象,该库在启动时会扫描此对象。
entrypoint: 作为特定集成专用初始化器的 Java 类的完全限定路径。
depends: 唯一模组标识符 (ModID) 的数组。这定义了在执行此入口点之前必须解析哪些第三方模组。
Java 实现示例
在 entrypoint 字段中指定的集成类必须实现 AlternationsRegistryInitializer 接口并重写 onInitialize() 方法。
执行流程:实际工作原理
与盲目初始化一切内容的静态加载器不同,AlternationsLib 会解析所有声明的配置块并协调动态的、分阶段的加载顺序:
1. 扫描阶段
在早期启动阶段,该库会扫描每个已安装模组的 fabric.mod.json 文件,索引所有注册的 AlternationsLib 配置块、其目标入口点及其依赖树。
2. 第一阶段:零依赖初始化
加载器在标准 Fabric 环境稳定后立即行动。它首先过滤并执行那些在 "depends" 数组中未声明任何依赖项的所有入口点。这些作为基线初始化器运行。
3. 标准游戏启动 (ModInitializer)
常规的原生和模组加载周期发生。Fabric 处理标准的模组设置,建立模组注册表、底层游戏系统和原生 ModInitializer 块。
4. 第二阶段:依赖解析执行
一旦核心环境完全激活,AlternationsLib 会重新评估剩余的索引入口点:
- 动态解析: 它检查环境中是否存在请求的
"depends" ID(例如 "example_depend_id")。
- 安全条件加载: 如果依赖模组处于活动状态,其相应的
entrypoint 类将被安全地加载到 JVM 中,并将其转换为 AlternationsRegistryInitializer 以触发 onInitialize()。这使得它能够无缝挂钩到已解析模组的方块和物品上。
⚠️ 关于兼容性要求的重要说明
? 关键要求: 为了使这种多阶段依赖系统正确工作并确保依赖模组在其目标依赖项之后执行,两个模组都必须使用 AlternationsLib。
目标依赖模组(你所依赖的那个模组)也必须通过该库的系统进行注册。如果目标模组使用标准的初始化方法而不是挂接到这个库,Phase 2 机制无法保证执行顺序。请确保所有参与的模组都接入 AlternationsLib 生态系统!
AlternationsLib — Advanced Dependency-Driven Entrypoint Loader for Fabric
AlternationsLib is a specialized initialization API for Fabric mod developers. It completely redefines how cross-mod integration works by introducing a multi-phase, dependency-aware loading sequence directly driven by mod metadata.
It allows you to safely use items, blocks, and mechanics from third-party mods without risking ClassNotFoundException or initialization crashes if those mods are absent.
⚙️ The Configuration Structure (fabric.mod.json)
To register your hooks, you declare them layout-style within the AlternationsLib block of your mod's metadata file.
? Legacy format (Supported in all versions, including 1.0-BETA-2 and higher):
{
"AlternationsLib": {
"entrypoint": "org.example.mod.integration.MyModHook",
"depends": [
"example_depend_id"
]
}
}
? New format (Supported in version 1.0-BETA-2 and higher):
{
"custom": {
"AlternationsLib": {
"entrypoint": "org.example.mod.integration.MyModHook",
"depends": [
"example_depend_id"
]
}
}
}
? Metadata Fields Breakdown:
AlternationsLib: The core configuration registry object scanned by this library at boot time.
entrypoint: The fully qualified path to your Java class acting as the dedicated initializer for this specific integration.
depends: An array of unique mod identifiers (ModID). This defines exactly which third-party mods must be resolved before this entrypoint is allowed to execute.
Java Implementation Example
Your integration class specified in the entrypoint field must implement the AlternationsRegistryInitializer interface and override the onInitialize() method.
Execution Pipeline: How It Actually Works
Unlike static loaders that initialize everything blindly, AlternationsLib parses all declared configuration blocks and orchestrates a dynamic, phased loading order:
1. The Scanning Phase
During the early launch stage, the library scans the fabric.mod.json files of every installed modification, indexing all registered AlternationsLib config blocks, their target entrypoints, and their dependency trees.
2. Phase 1: Zero-Dependency Initialization
The loader acts immediately after the standard Fabric environment settles. It first filters out and executes all entrypoints that have no dependencies declared in their "depends" array. These run as baseline initializers.
3. Standard Game Boot (ModInitializer)
The regular vanilla and mod loading cycles occur. Fabric handles standard mod setups, setting up mod registries, underlying game systems, and native ModInitializer blocks.
4. Phase 2: Dependency-Resolved Execution
Once the core environment is fully active, AlternationsLib re-evaluates the remaining indexed entrypoints:
- Dynamic Resolution: It checks the environment for the requested
"depends" IDs (e.g., "example_depend_id").
- Safe Conditional Loading: If a dependency mod is active, its corresponding
entrypoint class is safely loaded into the JVM, casting it to AlternationsRegistryInitializer to trigger onInitialize(). This allows it to seamlessly hook into the resolved mod's blocks and items.
⚠️ IMPORTANT NOTE ON COMPATIBILITY REQUIREMENTS
? Crucial Requirement: For this multi-phase dependency system to work correctly and guarantee that a dependent mod executes AFTER its target dependency, both mods must utilize AlternationsLib.
The target dependency mod (the one you are depending on) must also be registered via this library's system. If the target mod uses standard initialization methods instead of hanging on this library, the execution order cannot be guaranteed by Phase 2 mechanics. Make sure all participating mods hook into the AlternationsLib ecosystem!
评论 0
登录后参与评分
还没有评论,来抢沙发吧