Vienna-WebGPU-Engine

Version: v0.6-beta Status: Active Development

Thesis snapshot: the engine state this work builds on is preserved unchanged on the thesis branch.

A cross-platform, WebGPU-based game engine designed for educational purposes. Built with modern graphics APIs, it provides hands-on learning in game engine development using the WebGPU standard.

What’s new in v0.6-beta: the WebGPU stack moved to wgpu-native v29.0.1.1 and Dawn chromium/7871 on a shared header generation, with the backend freely selectable (WGPU, DAWN, EMDAWN). Every example now also builds for the browser (live demos below), the scene editor runs fully client-side on the web, lighting gained per-camera light clustering, and the tutorial suite was rewritten (unlit forward shading, custom bind groups, glass with reflections and shadows, post-processing).

Platform Support

Platform Status Compiler Notes
Windows ✅ Working MSVC 2019+ Primary development platform
macOS ✅ Working Clang (Xcode CLT) Tested on Apple Silicon
Linux ✅ Working Clang Tested on Arch Linux Hyperland
Web ✅ Working Emscripten (emdawnwebgpu) WEBGPU_BACKEND=EMDAWN, see doc/WebShipping.md

Working = Actively developed and tested. Untested = May require fixes.

Live Demos

Every example runs in the browser as WebAssembly on WebGPU (recent Chrome/Edge; Firefox 141+, Safari 26+). Built and published by the Web Demos workflow on tagged commits.

Demo Link What it shows
Main Demo live Deferred renderer on the SeaKeep scene: clustered lights, shadows, IBL, day-night cycle (~58 MB download)
Scene Editor live The dockable editor; edits live in browser memory
Tutorial live The getting-started example scene
Multi View live Several cameras in split viewports

All demos: hlavacs.github.io/Vienna-WebGPU-Engine

Features

Quick Start

Prerequisites

Tool Windows macOS Linux
CMake 3.15+ Download brew install cmake sudo apt install cmake
Ninja Download brew install ninja sudo apt install ninja-build
C++17 Compiler Visual Studio 2019+ or Build Tools xcode-select --install sudo apt install build-essential
Python 3 (for emscripten) Download Pre-installed sudo apt install python3

Installation

# 1. Clone repository
git clone https://github.com/hlavacs/Vienna-WebGPU-Engine.git
cd Vienna-WebGPU-Engine

# 2. Initialize submodules
git submodule update --init --recursive

# 3. Install Python dependencies (optional)
pip install -r requirements.txt

Note: If you are building on Linux or WSL, make sure your repository uses LF line endings. It is recommended to configure Git before cloning:

git config --global core.autocrlf input

If you already cloned the repository and encounter “cannot execute: required file not found”, you can fix the scripts with:

sudo apt install dos2unix
dos2unix scripts/*.sh

Building

  1. Open project in VS Code
  2. Press Ctrl+Shift+B (Windows/Linux) or ⌘+Shift+B (macOS)
  3. Select a build task:
    • Build Example: Main Demo (Debug)
    • Build Example: Tutorial (Debug)
  4. Press F5 to build and debug (You may have to select the correct project)

Option 2: Command Line

Windows:

scripts\build-example.bat main_demo Debug WGPU
scripts\build-example.bat tutorial Debug WGPU

macOS/Linux:

# First time only: make build scripts executable
chmod +x scripts/build-example.sh

# Then build
./scripts/build-example.sh main_demo Debug WGPU
./scripts/build-example.sh tutorial Debug WGPU

Output (per-backend build directories):

Option 3: IDE Setup

Visual Studio (Windows):

cmake -S . -B build_vs -G "Visual Studio 17 2022" -A x64
start build_vs\WebGPU_Engine.sln

Set example as startup project, enable C++ exceptions (Ctrl+Alt+E), press F5.

Xcode (macOS):

cmake -S . -B build_xcode -G Xcode
open build_xcode/WebGPU_Engine.xcodeproj

Select example scheme, press ⌘+R to run.

Documentation

Getting Started

Technical Reference

Tools

Path Management

The engine uses PathProvider for cross-platform path resolution:

// ✅ Application assets (example/assets/)
auto texture = PathProvider::getTextures("brick.png");
auto model = PathProvider::getModels("character.obj");

// ✅ Engine resources (engine/resources/)
auto shader = PathProvider::getResource("PBR_Lit_Shader.wgsl");

// ❌ Never use hardcoded paths
auto bad = "E:/Project/resources/texture.png";  // DON'T!
Type Debug Release
App Assets <example>/assets/ <exe>/assets/
Engine Resources <lib_project>/resources/ <dll>/resources/

See CorePrinciples.md for details.

Project Structure

Vienna-WebGPU-Engine/
├── include/engine/        # Public API headers
│   ├── core/              # Core systems (Handle, Identifiable, Versioned)
│   ├── resources/         # Resource management (Image, Material, Mesh)
│   ├── rendering/         # Rendering pipeline (Renderer, RenderPass)
│   ├── scene/             # Scene graph (Entity, Transform, Camera)
│   └── input/             # Input handling
├── src/engine/            # Engine implementation
├── resources/             # Engine shaders and built-in assets
├── examples/              # Example applications
│   ├── main_demo/         # Full-featured demo
│   ├── tutorial/          # Tutorial project
│   ├── multi_view/        # Multi-viewport demo
│   └── scene_editor/      # Scene editor (WIP)
├── external/              # Third-party dependencies
├── doc/                   # Documentation
└── scripts/               # Build automation

Known Limitations

Troubleshooting

Build Issues

“CMake not found”

# Verify installation
cmake --version

# Add to PATH or reinstall (see Prerequisites)

“Ninja not found”

# Verify installation
ninja --version

# Install via package manager (see Prerequisites)

“Visual Studio not found” (Windows)

“Xcode Command Line Tools not found” (macOS)

xcode-select --install
# Follow prompts, then restart terminal

Linux Graphics Issues

SDL Wayland/X11 Errors

If you encounter errors related to SDL video drivers or surface creation on Linux:

  1. Install SDL2 with video driver support: ```bash

    Ubuntu/Debian

    sudo apt-get install libsdl2-dev libwayland-dev libx11-dev

Fedora

sudo dnf install SDL2-devel wayland-devel libX11-devel

Arch

sudo pacman -S sdl2 wayland libx11


2. **If issues persist, force X11 mode:**
```bash
export SDL_VIDEODRIVER=x11
export DISPLAY=:0
./examples/build/tutorial/Linux/Debug/Tutorial

This is particularly useful on Wayland systems where SDL may not have proper Wayland support compiled in.

Contributing

Contributions welcome! This is an educational project:

Please read Engine Architecture and test on your platform before submitting PRs.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Happy Learning and Building! 🚀

This site is open source. Improve this page.