KSA Multiplayer

A multiplayer modification for Kitten Space Agency (KSA) that enables real-time cooperative gameplay. Players can see each other's spacecraft during orbital missions, maneuvers, and surface operations.

Architecture

This project uses a dedicated server architecture:

• Server - Standalone executable that relays messages between clients, manages authentication, and maintains authoritative game time
• Client - KSA mod that connects to the server and synchronizes vehicle data with other players

Features

• Dedicated Server - Server runs independently; no player needs to host (requires KSA installation for game DLLs)
• Real-time Vehicle Synchronization - See other players' spacecraft in orbit and on surfaces
• Shared Universe - Starts empty, keeps all session vessels, and replays them to late joiners
• Companies - Operate solo or create/join a persistent company with automatic time convergence
• Multiple Vessels - Every launched or controlled vessel remains in the shared world
• Event-based Architecture - Efficient network updates only on significant state changes
• In-game Chat - Communicate with other players
• Player Nametags - Visual indicators showing player names above vehicles
• Server-Authoritative Time Sync - Keeps all players synchronized
• Server-advertised Browser Login - The chosen server supplies its OIDC provider; the client uses Authorization Code + PKCE
• System Validation - Ensures all players run the same solar system
• EVA Support - Synchronizes astronaut objects between players
• StarMap Compatible - Works with both native KSA mod loading and StarMap loader
• Time Warp Support - Players can warp independently; use Sync button to catch up

Requirements

• Kitten Space Agency v3103 or compatible
• Windows 10 or later
• Internet access during installation

The installer manages the compatible StarMap loader and its private .NET runtime, so players do not need to maintain either dependency separately.

---

Installation (End Users)

Using the Installer (Recommended)

1. Download KSA-Multiplayer-Setup-v0.4.3-beta.1.exe from Releases.
2. Run the installer and select your KSA installation folder.
3. Launch the game using the KSA with Mods desktop shortcut.

Setup installs the multiplayer client, a pinned StarMap loader, and a private pinned .NET runtime. It does not install or start a dedicated server on the player's PC.

Manual Installation

1. Copy Launcher/* to [KSA Install]\Launcher\
2. Copy Content/Multiplayer/* to [KSA Install]\Content\Multiplayer\
3. Copy server files to [KSA Install]\ root:
   • RunServer.cmd
   • KSA-Dedicated-Server.dll
   • KSA-Dedicated-Server.deps.json
   • KSA-Dedicated-Server.runtimeconfig.json
   • server_config.json
4. Add to Content\manifest.toml:

   [[mods]]
   id = "Multiplayer"
   enabled = true

StarMap Mod Loader

This mod uses StarMap, the community mod loader. Setup installs and configures the pinned compatible version automatically, including its private .NET runtime.

---

Running the Server

Quick Start

1. Double-click the KSA Dedicated Server desktop shortcut

   • Or run RunServer.cmd from KSA installation folder

2. The server will start and display:

   ╔══════════════════════════════════════════╗
   ║      KSA DEDICATED SERVER v0.4.3         ║
   ╚══════════════════════════════════════════╝
   Server: KSA Multiplayer Server
   Port: 7777, Max Players: 8
   

Server Configuration

Edit server_config.json in your KSA folder:

{
  "ServerName": "My KSA Server",
  "Port": 7777,
  "MaxPlayers": 8,
  "Password": "",
  "SystemId": "Sol",
  "SystemDisplayName": "Solar System",
  "Motd": "Welcome to KSA Multiplayer!",
  "BannedIPs": []
}

Setting	Description
ServerName	Display name for your server
Port	UDP port (default: 7777)
MaxPlayers	Maximum concurrent players
Password	Leave empty for no password
SystemId	Sol, EarthMoon, or Earth
Motd	Message shown to players on join

Server Commands

Command	Description
help	Show available commands
status	Show server status and player count
list	List connected players
kick <name>	Kick a player by name
ban <name>	Ban a player (saves IP)
unban <ip>	Remove an IP from ban list
banlist	Show banned IPs
say <message>	Broadcast server message
quit	Graceful shutdown

Port Forwarding

To allow players outside your local network:

1. Forward port 7777 UDP in your router
2. Point a DNS hostname at the router's public address
3. Players can use the same hostname for HTTPS and the game because HTTPS uses TCP 443 while KSA uses UDP 7777

---

Running the Client

1. Double-click the KSA with Mods desktop shortcut
2. In-game, the Multiplayer window opens automatically
3. Enter connection details:
   • Server address - For example, ksa.example.com
   • Port - Server port (default: 7777)
4. Click Connect
5. The server tells the mod which identity provider to use. Complete the LLDAP/Authelia sign-in in the browser; the verified LLDAP username becomes the in-game player name.

After the first successful login, the mod stores a Windows DPAPI-encrypted refresh token in the current user's KSA AppData folder. Later connections on that Windows profile authenticate silently. A wiped profile or another PC requires a new browser login. Use Forget saved login beside Connect to remove the local credential and switch accounts.

The manager website can use the same host, such as https://ksa.example.com. Authelia allows members of the configured user groups to view status without opening the game, while operator groups can view sanitized diagnostics.

Important Notes

• All players must run the same solar system as configured in the server's server_config.json! (Solar System, Earth and Moon, or Earth Only)
• System mismatch will show an error and disconnect

Time Sync & Subspace

Players can time warp independently:

• In Sync (green) - See each other's vessels in 3D
• Out of Sync (orange) - Vessels appear as "ghosts" (map only)
• Sync Button - Jump forward to match another player's time

---

Development

Prerequisites

• .NET 10 SDK
• Kitten Space Agency installed (for assembly references)
• NSIS (for building installer)

Project Structure

KSA-Multiplayer/
├── Client/                      # Client mod source
│   ├── src/                     # C# source files
│   │   ├── Messages/            # Network message classes
│   │   ├── ModEntry.cs          # Mod entry point
│   │   ├── MultiplayerManager.cs
│   │   ├── NetworkPatches.cs    # Harmony patches
│   │   └── ...
│   ├── KSA-Multiplayer-Mod.csproj
│   └── mod.toml
│
├── Server/                      # Dedicated server source
│   ├── DedicatedServer.cs       # Main server logic
│   ├── ServerConfig.cs          # Configuration handling
│   ├── ServerConsole.cs         # Console UI
│   ├── KSA-Dedicated-Server.csproj
│   └── ...
│
├── KSA-Multiplayer-Package/     # Installer & distribution
│   ├── installer.nsi            # NSIS installer script
│   ├── build.bat                # Build script
│   ├── Content/Multiplayer/     # Client binaries
│   ├── Server/                  # Server binaries
│   └── Launcher/                # Mod loader
│
├── README.md
├── CHANGELOG.md
└── LICENSE

Building the Client Mod

cd Client
dotnet build -c Release

Output: Client/bin/Release/KSA.Mods.Multiplayer.dll

One-command client update

Run the managed updater after pulling a new version:

.\scripts\Update-KSAMultiplayer.ps1 -Launch

The updater requests administrator access, copies the packaged Multiplayer mod into KSA, installs the pinned and SHA-256-verified StarMap version, installs a private pinned .NET runtime for the loader, writes its KSA configuration, and creates the KSA with Mods desktop shortcut. Multiplayer updates therefore do not depend on a separately managed StarMap or system-wide .NET installation.

Building the Server

cd Server
dotnet build -c Release

Output: Server/bin/Release/net10.0/KSA-Dedicated-Server.exe

Building the Installer Package

The build.bat script builds everything and creates the installer:

cd KSA-Multiplayer-Package
.\build.bat

This will:

1. Build client mod (Release)
2. Build server (Release)
3. Copy binaries to package folders
4. Run NSIS to create KSA-Multiplayer-Setup.exe

Manual Development Workflow

1. Build client:

   cd Client
   dotnet build -c Release
   copy bin\Release\KSA.Mods.Multiplayer.dll "C:\Program Files\Kitten Space Agency\Content\Multiplayer\"

2. Build server:

   cd Server
   dotnet build -c Release
   copy bin\Release\net10.0\KSA-Dedicated-Server.dll "C:\Program Files\Kitten Space Agency\"
   copy bin\Release\net10.0\KSA-Dedicated-Server.deps.json "C:\Program Files\Kitten Space Agency\"

3. Run server from KSA folder (uses system .NET 10):

   cd "C:\Program Files\Kitten Space Agency"
   dotnet KSA-Dedicated-Server.dll

---

Dependencies

Component	Dependency	Version	License	Purpose
Client	Harmony	2.x	MIT	Runtime method patching
Client	MemoryPack	1.x	MIT	Binary serialization
Server	Brutal Framework	-	-	Networking (RakNet)
Server	MemoryPack	1.x	MIT	Binary serialization

---

Technical Details

The mod implements an "immortal vessel" pattern where remote vehicles exist as real Vehicle objects but are excluded from local physics simulation. Only the controlling player simulates physics; others receive position updates.

Key implementation:

• Dedicated server relays messages (star topology)
• Server-authoritative time synchronization (forward-only sync)
• Binary message serialization via MemoryPack
• Situation-aware coordinates (CCI for orbital, CCF for surface)
• Kepler orbital mechanics handle interpolation between sync points

---

Known Limitations

• Surface vehicle synchronization less tested than orbital

License

MIT License - see LICENSE

Credits

• Current maintainer: Niborian
• Originally created by: RacerX (@racerx2)

KSA Multiplayer is maintained by Niborian and built on the original work by RacerX.

Contributing

Contributions welcome! Submit issues and pull requests.

Changelog

See CHANGELOG.md