Development
Build advanced SoulFire plugins when scripting is not enough and you need low-level access to Minecraft or SoulFire internals.
Use this section when you need to go beyond SoulFire's visual scripting system. Plugin development is the right tool for advanced users who need low-level hooks, Mixins, protocol interception, custom settings pages, direct Minecraft object access, or in-process logic that would be awkward or impossible to model in scripts.
SoulFire plugin development is intentionally close to the real code. That gives you a lot of power, but it also means version upgrades can break low-level integrations. Keep your plugin version, the current Javadocs, and the current SoulFire source tree aligned.
Choose the right tool
Stay in Scripting when:
- you can express the behavior as triggers, actions, conditions, and data flow
- you want a stable, visual workflow that non-developers can edit
- you do not need custom Mixins, packet hooks, or direct Minecraft internals
Move to plugin development when:
- you need custom logic inside the bot tick loop or entity tick loop
- you need new settings pages, custom commands, or plugin-owned state
- you need to inspect, replace, or suppress packets
- you need Fabric mod APIs, Mixins, or access wideners
- you need direct access to
BotConnection,LocalPlayer,ClientPacketListener, or other low-level objects
Development map
Build Your First Plugin
Start from the official template, register an ExternalPlugin, build the jar, and load it into SoulFire.
Environment Setup
Set up Java, Gradle, IntelliJ, and a local source checkout that matches the SoulFire version you target.
Gradle And Project Layout
Configure Loom, Maven repositories, SoulFire dependencies, and the Fabric project files your plugin needs.
Event System
Learn the public event model, how listeners are registered, and which lifecycle, session, and bot events exist.
Settings And Metadata
Define typed settings, expose pages to the GUI and CLI, and store transient or persistent plugin state.
Bot Control And Direct Access
Use ControlState, ControllingTask, and direct BotConnection access when you need real in-process control.
Mixins And Access Wideners
Inject into Minecraft or SoulFire code when no stable event or API surface exists yet.
Architecture And Protocols
Understand how the launcher, server, instances, bots, settings, gRPC services, and script runtime fit together.
Developer Resources
Jump straight to the official Javadocs, Maven coordinates, source trees, built-in plugins, and proto definitions.
Canonical sources
Use these as your source of truth when writing or updating a plugin:
- SoulFire source repository
- SoulFirePluginExample template
- Official SoulFire Javadocs
- Built-in plugin sources
- Proto definitions for server, instance, bot, and scripting APIs
Related pages
- Plugins for the high-level Fabric-based model
- Install Plugins for loading a built jar into SoulFire
- Built-in Plugins for the currently shipped plugin list
- Scripting if your use case can stay in the visual editor
How is this page?
Last updated on