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

Commonwealth Online Qt GUI - Setup Instructions

Quick Setup (3 Steps)

Step 1: Install Qt6

1. Download Qt6 from: https://www.qt.io/download-open-source

2. Run the installer and select:

   • ✓ Qt 6.8 (or latest 6.x)
   • ✓ MSVC 2022 64-bit component
   • Install to default location: C:\Qt\6.8.0\

3. After installation, verify the path exists:

   C:\Qt\6.8.0\msvc2022_64\lib\cmake\Qt6
   

Step 2: Verify Prerequisites

Run the setup checker:

cd host-gui
check-setup.bat

This verifies:

• ✓ CMake 3.20+
• ✓ Visual Studio 2022
• ✓ Qt6 installation

Step 3: Build

cd host-gui
build.bat

The script will:

1. Auto-detect Qt6 location
2. Configure CMake
3. Build Release executable
4. Output: host-gui/build/bin/Release/CommonwealthOnlineHost.exe

---

Detailed Setup (If Quick Setup Fails)

Manual Qt6 Installation

1. Download Qt Online Installer

   • Go to https://www.qt.io/download-open-source
   • Download "Qt Online Installer for Windows"

2. Run Installer

   • Create Qt account (free)
   • Select "Custom installation"
   • Under "Qt 6.8.0" (or latest):
     • ✓ MSVC 2022 64-bit
     • ✓ Qt 5compat (optional)
   • Under "Developer and Designer Tools":
     • ✓ CMake (if not already installed)
   • Click "Install"

3. Verify Installation

   • Check that this folder exists:

     C:\Qt\6.8.0\msvc2022_64\
     

   • Should contain:

     lib\cmake\Qt6\
     bin\
     include\
     plugins\
     

Manual CMake Installation

If CMake isn't found:

1. Download from: https://cmake.org/download/
2. Run installer
3. When prompted, select "Add CMake to PATH"
4. Restart your terminal/command prompt

Manual Visual Studio 2022 Installation

If Visual Studio 2022 isn't found:

1. Download from: https://visualstudio.microsoft.com/downloads/
2. Run installer
3. Select "Desktop development with C++"
4. Install

---

Building Manually (If Scripts Fail)

Command Line Build

cd host-gui
mkdir build
cd build

# Configure (replace path with your Qt6 location)
cmake .. -G "Visual Studio 17 2022" -DCMAKE_PREFIX_PATH="C:\Qt\6.8.0\msvc2022_64"

# Build Release
cmake --build . --config Release

Visual Studio IDE Build

1. Open Visual Studio 2022
2. File → Open → Folder
3. Select host-gui folder
4. Wait for CMake configuration
5. Build → Build All
6. Executable at: host-gui/build/bin/Release/CommonwealthOnlineHost.exe

---

Troubleshooting

"Qt6 not found"

Solution 1: Edit build.bat and update Qt6 search paths

• Find the line with PATHS_TO_CHECK
• Add your Qt6 installation path

Solution 2: Use manual CMake with explicit path

cmake .. -G "Visual Studio 17 2022" -DCMAKE_PREFIX_PATH="C:\path\to\your\Qt6"

"Visual Studio not found"

Make sure Visual Studio 2022 is installed with C++ development tools:

1. Open Visual Studio Installer
2. Modify your installation
3. Select "Desktop development with C++"
4. Click "Modify"

"CMake not found"

Add CMake to PATH:

1. Install CMake from cmake.org
2. Select "Add CMake to PATH"
3. Restart terminal

"Build fails with link errors"

Ensure you're using the matching MSVC version:

• Qt6 installed for MSVC 2022 64-bit
• Building with "Visual Studio 17 2022" generator
• Using Release build configuration

---

Running the Application

After successful build:

cd host-gui
start build\bin\Release\CommonwealthOnlineHost.exe

Or double-click:

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

---

Environment Setup (Advanced)

If you want to set up your environment permanently:

Windows Environment Variables

1. Press Win + X, select "System"
2. Click "Advanced system settings"
3. Click "Environment Variables"
4. Add or update:

   CMAKE_PREFIX_PATH = C:\Qt\6.8.0\msvc2022_64
   

5. Restart terminal

Then you can just run:

cd host-gui
mkdir build
cd build
cmake ..
cmake --build . --config Release

---

Next Steps After Build

Once you have a successful build:

1. Test the Application

   • Launch CommonwealthOnlineHost.exe
   • Click "Start Server"
   • Verify logs appear

2. Connect Clients

   • Run fake_client from server directory
   • Should see client in GUI table

3. Customize

   • Edit colors/styling in MainWindow.cpp
   • Add admin buttons in MainWindow.h/cpp
   • Extend ServerProcess for more features

---

Support

If you encounter issues:

1. Run check-setup.bat to verify prerequisites
2. Review output and error messages carefully
3. Check this troubleshooting guide
4. Try manual CMake command with explicit paths