# openrune/openrune-server architecture

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

- Interactive diagram: https://gitdiagram.com/openrune/openrune-server
- Repository: https://github.com/openrune/openrune-server

## Overview

This repository is a modular Kotlin/JVM OSRS game-server platform built around a core server runtime plus separate content, cache, API, and tooling modules.

High-level shape:
- `game-server` is the runtime engine.
- `game-api` is the shared contract layer used by content plugins and server subsystems.
- `game-plugins` and `content` are gameplay/content modules loaded by the server.
- `cache` and `data` hold cache codecs, generated definitions, and server-side game data tooling.
- `ksp-processor` generates code used by plugin/content authoring.
- `util` provides shared low-level utilities.
- `http-api` is a separate Vue frontend for web-facing APIs.
- The repo is built as a Gradle multi-module project and targets Java 17/Kotlin.

Core server architecture

`game-server` is the central executable. It contains:
- Startup and environment entrypoints: `Launcher`, `Server`, `GameContext`, `DevContext`.
- System orchestration: `ServerSystem`, service abstractions, and background `GameTask`s.
- Networking and protocol integration through `rsprot` and message handlers.
- World simulation and state model.
- Login, saving, and persistence.
- Plugin/event dispatch.
- UI/interface rendering and client-script plumbing.

The server follows a classic event-driven MMO architecture:
1. A client connects using OSRS-compatible protocol handling.
2. Packets are decoded into internal message/event objects.
3. Message handlers translate client input into game events or actions.
4. The world state is advanced by periodic cycle tasks.
5. Plugins and mechanics subscribe to these events to implement gameplay.
6. State changes propagate back to the client through interface updates, entity updates, and region changes.
7. Player state is persisted through the saving layer.

Main server subsystems

1. Network and protocol boundary
- `game-server/rsprot` contains the bridge to the OSRS protocol layer and JS5/cache providers.
- Message handlers under `game-server/message/handler` cover all client interactions: movement, NPC/object/player clicks, dialogs, chat, UI button actions, teleports, camera/input events, and anti-tamper signals.
- This is the main inbound boundary from the client into the server.

2. World simulation
- `game-server/model` contains the canonical game state types: `World`, `Region`, `Chunk`, `Tile`, entities, inventories, items, skills, combat, timers, attributes, containers, movement, instances, interfaces, shops, and social state.
- Entity types include `Player`, `Npc`, `GameObject`, `GroundItem`, `Projectile`, `DynamicObject`, and their supporting state.
- Region and chunk modules support map loading, synchronization, and instanced content.

3. Game loop and scheduling
- `game-server/task` defines per-tick and batch tasks such as player cycles, NPC cycles, synchronization, chunk creation, message handling, queue handling, and world cleanup.
- `game-server/model/queue`, `timer`, and `movement` support deferred and time-based gameplay behavior.
- This subsystem is what advances the simulated world independently of client input.

4. Event and plugin runtime
- The newer plugin/event system lives in `game-server/pluginnew`.
- `PluginManager`, `EventManager`, and `GameEvent`/`EventListener` define the runtime dispatch model.
- Event types include login, dialogue, interface open/close, button clicks, item/NPC/object interactions, teleport events, world tick, timers, and movement-related events.
- There is also an older plugin abstraction in `game-server/plugin`; both coexist, but the repo’s content modules are clearly structured around event-driven plugins.

5. Persistence and account loading
- `game-server/saving` handles loading and saving player state.
- It supports multiple formats through `formats/impl`, including JSON and Mongo-backed persistence.
- Serializers cover appearance, attributes, containers, skills, timers, varps, and other player details.
- Login is separated into `LoginService`, `LoginWorker`, and request/result models, which keeps authentication/loading distinct from the main tick loop.

6. Service layer
- `game-server/service` contains reusable runtime services:
  - login
  - RSA / encryption-related logic
  - XTEA key service
  - world verification
  - logging
  - game metadata services such as item/object definitions and animation data
- These services sit between network/persistence/data and the simulation layer.

7. UI and client-facing interface model
- `game-server/ui` and `game-server/model/interf` represent gameframe, interface sets, sub-interface types, and interface listeners.
- `game-server/ui/collection` maps component events, targets, and translations.
- This is the server-side boundary for driving the client UI and reacting to client UI interactions.

Content and gameplay modules

The repo splits gameplay logic into feature-oriented modules rather than keeping it in the core server.

`game-plugins`
- Contains generalized gameplay systems and many reusable mechanics.
- Major areas:
  - combat system, combat formulas, strategies, attack tab, special attacks, ranged ammo/weapon definitions
  - commands for admins/developers/players
  - magic spells and teleports
  - mechanics such as aggro, multiway combat, random walking, poison, prayer, skull removal, starter kit
  - NPC-specific plugins such as cow and Barrows bosses, plus KBD content
  - a market value service under `service/marketvalue`
- This module looks like the reusable gameplay rule layer for broad OSRS mechanics.

`content`
- Contains more world/content-specific plugins, especially Lumbridge-area NPCs/objects/spawns, shops, skills, items, quests, interfaces, and mechanics.
- Major groups:
  - area plugins for Lumbridge NPCs, objects, and spawns
  - interface logic for gameframe, bank, equipment, journal, logout, settings, skill guides
  - item interactions such as consumables, prayer scrolls, rock cake, elemental shields, essence pouches, teleport tabs
  - mechanics like run energy and shops
  - NPC/object interaction plugins such as banker, bank booth, ladder, crates, bookcase, hay, ditch
  - skill implementations for firemaking, herblore, mining, prayer, runecrafting, smithing, woodcutting
  - quest framework and quests
- This module appears to be the “game content pack” loaded into the same plugin/event runtime as `game-plugins`.

Shared developer-facing API

`game-api`
- Provides the types and extensions that content authors depend on.
- Includes:
  - shared enums and protocol-facing abstractions such as `Skills`, `Spellbook`, `WeaponType`, `PrayerIcon`, `GameframeTab`
  - DSLs for loot tables, instanced maps, and NPC combat
  - extension functions for containers, items, interfaces, world, players, NPCs, tiles, and plugins
- This module is the boundary that keeps plugin code decoupled from core server internals.

Code generation and compile-time tooling

`ksp-processor`
- Kotlin Symbol Processing is used to generate content/plugin boilerplate.
- There are processors for:
  - dialogue generation
  - plugin settings generation
- This reduces repetitive manual wiring for content authors and indicates that a lot of the plugin metadata is defined declaratively.

Cache and game data pipeline

`cache`
- Handles cache decoding, server cache management, and packaging of OSRS-derived config data.
- Key responsibilities:
  - codecs for items, NPCs, objects, inventories, sequences, and health bars
  - tools for minifying cache data and packing OSRS config
  - helpers for enums, var types, game values, and tables
  - game-specific data extraction and transformation utilities
- The `data` directory holds the runtime inputs and generated outputs:
  - raw cache dumps
  - CSV/JSON/TOML/RSCM configuration files
  - item overrides, NPC/object lists, world config, gates/doors, music, spawns, and gamevals
- This forms the offline data-preparation pipeline that feeds the server’s metadata/services layer.

Other supporting modules

`util`
- Shared low-level utilities used across the project, including buffer, bit manipulation, naming, concurrency, and server property helpers.

`http-api`
- A Vue-based frontend, separate from the game runtime.
- It likely serves web-facing API/administration or player-related views rather than in-game simulation.
- From an architecture perspective, it is an external presentation layer around server data, not part of the live game loop.

Important data flows

1. Client interaction flow
- OSRS client connects to `game-server`.
- Protocol packets are handled by `message/handler`.
- These become plugin events or direct action invocations.
- Gameplay modules in `content` and `game-plugins` mutate server state.
- State changes are sent back through entity/UI/region update systems.

2. World tick flow
- The server’s cycle tasks advance the simulation.
- NPC/player synchronization, queue handling, and region updates run on schedule.
- Temporary actions and timers are resolved here, not in the network thread.

3. Login and persistence flow
- Login request enters the login service.
- RSA/XTEA and world verification are applied.
- Player state is loaded through the saving layer.
- On logout or save points, serialisation writes back to JSON/Mongo or the configured format.

4. Data/config flow
- Cache and raw data are processed through `cache` tools and generated resources.
- Metadata services in the server consume these definitions for items, objects, animations, and related game values.
- `data/` is the authoritative content/config source for many definitions and overrides.

5. Plugin compilation/runtime flow
- Developers write content against `game-api`.
- KSP processors generate supporting code.
- At runtime, `PluginManager` and `EventManager` route game events to plugin implementations.

Key architectural boundaries to show in a diagram
- External client boundary: OSRS-compatible client/protocol into `game-server`.
- Core engine boundary: simulation, tasks, services, persistence, and event dispatch inside `game-server`.
- Content boundary: `content` and `game-plugins` as independently organized gameplay modules.
- Shared contract boundary: `game-api` between engine and content.
- Offline data boundary: `cache` and `data` feeding metadata and configuration into runtime.
- Tooling boundary: `ksp-processor`, `util`, Docker/Gradle, and the Vue `http-api` frontend.

In short, this is a modular OSRS server stack where the core runtime is intentionally slim and most gameplay is implemented as event-driven plugin modules backed by shared API types and cache-derived metadata.

Main entry points: [`game-server/src/main/kotlin/org/alter/game/system/ServerSystem.kt`](https://github.com/openrune/openrune-server/blob/HEAD/game-server/src/main/kotlin/org/alter/game/system/ServerSystem.kt) (Server system), [`game-server/src/main/kotlin/org/alter/game/pluginnew/PluginManager.kt`](https://github.com/openrune/openrune-server/blob/HEAD/game-server/src/main/kotlin/org/alter/game/pluginnew/PluginManager.kt) (Plugin runtime), [`game-server/src/main/kotlin/org/alter/game/model/World.kt`](https://github.com/openrune/openrune-server/blob/HEAD/game-server/src/main/kotlin/org/alter/game/model/World.kt) (World model), [`game-plugins/src/main/kotlin/org/alter/plugins/content/OSRSPlugin.kt`](https://github.com/openrune/openrune-server/blob/HEAD/game-plugins/src/main/kotlin/org/alter/plugins/content/OSRSPlugin.kt) (Game plugins)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Core runtime"
  launcher(("Launcher<br/>entrypoint<br/>[Launcher.kt]"))
  server_ctx["Contexts<br/>runtime config<br/>[GameContext.kt]"]
  server_system["Server system<br/>orchestration<br/>[ServerSystem.kt]"]
  network_boundary["Protocol bridge<br/>network boundary"]
  message_handlers["Message handlers<br/>inbound handlers<br/>[OpNpcHandler.kt]"]
  world_model[("World model<br/>simulation state<br/>[World.kt]")]
  tasks["Game tasks<br/>tick scheduler<br/>[GameTask.kt]"]
  plugin_runtime["Plugin runtime<br/>event dispatch<br/>[PluginManager.kt]"]
  legacy_plugin["Legacy plugins<br/>plugin API<br/>[Plugin.kt]"]
  persistence[("Saving layer<br/>persistence<br/>[PlayerSaving.kt]")]
  service_layer["Services<br/>[GameService.kt]"]
  ui_layer["UI model<br/>client ui<br/>[UserInterface.kt]"]
end

subgraph "Gameplay content"
  game_plugins["Game plugins<br/>combat/content plugins<br/>[OSRSPlugin.kt]"]
  content_pack["Content pack<br/>world content<br/>[ClientScripts.kt]"]
end

subgraph "Shared contracts"
  game_api["Game API<br/>shared contract<br/>[Skills.kt]"]
  ksp_processor["KSP processor<br/>codegen"]
end

subgraph "Data pipeline"
  cache_pipeline["Cache tools<br/>codec pipeline"]
  game_data["Game data<br/>definitions<br/>[api.yml]"]
end

subgraph "Tooling"
  util_lib["Shared util<br/>utilities"]
end

subgraph "Web frontend"
  http_api["HTTP API UI<br/>vue frontend<br/>[App.vue]"]
end

launcher -->|"bootstraps"| server_ctx
server_ctx -->|"creates"| server_system
server_system -->|"starts"| network_boundary
server_system -->|"ticks"| tasks
network_boundary -->|"decodes"| message_handlers
message_handlers -->|"emits"| plugin_runtime
plugin_runtime -->|"dispatches"| game_plugins
plugin_runtime -->|"dispatches"| content_pack
game_plugins -->|"mutates"| world_model
content_pack -->|"mutates"| world_model
tasks -->|"advances"| world_model
world_model -->|"renders"| ui_layer
service_layer -->|"loads"| persistence
service_layer -->|"consumes"| cache_pipeline
cache_pipeline -->|"feeds"| game_data
game_api -->|"contracts"| game_plugins
game_api -->|"contracts"| content_pack
ksp_processor -.->|"generates"| game_plugins
ksp_processor -.->|"generates"| content_pack
util_lib -->|"supports"| server_system
util_lib -->|"supports"| cache_pipeline
http_api -.->|"queries"| service_layer
legacy_plugin -.->|"coexists"| plugin_runtime

click launcher "https://github.com/openrune/openrune-server/blob/main/game-server/src/main/kotlin/org/alter/game/Launcher.kt"
click server_ctx "https://github.com/openrune/openrune-server/blob/main/game-server/src/main/kotlin/org/alter/game/GameContext.kt"
click server_system "https://github.com/openrune/openrune-server/blob/main/game-server/src/main/kotlin/org/alter/game/system/ServerSystem.kt"
click network_boundary "https://github.com/openrune/openrune-server/blob/main/game-server/src/main/kotlin/org/alter/game/rsprot/NetworkServiceFactory.kt"
click message_handlers "https://github.com/openrune/openrune-server/blob/main/game-server/src/main/kotlin/org/alter/game/message/handler/OpNpcHandler.kt"
click world_model "https://github.com/openrune/openrune-server/blob/main/game-server/src/main/kotlin/org/alter/game/model/World.kt"
click tasks "https://github.com/openrune/openrune-server/blob/main/game-server/src/main/kotlin/org/alter/game/task/GameTask.kt"
click plugin_runtime "https://github.com/openrune/openrune-server/blob/main/game-server/src/main/kotlin/org/alter/game/pluginnew/PluginManager.kt"
click legacy_plugin "https://github.com/openrune/openrune-server/blob/main/game-server/src/main/kotlin/org/alter/game/plugin/Plugin.kt"
click persistence "https://github.com/openrune/openrune-server/blob/main/game-server/src/main/kotlin/org/alter/game/saving/PlayerSaving.kt"
click service_layer "https://github.com/openrune/openrune-server/blob/main/game-server/src/main/kotlin/org/alter/game/service/GameService.kt"
click ui_layer "https://github.com/openrune/openrune-server/blob/main/game-server/src/main/kotlin/org/alter/game/ui/UserInterface.kt"
click game_plugins "https://github.com/openrune/openrune-server/blob/main/game-plugins/src/main/kotlin/org/alter/plugins/content/OSRSPlugin.kt"
click content_pack "https://github.com/openrune/openrune-server/blob/main/content/src/main/kotlin/org/alter/ClientScripts.kt"
click game_api "https://github.com/openrune/openrune-server/blob/main/game-api/src/main/kotlin/org/alter/api/Skills.kt"
click ksp_processor "https://github.com/openrune/openrune-server/blob/main/ksp-processor/src/main/kotlin/org/alter/plugin/dialogue/DialogueGeneratorSymbolProcessor.kt"
click cache_pipeline "https://github.com/openrune/openrune-server/blob/main/cache/src/main/kotlin/dev/openrune/ServerCacheManager.kt"
click game_data "https://github.com/openrune/openrune-server/blob/main/data/api.yml"
click util_lib "https://github.com/openrune/openrune-server/blob/main/util/src/main/kotlin/gg/rsmod/util/ExtensionFunctions.kt"
click http_api "https://github.com/openrune/openrune-server/blob/main/http-api/src/App.vue"

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 launcher,server_ctx,server_system,network_boundary,message_handlers,world_model,tasks,plugin_runtime,legacy_plugin,persistence,service_layer,ui_layer toneBlue
class game_plugins,content_pack toneAmber
class game_api,ksp_processor toneMint
class cache_pipeline,game_data toneRose
class util_lib toneIndigo
class http_api toneTeal
```

## Components

### Core runtime

Executable server, simulation, networking, persistence, and UI

- [Launcher](https://github.com/openrune/openrune-server/blob/HEAD/game-server/src/main/kotlin/org/alter/game/Launcher.kt): entrypoint · Bootstraps the server runtime · `game-server/src/main/kotlin/org/alter/game/Launcher.kt`
- [Contexts](https://github.com/openrune/openrune-server/blob/HEAD/game-server/src/main/kotlin/org/alter/game/GameContext.kt): runtime config · Server and development environment wiring · `game-server/src/main/kotlin/org/alter/game/GameContext.kt`
- [Server system](https://github.com/openrune/openrune-server/blob/HEAD/game-server/src/main/kotlin/org/alter/game/system/ServerSystem.kt): orchestration · Coordinates services and subsystems · `game-server/src/main/kotlin/org/alter/game/system/ServerSystem.kt`
- [Protocol bridge](https://github.com/openrune/openrune-server/blob/HEAD/game-server/src/main/kotlin/org/alter/game/rsprot/NetworkServiceFactory.kt): network boundary · OSRS protocol, JS5, and connection handling · `game-server/src/main/kotlin/org/alter/game/rsprot/NetworkServiceFactory.kt`
- [Message handlers](https://github.com/openrune/openrune-server/blob/HEAD/game-server/src/main/kotlin/org/alter/game/message/handler/OpNpcHandler.kt): inbound handlers · Packet-to-action translation for client input · `game-server/src/main/kotlin/org/alter/game/message/handler/OpNpcHandler.kt`
- [World model](https://github.com/openrune/openrune-server/blob/HEAD/game-server/src/main/kotlin/org/alter/game/model/World.kt): simulation state · Canonical entities, regions, items, skills, and combat state · `game-server/src/main/kotlin/org/alter/game/model/World.kt`
- [Game tasks](https://github.com/openrune/openrune-server/blob/HEAD/game-server/src/main/kotlin/org/alter/game/task/GameTask.kt): tick scheduler · Per-tick cycle, synchronization, and cleanup work · `game-server/src/main/kotlin/org/alter/game/task/GameTask.kt`
- [Plugin runtime](https://github.com/openrune/openrune-server/blob/HEAD/game-server/src/main/kotlin/org/alter/game/pluginnew/PluginManager.kt): event dispatch · Plugin manager and game-event bus · `game-server/src/main/kotlin/org/alter/game/pluginnew/PluginManager.kt`
- [Legacy plugins](https://github.com/openrune/openrune-server/blob/HEAD/game-server/src/main/kotlin/org/alter/game/plugin/Plugin.kt): plugin API · Older plugin abstraction kept alongside the new event system · `game-server/src/main/kotlin/org/alter/game/plugin/Plugin.kt`
- [Saving layer](https://github.com/openrune/openrune-server/blob/HEAD/game-server/src/main/kotlin/org/alter/game/saving/PlayerSaving.kt): persistence · Player load/save and format adapters · `game-server/src/main/kotlin/org/alter/game/saving/PlayerSaving.kt`
- [Services](https://github.com/openrune/openrune-server/blob/HEAD/game-server/src/main/kotlin/org/alter/game/service/GameService.kt): runtime services · Login, RSA, XTEA, world verification, and metadata services · `game-server/src/main/kotlin/org/alter/game/service/GameService.kt`
- [UI model](https://github.com/openrune/openrune-server/blob/HEAD/game-server/src/main/kotlin/org/alter/game/ui/UserInterface.kt): client ui · Gameframe, interfaces, and component event mapping · `game-server/src/main/kotlin/org/alter/game/ui/UserInterface.kt`

### Gameplay content

Reusable mechanics and world-specific content modules

- [Game plugins](https://github.com/openrune/openrune-server/blob/HEAD/game-plugins/src/main/kotlin/org/alter/plugins/content/OSRSPlugin.kt): combat/content plugins · Reusable gameplay systems such as combat, commands, magic, and NPCs · `game-plugins/src/main/kotlin/org/alter/plugins/content/OSRSPlugin.kt`
- [Content pack](https://github.com/openrune/openrune-server/blob/HEAD/content/src/main/kotlin/org/alter/ClientScripts.kt): world content · Area scripts, skills, items, quests, interfaces, and world mechanics · `content/src/main/kotlin/org/alter/ClientScripts.kt`

### Shared contracts

API types and compile-time generation for content authors

- [Game API](https://github.com/openrune/openrune-server/blob/HEAD/game-api/src/main/kotlin/org/alter/api/Skills.kt): shared contract · Shared enums, DSLs, and extensions for plugin authors · `game-api/src/main/kotlin/org/alter/api/Skills.kt`
- [KSP processor](https://github.com/openrune/openrune-server/blob/HEAD/ksp-processor/src/main/kotlin/org/alter/plugin/dialogue/DialogueGeneratorSymbolProcessor.kt): codegen · Generates dialogue and plugin settings boilerplate · `ksp-processor/src/main/kotlin/org/alter/plugin/dialogue/DialogueGeneratorSymbolProcessor.kt`

### Data pipeline

Cache codecs, generated definitions, and offline game data

- [Cache tools](https://github.com/openrune/openrune-server/blob/HEAD/cache/src/main/kotlin/dev/openrune/ServerCacheManager.kt): codec pipeline · Cache decoding, packing, and server cache management · `cache/src/main/kotlin/dev/openrune/ServerCacheManager.kt`
- [Game data](https://github.com/openrune/openrune-server/blob/HEAD/data/api.yml): definitions · Raw dumps, overrides, and generated config sources · `data/api.yml`

### Tooling

Shared utilities and developer/runtime helpers

- [Shared util](https://github.com/openrune/openrune-server/blob/HEAD/util/src/main/kotlin/gg/rsmod/util/ExtensionFunctions.kt): utilities · Low-level buffer, concurrency, naming, and property helpers · `util/src/main/kotlin/gg/rsmod/util/ExtensionFunctions.kt`

### Web frontend

Separate Vue-based HTTP-facing UI

- [HTTP API UI](https://github.com/openrune/openrune-server/blob/HEAD/http-api/src/App.vue): vue frontend · Separate Vue-based web presentation layer · `http-api/src/App.vue`

## Connections

- Launcher → Contexts: bootstraps · Launch code selects runtime context
- Contexts → Server system: creates · Context wires the server system
- Server system → Protocol bridge: starts · System opens protocol and connection services
- Server system → Game tasks: ticks · Orchestrates scheduled world processing
- Protocol bridge → Message handlers: decodes · Inbound protocol traffic becomes handlers
- Message handlers → Plugin runtime: emits · Client actions are routed into events
- Plugin runtime → Game plugins: dispatches · Shared gameplay logic subscribes to events
- Plugin runtime → Content pack: dispatches · World content modules react to events
- Game plugins → World model: mutates · Gameplay systems update server state
- Content pack → World model: mutates · Area and skill scripts update state
- Game tasks → World model: advances · Simulation state progresses on tick
- World model → UI model: renders · State changes propagate to client UI
- Services → Saving layer: loads · Login and save services depend on stored player data
- Services → Cache tools: consumes · Metadata services use cache-derived definitions
- Cache tools → Game data: feeds · Offline tooling prepares runtime config/data
- Game API → Game plugins: contracts · Gameplay modules depend on shared API types
- Game API → Content pack: contracts · Content scripts are authored against the shared API
- KSP processor → Game plugins: generates · Compile-time processors reduce plugin boilerplate
- KSP processor → Content pack: generates · Compile-time processors support content authoring
- Shared util → Server system: supports · Common utilities back runtime subsystems
- Shared util → Cache tools: supports · Utility code is reused by offline tools
- HTTP API UI → Services: queries · Web UI sits beside the game runtime and reads server-facing data
- Legacy plugins → Plugin runtime: coexists · Older plugin abstraction remains alongside the new runtime
