Commonwealth-Online-Server/README.md

# 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/`](server/) folder and follow [server/README.md](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/`](server/) and is the supported way to host on Ubuntu, Debian, Arch Linux, CachyOS, Fedora, and similar distributions.

```bash
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](server/README.md) for systemd, journalctl, CRLF recovery, and admin-CLI usage

## Quick Start (GUI)

**First time? Follow the [Setup Instructions](SETUP.md)**

### Building

```bash
# 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](SETUP.md) for detailed instructions and troubleshooting.

## Building

### Quick Build

```bash
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)

```bash
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](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](SETUP.md)

**CMake error?**
- Install CMake from https://cmake.org/download/
- Select "Add CMake to PATH" during install

**Build fails?**
- See [SETUP.md](SETUP.md) for manual build instructions
- Review [DEVELOPMENT.md](DEVELOPMENT.md) for developer notes

## Future Enhancements

- [x] Player kick/ban buttons (via localhost admin port)
- [x] 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)