docs(gameengine): add README with build instructions and architecture overview

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-24 13:54:57 +00:00 · 2026-04-04 21:58:10 +01:00
parent a973b3cf8f
commit c0adf86740
1 changed files with 155 additions and 0 deletions
--- a/gameengine/README.md
+++ b/gameengine/README.md
@@ -0,0 +1,155 @@
+# GameEngine
+
+SDL3 GPU 2D/3D game engine with a JSON-driven workflow system. Built with C++20, using Conan for dependency management and CMake + Ninja for builds.
+
+## Quick Start
+
+### Prerequisites
+
+- C++20 compiler (MSVC, Clang, or GCC)
+- [CMake](https://cmake.org/) 3.24+
+- [Conan](https://conan.io/) 2.x
+- [Ninja](https://ninja-build.org/) (recommended)
+- Python 3.9+ (build helper)
+
+### Build & Run (Recommended)
+
+The `dev_commands.py` build helper runs the full pipeline: Conan install, CMake generate, configure, and build.
+
+```bash
+# Build and run the seed demo (auto-detects platform bootstrap)
+python python/dev_commands.py all --run
+
+# Equivalent explicit form on Windows
+python python/dev_commands.py all --run --bootstrap bootstrap_windows --game seed
+
+# macOS
+python python/dev_commands.py all --run --bootstrap bootstrap_mac --game seed
+
+# Linux
+python python/dev_commands.py all --run --bootstrap bootstrap_linux --game seed
+```
+
+### Build Steps (Manual)
+
+```bash
+# 1. Install Conan dependencies
+python python/dev_commands.py dependencies
+
+# 2. Generate CMakeLists.txt from cmake_config.json
+python python/dev_commands.py generate
+
+# 3. Configure CMake
+python python/dev_commands.py configure --preset conan-default
+
+# 4. Build
+python python/dev_commands.py build
+
+# 5. Run
+python python/dev_commands.py run -- --bootstrap bootstrap_windows --game seed
+```
+
+### Makefile (Unix)
+
+```bash
+make build                              # Build sdl3_app
+make build TARGET=sdl3_app              # Build specific target
+make test                               # Build and run all tests
+make rebuild                            # Clean + build
+make list-targets                       # Show available targets
+```
+
+## CLI Arguments
+
+The compiled `sdl3_app` binary accepts:
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--bootstrap` | `bootstrap_mac` | Platform bootstrap package |
+| `--game` | `standalone_cubes` | Game package to load |
+| `--project-root` | Current directory | Path to gameengine root |
+
+## Packages
+
+Game content and platform initialization are defined as JSON packages in `packages/`:
+
+| Package | Type | Description |
+|---------|------|-------------|
+| `bootstrap_windows` | bootloader | Windows init, SDL3 GPU with D3D12 |
+| `bootstrap_mac` | bootloader | macOS init, SDL3 GPU with Metal |
+| `bootstrap_linux` | bootloader | Linux init, SDL3 GPU with Vulkan |
+| `seed` | game | FPS demo: room with spinning cube, WASD movement, mouse look, jump. Bullet3 physics |
+| `standalone_cubes` | game | 11x11 grid of spinning colored cubes with per-cube animation offsets |
+| `quake3` | game | Quake 3 BSP map viewer with FPS controls |
+| `soundboard` | game | Audio cues + GUI controls |
+| `engine_tester` | game | Validation tour with teleport checkpoints, captures, and diagnostics |
+| `asset_loader` | library | Universal asset loading with cross-engine unit conversion (JSON-driven) |
+| `assets` | library | Shared runtime assets (audio, fonts, images) |
+| `materialx` | library | MaterialX integration |
+
+## Architecture
+
+```
+src/
+  main.cpp                          # Entry point, CLI parsing, workflow bootstrap
+  services/
+    interfaces/                     # Abstract service interfaces (16 services)
+      i_audio_service.hpp
+      i_graphics_service.hpp
+      i_input_service.hpp
+      i_physics_service.hpp
+      i_scene_service.hpp
+      i_window_service.hpp
+      i_workflow_executor.hpp
+      ...
+    impl/                           # Concrete implementations
+      workflow/                     # Workflow step implementations
+      diagnostics/                  # Logging
+      app/                          # CLI, platform services
+
+packages/                           # JSON-driven game content
+  {package}/
+    package.json                    # Package metadata, config, shader list
+    workflows/*.json                # Workflow definitions (v2.2.0 format)
+    shaders/spirv/                  # SPIR-V shaders (Vulkan, D3D12)
+    shaders/msl/                    # Metal shaders (macOS)
+    scene/*.json                    # Scene definitions
+    assets/                         # Package-specific assets
+
+python/
+  dev_commands.py                   # Build helper CLI
+  generate_cmake.py                 # CMakeLists.txt generator from cmake_config.json
+  export_room_gltf.py              # Seed demo room glTF exporter
+```
+
+## Dependencies (Conan)
+
+| Library | Version | Purpose |
+|---------|---------|---------|
+| SDL | 3.2.20 | Windowing, input, GPU API |
+| Bullet3 | 3.25 | 3D physics |
+| Box2D | 3.1.1 | 2D physics |
+| EnTT | 3.16.0 | Entity Component System |
+| Assimp | 6.0.2 | 3D model import |
+| glm | 1.0.1 | Math library |
+| nlohmann_json | 3.11.3 | JSON parsing |
+| RapidJSON | cci.20230929 | JSON parsing (performance) |
+| FFmpeg | 8.0.1 | Audio/video decoding |
+| FreeType | 2.13.2 | Font rendering |
+| Cairo | 1.18.0 | 2D vector graphics |
+| stb | cci.20230920 | Image loading |
+| LunaSVG | 3.0.1 | SVG rendering |
+| libzip | 1.10.1 | ZIP archive support |
+| cpptrace | 1.0.4 | Stack traces |
+| CLI11 | 2.6.0 | Command-line parsing |
+| GTest | 1.17.0 | Testing framework |
+
+## Testing
+
+```bash
+# Via Makefile
+make test
+
+# Via dev_commands.py
+python python/dev_commands.py build --target test_exit_step
+```