Build Your First Plugin

This guide takes the shortest path to a real plugin. It uses the official template instead of starting from an empty Fabric project, because the template already includes the SoulFire-specific wiring.

Before you start

• Install Java 25.
• Install Git.
• Use IntelliJ IDEA if possible. It is the least painful option for Fabric Loom, Mixins, and Java plugin work.
• Have a working SoulFire install where you can test jars in minecraft/mods.

Create the project

git clone https://github.com/AlexProgrammerDE/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.

Verify that it loaded

Use the built-in plugin inspection tools:

• open the instance UI and check 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, check the startup logs first. Fabric loading problems, missing dependencies, and bad mixin config usually fail before SoulFire ever sees your ExternalPlugin.

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