Build Your First Plugin

This guide builds a plugin that SoulFire can load. The official template already contains the required Fabric, Loom, and SoulFire setup.

If you are new to Fabric itself, keep Fabric Documentation open too.

Before you start

• Install Java 25.
• Install Git.
• Use IntelliJ IDEA for Fabric Loom, Mixins, and Java plugin work.
• Have a working SoulFire install where you can test jars in minecraft/mods.

Success criteria

At the end of this guide, you will have:

• a plugin project cloned from the template
• a ModInitializer that registers your ExternalPlugin
• a built jar in build/libs
• a jar that loads from SoulFire's minecraft/mods directory

Create the project

git clone https://github.com/soulfiremc-com/SoulFirePluginExample.git my-soulfire-plugin
cd my-soulfire-plugin

package com.example.myplugin;

import com.soulfiremc.server.api.SoulFireAPI;
import net.fabricmc.api.ModInitializer;

public final class Main implements ModInitializer {
  @Override
  public void onInitialize() {
    SoulFireAPI.registerServerExtension(new MyPlugin());
  }
}

package com.example.myplugin;

import com.soulfiremc.server.api.ExternalPlugin;
import com.soulfiremc.server.api.PluginInfo;
import com.soulfiremc.server.api.event.bot.BotConnectionInitEvent;
import lombok.extern.slf4j.Slf4j;
import net.lenni0451.lambdaevents.EventHandler;

@Slf4j
public final class MyPlugin extends ExternalPlugin {
  public MyPlugin() {
    super(new PluginInfo(
      "my-plugin",
      "1.0.0",
      "Example SoulFire plugin",
      "YourName",
      "MIT",
      "https://example.com"
    ));
  }

  @EventHandler
  public void onBotInit(BotConnectionInitEvent event) {
    log.info("Bot {} was initialized", event.connection().accountName());
  }
}

./gradlew build

Add settings and a plugin page

The official example plugin shows the standard pattern:

1. create a SettingsObject class with public static final properties
2. listen for InstanceSettingsRegistryInitEvent
3. call event.settingsPageRegistry().addPluginPage(...)
4. read values through connection.settingsSource()

That makes your settings appear in the GUI, CLI, and exported instance metadata automatically.

Make sure that the plugin loaded

Use the built-in plugin inspection tools:

• open the instance UI and view Plugins
• run plugins in the terminal
• run print-docs plugins if you want the current built-in plugin documentation output

If the mod failed before registration, read the startup logs first. Fabric loading problems, missing dependencies, and bad mixin config usually fail before SoulFire ever sees your ExternalPlugin.

If Fabric itself is complaining, go back to:

• Gradle And Project Layout
• Fabric Documentation

What to do next

• Environment Setup to align your IDE and source checkout
• Gradle And Project Layout for the important build files
• Event System to choose the right hook
• Mixins And Access Wideners if events are not enough