# nikkiii/hyperion architecture

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

- Interactive diagram: https://gitdiagram.com/nikkiii/hyperion
- Repository: https://github.com/nikkiii/hyperion

## Overview

Hyperion is a Java RuneScape gameserver suite. Clients connect to the game server for login and gameplay; the world loads configuration and map data, then the game engine runs player and world logic and serves protocol updates. A separate file server streams cache data, while an optional login-server connection supports multi-world coordination and cross-world messaging. The graph preserves these documented capabilities, but unsampled modules and their internal wiring are represented conservatively; dashed edges mark relationships documented by the README rather than shown in sampled code.

Main entry points: [`src/org/hyperion/rs2/model/World.java`](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/model/World.java) (World state), [`src/org/hyperion/rs2/model/Player.java`](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/model/Player.java) (Player state), [`src/org/hyperion/Server.java`](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/Server.java) (Server launcher), [`src/org/hyperion/rs2/model/ObjectManager.java`](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/model/ObjectManager.java) (Object loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server runtime"]
  node_server["Server launcher<br/>[Server.java]"]
  node_gameserver["Game server<br/>[RS2Server.java]"]
  node_connection["Session handler"]
  node_packets["Packet routing<br/>[PacketManager.java]"]
  node_handlers["Game packet handlers<br/>[PacketHandler.java]"]
end

subgraph group_game["Game world"]
  node_world["World state<br/>[World.java]"]
  node_engine["Game engine<br/>[GameEngine.java]"]
  node_playerstate["Player state<br/>[Player.java]"]
  node_regions["Region manager<br/>[RegionManager.java]"]
  node_objects["Object loading<br/>[ObjectManager.java]"]
  node_actions["Actions and events"]
end

subgraph group_cache["Cache delivery"]
  node_fileserver["Update server<br/>[FileServer.java]"]
  node_requests["Update requests"]
  node_cache[("Cache reader<br/>[Cache.java]")]
end

subgraph group_multiworld["Multi-world login"]
  node_loginserver["Login server<br/>[LoginServer.java]"]
  node_node["World node<br/>[Node.java]"]
  node_nodemanager["Node registry<br/>[NodeManager.java]"]
  node_connector["Login connector"]
end

node_player(("Game client"))
node_updateclient(("Cache client"))

node_server -->|"initializes"| node_world
node_server -->|"starts"| node_fileserver
node_server -->|"starts"| node_gameserver
node_player -.->|"connects"| node_gameserver
node_gameserver -.->|"accepts sessions"| node_connection
node_connection -.->|"dispatches packets"| node_packets
node_packets -->|"routes by opcode"| node_handlers
node_handlers -->|"handles player input"| node_playerstate
node_world -->|"owns"| node_engine
node_engine -->|"runs logic for"| node_world
node_world -->|"loads objects"| node_objects
node_objects -->|"reads cache"| node_cache
node_objects -->|"places objects"| node_regions
node_regions -->|"queries nearby players"| node_playerstate
node_playerstate -->|"queues actions"| node_actions
node_fileserver -.->|"handles requests"| node_requests
node_requests -->|"serves cache files"| node_cache
node_updateclient -.->|"requests updates"| node_fileserver
node_world -->|"configures optional login"| node_connector
node_connector -.->|"connects for worlds"| node_loginserver
node_loginserver -->|"manages world nodes"| node_node
node_nodemanager -->|"registers nodes"| node_node
node_node -->|"loads player state"| node_playerstate

click node_server "https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/Server.java"
click node_gameserver "https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/RS2Server.java"
click node_connection "https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/ConnectionHandler.java"
click node_packets "https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/net/PacketManager.java"
click node_handlers "https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/packet/PacketHandler.java"
click node_world "https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/model/World.java"
click node_engine "https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/GameEngine.java"
click node_playerstate "https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/model/Player.java"
click node_regions "https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/model/region/RegionManager.java"
click node_objects "https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/model/ObjectManager.java"
click node_actions "https://github.com/nikkiii/hyperion/tree/master/src/org/hyperion/rs2/action"
click node_fileserver "https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/fileserver/FileServer.java"
click node_requests "https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/fileserver/RequestHandler.java"
click node_cache "https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/cache/Cache.java"
click node_loginserver "https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/ls/LoginServer.java"
click node_node "https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/ls/Node.java"
click node_nodemanager "https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/ls/NodeManager.java"
click node_connector "https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/login/LoginServerConnector.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_server,node_gameserver,node_connection,node_packets,node_handlers,node_player toneBlue
class node_world,node_engine,node_playerstate,node_regions,node_objects,node_actions,node_updateclient toneAmber
class node_fileserver,node_requests,node_cache toneMint
class node_loginserver,node_node,node_nodemanager,node_connector toneRose
```

## Components

### Server runtime

- [Server launcher](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/Server.java): `src/org/hyperion/Server.java`
- [Game server](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/RS2Server.java): `src/org/hyperion/rs2/RS2Server.java`
- [Session handler](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/ConnectionHandler.java): `src/org/hyperion/rs2/ConnectionHandler.java`
- [Packet routing](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/net/PacketManager.java): `src/org/hyperion/rs2/net/PacketManager.java`
- [Game packet handlers](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/packet/PacketHandler.java): `src/org/hyperion/rs2/packet/PacketHandler.java`

### Game world

- [World state](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/model/World.java): `src/org/hyperion/rs2/model/World.java`
- [Game engine](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/GameEngine.java): `src/org/hyperion/rs2/GameEngine.java`
- [Player state](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/model/Player.java): `src/org/hyperion/rs2/model/Player.java`
- [Region manager](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/model/region/RegionManager.java): `src/org/hyperion/rs2/model/region/RegionManager.java`
- [Object loading](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/model/ObjectManager.java): `src/org/hyperion/rs2/model/ObjectManager.java`
- [Actions and events](https://github.com/nikkiii/hyperion/tree/master/src/org/hyperion/rs2/action): `src/org/hyperion/rs2/action`

### Cache delivery

- [Update server](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/fileserver/FileServer.java): `src/org/hyperion/fileserver/FileServer.java`
- [Update requests](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/fileserver/RequestHandler.java): `src/org/hyperion/fileserver/RequestHandler.java`
- [Cache reader](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/cache/Cache.java): `src/org/hyperion/cache/Cache.java`

### Multi-world login

- [Login server](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/ls/LoginServer.java): `src/org/hyperion/ls/LoginServer.java`
- [World node](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/ls/Node.java): `src/org/hyperion/ls/Node.java`
- [Node registry](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/ls/NodeManager.java): `src/org/hyperion/ls/NodeManager.java`
- [Login connector](https://github.com/nikkiii/hyperion/blob/master/src/org/hyperion/rs2/login/LoginServerConnector.java): `src/org/hyperion/rs2/login/LoginServerConnector.java`

### Other components

- **Game client**
- **Cache client**

## Connections

- Server launcher → World state: initializes (evidence: `src/org/hyperion/Server.java`)
- Server launcher → Update server: starts (evidence: `src/org/hyperion/Server.java`)
- Server launcher → Game server: starts (evidence: `src/org/hyperion/Server.java`)
- Game client → Game server: connects
- Game server → Session handler: accepts sessions
- Session handler → Packet routing: dispatches packets
- Packet routing → Game packet handlers: routes by opcode (evidence: `src/org/hyperion/rs2/net/PacketManager.java`)
- Game packet handlers → Player state: handles player input (evidence: `src/org/hyperion/rs2/packet/PacketHandler.java`)
- World state → Game engine: owns (evidence: `src/org/hyperion/rs2/model/World.java`)
- Game engine → World state: runs logic for (evidence: `src/org/hyperion/rs2/GameEngine.java`)
- World state → Object loading: loads objects (evidence: `src/org/hyperion/rs2/model/ObjectManager.java`)
- Object loading → Cache reader: reads cache (evidence: `src/org/hyperion/rs2/model/ObjectManager.java`)
- Object loading → Region manager: places objects (evidence: `src/org/hyperion/rs2/model/ObjectManager.java`)
- Region manager → Player state: queries nearby players (evidence: `src/org/hyperion/rs2/model/region/RegionManager.java`)
- Player state → Actions and events: queues actions (evidence: `src/org/hyperion/rs2/model/Player.java`)
- Update server → Update requests: handles requests
- Update requests → Cache reader: serves cache files (evidence: `src/org/hyperion/fileserver/RequestHandler.java`)
- Cache client → Update server: requests updates
- World state → Login connector: configures optional login (evidence: `src/org/hyperion/rs2/model/World.java`)
- Login connector → Login server: connects for worlds
- Login server → World node: manages world nodes (evidence: `src/org/hyperion/ls/Node.java`)
- Node registry → World node: registers nodes (evidence: `src/org/hyperion/ls/NodeManager.java`)
- World node → Player state: loads player state (evidence: `src/org/hyperion/ls/Node.java`)
