Alternations Lib

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!