# godarklight/darkmultiplayer architecture

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

- Interactive diagram: https://gitdiagram.com/godarklight/darkmultiplayer
- Repository: https://github.com/godarklight/darkmultiplayer

## Overview

1. **What this repo is:** DarkMultiPlayer is a two-part multiplayer system for Kerbal Space Program: a **client-side game plugin** and a **standalone server**. The server is the authority for shared game state, while the client integrates into KSP and mirrors/sends local player actions.

2. **Top-level boundaries:** The code is split into `Client/`, `Server/`, and `Common/`. `Client` depends on KSP runtime APIs and UI, `Server` is a headless .NET service, and `Common` holds shared utilities used by both sides for byte handling, compression, recycling, and message serialization support.

3. **Client role:** The client is the in-game mod. It handles connection setup, local UI, and translating KSP events into network updates. Its major subsystems are organized by responsibility: vessel control/update, chat, player status, groups/permissions, lock management, mod control, warp/time sync, screenshots, scenario sync, and universe conversion/cache.

4. **Server role:** The server accepts connections, authenticates and tracks clients, enforces bans/whitelist/permissions, and distributes authoritative state. It also manages admin commands, modpack rules, gameplay settings, lock state, and various cleanup/expiration tasks for transient data like screenshots or log records.

5. **Network architecture:** Communication is message-driven. The server has a `Messages/` namespace with explicit message types such as handshake, heartbeat, vessel updates, player status, chat, warp control, lock system, mod data, scenario data, screenshots, and server settings. This implies a protocol where clients send intent/state changes and the server routes, validates, and broadcasts them.

6. **Shared-world synchronization:** The core gameplay data flow centers on **vessels** and **scene state**. Client workers such as `VesselWorker`, `VesselUpdate`, `VesselProtoUpdate`, `VesselCtrlUpdate`, `ScenarioWorker`, and `CraftLibraryWorker` sync KSP entities and persistence data; the server counterpart receives these updates and redistributes them to other players as needed.

7. **Time and warp model:** A distinct subsystem handles multiplayer time coordination. Files like `TimeSyncer`, `WarpWorker`, `DynamicTickWorker`, `Server/Messages/WarpControl.cs`, and the repo docs on subspace locking indicate support for **subspace-style warp** and **master-controlled warp**, with time synchronization treated as first-class network state.

8. **Authority, locks, and access control:** Collaborative play is mediated by server-side and client-side lock systems. The repo includes permissions, groups, admin systems, ban/whitelist commands, and lock propagation. These features are central to deciding who can control vessels, edit shared state, or issue administrative actions.

9. **Mod and content compatibility:** There is explicit support for modpack/mod-control syncing and compatibility checks. The client can generate a `DMPModControl.txt`, and both client/server include modpack and mod data handling. This means connection acceptance depends not just on network reachability, but also on matching or approved game content.

10. **UI and KSP integration:** The client has many windows and helpers for connection, server lists, options, debug, permissions, groups, player status, universe conversion, and disclaimers. `DMPModInterface`, toolbar support, and other wrappers show that the plugin is deeply embedded into KSP’s UI and game lifecycle rather than being a separate launcher app.

11. **Runtime and deployment:** The project is cross-platform. The README and tree show support for .NET builds, Mono on Unix-like systems, a `Dockerfile`, and a `dmp@.service` unit file. External vendored dependencies under `External/` provide KSP assemblies and helper libraries for config parsing, message streaming, and UDP mesh functionality.

12. **Useful diagram takeaway:** The architecture diagram should show a **KSP client plugin** talking over a custom message protocol to a **central authoritative server**, with `Common` as shared serialization infrastructure and separate subsystems for vessel sync, time/warp sync, permissions/locks, chat/admin, modpack enforcement, and persistent server configuration/state.

Main entry points: [`Server/Messages/Handshake.cs`](https://github.com/godarklight/darkmultiplayer/blob/master/Server/Messages/Handshake.cs) (Message protocol), [`Server/ClientHandler.cs`](https://github.com/godarklight/darkmultiplayer/blob/master/Server/ClientHandler.cs) (Client handler), [`Client/NetworkWorker.cs`](https://github.com/godarklight/darkmultiplayer/blob/master/Client/NetworkWorker.cs) (Network worker), [`Client/Main.cs`](https://github.com/godarklight/darkmultiplayer/blob/master/Client/Main.cs) (Client core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_client_main["Client core<br/>plugin bootstrap<br/>[Main.cs]"]
  node_client_net["Network worker<br/>protocol client<br/>[NetworkWorker.cs]"]
  node_client_vessel["Vessel sync<br/>state sync<br/>[VesselWorker.cs]"]
  node_client_time["Time sync<br/>warp coordinator<br/>[TimeSyncer.cs]"]
  node_client_scene["Scene sync<br/>persistence sync<br/>[ScenarioWorker.cs]"]
  node_client_social["Social state<br/>player services<br/>[ChatWorker.cs]"]
  node_client_mods["Mod control<br/>compatibility<br/>[ModWorker.cs]"]
  node_client_ui["UI layer<br/>in-game UI"]
  node_client_ksp["KSP wrappers<br/>game integration<br/>[DMPGame.cs]"]
end

subgraph group_server["Server"]
  node_server_main["Server core<br/>service bootstrap<br/>[Main.cs]"]
  node_server_conn["Client handler<br/>session manager<br/>[ClientHandler.cs]"]
  node_server_proto["Message protocol<br/>message set<br/>[Handshake.cs]"]
  node_server_state["World state<br/>authority<br/>[LockSystem.cs]"]
  node_server_access["Access control<br/>policy<br/>[BanSystem.cs]"]
  node_server_mods["Modpack rules<br/>compatibility<br/>[ModpackSystem.cs]"]
  node_server_ops["Ops tasks<br/>maintenance<br/>[LogExpire.cs]"]
end

subgraph group_common["Common"]
  node_common_core["Common core<br/>shared library<br/>[Common.cs]"]
end

node_client_main -->|"drives"| node_client_net
node_client_main -->|"opens"| node_client_ui
node_client_main -->|"hooks"| node_client_ksp
node_client_net -->|"connects"| node_server_conn
node_client_net -->|"sends/receives"| node_server_proto
node_client_vessel -->|"syncs"| node_server_proto
node_client_time -->|"coordinates"| node_server_proto
node_client_scene -->|"syncs"| node_server_proto
node_client_social -->|"updates"| node_server_proto
node_client_mods -->|"matches"| node_server_mods
node_client_ui -->|"controls"| node_client_net
node_client_ui -->|"surfaces"| node_client_social
node_common_core -->|"shared lib"| node_client_net
node_common_core -->|"shared lib"| node_server_proto
node_server_main -->|"accepts"| node_server_conn
node_server_conn -->|"updates"| node_server_state
node_server_conn -->|"checks"| node_server_access
node_server_conn -->|"verifies"| node_server_mods
node_server_state -->|"broadcasts"| node_server_proto
node_server_ops -->|"cleans"| node_server_state
node_server_ops -->|"supports"| node_server_conn

click node_client_main "https://github.com/godarklight/darkmultiplayer/blob/master/Client/Main.cs"
click node_client_net "https://github.com/godarklight/darkmultiplayer/blob/master/Client/NetworkWorker.cs"
click node_client_vessel "https://github.com/godarklight/darkmultiplayer/blob/master/Client/VesselWorker.cs"
click node_client_time "https://github.com/godarklight/darkmultiplayer/blob/master/Client/TimeSyncer.cs"
click node_client_scene "https://github.com/godarklight/darkmultiplayer/blob/master/Client/ScenarioWorker.cs"
click node_client_social "https://github.com/godarklight/darkmultiplayer/blob/master/Client/ChatWorker.cs"
click node_client_mods "https://github.com/godarklight/darkmultiplayer/blob/master/Client/ModWorker.cs"
click node_client_ui "https://github.com/godarklight/darkmultiplayer/blob/master/Client/ConnectionWindow.cs"
click node_client_ksp "https://github.com/godarklight/darkmultiplayer/blob/master/Client/DMPGame.cs"
click node_common_core "https://github.com/godarklight/darkmultiplayer/blob/master/Common/Common.cs"
click node_server_main "https://github.com/godarklight/darkmultiplayer/blob/master/Server/Main.cs"
click node_server_conn "https://github.com/godarklight/darkmultiplayer/blob/master/Server/ClientHandler.cs"
click node_server_proto "https://github.com/godarklight/darkmultiplayer/blob/master/Server/Messages/Handshake.cs"
click node_server_state "https://github.com/godarklight/darkmultiplayer/blob/master/Server/LockSystem.cs"
click node_server_access "https://github.com/godarklight/darkmultiplayer/blob/master/Server/BanSystem.cs"
click node_server_mods "https://github.com/godarklight/darkmultiplayer/blob/master/Server/ModpackSystem.cs"
click node_server_ops "https://github.com/godarklight/darkmultiplayer/blob/master/Server/LogExpire.cs"

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_client_main,node_client_net,node_client_vessel,node_client_time,node_client_scene,node_client_social,node_client_mods,node_client_ui,node_client_ksp toneBlue
class node_server_main,node_server_conn,node_server_proto,node_server_state,node_server_access,node_server_mods,node_server_ops toneAmber
class node_common_core toneMint
```

## Components

### Client

KSP in-game multiplayer plugin and UI

- [Client core](https://github.com/godarklight/darkmultiplayer/blob/master/Client/Main.cs): plugin bootstrap · KSP mod entry, lifecycle, and top-level client coordination · `Client/Main.cs`
- [Network worker](https://github.com/godarklight/darkmultiplayer/blob/master/Client/NetworkWorker.cs): protocol client · Connection setup, message dispatch, and network orchestration · `Client/NetworkWorker.cs`
- [Vessel sync](https://github.com/godarklight/darkmultiplayer/blob/master/Client/VesselWorker.cs): state sync · Vessel updates, control changes, and range/safety handling · `Client/VesselWorker.cs`
- [Time sync](https://github.com/godarklight/darkmultiplayer/blob/master/Client/TimeSyncer.cs): warp coordinator · Subspace time sync, warp control, and dynamic tick handling · `Client/TimeSyncer.cs`
- [Scene sync](https://github.com/godarklight/darkmultiplayer/blob/master/Client/ScenarioWorker.cs): persistence sync · Scenario, craft library, asteroid, flag, and universe conversion state · `Client/ScenarioWorker.cs`
- [Social state](https://github.com/godarklight/darkmultiplayer/blob/master/Client/ChatWorker.cs): player services · Chat, player status, color, groups, permissions, and admin actions · `Client/ChatWorker.cs`
- [Mod control](https://github.com/godarklight/darkmultiplayer/blob/master/Client/ModWorker.cs): compatibility · Modpack, mod data, install checks, and mod interface integration · `Client/ModWorker.cs`
- [UI layer](https://github.com/godarklight/darkmultiplayer/blob/master/Client/ConnectionWindow.cs): in-game UI · Connection, server list, options, debug, permissions, groups, and disclaimers windows · `Client/ConnectionWindow.cs`
- [KSP wrappers](https://github.com/godarklight/darkmultiplayer/blob/master/Client/DMPGame.cs): game integration · Toolbar, game hooks, vessel utilities, and plugin-facing helpers · `Client/DMPGame.cs`

### Server

Headless authoritative multiplayer service

- [Server core](https://github.com/godarklight/darkmultiplayer/blob/master/Server/Main.cs): service bootstrap · Headless server entry point and runtime wiring · `Server/Main.cs`
- [Client handler](https://github.com/godarklight/darkmultiplayer/blob/master/Server/ClientHandler.cs): session manager · Connection handling, handshake flow, and client session lifecycle · `Server/ClientHandler.cs`
- [Message protocol](https://github.com/godarklight/darkmultiplayer/blob/master/Server/Messages/Handshake.cs): message set · Handshake, heartbeat, vessel, chat, warp, lock, mod, scenario, and settings messages · `Server/Messages/Handshake.cs`
- [World state](https://github.com/godarklight/darkmultiplayer/blob/master/Server/LockSystem.cs): authority · Authoritative vessel, lock, groups, permissions, gameplay settings, and plugin state · `Server/LockSystem.cs`
- [Access control](https://github.com/godarklight/darkmultiplayer/blob/master/Server/BanSystem.cs): policy · Bans, whitelist, kick/admin commands, and moderation boundaries · `Server/BanSystem.cs`
- [Modpack rules](https://github.com/godarklight/darkmultiplayer/blob/master/Server/ModpackSystem.cs): compatibility · Modpack enforcement, backwards compatibility, and plugin interface support · `Server/ModpackSystem.cs`
- [Ops tasks](https://github.com/godarklight/darkmultiplayer/blob/master/Server/LogExpire.cs): maintenance · Log and screenshot expiration, file safety, cleanup, and server info · `Server/LogExpire.cs`

### Common

Shared transport and serialization helpers

- [Common core](https://github.com/godarklight/darkmultiplayer/blob/master/Common/Common.cs): shared library · Shared byte, compression, and recycler primitives used by both sides · `Common/Common.cs`

## Connections

- Client core → Network worker: drives · Client bootstrap starts and coordinates networking
- Client core → UI layer: opens · Client entry exposes in-game windows and controls
- Client core → KSP wrappers: hooks · Client integrates with KSP lifecycle and wrappers
- Network worker → Client handler: connects · Client session connects to the authoritative server
- Network worker → Message protocol: sends/receives · Message-driven protocol carries all multiplayer traffic
- Vessel sync → Message protocol: syncs · Vessel state and control updates flow through protocol messages
- Time sync → Message protocol: coordinates · Warp and time coordination use dedicated protocol messages
- Scene sync → Message protocol: syncs · Scenario, craft, flags, and universe state are exchanged
- Social state → Message protocol: updates · Chat, player status, groups, and permissions are propagated
- Mod control → Modpack rules: matches · Client modpack and mod data must satisfy server rules
- UI layer → Network worker: controls · UI initiates connections, settings changes, and status actions
- UI layer → Social state: surfaces · Windows expose players, permissions, and admin tools
- Common core → Network worker: shared lib · Client uses shared serialization and buffer utilities
- Common core → Message protocol: shared lib · Server message handling depends on common helpers
- Server core → Client handler: accepts · Server bootstrap creates client/session handlers
- Client handler → World state: updates · Connected clients mutate authoritative shared world state
- Client handler → Access control: checks · Connections are filtered by ban, whitelist, and admin policy
- Client handler → Modpack rules: verifies · Incoming clients are checked against modpack expectations
- World state → Message protocol: broadcasts · Authoritative changes are redistributed through message types
- Ops tasks → World state: cleans · Expiration tasks remove transient records and stale data
- Ops tasks → Client handler: supports · Operational tasks help maintain active sessions and logs
