How openrune/openrune-server works
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 GameTasks.
• 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: ServerSystem.kt Server system · PluginManager.kt Plugin runtime · World.kt World model · OSRSPlugin.kt Game plugins
Components 20
Core runtime
Executable server, simulation, networking, persistence, and UI
- Launcher · Bootstraps the server runtime
game-server/src/main/kotlin/org/alter/game/Launcher.kt - Contexts · Server and development environment wiring
game-server/src/main/kotlin/org/alter/game/GameContext.kt - Server system · Coordinates services and subsystems
game-server/src/main/kotlin/org/alter/game/system/ServerSystem.kt - Protocol bridge · OSRS protocol, JS5, and connection handling
game-server/src/main/kotlin/org/alter/game/rsprot/NetworkServiceFactory.kt - Message handlers · Packet-to-action translation for client input
game-server/src/main/kotlin/org/alter/game/message/handler/OpNpcHandler.kt - World model · Canonical entities, regions, items, skills, and combat state
game-server/src/main/kotlin/org/alter/game/model/World.kt - Game tasks · Per-tick cycle, synchronization, and cleanup work
game-server/src/main/kotlin/org/alter/game/task/GameTask.kt - Plugin runtime · Plugin manager and game-event bus
game-server/src/main/kotlin/org/alter/game/pluginnew/PluginManager.kt - Legacy plugins · Older plugin abstraction kept alongside the new event system
game-server/src/main/kotlin/org/alter/game/plugin/Plugin.kt - Saving layer · Player load/save and format adapters
game-server/src/main/kotlin/org/alter/game/saving/PlayerSaving.kt - Services · Login, RSA, XTEA, world verification, and metadata services
game-server/src/main/kotlin/org/alter/game/service/GameService.kt - UI model · 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 · Reusable gameplay systems such as combat, commands, magic, and NPCs
game-plugins/src/main/kotlin/org/alter/plugins/content/OSRSPlugin.kt - Content pack · 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 · Shared enums, DSLs, and extensions for plugin authors
game-api/src/main/kotlin/org/alter/api/Skills.kt - KSP processor · 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 · Cache decoding, packing, and server cache management
cache/src/main/kotlin/dev/openrune/ServerCacheManager.kt - Game data · Raw dumps, overrides, and generated config sources
data/api.yml
Tooling
Shared utilities and developer/runtime helpers
- Shared util · 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 · Separate Vue-based web presentation layer
http-api/src/App.vue
Connections 23
- 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