Skip to content

Building

Jump to bottom
Peter Robinson edited this page Jun 27, 2026 · 3 revisions

Torque2D builds with CMake, which is the single source of truth for every platform. You generate a project (or Makefile) for your toolchain from the root CMakeLists.txt, then build it. The compiled executable is written to the repository root, next to main.cs.

Prerequisite on every platform: CMake 3.21 or newer. (The "Visual Studio 18 2026" generator needs CMake 4.x.) Install it from cmake.org or your package manager.

Running

Read this first — it trips everyone up. Whichever platform you build for (see below), the resulting executable must be run from the repository root, so that it can find main.cs and the script/asset trees (editor/, library/, toybox/, tools/). Run it from somewhere else and it won't find its content. On launch it opens the Project Manager. Once you've selected a project and it's running, you can bring up the in-engine console at any time with **Ctrl + ~** (tilde).

Build configurations

There are three configurations, mirroring the historical build:

  • Debug — unoptimized, with debug info; produces Torque2D_DEBUG.
  • Release — optimized; produces Torque2D.
  • Shipping — Release plus TORQUE_SHIPPING (compiles out the unit tests and dev-only code); produces Torque2D.

Multi-config generators (Visual Studio, Xcode) pick the configuration at build time with --config <cfg>. Single-config generators (Makefiles) pick it at configure time with -DCMAKE_BUILD_TYPE=<cfg>.

Quick reference

Platform Generate Build
Windows generate-vs2022.bat (or generate-vs2026.bat) open the solution, or cmake --build build --config Debug
macOS ./generate-xcode.command Xcode (Cmd-R), or cmake --build build/xcode --config Debug
Linux ./build-linux.sh one-shot (configures and compiles)
Android open engine/compilers/android-studio ./gradlew assembleDebug
iOS cmake … -DCMAKE_SYSTEM_NAME=iOS … cmake --build build/ios --config Debug
Web ./generate-emscripten.sh (needs emsdk) cmake --build build/emscripten -j, then serve over HTTP

Windows

Prerequisites: Visual Studio 2022 (the free Community edition is perfect) or 2026. When you install it, make sure the "Desktop development with C++" workload is ticked — that's the part that actually compiles C++, and it's easy to skip by accident. You'll also need CMake (cmake.org).

  1. In File Explorer, open the Torque2D folder and double-click generate-vs2022.bat (or generate-vs2026.bat if you're on VS2026). A console window opens, runs CMake, and then opens the finished solution in Visual Studio for you — you don't need to know anything about CMake to get this far.
    • Prefer the command line? From the repo folder run cmake -S . -B build -G "Visual Studio 17 2022" -A x64 (use -A Win32 for a 32-bit build, or the "Visual Studio 18 2026" generator for VS2026).
  2. In Visual Studio, pick Debug or Release from the dropdown in the toolbar, then press F5 to build and run (or Ctrl+F5 to run without attaching the debugger). The first build takes a few minutes.
    • To build without opening Visual Studio at all: cmake --build build --config Debug (also Release / Shipping).

The Torque2D project is already set as the startup project, with its working directory pointed at the repo root, so it just runs. The finished Torque2D_DEBUG.exe (Debug) or Torque2D.exe (Release) lands at the top of the repository folder.

macOS

Macs come with one of two kinds of processor, and the engine has to be built for whichever one you have. Apple Silicon Macs use Apple's own "M" chips (M1, M2, M3, and newer — that's most Macs sold since late 2020); older Intel Macs use Intel chips. The two use different processor architectures (arm64 for Apple Silicon, x86_64 for Intel), so a build made for one won't run natively on the other. Not sure which you have? Click the Apple menu in the top-left corner of the screen, choose About This Mac, and look at the "Chip" (or "Processor") line — it will say either "Apple M…" or "Intel".

By default these steps build for Apple Silicon, which is what most people on a recent Mac want. If you're on an Intel Mac, follow Building for an Intel Mac just below instead.

Prerequisites: the full Xcode app — install it for free from the Mac App Store (the much smaller "Command Line Tools" by themselves are not enough). You'll also need CMake.

  1. In the Finder, open the Torque2D folder and double-click generate-xcode.command. This runs CMake and creates an Xcode project for you. (If macOS refuses to open it the first time, right-click the file and choose Open to confirm you trust it.)
    • Prefer the Terminal? From inside the repo folder, run ./generate-xcode.command (or cmake -S . -B build/xcode -G Xcode).
  2. Open the project that was created in Xcode, make sure Torque2D is the selected scheme near the top-left of the window, and press Cmd-R to build and run. The first build takes a few minutes.

This produces a ready-to-run, code-signed Torque2D_DEBUG.app at the top level of the repository folder, and launches it. Torque finds main.cs right next to the app automatically, so there's nothing extra to copy. (You can also build from the Terminal with cmake --build build/xcode --config Debug.)

A macOS .app must be launched the normal way — double-click it, use Open, or run it from Xcode — not by reaching inside the bundle to run the raw program file.

Building for an Intel Mac

If About This Mac says Intel, add one option when you generate the project so CMake builds for the Intel architecture. From the Terminal, in the repo folder:

cmake -S . -B build/xcode -G Xcode -DCMAKE_OSX_ARCHITECTURES=x86_64

Then build it the same way as before — open the project in Xcode and press Cmd-R, or run cmake --build build/xcode --config Debug.

Want one app that runs natively on both Apple Silicon and Intel Macs? That's called a universal build (useful if you plan to share the app with other people who might have either kind of Mac). Ask for both architectures at once:

cmake -S . -B build/xcode -G Xcode -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"

Linux (64- and 32-bit)

Grab the development packages first. On Debian/Ubuntu:

sudo apt install build-essential cmake nasm \
  libsdl1.2-dev libx11-dev libxft-dev libfreetype6-dev libopenal-dev libgl1-mesa-dev

One gotcha worth knowing up front: it's SDL 1.2, not SDL2. The X11 back-end calls SDL-1.2-only APIs, and some distros now ship the SDL2-based sdl12-compat shim under the old package name — which won't link. Build on a release that still carries genuine SDL 1.2 (Ubuntu 22.04 is a safe bet).

For a 64-bit build the easy path is the one-shot script — it configures, compiles, and drops the executable at the repo root in a single step:

./build-linux.sh [Debug|Release|Shipping]

Prefer to drive it yourself? Configure with ./generate-make.sh Debug, then cmake --build build/make -j$(nproc).

A 32-bit build is the same idea with a multilib twist: install the :i386 versions of the dev libraries alongside the multilib toolchain, then configure with -DCMAKE_C_FLAGS=-m32 -DCMAKE_CXX_FLAGS=-m32 -DCMAKE_EXE_LINKER_FLAGS=-m32 and PKG_CONFIG_PATH=/usr/lib/i386-linux-gnu/pkgconfig. (NASM earns its keep here — it assembles the 32-bit CPU-detection routine.)

Heads-up: actually seeing the window needs a real display and GL. Under WSL that means WSLg (or your own X server) — a headless box builds and links cleanly but never shows a window.

Android (arm64-v8a)

On Android the engine is built as a shared library (libtorque2d.so) and bundled into an APK. Gradle runs the whole show and calls CMake under the hood (the same root CMakeLists.txt), so you mostly work through Android Studio rather than touching CMake directly.

Prerequisites: Android Studio (or the command-line SDK), with NDK 25.2.9519653 and CMake 3.22.1 installed through the SDK Manager.

The simplest path is to open the engine/compilers/android-studio folder as a project in Android Studio and press Run. From a terminal, that same folder builds with ./gradlew assembleDebug.

For now the build targets arm64-v8a only — it's the one ABI we ship prebuilt FreeType and OpenAL for. The APK builds and runs: it's been verified on a real device (a Pixel 7 Pro on Android 13) — the engine starts up, loads its assets out of the APK, brings up OpenGL ES, and the editor renders with text. The only known gap is that a few stylized editor heading fonts render blank (see the Android Development Guide for the details); your normal UI text is fine.

iOS (arm64)

iOS builds, runs, and is verified on both the simulator and a real device (arm64) — the editor renders, the GUI scale is correct, and touch input works. You'll need the full Xcode app and CMake.

Generate and build for the simulator like this:

cmake -S . -B build/ios -G Xcode -DCMAKE_SYSTEM_NAME=iOS \
  -DCMAKE_OSX_SYSROOT=iphonesimulator -DCMAKE_OSX_ARCHITECTURES=arm64 \
  -DCMAKE_OSX_DEPLOYMENT_TARGET=12.0
cmake --build build/ios --config Debug

For a real device instead of the simulator, use ./generate-xcode-ios-device.command (it configures with -DCMAKE_OSX_SYSROOT=iphoneos). Supply your signing identity either with -DTORQUE_IOS_TEAM=<10-char team id> or by picking the team in Xcode's Signing & Capabilities tab; a free Apple ID works for running on your own device. The maintainer reference cmake/BUILD-PLATFORM-NOTES.md in the engine repo has the full device-signing notes.

Web (Emscripten / WebAssembly)

The Web target builds and runs in-browser. It needs the Emscripten SDK (emsdk); everything else goes through the same CMake build. Full walkthrough and limitations are in the Web Deployment Guide — the short version:

  1. Install and activate emsdk once, then activate it in your shell: 
    git clone https://github.com/emscripten-core/emsdk
cd emsdk && ./emsdk install latest && ./emsdk activate latest
source ./emsdk_env.sh        # emsdk_env.bat on Windows cmd
  2. From the repo root, configure with the helper (it runs emcmake), then build. A make program must be on your PATH. 
    ./generate-emscripten.sh                 # = emcmake cmake -S . -B build/emscripten -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug
cmake --build build/emscripten -j
  3. Run it by serving the output over HTTP (a browser won't load it from file://): 
    cd build/emscripten && python -m http.server 8000
# then open http://localhost:8000/Torque2D_DEBUG.html

The bundle is Torque2D_DEBUG.{html,js,wasm,data} in build/emscripten (it stays there — it's a web bundle, not run from the repo root like the desktop builds). Verified with emsdk 6.0.1.

Running the unit tests

The unit tests use GoogleTest and run inside the engine. Launch with the alternate boot script main.runAllUnitTests.cs (it calls runAllUnitTests() and quits), or call runAllUnitTests() directly from the console. Tests are compiled out of Shipping builds.

Maintainer reference: the authoritative per-platform recipes, caveats, and runtime-verification status live in the engine repo at cmake/BUILD-PLATFORM-NOTES.md.

Clone this wiki locally