docs: Initialize comprehensive project documentation
Migrates existing GDD and engine design notes from HacknPlan into a new Obsidian vault. This establishes a centralized, version-controlled knowledge base covering engine architecture, game constraints, design decisions, and open questions.
This commit is contained in:
@@ -0,0 +1,84 @@
|
||||
---
|
||||
tags:
|
||||
- engine
|
||||
- architecture
|
||||
---
|
||||
|
||||
# Engine Overview
|
||||
|
||||
## Scope
|
||||
|
||||
The **engine** is game-agnostic. It knows nothing about cards, towers, lanes or waves. It provides:
|
||||
|
||||
- the main loop and time model
|
||||
- windowing and platform services
|
||||
- input, rendering, assets and audio
|
||||
- a script host
|
||||
- scenes and an ECS world
|
||||
- RNG
|
||||
- debug tooling
|
||||
|
||||
The **game** layer defines everything specific to the tower defense deck-builder.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Main[Main.cpp] --> Game
|
||||
Game[Game layer<br/>cards · deck · towers · enemies · lanes · waves · run map] --> Engine
|
||||
Scripts[Content scripts<br/>Assets/Scripts] -. bound via .-> Game
|
||||
Engine[siege_engine<br/>loop · render · assets · audio · input · script host · scenes · ECS] --> Libs
|
||||
Libs[SDL3 · SDL_GPU · SDL_image · SDL_ttf · SDL_mixer · glm · EnTT · ImGui · spdlog]
|
||||
```
|
||||
|
||||
> [!important] Dependency rule
|
||||
> `Engine/` must never include anything from `Game/`. The CMake target split enforces this.
|
||||
|
||||
## Source layout
|
||||
|
||||
```
|
||||
Source/
|
||||
Engine/ static lib `siege_engine`
|
||||
Core/ Log, Assert, Result (std::expected), Id/Handle, StringId
|
||||
Platform/ Window, SDL init, paths (base/pref), file watcher
|
||||
Time/ FrameClock, SimClock, Timer, Tween
|
||||
Input/ InputState, ActionMap
|
||||
Render/ RenderDevice, SceneRenderer3D, Renderer2D, Camera, text
|
||||
Animation/ rigid node clips, animator
|
||||
Assets/ AssetManager, Handle<T>, loaders, hot reload
|
||||
Audio/ AudioSystem (buses, voice limiting)
|
||||
Script/ ScriptHost / backend (language TBD)
|
||||
Scene/ Scene, SceneStack
|
||||
Ecs/ World (entt::registry wrapper), common components
|
||||
Random/ Rng, RngStreams
|
||||
Debug/ ImGui layer, panel registry, script console, profiling
|
||||
Application.h/.cpp
|
||||
Game/ everything specific to siege-deck
|
||||
Main.cpp a few lines: build AppConfig, run the game
|
||||
```
|
||||
|
||||
## CMake targets
|
||||
|
||||
| Target | Kind | Links |
|
||||
|---|---|---|
|
||||
| `siege_engine` | static lib | SDL3 family, glm, EnTT, ImGui, spdlog, script runtime |
|
||||
| `siege_deck` | executable | `siege_engine` + `Game/` |
|
||||
| `siege_tests` (later) | executable | engine + game logic, headless |
|
||||
|
||||
## Principles
|
||||
|
||||
1. **No singletons.** `Application` owns every subsystem and passes an `EngineContext&` to scenes. That keeps code testable and allows a headless run (the existing `--frames N` flag).
|
||||
2. **Handles over shared ownership.** Assets are `Handle<T>` (index plus generation), not `Ref<T>`. See [[Assets]].
|
||||
3. **Instances reference definitions by ID.** A live tower stores a `DefId`, never a copy of its definition, so hot-reloaded content takes effect immediately.
|
||||
4. **Scripts on events, C++ per tick.** See [[Scripting]].
|
||||
5. **Single-threaded by design.** Asynchronous asset loading can come later behind the same API.
|
||||
6. **Recoverable errors are values; fatal ones are exceptions.** Loaders return `std::expected`: a broken asset or script logs an error and falls back, it doesn't crash. Startup failures and broken invariants throw from constructors and are caught once in `main`. See [[Decision Log#Error handling split]].
|
||||
|
||||
## Subsystems
|
||||
- [[Main Loop and Time]]
|
||||
- [[Scenes and ECS]]
|
||||
- [[Rendering]] and [[Rigid-Part Animation]]
|
||||
- [[Assets]]
|
||||
- [[Scripting]]
|
||||
- [[Randomness]]
|
||||
- [[Input]]
|
||||
- [[Audio]]
|
||||
- [[Debug and Tooling]]
|
||||
Reference in New Issue
Block a user