Development
Build a plugin when visual scripting cannot provide the Minecraft or SoulFire access that you need.
Use plugins when visual scripting cannot provide the control that you need. Plugins can add low-level hooks, Mixins, packet handling, settings pages, and direct access to Minecraft objects.
SoulFire plugins can access internal code. A SoulFire update can break integrations that use this access. 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
Read in this order
For your first plugin, read these pages in order:
- Build Your First Plugin to get one jar loading inside SoulFire
- Environment Setup to align Java, IntelliJ, and your local source checkout
- Gradle And Project Layout when you start changing the template
- Event System and Settings And Metadata for normal plugin work
- Bot Control And Direct Access only when you need real runtime objects or controlling tasks
- Mixins And Access Wideners only when the public API is not enough
- Architecture And Protocols when you need to trace how SoulFire wires the internals together
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 server lifecycle and bot events exist.
Settings And Metadata
Define typed settings, add GUI and CLI pages, and store temporary or saved plugin data.
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 is available.
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 SoulFire-specific 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
Fabric and Mixin references
SoulFire plugin development sits on top of Fabric, Loom, and Mixins. These are the external references worth keeping open in another tab:
| Topic | Link |
|---|---|
| Fabric documentation | docs.fabricmc.net |
| Fabric wiki: Mixin injection reference | tutorial:mixin_injects |
| Fabric wiki: Access wideners | tutorial:accesswideners |
| SpongePowered Mixin wiki | github.com/SpongePowered/Mixin/wiki |
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