# kolief/solace architecture

> Architecture diagram of the GitHub repository kolief/solace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kolief/solace
- Repository: https://github.com/kolief/solace

## Overview

#### Purpose and Runtime Entry Points
Solace is a Java/Gradle desktop client built atop a pinned RuneLite version, providing automation-oriented APIs, an SDK, bundled plugins, and loadable external PF4J plugins. Production starts from `client/loader/src/main/java/net/solace/loader/SolaceLauncher.java` (packaged as a fat JAR); development uses `SolaceLoaderDev.java`. `SolaceInitializer.java` wires client services during RuneLite startup.

#### Module Boundaries
The public automation contract is `api/src/main/java/net/solace/api/Solace.java`, with interfaces for game state, entities, items, movement, widgets, interaction, events, and plugins. Concrete RuneLite-backed implementations live separately in `client/bindings/src/main/java/net/solace/impl/`, rooted by `ApiModule.java`. This interface/implementation boundary isolates scripts and plugins from RuneLite internals and version-specific reflection.

#### Client Bootstrap and Service Composition
The loader initializes shared state and dependency modules, then integrates interaction, external-plugin, UI, and event facilities:
- `client/loader/src/main/java/net/solace/loader/SolaceLoader.java`
- `client/loader/src/main/java/net/solace/loader/modules/LoaderModule.java`
- `client/loader/src/main/java/net/solace/loader/modules/InteractionModule.java`
- `client/loader/src/main/java/net/solace/loader/events/EventManager.java`

Control flow is launcher → loader/initializer → dependency injection/modules → RuneLite client and plugin managers. Shared local directories and loader state are represented in `common/src/main/java/net/solace/loader/Directories.java` and `SolaceManager.java`.

#### Game Observation and Automation
Bindings wrap RuneLite actors, tiles, items, widgets, and game state, while API providers and queries expose filtered script-facing views. Representative paths:
- `api/src/main/java/net/solace/api/query/Query.java`
- `api/src/main/java/net/solace/api/interact/Automation.java`
- `client/bindings/src/main/java/net/solace/impl/domain/game/ClientImpl.java`

An interaction request is built for an actor/item/tile/widget, queued through the loader interaction manager, executed as automated menu/mouse activity, and surfaced through pre/post automation events. Mouse execution is configurable via `MouseManager.java` and movement strategies under `api/.../interact/mouse/`.

#### Movement and World Data
Movement combines local collision, global collision maps, teleports, and transports to produce walking behavior:
- `client/bindings/src/main/java/net/solace/impl/movement/pathfinder/Pathfinder.java`
- `client/bindings/src/main/java/net/solace/impl/movement/WalkerManager.java`
- `api/src/main/java/net/solace/api/movement/pathfinder/GlobalCollisionMap.java`

Offline cache tooling generates collision-map data from the RuneScape cache in `data/cache-tools/src/main/java/net/solace/rscache/map/MapGenerator.java`; generated artifacts are consumed by the `data/collision-maps` module. Teleport/transport decisions are constrained by item, quest, skill, variable, and charge requirements.

#### Plugin Ecosystem and UI
Built-in automation plugins are compiled in `plugins/bundled`, using looped/task plugin abstractions from `api/.../plugins`; loader-side managers schedule and isolate their execution:
- `client/loader/src/main/java/net/solace/loader/plugins/PluginManagerImpl.java`
- `client/loader/src/main/java/net/solace/loader/plugins/DefaultLoopedPluginExecutor.java`
- `plugins/bundled/src/main/java/net/solace/loader/plugins/fighter/SolaceFighterPlugin.java`

External JARs from `~/.solace/plugins/` are discovered and loaded through PF4J-based SDN support in `plugins/hub/src/main/java/net/solace/sdn/pf4j/SdnPf4jPluginManager.java`. Swing-based configuration, profile, plugin-list, loadout, and external-plugin panels are provided by the `ui` module, notably `ui/src/main/java/net/solace/ui/module/UiModule.java`.

#### SDK and Version-Mapping Infrastructure
`SDK` offers ergonomic static façades over API services for third-party script authors, e.g. `sdk/src/main/java/net/solace/sdk/game/Client.java` and `sdk/src/main/java/net/solace/sdk/movement/Walker.java`. RuneLite updates require canonical/version mappings, generated and applied through `mappings/generator/.../MappingGenerator.java` and `mappings/tool/.../GenerateVersionPackage.java`; these mappings are a critical compatibility boundary between Solace bindings and obfuscated RuneLite code.

Main entry points: [`client/loader/src/main/java/net/solace/loader/SolaceLoader.java`](https://github.com/kolief/solace/blob/master/client/loader/src/main/java/net/solace/loader/SolaceLoader.java) (Loader and initializer), [`client/bindings/src/main/java/net/solace/impl/ApiModule.java`](https://github.com/kolief/solace/blob/master/client/bindings/src/main/java/net/solace/impl/ApiModule.java) (RuneLite bindings), [`api/src/main/java/net/solace/api/Solace.java`](https://github.com/kolief/solace/blob/master/api/src/main/java/net/solace/api/Solace.java) (Public Solace API), [`client/loader/src/main/java/net/solace/loader/plugins/PluginManagerImpl.java`](https://github.com/kolief/solace/blob/master/client/loader/src/main/java/net/solace/loader/plugins/PluginManagerImpl.java) (Bundled plugin manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Client Runtime"]
  node_launcher["Solace launcher<br/>fat-JAR entry point"]
  node_loader["Loader and initializer<br/>bootstrap<br/>[SolaceLoader.java]"]
  node_loader_module["Loader module<br/>DI module<br/>[LoaderModule.java]"]
  node_interaction_module["Interaction module<br/>DI module"]
  node_shared_state["Directories and manager<br/>shared state"]
  node_runelite{{"Pinned RuneLite client<br/>upstream client runtime"}}
  node_events["Automation events<br/>event manager<br/>[EventManager.java]"]
end

subgraph group_automation["Automation API"]
  node_api["Public Solace API<br/>automation contract<br/>[Solace.java]"]
  node_queries["Queries<br/>API query layer<br/>[Query.java]"]
  node_bindings["RuneLite bindings<br/>API implementations<br/>[ApiModule.java]"]
  node_game_client["Game client binding<br/>game-state adapter<br/>[ClientImpl.java]"]
  node_automation["Automation requests<br/>interaction API<br/>[Automation.java]"]
  node_sdk["SDK façades<br/>script author SDK<br/>[Client.java]"]
end

subgraph group_movement["Movement Data"]
  node_pathfinder["Pathfinder and walker<br/>movement engine<br/>[Pathfinder.java]"]
  node_collision_data[("Collision maps<br/>world-data artifact")]
  node_map_generator["Map generator<br/>offline cache tooling<br/>[MapGenerator.java]"]
end

subgraph group_plugins["Plugin Ecosystem"]
  node_plugin_manager["Bundled plugin manager<br/>plugin scheduler"]
  node_bundled_plugins["Bundled plugins<br/>automation plugins"]
  node_external_plugins["PF4J external plugins<br/>plugin loader"]
  node_ui["Swing UI<br/>configuration panels<br/>[UiModule.java]"]
end

subgraph group_compatibility["Compatibility Tooling"]
  node_mappings["Version mappings<br/>compatibility generator"]
end

node_launcher -->|"starts"| node_loader
node_loader -->|"installs"| node_loader_module
node_loader -->|"installs"| node_interaction_module
node_loader -->|"initializes"| node_shared_state
node_loader -->|"integrates with"| node_runelite
node_loader_module -->|"composes"| node_bindings
node_bindings -->|"implements"| node_api
node_game_client -->|"wraps"| node_runelite
node_bindings -->|"includes"| node_game_client
node_queries -->|"extends"| node_api
node_sdk -->|"facades over"| node_api
node_automation -->|"queues actions through"| node_interaction_module
node_interaction_module -->|"emits"| node_events
node_pathfinder -->|"uses"| node_collision_data
node_map_generator -->|"generates"| node_collision_data
node_bindings -->|"provides movement"| node_pathfinder
node_plugin_manager -->|"schedules"| node_bundled_plugins
node_bundled_plugins -->|"automates through"| node_api
node_external_plugins -->|"loads into"| node_plugin_manager
node_ui -->|"manages"| node_external_plugins
node_mappings -.->|"maintains compatibility for"| node_bindings
node_plugin_manager -->|"coordinates plugins with"| node_runelite

click node_launcher "https://github.com/kolief/solace/blob/master/client/loader/src/main/java/net/solace/loader/SolaceLauncher.java"
click node_loader "https://github.com/kolief/solace/blob/master/client/loader/src/main/java/net/solace/loader/SolaceLoader.java"
click node_loader_module "https://github.com/kolief/solace/blob/master/client/loader/src/main/java/net/solace/loader/modules/LoaderModule.java"
click node_interaction_module "https://github.com/kolief/solace/blob/master/client/loader/src/main/java/net/solace/loader/modules/InteractionModule.java"
click node_api "https://github.com/kolief/solace/blob/master/api/src/main/java/net/solace/api/Solace.java"
click node_queries "https://github.com/kolief/solace/blob/master/api/src/main/java/net/solace/api/query/Query.java"
click node_bindings "https://github.com/kolief/solace/blob/master/client/bindings/src/main/java/net/solace/impl/ApiModule.java"
click node_game_client "https://github.com/kolief/solace/blob/master/client/bindings/src/main/java/net/solace/impl/domain/game/ClientImpl.java"
click node_automation "https://github.com/kolief/solace/blob/master/api/src/main/java/net/solace/api/interact/Automation.java"
click node_events "https://github.com/kolief/solace/blob/master/client/loader/src/main/java/net/solace/loader/events/EventManager.java"
click node_pathfinder "https://github.com/kolief/solace/blob/master/client/bindings/src/main/java/net/solace/impl/movement/pathfinder/Pathfinder.java"
click node_collision_data "https://github.com/kolief/solace/blob/master/api/src/main/java/net/solace/api/movement/pathfinder/GlobalCollisionMap.java"
click node_map_generator "https://github.com/kolief/solace/blob/master/data/cache-tools/src/main/java/net/solace/rscache/map/MapGenerator.java"
click node_plugin_manager "https://github.com/kolief/solace/blob/master/client/loader/src/main/java/net/solace/loader/plugins/PluginManagerImpl.java"
click node_bundled_plugins "https://github.com/kolief/solace/blob/master/plugins/bundled/src/main/java/net/solace/loader/plugins/fighter/SolaceFighterPlugin.java"
click node_external_plugins "https://github.com/kolief/solace/blob/master/plugins/hub/src/main/java/net/solace/sdn/pf4j/SdnPf4jPluginManager.java"
click node_ui "https://github.com/kolief/solace/blob/master/ui/src/main/java/net/solace/ui/module/UiModule.java"
click node_sdk "https://github.com/kolief/solace/blob/master/sdk/src/main/java/net/solace/sdk/game/Client.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_launcher,node_loader,node_loader_module,node_interaction_module,node_shared_state,node_runelite,node_events toneBlue
class node_api,node_queries,node_bindings,node_game_client,node_automation,node_sdk toneAmber
class node_pathfinder,node_collision_data,node_map_generator toneMint
class node_plugin_manager,node_bundled_plugins,node_external_plugins,node_ui toneRose
class node_mappings toneIndigo
```

## Components

### Client Runtime

- [Solace launcher](https://github.com/kolief/solace/blob/master/client/loader/src/main/java/net/solace/loader/SolaceLauncher.java): fat-JAR entry point · Production startup entry point. · `client/loader/src/main/java/net/solace/loader/SolaceLauncher.java`
- [Loader and initializer](https://github.com/kolief/solace/blob/master/client/loader/src/main/java/net/solace/loader/SolaceLoader.java): bootstrap · Wires Solace into RuneLite startup. · `client/loader/src/main/java/net/solace/loader/SolaceLoader.java`
- [Loader module](https://github.com/kolief/solace/blob/master/client/loader/src/main/java/net/solace/loader/modules/LoaderModule.java): DI module · `client/loader/src/main/java/net/solace/loader/modules/LoaderModule.java`
- [Interaction module](https://github.com/kolief/solace/blob/master/client/loader/src/main/java/net/solace/loader/modules/InteractionModule.java): DI module · `client/loader/src/main/java/net/solace/loader/modules/InteractionModule.java`
- **Directories and manager**: shared state · Owns local directories and loader state.
- **Pinned RuneLite client**: upstream client runtime · Provides client and native plugin managers.
- [Automation events](https://github.com/kolief/solace/blob/master/client/loader/src/main/java/net/solace/loader/events/EventManager.java): event manager · Publishes pre/post automation events. · `client/loader/src/main/java/net/solace/loader/events/EventManager.java`

### Automation API

- [Public Solace API](https://github.com/kolief/solace/blob/master/api/src/main/java/net/solace/api/Solace.java): automation contract · Stable script and plugin interfaces over game facilities. · `api/src/main/java/net/solace/api/Solace.java`
- [Queries](https://github.com/kolief/solace/blob/master/api/src/main/java/net/solace/api/query/Query.java): API query layer · Provides filtered script-facing game views. · `api/src/main/java/net/solace/api/query/Query.java`
- [RuneLite bindings](https://github.com/kolief/solace/blob/master/client/bindings/src/main/java/net/solace/impl/ApiModule.java): API implementations · Version-isolating implementations of API interfaces. · `client/bindings/src/main/java/net/solace/impl/ApiModule.java`
- [Game client binding](https://github.com/kolief/solace/blob/master/client/bindings/src/main/java/net/solace/impl/domain/game/ClientImpl.java): game-state adapter · `client/bindings/src/main/java/net/solace/impl/domain/game/ClientImpl.java`
- [Automation requests](https://github.com/kolief/solace/blob/master/api/src/main/java/net/solace/api/interact/Automation.java): interaction API · Builds actor, item, tile, and widget actions. · `api/src/main/java/net/solace/api/interact/Automation.java`
- [SDK façades](https://github.com/kolief/solace/blob/master/sdk/src/main/java/net/solace/sdk/game/Client.java): script author SDK · Ergonomic static access to API services. · `sdk/src/main/java/net/solace/sdk/game/Client.java`

### Movement Data

- [Pathfinder and walker](https://github.com/kolief/solace/blob/master/client/bindings/src/main/java/net/solace/impl/movement/pathfinder/Pathfinder.java): movement engine · Combines collision, teleports, and transports into walking behavior. · `client/bindings/src/main/java/net/solace/impl/movement/pathfinder/Pathfinder.java`
- [Collision maps](https://github.com/kolief/solace/blob/master/api/src/main/java/net/solace/api/movement/pathfinder/GlobalCollisionMap.java): world-data artifact · Global collision data consumed by pathfinding. · `api/src/main/java/net/solace/api/movement/pathfinder/GlobalCollisionMap.java`
- [Map generator](https://github.com/kolief/solace/blob/master/data/cache-tools/src/main/java/net/solace/rscache/map/MapGenerator.java): offline cache tooling · Generates collision data from the RuneScape cache. · `data/cache-tools/src/main/java/net/solace/rscache/map/MapGenerator.java`

### Plugin Ecosystem

- [Bundled plugin manager](https://github.com/kolief/solace/blob/master/client/loader/src/main/java/net/solace/loader/plugins/PluginManagerImpl.java): plugin scheduler · Schedules and isolates built-in automation plugins. · `client/loader/src/main/java/net/solace/loader/plugins/PluginManagerImpl.java`
- [Bundled plugins](https://github.com/kolief/solace/blob/master/plugins/bundled/src/main/java/net/solace/loader/plugins/fighter/SolaceFighterPlugin.java): automation plugins · `plugins/bundled/src/main/java/net/solace/loader/plugins/fighter/SolaceFighterPlugin.java`
- [PF4J external plugins](https://github.com/kolief/solace/blob/master/plugins/hub/src/main/java/net/solace/sdn/pf4j/SdnPf4jPluginManager.java): plugin loader · Discovers external JARs from ~/.solace/plugins/. · `plugins/hub/src/main/java/net/solace/sdn/pf4j/SdnPf4jPluginManager.java`
- [Swing UI](https://github.com/kolief/solace/blob/master/ui/src/main/java/net/solace/ui/module/UiModule.java): configuration panels · Provides profiles, plugin lists, loadouts, and external-plugin panels. · `ui/src/main/java/net/solace/ui/module/UiModule.java`

### Compatibility Tooling

- **Version mappings**: compatibility generator · Maintains bindings against obfuscated RuneLite versions.

## Connections

- Solace launcher → Loader and initializer: starts
- Loader and initializer → Loader module: installs
- Loader and initializer → Interaction module: installs
- Loader and initializer → Directories and manager: initializes
- Loader and initializer → Pinned RuneLite client: integrates with
- Loader module → RuneLite bindings: composes
- RuneLite bindings → Public Solace API: implements
- Game client binding → Pinned RuneLite client: wraps
- RuneLite bindings → Game client binding: includes
- Queries → Public Solace API: extends
- SDK façades → Public Solace API: facades over
- Automation requests → Interaction module: queues actions through
- Interaction module → Automation events: emits
- Pathfinder and walker → Collision maps: uses
- Map generator → Collision maps: generates
- RuneLite bindings → Pathfinder and walker: provides movement
- Bundled plugin manager → Bundled plugins: schedules
- Bundled plugins → Public Solace API: automates through
- PF4J external plugins → Bundled plugin manager: loads into
- Swing UI → PF4J external plugins: manages
- Version mappings → RuneLite bindings: maintains compatibility for
- Bundled plugin manager → Pinned RuneLite client: coordinates plugins with