👉 How to set up a Windows computer for GnollHack development and build every modern client, its native libraries and its assets.
🏁 Start Here
The modern clients are one .NET MAUI app, GnollHackM, built in two steps: first the native solution win\win32\vs\GnollHack.sln, which compiles the game engine, makes the game data and converts the shared XAML files, and then GnollHackM itself. Every client is built on a Windows computer.
📢 Important: If you are new to the codebase, read Overview of Building GnollHack with .NET MAUI first. It explains how the native C library, the C# app and the build-time tools fit together. Skipping it is the most common reason a build fails.
- Overview of Building GnollHack with .NET MAUI — The two-step build, its solution platforms and its command-line alternatives
-
Instructions for Developing GnollHackM Project (.NET MAUI) — Why XAML is edited in
GnollHackX, and which C# rules the shared code follows - Known Working Build Setups — The Visual Studio, SDK and Xcode versions known to build the game
💡 Tip: Before setting up your computer, check Known Working Build Setups to make sure your operating system and SDK versions match a verified configuration.
📋 Setting Up a Computer
Do these once on a new computer, in this order:
- Install Visual Studio 2026 for .NET MAUI Development
- Clone Repository in Visual Studio
- Install Windows Subsystem for Linux — For the Android, iOS, Linux and macOS clients, whose game data is made in WSL
- Configure Visual Studio for Mobile Version Development — Visual Studio's connection to WSL, for the native solution's Linux projects
- Set Up SSH Access to the Mac for Native Libraries — For the iOS and macOS clients, whose game engine is compiled on a Mac
- Install Tile Sets and FMOD Sound Banks
- Install Secrets File
Smaller how-tos that the instructions refer to:
- Open GnollHack Solution in Visual Studio
- Open GnollHackM Solution in Visual Studio
- Rebuild Solution
- How to Add Environment Variable on Windows
- Add New Path to PATH Environment Variable on Windows
- Enroll for Apple Development Program (Mac) — Needed for releasing the iOS and macOS clients
🛠️ Building the Modern Clients
| Client | User Interface | Also Needs | Released As | Instructions |
|---|---|---|---|---|
| Windows (WinUI 3) | .NET MAUI on WinUI 3 | WSL only to convert edited XAML files | Steam and an MSIX package | Build Instructions for WinUI3 Version on Windows (.NET MAUI) |
| Android | .NET MAUI | WSL; an Android device | Google Play | Build Instructions for Android Version on Windows (.NET MAUI) |
| iOS | .NET MAUI | WSL; a Mac over SSH; an iPhone or iPad | App Store | Build Instructions for iOS Version on Windows (.NET MAUI) |
| Linux | .NET MAUI on Avalonia | WSL; the Avalonia port's .NET SDK | Steam and an AppImage | Build Instructions for Avalonia Linux Version on Windows |
| macOS | .NET MAUI on Avalonia | WSL; a Mac with Apple Silicon over SSH; the Avalonia port's .NET SDK | Steam, signed and notarized | Build Instructions for Avalonia macOS Version on Windows |
| Windows (Avalonia) | .NET MAUI on Avalonia | The Avalonia port's .NET SDK | Not released; a folder for testers | Build Instructions for Avalonia Windows Version on Windows |
The Avalonia clients use a newer .NET SDK than the others, pinned in win\win32\xpl\GnollHackM\Platforms\Avalonia\global.json; see Avalonia Port.
⚠️ Warning (Common Pitfall): Make sure that the .NET MAUI workload is fully installed in Visual Studio. A missing platform workload (Android or iOS) causes project loading errors.
🧩 Native Libraries and Assets
These are built apart from the clients, and the clients use the results:
- Building iOS and macOS Native Libraries over SSH — How the iOS and macOS game engines are compiled on a Mac over SSH, and how to fix that build
- Build Instructions for Native Crash Reporting — Rebuilding the three native crash reporting libraries, the build-time check, and updating Sentry
- SkiaSharp Build Instructions — Custom SkiaSharp builds, mainly for reference
- Updating Tileset for GnollHackM (.NET MAUI) — Making a new tile set for the modern clients
- Verify Mobile Sound Banks — Matching the mobile sound banks with the checksums the apps verify
🔧 Troubleshooting
- Troubleshooting Building GnollHack with .NET MAUI — Locked files, slow builds and command-line builds
- Troubleshooting Android Build Errors and Runtime Errors — Errors caused by a long repository path
Each Avalonia build page also has a Troubleshooting section of its own.