Adding Dependencies

If you want to interact with code from other mods, you usually need to add these projects to your development environment. You do this in Balm the same way you would in any other single-loader project, using the Gradle dependency system.

Once dependencies are declared and you've refreshed Gradle in your IDE, you can access third party mod classes in the same way you access Minecraft code. You can even launch (and debug) the game with those mods installed from your IDE.

Adding other mods to your development environment

To add a mod dependency to your environment, you need to know the Repository and the Artifact Descriptor that it is deployed under. For example, Balm is located on the https://maven.twelveiterations.com/repository/maven-public/ repository, and its artifact is located under e.g. net.blay09.mods:balm-common:26.1.0.1.

repositories {
  maven {
    url = 'https://example.com/repository/maven-public/'
    content {
      includeGroup 'com.example'
    }
  }
}

dependencies {
  compileOnly 'com.example:thirdpartymod:26.1.0.1'
}

Third party repositories are not always easy to find, so the easiest way to quickly get a mod into your development environment is using CurseMaven, which instead uses CurseForge project and file IDs to identify an artifact. CurseForge also provides a "Curse Maven Snippet" on the File Details page that you can use directly.

dependencies {
  compileOnly "curse.maven:waystones-245755:7844805"
  localRuntime "curse.maven:waystones-245755:7844805"
}

The project templates come with a set of common repositories already set up, including CurseMaven - you can find them in repositories.gradle. Dependencies themselves should be defined in the dependencies.gradle file in common and the loader subfolders.

Dependency Types

The most common options for dependencies are compileOnly, implementation and localRuntime.

• Start with compileOnly, which grants you access to another mod's classes in your code.
  • This is useful for when you have optional compatibility with a mod, such as integration code that only gets loaded when both mods are installed.
  • With this alone, the third party mod will not automatically be loaded when you launch the game from your IDE.
• Only use implementation if your mod explicitly depends on the third party mod to run.
  • The third party mod will be loaded when you launch the game from your IDE, and declared as a transitive Maven dependency of your own mod.
  • For example, this is what's used to add Balm to your project. That way, any third party mods adding your mod as a dependency will also automatically pull in a Gradle dependency on Balm.
• Use localRuntime when you want an optional mod to be loaded when you launch the game from your IDE.
  • Either used for mods that you just like to have in your development environment, or ones that you have soft dependencies for and are actively testing with.
  • The third party mod will be loaded when you launch the game from your IDE, but unlike implementation it will not be marked as a transitive dependency for your mod.

Dependencies in Common Code

When adding support for other multiloader mods, it's usually best to do so in your common project so you don't have to duplicate your integration code.

In order to do so, you may have to find a mojmap or common artifact of said mod. Those artifacts would generally only be found on the mods' real Maven repositories (i.e. not on CurseMaven).

If all else fails, you can try depending on the NeoForge version of the mod in your common project. This may or may not work, depending on your Minecraft version. Starting with Minecraft 26.1 and the removal of obfuscation, this should hopefully be a lot easier now.

Declaring Hard Dependencies

Adding a Gradle dependency only pulls the mod into your development environment - it does not define the mod as a dependency on CurseForge, nor will it be considered a dependency when loading the game.

If your mod actually requires the third party mod to be present, be sure to also add it as a dependency in your mod metadata files (e.g. fabric.mod.json), and when uploading files to CurseForge. See Releasing your Mod for detailed information.

Utilizing Soft Dependencies safely

In most cases, you want other mods to be supported as soft dependencies only, i.e. your mod should still be able to run and function even if the third party mod is not installed. In order to ensure that, you must only load those mods' classes if the mod is actually present.

Balm offers a helper for this:

Balm.initializeIfLoaded("othermodid", "com.example.yourmod.compat.OtherModIntegration");

When the other mod is loaded, this method will construct an instance of your OtherModIntegration class. Make sure it has a public no-arg constructor!

In that class, you can import packages and access classes from the third party mod safely, as long as you don't have any other references to OtherModIntegration anywhere in your code.