Commonwealth-Online-Public/host-gui/README.md

Commonwealth Online - Qt GUI Host

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

Quick Start

First time? Follow the Setup Instructions

Building

cd host-gui

# Check prerequisites
check-setup.bat

# Build
build.bat

Output: host-gui\build\bin\Release\CommonwealthOnlineHost.exe

Features

• Start/Stop Server: One-click server control with live status indicator
• Real-time Stats: Monitor uptime, connected players, packet rates
• Client List: Live table showing connected clients and their connection details
• Server Logs: Real-time log viewer with timestamps
• Dark Theme: Fallout 4-inspired dark UI with amber/green accents
• 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

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

From Visual Studio

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

From Command Line (Manual)

cd host-gui
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 Server"
3. Server will bind to 0.0.0.0:7777 (configurable in commonwealth-server.json)
4. View real-time logs and connected clients

Configuration

Edit commonwealth-server.json in the server folder to customize:

• host: Bind address
• port: Server port
• server_name: Display name
• max_players: Max player count
• log_verbosity: debug/info/warning/error

Layout

host-gui/
├── 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
│   ├── ServerProcess.h/cpp     # Subprocess manager for relay server
│   └── resources/
│       ├── resources.qrc       # Qt resource manifest
│       └── icons/
│           └── app.ico         # Application icon
└── 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

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