Gradle And Project Layout

This page explains each build file in the plugin template. SoulFire plugins use a Fabric Loom project with SoulFire dependencies and resources.

Published coordinates

SoulFire publishes plugin dependencies under the com.soulfiremc group:

What	Value
Maven repository	`https://repo.codemc.org/repository/maven-public/`
Main plugin dependency	`com.soulfiremc:mod`
Companion compile-only dependency	`com.soulfiremc:shared`
Release metadata	`https://repo.codemc.org/repository/maven-public/com/soulfiremc/mod/maven-metadata.xml`
Shared metadata	`https://repo.codemc.org/repository/maven-public/com/soulfiremc/shared/maven-metadata.xml`

The public metadata currently exposes a newer release than the version pinned in the template repository. Read the metadata before you select a version, especially for a recent SoulFire build.

External references for this page

Minimal repositories block

These repositories provide the required dependencies:

repositories {
  maven("https://repo.codemc.org/repository/maven-public/")
  maven("https://maven.fabricmc.net")
  maven("https://libraries.minecraft.net")
  mavenCentral()
}

The official template contains additional repositories for transitive dependencies. If you are unsure, copy the complete block from the template.

Minimal dependency shape

The core structure looks like this:

dependencies {
  minecraft("com.mojang:minecraft:<minecraft-version>")
  implementation("net.fabricmc:fabric-loader:<fabric-loader-version>")

  implementation("com.soulfiremc:mod:<soulfire-version>")
  compileOnly("com.soulfiremc:shared:<soulfire-version>")

  compileOnly("org.projectlombok:lombok:<lombok-version>")
  annotationProcessor("org.projectlombok:lombok:<lombok-version>")
}

Use implementation for com.soulfiremc:mod because your plugin uses this API while SoulFire runs. Use compileOnly for shared unless you know you need it packaged differently.

Loom configuration

The example plugin uses this pattern:

loom {
  accessWidenerPath = file("src/main/resources/my-plugin.accesswidener")

  runs {
    removeIf { true }
  }
}

That means:

your plugin can ship an access widener if needed
the template disables Loom run configurations because the plugin is not a standalone game or server

Test the plugin against a real SoulFire install instead of expecting the plugin project itself to boot SoulFire.

SoulFire's current template and runtime use Mixins with compatibilityLevel: "JAVA_21" while the overall project toolchain runs on Java 25. Do not "fix" that blindly. Follow the current template and the current SoulFire runtime you target.

Recommended file layout

File	Purpose
`settings.gradle.kts`	Gradle project identity
`build.gradle.kts`	Loom, repositories, dependencies, and build logic
`gradle/libs.versions.toml`	central place for Minecraft, Fabric Loader, and SoulFire versions
`src/main/resources/fabric.mod.json`	Fabric mod metadata and entrypoint registration
`src/main/resources/<plugin-id>.mixins.json`	Mixin configuration
`src/main/resources/<plugin-id>.accesswidener`	optional access widener
`src/main/java/.../Main.java`	`ModInitializer` entrypoint
`src/main/java/.../MyPlugin.java`	your `ExternalPlugin` implementation

`fabric.mod.json`

At minimum, your metadata file needs:

a unique id
a main entrypoint
a SoulFire dependency entry under depends
your mixin config name if you use Mixins
your access widener name if you use one

The official example uses this dependency block:

"depends": {
  "fabricloader": "*",
  "minecraft": "*",
  "soulfire": "*"
}

That keeps the plugin aligned with the SoulFire runtime instead of hardcoding narrow mod dependency rules.

Build output and installation

Build the jar with:

./gradlew build

Then install the resulting jar into SoulFire's minecraft/mods directory and restart SoulFire.

SoulFire loads your plugin through Fabric, not through a separate SoulFire-specific plugin loader. If the jar is not a valid Fabric mod jar, SoulFire will never reach your ExternalPlugin.

What to copy directly from the template

Copy these without trying to be clever on day one:

the Gradle wrapper
the Loom plugin setup
the version catalog structure
the fabric.mod.json skeleton
the mixin config skeleton
the access widener file name wiring

Once the plugin works, then simplify the build.