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:
2026-09-24 23:55:48 +02:00
parent bae6567842
commit 45b246c1d7
36 changed files with 1682 additions and 0 deletions
+45
View File
@@ -0,0 +1,45 @@
---
tags:
- engine
- ecs
---
# Scenes and ECS
## Scene stack
- `SceneStack` supports **push, pop and replace**.
- Each scene declares `blocksUpdate` and `blocksRender`.
- A pause menu or card-reward overlay on top of Combat blocks Combat's update but not its render.
- Scene callbacks: `OnEnter`, `OnExit`, `Update(dt)`, `FixedUpdate(dt)`, `Render(renderer, alpha)`.
- Scenes receive an `EngineContext&`; nothing is global.
Game-side scenes (examples, not engine code): MainMenu, RunMap, Combat, Shop, Reward.
## World (ECS)
- **One `World` (an `entt::registry` wrapper) per scene.** Leaving a combat throws its whole world away, which is simpler than cleaning up individual entities.
- **Run state is not ECS data.** Deck, relics, gold and map are plain C++ owned by the game and persist across scenes.
### Engine components
| Component | Purpose |
|---|---|
| `Transform3D` | vec3 position, quat rotation, vec3 scale (render space) |
| `PrevTransform` | for interpolation, see [[Main Loop and Time]] |
| `MeshRenderer` | model and material handles |
| `Animator` | rigid clip playback, see [[Rigid-Part Animation]] |
| `Tweened` | active tweens on this entity |
Gameplay components (`Health`, `Tower`, `LaneFollower`, `Targeting`, `StatusEffects`, …) live in `Game/`.
> [!note] Sim position vs render transform
> Gameplay systems write a 2D ground-plane position. A sync step turns it into the `Transform3D` render transform (adding height, facing and bobbing). The simulation never reads `Transform3D`.
## Events
- A **queued bus** wraps `entt::dispatcher` and flushes at the end of each fixed step.
- Deck-builders stack triggers ("when an enemy dies, draw 1"). Queueing gives a defined resolution order and stops handlers from mutating the world while a system is iterating it.
- The engine provides the bus; the game defines the event types and the trigger and effect resolution.
Related: [[Scripting]] (hooks fire from events)