Commonwealth Online - Qt GUI Host

Production-ready Qt6 GUI application for hosting Commonwealth Online servers on Windows.

Looking for the CLI only? You do not need to build this repo. Download the server/ folder and follow server/README.md — run start.bat (Windows) or ./start.sh (Linux / macOS). Python 3.9+ is all you need.

This repository is for building the Host GUI. The GUI wraps the same Python server from server/ in a native Windows UI.

Linux dedicated server

The dedicated server lives in server/ and is the supported way to host on Ubuntu, Debian, Arch Linux, CachyOS, Fedora, and similar distributions.

cd server
# Ubuntu/Debian: sudo apt install python3 python3-venv
# Arch/CachyOS:  sudo pacman -S --needed python
# Fedora:        sudo dnf install python3
chmod +x start.sh
./start.sh

Important notes:

• ./start.sh creates a local .venv and never uses --break-system-packages
• Do not run sudo ./start.sh
• Fish shell users do not need to activate the virtual environment
• Allow TCP 7777 (and optionally UDP 7778 for LAN discovery) through the firewall
• 0.0.0.0 is a bind address, not the address players should join
• See server/README.md for systemd, journalctl, CRLF recovery, and admin-CLI usage

Quick Start (GUI)

First time? Follow the Setup Instructions

Building

# Check prerequisites
check-setup.bat

# Build
build.bat

Output: build\bin\Release\CommonwealthOnlineHost.exe

Features

• Start/Stop Server: Compact toolbar controls with a live status indicator
• Server Settings: Edit name, description, bind address, port, max players, and log level from Settings
• Status Strip: Bind address, LAN, clients, uptime, and packet counters at a glance
• Client List: Live table of connected clients and connection details
• Server Logs: Resizable log pane with timestamps
• Utility UI: Light admin-tool layout (toolbar, status strip, splitter panes)
• Auto-detection: Automatically finds Python and server directory
• Subprocess Management: Server runs in separate process; GUI crash doesn't kill server

Requirements

• Windows 10 or later
• Qt 6.4+ (install from https://www.qt.io/download-open-source)
• Visual Studio 2022 with C++ tools
• CMake 3.20+
• Python 3.9+ (for running the relay server)

Setup Issues?

See SETUP.md for detailed instructions and troubleshooting.

Building

Quick Build

check-setup.bat        # Verify prerequisites
build.bat              # Auto-detect Qt6 and build

From Visual Studio

1. Open this repository folder in Visual Studio 2022
2. Wait for CMake to auto-configure
3. Build → Build All
4. Run the executable

From Command Line (Manual)

mkdir build
cd build
cmake .. -G "Visual Studio 17 2022" -DCMAKE_PREFIX_PATH="C:\Qt\6.8.0\msvc2022_64"
cmake --build . --config Release

First Run

1. Double-click CommonwealthOnlineHost.exe
2. Click Start
3. Server will bind to 0.0.0.0:7777 (configurable in commonwealth-server.json)
4. View real-time logs and connected clients

Configuration

Use Settings in the Host GUI to edit settings, or edit commonwealth-server.json in the server folder:

• host: Bind address
• port: Server port
• server_name: Display name (shown in LAN browser)
• server_description: Short description (optional)
• max_players: Max player count
• log_verbosity: debug/info/warning/error

Saved changes apply the next time the server is started. If the server is already running, stop and start it again.

Layout

├── CMakeLists.txt              # Build configuration
├── build.bat                   # Auto-build script
├── check-setup.bat             # Verify prerequisites
├── SETUP.md                    # Setup instructions
├── README.md                   # This file
├── DEVELOPMENT.md              # Developer guide
├── IMPLEMENTATION.md           # Architecture docs
├── src/
│   ├── main.cpp                # Application entry point
│   ├── MainWindow.h/cpp        # Main window UI and logic
│   ├── ConfigDialog.h/cpp      # Server settings editor dialog
│   ├── ServerProcess.h/cpp     # Subprocess manager for relay server
│   └── resources/
│       ├── resources.qrc       # Qt resource manifest
│       └── icons/
│           └── app.ico         # Application icon
├── server/                     # Python relay server (CLI; no build needed)
└── build/                      # Build output directory (after building)
    └── bin/
        └── Release/
            └── CommonwealthOnlineHost.exe

Architecture

The GUI spawns the Python relay server (consumer_server_cli.py) as a subprocess and:

• Captures stdout/stderr for real-time logs
• Parses log output to extract stats and client info
• Provides UI for server control and monitoring
• Maintains server state even if GUI crashes

See IMPLEMENTATION.md for detailed architecture.

Troubleshooting

Qt6 not found?

• Install Qt6 from https://www.qt.io/download-open-source
• Use default path: C:\Qt\6.8.0\msvc2022_64
• Run check-setup.bat to verify

Visual Studio not found?

• Install Visual Studio 2022 with C++ tools
• See SETUP.md

CMake error?

• Install CMake from https://cmake.org/download/
• Select "Add CMake to PATH" during install

Build fails?

• See SETUP.md for manual build instructions
• Review DEVELOPMENT.md for developer notes

Future Enhancements

• Player kick/ban buttons (via localhost admin port)
• Config file editor in GUI (Settings dialog)
• Admin commands (set time/weather directly from GUI)
• Ban reason dialog in GUI
• System tray icon with quick access
• Server history and logs export
• Installer (.msi or .exe wrapper)