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

Qt GUI Host Development

This directory contains the native C++ Qt6 GUI application for hosting Commonwealth Online servers.

Quick Start for Developers

Prerequisites

1. Qt6.4+

   • Download from https://www.qt.io/download-open-source
   • Install to default location (C:\Qt\6.4.0) or adjust build.bat

2. Visual Studio 2022

   • Install C++ development tools
   • Required for MSVC compiler

3. CMake 3.20+

   • Download from https://cmake.org/download

4. Python 3.9+

   • Required for running the relay server subprocess
   • Add to PATH

Building

cd host-gui
build.bat

Or manually:

cd host-gui
mkdir build
cd build
cmake .. -G "Visual Studio 17 2022"
cmake --build . --config Release

Running

.\build\bin\Release\CommonwealthOnlineHost.exe

Project Structure

• CMakeLists.txt - Qt6 build configuration
• src/main.cpp - Application entry point
• src/MainWindow.h/cpp - Main UI window
• src/ServerProcess.h/cpp - Subprocess manager for relay
• src/resources/ - Icons and resources
• build.bat - Windows build script
• README.md - User documentation

Architecture

MainWindow

• Handles all UI elements (buttons, tables, labels, text areas)
• Manages server start/stop through ServerProcess
• Updates stats and client list in real-time
• Displays logs with timestamps

ServerProcess

• Spawns Python relay server as subprocess
• Captures stdout/stderr in real-time
• Parses log output
• Handles process lifecycle (start, stop, errors)

Communication

• Uses QProcess for subprocess management
• Parses CLI output for stats and client data
• Emits Qt signals for UI updates

Design Decisions

1. Subprocess Architecture: Server runs in separate process so GUI can restart/crash without affecting active connections

2. Python Relay: Uses existing Python CLI to avoid duplicating networking logic in C++

3. Live Logs: Captures and displays all server output for debugging and transparency

4. Minimal Dependencies: Qt6 core only, no additional frameworks or heavy dependencies

5. Dark Theme: Fallout 4-inspired styling with amber/green accents matches game aesthetic

Performance

• Startup: <1 second (just Qt6 initialization)
• Memory: ~50-100 MB baseline
• Executable Size: ~15-20 MB (with Qt6 DLLs included)
• CPU: Minimal, only updates on events

Next Steps

• Implement stats fetching via CLI JSON output
• Add admin command buttons (set time/weather)
• Config file editor panel
• System tray icon
• Settings panel
• Player kick/ban interface
• Logging export functionality
• Performance profiling and optimization

Troubleshooting

CMake can't find Qt6

Ensure Qt6 path is set in build.bat or CMake cache.

Build fails with MSVC errors

Check that Visual Studio 2022 with C++ tools is installed.

Python not found at runtime

Ensure Python 3.9+ is installed and in PATH. Restart the GUI or set PYTHON environment variable.

Application window appears but doesn't respond

Check console output or run from command line to see error messages.