Commonwealth-Online-Public/server

Server

This folder is for the external multiplayer test server.

The current server is a local-only TCP test server. It listens on 127.0.0.1:7777, accepts one or more clients, reads newline-separated JSON packets, assigns incrementing playerId values, sends welcome packets, adds playerId and serverTime to transform packets, broadcasts transform packets to every other connected client, and broadcasts disconnect packets when clients disconnect.

Transform packets may include optional movement-state fields such as isMoving, isSprinting, isSneaking, isJumping, weaponDrawn, and movementSpeed. The server preserves these fields automatically because it broadcasts the original transform packet after adding server-owned fields.

This is still a local prototype. It does not make Fallout 4 multiplayer playable yet.

Run

Terminal server:

cd server
python server.py

Developer GUI server:

cd server
pip install -r requirements.txt
python dev_server_app.py

Then launch Fallout 4 through F4SE and move the player. The plugin should send local player transform packets, and this server should print matching transform packets.

In the developer GUI, the Fake Clients tab can create simple synthetic TCP clients for local relay testing. Click Start Server, then click + Add Fake Client. Each fake client connects to 127.0.0.1:7777, receives a server-assigned playerId, appears in both GUI client tables, and sends one idle transform per second for F4TTestCell01.

If the server is not running, the plugin should log a warning and Fallout 4 should continue launching normally.

Structure

• server.py: thin terminal launcher for the local test server.
• server_core.py: reusable FalloutTogetherServer core for networking, lifecycle control, packet relay, stats, client snapshots, and log callbacks.
• client_session.py: ClientSession state model for connected clients.
• dev_server_app.py: PySide6 developer GUI that starts/stops the reusable server core, displays logs, shows live stats, and lists connected clients.
• fake_player.py: GUI fake-player test tooling. It owns background synthetic TCP clients that connect through the normal server socket and send idle transform packets.
• fake_client.py: lightweight receiver for testing welcome, transform, and disconnect packets without launching a second Fallout 4 instance.
• requirements.txt: optional Python dependencies for the desktop developer GUI.

The reusable server core exposes methods intended for a future desktop dev server UI:

• start()
• serve_forever()
• stop()
• is_running()
• get_clients()
• get_stats()
• add_log_listener()
• remove_log_listener()

get_clients() and get_stats() return snapshot dictionaries, not live internal server state. Log listeners receive the same useful console messages that the terminal launcher prints today.

Current Test Flow

Terminal 1:

cd server
python server.py

Terminal 2:

cd server
python fake_client.py

Then launch Fallout 4 through F4SE and move the player.

Alternative GUI flow:

cd server
pip install -r requirements.txt
python dev_server_app.py

Click Start Server, then run python fake_client.py or launch Fallout 4 through F4SE. You can also click + Add Fake Client to create a GUI-managed synthetic client that sends an idle transform once per second. Select a fake client row and click - Remove Selected to disconnect it cleanly.

Expected behavior:

• The server assigns a playerId to each connected client and sends each client a welcome packet.
• The server receives transforms from the Fallout 4 plugin.
• The server adds playerId and serverTime to each transform packet before broadcast.
• The server preserves optional movement-state fields on transform packets.
• The server broadcasts those transform packets to connected clients except the sender.
• fake_client.py receives broadcast transform packets.
• fake_client.py stores remote player state by playerId.
• GUI fake clients connect as ordinary external TCP clients, receive a welcome packet, store their assigned playerId, and send idle transforms for cell 0B000F99.
• When a client disconnects, the server removes that client and broadcasts a disconnect packet with the departed playerId to the remaining clients.
• fake_client.py removes disconnected players from its in-memory remote_players table.

The fake client exists so broadcast behavior can be tested before coordinating a second Fallout 4/F4SE instance. It stores remote player transform state only; it does not spawn remote actors or send movement.

Validation

From inside this folder:

python -m py_compile server.py server_core.py client_session.py fake_client.py dev_server_app.py fake_player.py

Then run the terminal server:

python server.py

In another terminal, run:

python fake_client.py

To validate the developer GUI instead of the terminal launcher:

pip install -r requirements.txt
python dev_server_app.py

Click Start Server, then connect fake_client.py or the Fallout 4 plugin. To validate GUI fake clients, click + Add Fake Client and confirm the fake client appears in the Fake Clients table and Connected Clients table with an assigned player ID. Click - Remove Selected and confirm it disconnects.

For in-game validation, launch Fallout 4 through F4SE and confirm the plugin connects, receives a welcome packet, sends transforms, and receives relayed remote transforms or disconnect packets when another client is connected.

Implemented

• Start local server
• Accept client connections
• Assign server-owned player IDs
• Send welcome packets
• Receive transform packets
• Add server timestamps
• Preserve optional transform fields
• Broadcast transforms to other connected clients
• Broadcast disconnect packets
• Handle disconnect cleanup
• Reusable server core with thread-safe client/stat snapshots
• Log callbacks for future server console UI
• PySide6 developer server GUI with live logs, stats, connected-client table, and a Fake Clients tab that can spawn idle synthetic TCP clients
• GUI-managed fake clients that receive welcome packets and send idle transforms

Working In Fake Client Only

• Receiving welcome packets
• Receiving transform broadcasts
• Storing remote player state
• Removing disconnected remote players

Planned Later

• Fake client management
• Fake client movement scripts
• Gameplay synchronization
• Authentication
• Public matchmaking
• Anti-cheat
• Persistence
• Quest state
• Settlement state
• Large-scale world simulation