Getting Started

Mosaic uses CMake as its build system. Most dependencies are managed via vcpkg, while those unavailable through vcpkg — such as WebGPU, utility libraries, or components requiring special build profiles — are included as submodules under the vendor/ directory.

On Windows, we recommend using Visual Studio 2022 over VS Code for better CMake integration. The default compiler on Windows is MSVC, but Clang is also supported — and is the preferred compiler on Linux and Web targets (via Emscripten).

Environment Setup

Tip

Before building Mosaic, you’ll need to set up a few tools and SDKs. The engine targets Windows, Linux, Web and Android but you can ignore requirements for the build configurations you’re not interested in.

Caution

Development for the Web is currently on hold due to ongoing instability in the WebGPU API. The API is still under heavy development and changes frequently, which makes maintaining a stable web build impractical at this time. Web support will resume once the WebGPU specification and tooling become more stable.

Note

Development for Android is currently on hold Due to significant technical challenges with Android’s GameTextInput and IME (soft keyboard) implementation.

Prerequisites

• CMake 3.25 or later
• Git — with submodule support
• Python 3 — required for Emscripten and some build scripts
• A C++23-compliant compiler (MSVC ≥ 17.13 Preview 2, Clang ≥ 13, or GCC ≥ 14)

Install vcpkg

We use vcpkg in manifest mode to manage most dependencies.

1. Clone vcpkg:

   git clone https://github.com/microsoft/vcpkg.git
   ./vcpkg/bootstrap-vcpkg.sh  # or .\bootstrap-vcpkg.bat on Windows

2. If needed, set the environment variable VCPKG_ROOT to point to your vcpkg directory.

Tip

No need to integrate VCPKG globally — Mosaic uses the local vcpkg.json manifest.

Setup for Web (Emscripten/WebGPU)

1. Install the Emscripten SDK:

   git clone https://github.com/emscripten-core/emsdk.git
   cd emsdk
   ./emsdk install latest
   ./emsdk activate latest
   source ./emsdk_env.sh  # or emsdk_env.bat on Windows

2. Ensure emcc is in your PATH before running CMake.

3. Confirm that -pthread, -matomics, and -mbulk-memory flags are supported — see build notes below if WebGPU issues arise.

Tip

We suggest debugging Emscripten builds directly inside the browser either using the built-in dev-tools or installing the WASM debugging plugin available on the Chrome Web Store. The project is automatically configured to generate teh relevant debug information.

Setup for Windows (Visual Studio 2022)

• Install Visual Studio 2022 with the following components:

  • “Desktop development with C++”
  • “C++ CMake tools for Windows”
  • “MSVC v143” or later
  • “Windows 10 or 11 SDK”

Setup for Linux

• Install required packages:

  sudo apt update
  sudo apt install build-essential cmake git ninja-build python3 python3-pip libx11-dev libxcursor-dev libxrandr-dev libxi-dev libgl1-mesa-dev libvulkan-dev

Setup for Android Experimental

1. Install Android Studio.

2. Inside the SDK Manager, install:

   • Android NDK (r23 or newer)
   • CMake and LLDB
   • SDK tools for API level 24+ (Vulkan support)

3. Set the environment variable ANDROID_NDK_HOME to point to your NDK installation.

Build Instructions

1. Clone the repository and initialize submodules. git clone --recurse-submodules https://github.com/WilliamKarolDiCioccio/mosaic.

2. Select a CMake configure preset, then a build preset (the vcpkg toolchain manages installation automatically).

3. Build the project — and you’re good to go!

Caution

When building for the Web, you might encounter issues related to threading support.

Mosaic uses the -pthread flag in Emscripten to enable Web Workers, which helps retain compatibility with native threading code. Occasionally, you may need to manually patch the build system to support this.

If the build fails with missing atomic features, add the following flag manually in the emdawnwebgpu.port.py file located at:

out/build/emscripten-${PROFILE}/\_deps/emdawnwebgpu-src/

Update the flags section as follows:

flags = ['-g', '-std=c++17', '-fno-exceptions']
flags += ['-matomics', '-mbulk-memory'] # <-- Add this line
flags += compute_library_compile_flags(settings)

This ensures compatibility with multi-threaded WebAssembly targets.

---

License

Mosaic is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0), a strong copyleft license that requires derivative works and networked software to remain open source under the same license. See the LICENSE.md file for full details.

Permissive	Commercial Use	Attribution Required	Copyleft (Same License)	Can Use in Closed Source
❌	✅	✅	✅	❌