Commonwealth-Online-Server/server

Commonwealth Online Dedicated Server

The dedicated server is implemented in C# on .NET 8. Valve GameNetworkingSockets remains in the native C++ bridge under native_transport/, and the C# server loads its C ABI directly.

Run

Packaged Windows:

CommonwealthOnline.Server.exe serve --config commonwealth-server.json

Packaged Linux:

./CommonwealthOnline.Server serve --config commonwealth-server.json

Source checkout:

dotnet build CommonwealthOnline.Server.csproj -c Release
dotnet run --project tests/CommonwealthOnline.Server.Tests.csproj -c Release
dotnet run --project CommonwealthOnline.Server.csproj -- serve --config commonwealth-server.json --interactive

start.bat and start.sh prefer a published apphost, then a framework-dependent DLL, then dotnet run in a source checkout.

Tests

• tests/ — fast in-memory unit/component tests over the authoritative core (run in the CSharp Server Gate CI).
• acceptance/ — end-to-end acceptance harness (issue #15): stands up the real server behind the real TCP transport on a loopback port and drives real client sockets through the baseline-protocol, TCP-compatibility, and interest-management matrix sections. Runs in the Acceptance (end-to-end TCP) CI, or locally:

dotnet run --project acceptance/CommonwealthOnline.Server.Acceptance.csproj -c Release

Config

Generate defaults:

dotnet run --project CommonwealthOnline.Server.csproj -- config init commonwealth-server.json

Existing field names remain supported:

{
  "host": "0.0.0.0",
  "port": 7777,
  "server_name": "Commonwealth Online Server",
  "server_description": "",
  "max_players": 16,
  "log_verbosity": "info",
  "admin_port": 7779,
  "enable_gns_transport": false,
  "gns_bridge_path": null
}

When GNS is enabled, host must be an explicit IPv4 bind address. TCP and GNS may use the same numeric game port because they use TCP and UDP separately.

Ports

• TCP 7777 by default: gameplay compatibility
• UDP 7777 by default: GNS gameplay when enabled
• UDP 7778: LAN discovery
• TCP 127.0.0.1:7779 by default: authenticated administration

Admin CLI

dotnet run --project CommonwealthOnline.Server.csproj -- status --config commonwealth-server.json
dotnet run --project CommonwealthOnline.Server.csproj -- clients --config commonwealth-server.json
dotnet run --project CommonwealthOnline.Server.csproj -- kick 2 --reason griefing --config commonwealth-server.json
dotnet run --project CommonwealthOnline.Server.csproj -- ban 2 --reason griefing --config commonwealth-server.json
dotnet run --project CommonwealthOnline.Server.csproj -- unban 192.0.2.5 --config commonwealth-server.json
dotnet run --project CommonwealthOnline.Server.csproj -- bans --config commonwealth-server.json
dotnet run --project CommonwealthOnline.Server.csproj -- world time 1430 --config commonwealth-server.json
dotnet run --project CommonwealthOnline.Server.csproj -- world weather 0002b52a --config commonwealth-server.json

The admin channel authenticates with .admin-token beside the config file and binds to localhost only.

Load test

The C# synthetic Protocol V2 client provides deterministic multi-client load coverage:

dotnet run --project CommonwealthOnline.Server.csproj -- load-test --host 127.0.0.1 --port 7777 --clients 16

Architecture

C# owns:

• Protocol V2 decoding/validation
• session admission and server-owned player IDs
• movement validation and corrections
• cell/worldspace interest filtering
• durable player state
• scoped NPC authority and epochs
• combat routing
• world state
• bans and rate limits
• handshake and idle timeouts
• TCP compatibility
• GNS sequencing/envelope handling
• LAN discovery
• admin control

C++ owns only the Valve GNS transport bridge:

• initialization/shutdown
• UDP listen socket
• GNS connection lifecycle
• message polling/sending
• disconnects
• remote endpoint lookup

Protocol guarantees

• Maximum message size remains 64 KiB.
• transform and npcState are unreliable/sequenced under GNS.
• Reliable gameplay/control packets remain reliable/ordered.
• Snapshot sequences are wrap-safe; stale and duplicate snapshots are rejected.
• Server-owned identity is applied before mutation/relay.
• Movement validation runs before transform mutation/relay.
• Interest filtering remains authoritative.
• NPC authority is scoped by cell/worldspace and epoch.
• Durable player state is cached; action events are not replay-cached.
• Ban, connection throttle and packet-rate checks remain server-side.

Publish

Linux self-contained:

dotnet publish CommonwealthOnline.Server.csproj -c Release -r linux-x64 --self-contained true -p:PublishSingleFile=true -o publish/linux-x64

Windows self-contained:

dotnet publish CommonwealthOnline.Server.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -o publish\win-x64

commonwealth-online.service.example is provided for Linux systemd deployment.