Chapter 1 · The Landscape & the Plan

Milestone: no engine code yet — this chapter is the map and the setup. By its end you'll understand the one idea the entire series rests on, know exactly what this first book delivers, and have every tool installed to build it — on Windows, Linux, macOS, and mobile.

A note on the code, up front. This series ships no finished codebase — there is no git clone that hands you the engine done. Every line you need is printed in these chapters; you copy it from the page, or you type it yourself. That's deliberate. Programmers don't really want someone else's finished product to import — they want to make things their own. So what this book gives you is a template: a proven structure and the code to stand it up, which you then bend into an engine that's yours. Copy it verbatim to start, then change everything. By the last page, the code in your editor is your engine, not a package you depend on.

1.1 Five APIs, one problem

Sit down to write a renderer today and the first decision is also the hardest: which graphics API? Pick DirectX 12 and you have abandoned everyone not on Windows. Pick Metal and you are Apple-only. Pick Vulkan and you have signed up for its ceremony on every platform, including the ones where a simpler API would have done. Pick OpenGL and you are comfortable and portable right up until you need something modern, or you need to ship on a platform that has quietly deprecated it.

There is no right answer to that question, because it is the wrong question. A real engine does not pick one API. It supports the ones its platforms need — DirectX 12 and Vulkan on Windows, Vulkan on Linux, Metal on Apple hardware, OpenGL ES on older mobile — and it does so without rewriting the engine five times.

The naive way to support five APIs is to write five renderers. That way lies madness: five copies of every feature, five places for every bug, five times the work for every new capability, and shader code smeared across four incompatible languages. Nobody ships that and stays sane.

The sane way is an abstraction: a single interface that the whole engine talks to, with a thin implementation per API hidden behind it. Get that interface right and the engine is written once; each backend is a self-contained module that teaches one API to speak the engine's language. Get it wrong and the abstraction leaks — API-specific assumptions bleed upward, and you are back to five renderers wearing a trench coat.

Getting it right is the through-line of this series. We call the interface the RHI — the render hardware interface — and it is the single most important thing we build.

1.2 The RHI: one boundary, drawn on purpose

Picture a horizontal line through the engine. Above it: everything that decides what to draw — sprites, tilemaps, meshes, cameras, the 2D and 3D renderers, the game itself. Below it: everything that knows how a particular GPU draws — the DirectX 12 command lists, the Vulkan descriptor sets, the Metal argument buffers, the OpenGL state machine.

The RHI is that line. It is a small, deliberate interface: create a device, create a swapchain, make buffers and textures, build a pipeline from shaders, record commands, submit, present. Nothing in it names a specific API. Nothing above it is allowed to.

Design lesson — an abstraction earns its keep at the second implementation. A boundary you can only see one side of is a guess. The first backend will make the RHI look done; the second will tell you whether it actually is. That is why this series adds a second backend early — in this very book, at Chapter 18 — not to support more platforms yet, but to prove the line is in the right place before we build a mountain of engine on top of it.

Two properties make or break the RHI, and we will return to them constantly:

• Nothing leaks. No DirectX type, no Vulkan handle, no GL enum appears above the line. The compiler enforces it: the engine simply does not include those headers. If engine code above the RHI cannot name an API type, it cannot accidentally depend on one.
• It exposes the modern shape, not the lowest common denominator. The temptation with a multi-API abstraction is to flatten everything to what the oldest API can do. That throws away the reason to use the modern ones. The RHI's job is to expose explicit, modern concepts — command recording, pipeline state objects, explicit resource lifetimes — coherently, and let each backend map them to its API. OpenGL will have to emulate some of what DirectX 12 and Vulkan express natively; that is the backend's problem to solve, not the engine's to avoid.

If those two sentences sound like a lot to ask of one interface — they are. Most of the craft in this book is in exactly where that line falls.

1.3 The shader problem, and our answer

An abstraction over the API solves half the multi-backend problem. The other half is shaders.

A shader is a program that runs on the GPU, and every API wants it in a different language: HLSL for DirectX, MSL for Metal, GLSL for OpenGL and its ES variant, and SPIR-V — a binary intermediate form — for Vulkan. Support five backends and a single triangle needs its shader in four languages. Multiply that by every shader in a real engine and hand-authoring is finished before it starts.

Real engines answer this with a common shader language: you author each shader once, in one language, and a tool converts it to whatever each backend needs. That tool is a small compiler — a frontend that parses your language into a typed intermediate representation, and a set of backends that emit HLSL, SPIR-V, MSL, and GLSL from that IR, each with the reflection data the engine needs to bind resources correctly.

We build that compiler. We call the language the CSL and the tool shaderc, and — this matters — we build it early, in Book 2, the moment the second backend makes hand-authoring untenable. It is not a bonus chapter tacked on at the end; it is load-bearing infrastructure that everything after it depends on. It is also, frankly, one of the most fun things in the whole series: writing a language and watching one source file become four.

1.4 What we build, and in what order

Here is the shape of the whole series, so every chapter has a place to sit.

• This book — Foundations. The platform layer, the RHI, and then — the whole point — all five backends behind that one interface, a 2D engine, and a playable cross-platform RPG that runs on every one of them.
• Book 2 — Shaders & the Common Shader Language. Book 1 ends with the same shader hand-copied five times; Book 2 kills that wall — one CSL source, cross-compiled to GLSL/ESSL/HLSL/SPIR-V/MSL by a from-scratch shaderc.
• Book 3 — Into 3D. Depth, cameras, meshes, materials, lighting, terrain, water, sky.
• Book 4 — The Editor. A 3D scene editor for the world Book 3 renders: pick, gizmo, inspect, save an .ebscene, and play the level in-editor.
• Book 5 — Characters & Animation. Rigs, clips, skinning on the CPU and the GPU, and the sockets that hang a sword off a hand.
• Book 6 — Physics. A physics library written from scratch, not bound to someone else's — colliders, solvers, and a fighting game to prove it.
• Book 7 — Scripting & Embedded Languages. A host API and hot-reloadable native game modules, so gameplay iterates without rebuilding the engine — then C#, Lua and the game-as-data database that lets any of them drive it.
• Book 8 — Advanced 3D & Shaders. Bindless, mesh shaders, GPU-driven culling, compute — the work that locks the RHI's shape for good.
• Book 9 — The Trailing Backends. The three OpenGL ceilings, and what it costs to keep a backend that cannot follow.
• Book 10 — Shadows. Shadow maps done properly, measured against a path-traced ground truth.
• Book 11 — MeshEdit. A Blender-shaped modeller: a half-edge kernel, a modifier stack, UVs, and rigging that hands finished assets to Book 5.
• Book 12 — Modular Buildings. Pieces, sockets and snapping — building interiors and exteriors from parts, in the editor.
• Book 13 — Building the Engine. The engine turned on itself: the tooling, the build, and the parts a shipped engine needs that a book usually skips.
• Book 14 — Chernozem. The capstone. Everything above, pointed at one co-op game, networked and playable.
• Book 15 — Shipping. Packaging, performance, and getting to the stores.

The order is not arbitrary. Each book leaves the engine strictly more capable than the last. Book 1 proves the RHI the hard way — five backends, and a real game shipping on all of them — and that proof is exactly what turns the five hand-copied shaders into a debt worth paying; Book 2 pays it with the shader language. 3D, the editor, characters, physics and scripting then all build on that solid, backend-agnostic base, and the tools books after them are only possible because the engine underneath them is finished enough to build tools with. You cannot honestly write "migrate a real engine" or "make it fast" as chapter one — you have to earn those chapters by building the engine first. That is what a series buys us that a single book cannot.

1.5 What this book delivers

By the last page of Book 1 you will have, running on your own machine:

• a window and event loop that behaves the same across operating systems;
• an input and timing layer, and the frame loop that drives everything;
• the RHI — the graphics boundary the entire series rests on;
• all five graphics backends behind that one interface — OpenGL, OpenGL ES, Direct3D 12, Vulkan, and Metal — each proven by the same running app;
• a 2D engine (sprites, text, tilemaps, an entity system, scenes) and a playable cross-platform RPG built on it; and
• the project and cross-platform CMake set up properly, plus CI that builds and tests on every platform — and the five hand-kept shader copies that are the standing motivation for Book 2's shader language.

We choose our first backend in the next chapter, when we set up the toolchain. Because everything above the RHI is backend-neutral, that choice is not a lock-in — it is simply where we get our first pixels. The other four arrive later in this same book, behind the same interface.

Gotcha — the abstraction you design without a second backend is fiction. We will spend real effort in this book on an RHI with exactly one implementation behind it. Keep a healthy suspicion of it until Book 2, where the second backend audits every decision we are about to make. Where I am confident a choice is backend-neutral, I will say so; where I am guessing, I will say that too.

1.6 What you'll install

The rest of this chapter gets your machine ready — thoroughly, and in one place, so the rest of the book is uninterrupted. It's long because we're a cross-platform engine and "set up your environment" genuinely means five platforms' worth of tools. Everything here is free.

You will not install five graphics SDKs today. Each backend's SDK — the DirectX Agility SDK, the Vulkan SDK, and so on — is installed when the chapter that needs it arrives, and our build fetches or pins what it can. Right now we install the common toolchain — a compiler, CMake, Ninja, Git, and Python — plus whichever platform toolchains you intend to target.

Set up the platform(s) you have now; come back for the others when you want them. Start with your primary desktop OS.

1.7 Windows: Visual Studio & the toolchain

Windows is the most common starting point, and Visual Studio does most of the work for you.

1. Install Visual Studio. Download Visual Studio 2022 or 2026 Community (free) from visualstudio.microsoft.com and run the installer.
2. Pick the C++ workload. On the Workloads screen, check "Desktop development with C++." That one workload installs the MSVC compiler, the Windows SDK, and bundled copies of CMake and Ninja — most of your toolchain in a single box.
3. Confirm two components. Switch to the Individual components tab and make sure "C++ CMake tools for Windows" is checked (it brings CMake + Ninja). Optionally check "C++ Clang tools for Windows" to get a second compiler; compiling under both MSVC and Clang catches far more bugs than either alone.
4. Prefer no IDE? Install "Build Tools for Visual Studio" instead of the full product — same compiler and SDK, no editor. This is what CI machines use.
5. Git (and Git Bash): winget install Git.Git, or from git-scm.com. Git for Windows includes Git Bash, a Unix-style shell — use it to run this book's commands. They're written Unix-style (ls, ./sandbox, forward slashes), which work as-is in Git Bash (or WSL) but need translating in PowerShell or cmd. On Windows, treat Git Bash as part of the toolchain.
6. Standalone tools (optional). If you skipped the bundled ones: winget install Kitware.CMake Ninja-build.Ninja. A separate LLVM/Clang: winget install LLVM.LLVM.

Using the compiler from a terminal. MSVC needs its environment set up. The simplest path is to open the "x64 Native Tools Command Prompt for VS" from the Start menu — it puts cl on PATH — or just let CMake's Visual Studio generator handle it for you (Chapter 2), which needs no special prompt.

1.8 Linux, via WSL (or native)

You don't need a second computer to build for Linux — Windows Subsystem for Linux runs a real Ubuntu on your Windows machine, and it's exactly how this book's Linux results were produced.

Our reference Linux is Ubuntu (WSL's default). Every sudo apt … command in this book is precisely what you type on Ubuntu — and note it's sudo apt install <package>, not a bare install (that's an unrelated file-copy tool). On other distributions, swap the package manager: Fedora sudo dnf install …, Arch sudo pacman -S …; package names occasionally differ but the tools are the same.

1. Install WSL. In an Administrator PowerShell: wsl --install. That enables WSL2 and installs Ubuntu by default. Reboot when asked, then launch Ubuntu from the Start menu and create your Linux username and password.
2. Update and install the toolchain, inside the Ubuntu shell:

   sudo apt update && sudo apt upgrade -y
   sudo apt install -y build-essential clang cmake ninja-build git
   

   build-essential brings GCC and Make; clang gives you a second compiler for free.
3. Where your files live. Your Windows drives appear under /mnt — E:\enginebook is /mnt/e/enginebook. You can build there directly. For faster builds you can instead git clone into your Linux home (~), because the Linux-native filesystem is quicker than the Windows bridge; either works.
4. Driving it from Windows. From a Windows terminal you can run a Linux command without opening the Ubuntu shell: wsl -- cmake --version. (From Git Bash specifically, prefix MSYS_NO_PATHCONV=1 so it doesn't rewrite the Unix paths.)

On a native Linux machine the steps are just 2 onward. Fedora: sudo dnf install gcc-c++ clang cmake ninja-build git. Arch: sudo pacman -S base-devel clang cmake ninja git.

A Linux command primer

If you're mainly a Windows or macOS developer, here is the working set of shell commands this book actually uses. It's not a Linux course — just enough to be fluent in the terminal.

sudo runs a command with administrator rights (it'll ask your password); ~ is your home directory; $VAR reads an environment variable; and ~/.bashrc is the script that runs when a shell opens — the place to put export lines you want every session.

Optional: passwordless sudo

Every sudo prompts for your password. On a personal machine — and WSL in particular — many developers turn that prompt off for convenience. It's entirely optional and it's a security trade-off: NOPASSWD:ALL lets anything running as your user become root with no prompt, which is fine on a private dev box but not on a shared or production machine.

Do it the safe way — a dedicated drop-in file (never edit /etc/sudoers directly), with a syntax check so you can't lock yourself out:

echo "$USER ALL=(ALL) NOPASSWD:ALL" | sudo tee /etc/sudoers.d/$USER
sudo chmod 0440 /etc/sudoers.d/$USER
sudo visudo -c          # confirms the sudoers files still parse OK

Open a new shell, then verify with sudo -n true (exit status 0 means no password is needed). Prefer to keep it narrow — just package installs, nothing else? Scope the rule instead:

echo "$USER ALL=(ALL) NOPASSWD: /usr/bin/apt, /usr/bin/apt-get" | sudo tee /etc/sudoers.d/$USER-apt
sudo chmod 0440 /etc/sudoers.d/$USER-apt

To undo either, remove the file: sudo rm /etc/sudoers.d/$USER (or …-apt).

Seeing a Linux window on your Windows desktop (X11 / WSLg)

Later in the book the engine opens a window. When you build under WSL, that window must appear on your Windows desktop — and that's the job of an X server: the display server of the X Window System ("X11"), the protocol Linux GUIs use to put pixels on screen. (Modern systems also use Wayland; WSL supports both.)

Windows 11 — nothing to install (WSLg). Windows 11's WSL bundles WSLg, a built-in display server. Linux GUI apps — X11 and Wayland — just launch and appear as ordinary Windows windows, with GPU acceleration and audio. Confirm it works:

sudo apt update && sudo apt install -y x11-apps mesa-utils
xeyes      # command from x11-apps  — a pair of eyes pops up on your desktop
glxgears   # command from mesa-utils — spinning gears; prints the frame rate

Note the test programs live inside packages: xeyes ships in x11-apps and glxgears in mesa-utils — there is no package literally named xeyes (apt will say so and point you at x11-apps). If those windows appear, your Linux GUI and OpenGL are ready — nothing else to do.

Habit — apt update before you install. On Debian/Ubuntu, apt installs from a cached list of available packages. sudo apt update refreshes that list (it changes nothing installed); sudo apt upgrade is the separate step that actually updates your packages. Run apt update first and a surprising number of "package not found" and "wrong version" problems simply vanish. We chain it — sudo apt update && sudo apt install … — throughout.

Windows 10 — run a third-party X server. Windows 10's WSL has no built-in display, so you run an X server on the Windows side:

1. Install VcXsrv (free). Launch XLaunch → Multiple windows → display number 0 → Start no client → and, important for WSL2, check Disable access control.
2. Point DISPLAY at the Windows host — WSL2 is on its own virtual network, so localhost won't do. Add to ~/.bashrc:

   export DISPLAY=$(ip route show default | awk '{print $3}'):0.0
   

3. Allow VcXsrv through the Windows Firewall (both Private and Public), or WSL2 can't reach it.
4. Test with xeyes. OpenGL through VcXsrv is limited; you may need software rendering (export LIBGL_ALWAYS_SOFTWARE=1, slower). This friction is exactly what WSLg removes — use Windows 11 if you can.

Building GUI apps needs the X development headers. Displaying an X app is one thing; compiling against X needs the dev libraries — libx11-dev and its companions, plus libgl1-mesa-dev for OpenGL. We install the exact set in the platform-layer chapter, where the engine first opens a window; they're noted here so the X picture is complete.

1.9 macOS: Xcode & Homebrew

macOS is required for the Metal backend and for building to Apple devices.

1. Install Xcode from the Mac App Store (it's large — it carries the Metal toolchain, the SDKs, and code-signing). Launch it once to finish setup, then accept the license: sudo xcodebuild -license accept.
2. Command-line tools: xcode-select --install. If you have full Xcode, point the tools at it with sudo xcode-select -s /Applications/Xcode.app.
3. Homebrew (the package manager), from [brew.sh], then the build tools:

   brew install cmake ninja git
   

4. Verify: xcodebuild -version, cmake --version, ninja --version.

1.10 Building on a Mac remotely (SSH / Remote Login)

You'll often want to build and test on a Mac from your main desktop — for the Metal backend and for Apple-device builds — without switching machines. macOS has a built-in SSH server; enabling it is what makes remote builds (and the automated verification used in this book) possible.

On the Mac, one time:

1. Turn on the SSH server. System Settings → General → Sharing → Remote Login → On. Under "Allow access for," you can restrict it to your user. (CLI equivalent: sudo systemsetup -setremotelogin on.)
2. Find the Mac's address on your network — either works:
   • name: scutil --get LocalHostName → use <name>.local
   • IP: ipconfig getifaddr en0 (Wi-Fi) or en1 (Ethernet)

From your desktop, set up passwordless login (so builds don't stop for a password):

ssh-keygen -t ed25519            # only if you don't already have a key
ssh-copy-id <user>@<name>.local  # installs your public key on the Mac
ssh <user>@<name>.local echo ok  # should print "ok" with no password prompt

Sync the source and build remotely. Because the repo is local, copy it up and drive the build over SSH:

rsync -az --delete --exclude build/ ./ <user>@<name>.local:~/enginebook/
ssh <user>@<name>.local 'cd ~/enginebook && cmake --preset ninja \
    && cmake --build --preset ninja-debug && ctest --preset ninja-debug'

Only enable Remote Login on networks you trust, and prefer key auth over passwords. These same steps, condensed, live in docs/remote-build.md.

1.11 Android (and iOS)

Mobile builds cross-compile — you build on a desktop or Mac, targeting the device.

• Android. Install Android Studio (developer.android.com/studio). In its SDK Manager, install the Android SDK, the NDK (Side by side), and CMake. Note the NDK path and expose it as an environment variable — ANDROID_NDK (for example, ~/Android/Sdk/ndk/<version>). Android builds use the NDK's own CMake toolchain file; we wire that up in the chapter that first targets Android. (No IDE, prefer the command line? Install the command-line tools and use sdkmanager to fetch the same packages.)
• iOS. Handled by Xcode on macOS (§1.9) — the iOS SDKs come with it. Device builds need an Apple developer account for signing; the simulator does not.

Neither is required to follow the desktop chapters; set them up when you reach the mobile ones.

1.12 Python (for tooling & asset generation)

Throughout the series we use small Python scripts as tooling — most visibly to generate assets. Rather than hand-draw every test sprite, texture, or data file, we write a few lines of Python to produce them procedurally: it's faster, it's reproducible, and it keeps opaque binary blobs out of the repo, since the script is the real source and the asset is regenerated on demand. Python also handles the occasional build or code-generation helper.

Install Python 3.10 or newer:

• Windows: winget install Python.Python.3.12, or from python.org — tick Add python.exe to PATH in the installer.
• Linux / WSL: usually already there; if not, sudo apt update && sudo apt install python3 python3-pip python3-venv.
• macOS: brew install python.

Then the two packages our asset tooling leans on — Pillow (image creation and manipulation) and NumPy (fast array math for procedural pixels and audio samples):

python -m pip install pillow numpy

Use python3 / pip3 on Linux and macOS if python isn't mapped. A virtual environment (python -m venv .venv) is optional but tidy; we mention it when a script needs a specific set of packages.

1.13 Your editor & code intelligence

Any editor works — the build doesn't care. But if you want one recommendation that behaves the same on every platform we target, use Visual Studio Code: it's free, runs on Windows, Linux, and macOS alike, and pairs with C++ through the clangd (or CMake Tools + C/C++) extensions. It's the editor this book assumes when it mentions one, precisely because it's cross-platform. Strong alternatives — CLion, Visual Studio, Xcode — all work too.

Whatever you choose, prefer one that understands C++ through a language server like clangd. Our CMake setup emits a compile_commands.json (Chapter 2) that clangd reads to give accurate autocompletion, go-to-definition, and diagnostics — including across all five backends, because that database records exactly how each file is compiled.

1.14 Verify you're ready

On your desktop OS, each of these should print a version:

git --version
cmake --version      # expect 3.21 or newer
ninja --version
python --version     # or python3 --version
# and at least one compiler:
cl                   # Windows/MSVC (in an "x64 Native Tools" prompt)
clang++ --version
g++ --version

If they do, your machine is ready. You don't need every platform configured to continue — your primary desktop is enough to build the whole of Book 1; the Mac, Linux, and mobile setups matter only when a chapter reaches for them.

With the tools in place, we make the empty folder real: in the next chapter we lay out the repository and get the first build running — the ground everything else stands on.

In summary

No engine code yet: this chapter is the map and the setup. Five APIs are one problem, and the answer is a single boundary — the RHI — with a thin implementation per API behind it.

What the plan commits to:

• the RHI's two properties — nothing leaks (no D3D type, Vulkan handle, or GL enum above the line, enforced by the compiler), and it exposes the modern shape rather than the lowest common denominator;
• the shader answer — one language, the CSL, and a from-scratch compiler, shaderc, emitting HLSL, SPIR-V, MSL, and GLSL, built in Book 2 because Book 1 ends with the same shader hand-copied five times;
• what this book delivers — window and event loop, input and timing, the RHI, all five backends behind it, a 2D engine, a playable cross-platform RPG, and cross-platform CMake with CI;
• the toolchain — a C++20 compiler, CMake 3.21+, Ninja 1.10+, Git, and Python 3.10+ with Pillow and NumPy, plus setup for Windows, Linux, macOS, remote Mac builds, and mobile. No graphics SDKs today; each arrives with the chapter that needs it.

Verification is §1.14: each tool prints a version, and one desktop OS is enough to build the whole of Book 1.

The standing debt is stated plainly — an abstraction with one implementation behind it is fiction. Chapter 18 adds the second backend and audits every decision made before it.

Take it further

§1.14 verifies that the tools are installed, not that they work together. cl, clang++, cmake --version — each prints a banner, and a banner proves a binary is on PATH and nothing else. It does not prove MSVC can find the Windows SDK from the shell you happen to be in, that your Clang has a usable standard library beside it, or that CMake will pick a generator it can actually drive. The honest check is a five-line CMake project that configures, builds, and runs a main printing "ok" — because that is the first thing Chapter 2 does anyway, which is exactly why it isn't duplicated here. If you are setting up a machine that isn't yours, spend the extra ten minutes and build the hello project before you read on; a broken toolchain discovered in Chapter 4 looks like an engine bug.

There is no bootstrap script. No scripts/setup-windows.ps1, no scripts/setup-linux.sh — the setup is thirty paragraphs of prose because prose is what teaches you what got installed and why. That's the right trade for a first read and the wrong one for the fifth machine. Each platform's section collapses to about twenty lines of shell (winget install …, sudo apt install …, brew install …), plus a verification step that runs the smoke build above. An afternoon per platform, and the value is not the time saved — it's that the script is a checked record of the environment, where a chapter is only a described one.

Nothing here sets up a debugger. §1.13 gets you as far as a language server: clangd reads the compile_commands.json CMake emits and gives you navigation and diagnostics. It never tells you how to set a breakpoint. That's a real gap, because from Chapter 4 onward this book says "build and run it" on almost every page, and half of what you'll learn from those runs comes from stopping in the middle. A .vscode/launch.json with three configurations — cppvsdbg against build/bin/Debug/sandbox.exe on Windows, lldb on macOS, gdb on Linux — is an hour of work and it is missing for no better reason than that I had my debugger set up already and never wrote mine down.