Environment Setup

This page prepares a workspace for SoulFire plugin development. The finished workspace can build and debug a plugin and show the current API.

Recommended stack

Java 25: SoulFire currently builds and generates Javadocs with JDK 25.
Gradle Wrapper: use the wrapper from your plugin project and from the SoulFire source checkout.
IntelliJ IDEA: recommended for Fabric Loom, Mixins, Lombok, and large Java source navigation.
A local SoulFire checkout: use it as the real reference, even if your plugin lives in a separate repository.

Keep these references open

Fabric Documentation for the underlying modding toolchain
Fabric wiki: Access wideners if you need widened visibility later
SpongePowered Mixin wiki if you end up debugging low-level injection behavior

SoulFire's current build logic and aggregated Javadocs both target Java 25. An older JDK can cause build and toolchain errors.

Clone the repos you need

Clone these repositories into the same parent directory:

git clone https://github.com/soulfiremc-com/SoulFire.git
git clone https://github.com/soulfiremc-com/SoulFirePluginExample.git

Use:

SoulFire as the source of truth for current internals, built-in plugins, settings, gRPC services, and proto contracts
SoulFirePluginExample as the starting template for new plugins

Use the template for project structure. Use the SoulFire repository and Javadocs for current API behavior.

Recommended IntelliJ setup

If you use IntelliJ IDEA:

open the plugin project as a Gradle project
let Loom finish dependency setup before judging the project state
install Lombok support if IntelliJ prompts you
if you also open the SoulFire repo, import its inspection profile from config/intellij_inspections.xml

You do not need to open the whole SoulFire repo as a second module in the same project, but it is often useful.

What to inspect in the SoulFire source tree

Source location	Why it matters
`mod/src/main/java/com/soulfiremc/server/api`	Public plugin API classes such as `SoulFireAPI`, `Plugin`, and event types
`mod/src/main/java/com/soulfiremc/server/settings`	Typed settings model, property classes, and settings page registration
`mod/src/main/java/com/soulfiremc/server/bot`	`BotConnection`, `ControlState`, and `ControllingTask`
`mod/src/main/java/com/soulfiremc/server/plugins`	Built-in plugins that show real patterns used by the project
`mod/src/main/java/com/soulfiremc/server/grpc`	How GUI and CLI actions are translated into in-process bot operations
`proto/src/main/proto/soulfire`	The wire contracts for server info, instance info, bot control, scripting, and more

Keep versions aligned

Keep the plugin and SoulFire versions aligned.

Match your plugin dependency version to the SoulFire version you actually run.
Read the current CodeMC Maven metadata before you select a version.
Use the example plugin as a starting template.
Use the current Javadocs for low-level API details.

The current example repository pins an older SoulFire version than the latest CodeMC metadata. Before you copy low-level code, compare it with the current Javadocs and source.

When another IDE is acceptable

Other IDEs can work if they handle:

Gradle Kotlin DSL
annotation processing
Loom and Fabric dependency resolution
large Java projects with generated sources

IntelliJ is still the easiest path when you start debugging Mixins or browsing Minecraft and SoulFire source at the same time.