Architecture And Protocols

Read this page after you load your first plugin. It explains how a UI or RPC request becomes bot behavior.

Runtime layers

SoulFire has these runtime layers:

1. Bootstrap and launcher prepare startup, properties, and mixin loading.
2. Fabric loads SoulFire itself as a mod and also loads your external plugin jar as another Fabric mod.
3. SoulFireServer manages the global server process, settings, auth, RPC server, and instances.
4. InstanceManager manages one separate group of settings, accounts, proxies, metrics, and automation.
5. BotStateManager persists each bot's desired state and reconciles connection attempts.
6. BotConnection owns one bot's headless Minecraft client copy plus settings, metadata, scheduler, and control state.
7. Plugins listen to events, register settings pages, and optionally use Mixins for deeper integration.

For plugin authors, the important points are:

• Fabric loads both SoulFire and your plugin jar
• SoulFire exposes higher-level hooks through events, settings, metadata, and control APIs
• the GUI and CLI are thin clients over structured gRPC and proto definitions
• when you need to go lower, you are following the same path SoulFire itself follows

Internal plugins versus external plugins

SoulFire has two plugin loading models:

• internal plugins are scanned from com.soulfiremc.server.plugins using @InternalPluginClass
• external plugins are ordinary Fabric mods that call SoulFireAPI.registerServerExtension(...) from a ModInitializer

The built-in plugin directory contains useful examples. Internal and external plugins use the same event, settings, metadata, and control APIs.

The core objects

Settings and UI protocol

The GUI and CLI do not hardcode plugin pages. Instead, SoulFire exports structured definitions over gRPC:

• server.proto exposes server config, setting definitions, pages, and plugins
• instance.proto exposes instance config, setting definitions, pages, and plugins
• common.proto defines SettingsDefinition, SettingsPage, SettingsNamespace, and ServerPlugin

After registration, your settings page appears in the GUI and CLI.

Bot action protocol

SoulFire's internal action protocol for live bot control is described in bot.proto. That service includes:

• per-bot desired state, restart, and status streaming
• movement state updates
• rotation updates
• hotbar selection
• inventory clicks and container button clicks
• world mouse clicks
• container text input
• POV rendering
• dialog retrieval and interaction

The important implementation detail is what happens after the RPC call arrives:

1. the request is resolved to an online BotConnection
2. permissions are checked
3. SoulFire schedules a low-level operation through BotControlAPI or direct player and gameMode access
4. control state or staged tasks drive the actual Minecraft-side behavior

Plugins follow the same process.

How low-level actions reach Minecraft

The typical path is:

GUI or CLI action -> gRPC/proto request -> service implementation -> BotConnection -> ControlState or ControllingTask -> Minecraft classes or mixin hook

Examples from the current implementation:

• movement RPCs write to ControlState
• rotation, hotbar, inventory, mouse, and dialog actions typically use ControllingTask.singleTick(...)
• multi-step automation uses staged controlling tasks
• input booleans become real player movement through SoulFire's keyboard input mixin

Script protocol

The visual scripting system is a separate higher-level automation layer. Its wire model lives in script.proto and describes:

• edge types
• port types
• type descriptors
• node definitions
• script graphs and execution metadata

If scripting supports your use case, use scripting. Plugin development is what you use when you need lower-level access than the script graph model exposes.

Why Mixins appear in the architecture

SoulFire is built on Fabric and real Minecraft client code. That means some of its own public hooks are created by Mixins:

• packet pre-send and pre-receive events
• chat receive event
• bot pre-tick and post-tick events
• client brand and client settings overrides
• control-state-driven input

So when you write a plugin Mixin, you are not leaving the architecture. You are using the same extension mechanism SoulFire itself uses for its lowest-level integrations.

Best places to trace behavior

• SoulFire source root
• gRPC service implementations
• Proto definitions
• Built-in plugins
• Javadocs package index

Next steps

• Developer Resources
• Bot Control And Direct Access