Engine Architecture and Directory Layout: A Principal Engineer's Guide
A Comparative Survey of AAA Engine Source Trees and the Design Rationale Behind the Graphical Playground Engine
"Architecture is not the directory tree. The directory tree is the architecture made visible. Open any AAA engine and within thirty seconds you can read its philosophy off the file system."
Abstract
Game engine architecture usually gets discussed in terms of subsystems: renderers, physics, audio, animation. But before any code is written, a more concrete question shapes everything: how is the source tree organized? Where does a piece of code physically live, what is allowed to depend on it, and what does that dependency mean at compile-time, link-time, and runtime? This paper takes a close look at directory layout as an architectural tool. We survey the publicly documented source trees of seven canonical engines, Unreal Engine 5, Godot, id Tech 4 / Doom 3, O3DE, Bevy, Unity, and Cocos2d-x, and the publicly documented architectural philosophies of five proprietary AAA engines, Frostbite (DICE/EA), Decima (Guerrilla Games), Anvil (Ubisoft Montreal), Snowdrop (Ubisoft Massive), and RE Engine (Capcom). We pull out a taxonomy of five layout strategies, weigh the trade-offs of each, and present the Graphical Playground (GP) Engine layout: a hybrid that borrows Unreal Engine's Public/Private/Internal discipline and reshapes it for educational clarity, multi-backend pluggability, and declarative CMake builds via our custom orchestration layer (GPBT). It closes with the complete GP Engine repository topology, module anatomy, and the rationale for every directory we ship.
Keywords: engine architecture, directory layout, module system, build system, CMake, GPBT, public/private boundary, RHI, plug-in architecture, monorepo, dependency visibility