From 45b246c1d799e6c1e71152caf89c8c68f1ae0f79 Mon Sep 17 00:00:00 2001 From: Erik Simon Date: Thu, 24 Sep 2026 23:55:48 +0200 Subject: [PATCH] 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. --- .gitignore | 2 + Docs/SiegeDeck/.obsidian/app.json | 1 + Docs/SiegeDeck/.obsidian/appearance.json | 1 + Docs/SiegeDeck/.obsidian/core-plugins.json | 33 +++ Docs/SiegeDeck/.obsidian/graph.json | 22 ++ Docs/SiegeDeck/.obsidian/workspace.json | 250 ++++++++++++++++++ Docs/SiegeDeck/Decision Log.md | 51 ++++ Docs/SiegeDeck/Engine/Assets.md | 45 ++++ Docs/SiegeDeck/Engine/Audio.md | 15 ++ Docs/SiegeDeck/Engine/Build Order.md | 18 ++ Docs/SiegeDeck/Engine/Debug and Tooling.md | 27 ++ Docs/SiegeDeck/Engine/Engine Overview.md | 84 ++++++ Docs/SiegeDeck/Engine/Input.md | 15 ++ Docs/SiegeDeck/Engine/Main Loop and Time.md | 58 ++++ Docs/SiegeDeck/Engine/Randomness.md | 31 +++ Docs/SiegeDeck/Engine/Rendering.md | 63 +++++ Docs/SiegeDeck/Engine/Rigid-Part Animation.md | 43 +++ Docs/SiegeDeck/Engine/Scenes and ECS.md | 45 ++++ Docs/SiegeDeck/Engine/Scripting.md | 103 ++++++++ Docs/SiegeDeck/GDD/Characters.md | 40 +++ .../Einheiten Karten oder Spawn Gebäude.md | 43 +++ .../SiegeDeck/GDD/Discussions/GDD Workflow.md | 24 ++ .../Grundlegende Gamedesign Fragen.md | 43 +++ .../GDD/Discussions/Stages und Mapgröße.md | 58 ++++ Docs/SiegeDeck/GDD/GDD.md | 79 ++++++ Docs/SiegeDeck/GDD/Ideas/Card Types.md | 115 ++++++++ .../Ideas/Characters with own Card Pools.md | 17 ++ Docs/SiegeDeck/GDD/Ideas/Enemy Archetypes.md | 21 ++ Docs/SiegeDeck/GDD/Ideas/Gameplay Loop.md | 88 ++++++ Docs/SiegeDeck/GDD/Ideas/Resources.md | 65 +++++ Docs/SiegeDeck/GDD/Ideas/Unit Archetypes.md | 28 ++ Docs/SiegeDeck/GDD/Inspiration.md | 51 ++++ Docs/SiegeDeck/GDD/Units.md | 23 ++ Docs/SiegeDeck/Game/Game Constraints.md | 23 ++ Docs/SiegeDeck/Home.md | 30 +++ Docs/SiegeDeck/Open Questions.md | 27 ++ 36 files changed, 1682 insertions(+) create mode 100644 Docs/SiegeDeck/.obsidian/app.json create mode 100644 Docs/SiegeDeck/.obsidian/appearance.json create mode 100644 Docs/SiegeDeck/.obsidian/core-plugins.json create mode 100644 Docs/SiegeDeck/.obsidian/graph.json create mode 100644 Docs/SiegeDeck/.obsidian/workspace.json create mode 100644 Docs/SiegeDeck/Decision Log.md create mode 100644 Docs/SiegeDeck/Engine/Assets.md create mode 100644 Docs/SiegeDeck/Engine/Audio.md create mode 100644 Docs/SiegeDeck/Engine/Build Order.md create mode 100644 Docs/SiegeDeck/Engine/Debug and Tooling.md create mode 100644 Docs/SiegeDeck/Engine/Engine Overview.md create mode 100644 Docs/SiegeDeck/Engine/Input.md create mode 100644 Docs/SiegeDeck/Engine/Main Loop and Time.md create mode 100644 Docs/SiegeDeck/Engine/Randomness.md create mode 100644 Docs/SiegeDeck/Engine/Rendering.md create mode 100644 Docs/SiegeDeck/Engine/Rigid-Part Animation.md create mode 100644 Docs/SiegeDeck/Engine/Scenes and ECS.md create mode 100644 Docs/SiegeDeck/Engine/Scripting.md create mode 100644 Docs/SiegeDeck/GDD/Characters.md create mode 100644 Docs/SiegeDeck/GDD/Discussions/Einheiten Karten oder Spawn Gebäude.md create mode 100644 Docs/SiegeDeck/GDD/Discussions/GDD Workflow.md create mode 100644 Docs/SiegeDeck/GDD/Discussions/Grundlegende Gamedesign Fragen.md create mode 100644 Docs/SiegeDeck/GDD/Discussions/Stages und Mapgröße.md create mode 100644 Docs/SiegeDeck/GDD/GDD.md create mode 100644 Docs/SiegeDeck/GDD/Ideas/Card Types.md create mode 100644 Docs/SiegeDeck/GDD/Ideas/Characters with own Card Pools.md create mode 100644 Docs/SiegeDeck/GDD/Ideas/Enemy Archetypes.md create mode 100644 Docs/SiegeDeck/GDD/Ideas/Gameplay Loop.md create mode 100644 Docs/SiegeDeck/GDD/Ideas/Resources.md create mode 100644 Docs/SiegeDeck/GDD/Ideas/Unit Archetypes.md create mode 100644 Docs/SiegeDeck/GDD/Inspiration.md create mode 100644 Docs/SiegeDeck/GDD/Units.md create mode 100644 Docs/SiegeDeck/Game/Game Constraints.md create mode 100644 Docs/SiegeDeck/Home.md create mode 100644 Docs/SiegeDeck/Open Questions.md diff --git a/.gitignore b/.gitignore index 0f973ec..eea23aa 100644 --- a/.gitignore +++ b/.gitignore @@ -45,3 +45,5 @@ imgui.ini .DS_Store *~ *.swp + +Docs/SiegeDeck/.trash/ diff --git a/Docs/SiegeDeck/.obsidian/app.json b/Docs/SiegeDeck/.obsidian/app.json new file mode 100644 index 0000000..9e26dfe --- /dev/null +++ b/Docs/SiegeDeck/.obsidian/app.json @@ -0,0 +1 @@ +{} \ No newline at end of file diff --git a/Docs/SiegeDeck/.obsidian/appearance.json b/Docs/SiegeDeck/.obsidian/appearance.json new file mode 100644 index 0000000..9e26dfe --- /dev/null +++ b/Docs/SiegeDeck/.obsidian/appearance.json @@ -0,0 +1 @@ +{} \ No newline at end of file diff --git a/Docs/SiegeDeck/.obsidian/core-plugins.json b/Docs/SiegeDeck/.obsidian/core-plugins.json new file mode 100644 index 0000000..639b90d --- /dev/null +++ b/Docs/SiegeDeck/.obsidian/core-plugins.json @@ -0,0 +1,33 @@ +{ + "file-explorer": true, + "global-search": true, + "switcher": true, + "graph": true, + "backlink": true, + "canvas": true, + "outgoing-link": true, + "tag-pane": true, + "footnotes": false, + "properties": true, + "page-preview": true, + "daily-notes": true, + "templates": true, + "note-composer": true, + "command-palette": true, + "slash-command": false, + "editor-status": true, + "bookmarks": true, + "markdown-importer": false, + "zk-prefixer": false, + "random-note": false, + "outline": true, + "word-count": true, + "slides": false, + "audio-recorder": false, + "workspaces": false, + "file-recovery": true, + "publish": false, + "sync": true, + "bases": true, + "webviewer": false +} \ No newline at end of file diff --git a/Docs/SiegeDeck/.obsidian/graph.json b/Docs/SiegeDeck/.obsidian/graph.json new file mode 100644 index 0000000..42a46ec --- /dev/null +++ b/Docs/SiegeDeck/.obsidian/graph.json @@ -0,0 +1,22 @@ +{ + "collapse-filter": true, + "search": "", + "showTags": false, + "showAttachments": false, + "hideUnresolved": false, + "showOrphans": true, + "collapse-color-groups": true, + "colorGroups": [], + "collapse-display": true, + "showArrow": false, + "textFadeMultiplier": 0, + "nodeSizeMultiplier": 1, + "lineSizeMultiplier": 1, + "collapse-forces": true, + "centerStrength": 0.518713248970312, + "repelStrength": 10, + "linkStrength": 1, + "linkDistance": 250, + "scale": 1, + "close": true +} \ No newline at end of file diff --git a/Docs/SiegeDeck/.obsidian/workspace.json b/Docs/SiegeDeck/.obsidian/workspace.json new file mode 100644 index 0000000..7b10ba8 --- /dev/null +++ b/Docs/SiegeDeck/.obsidian/workspace.json @@ -0,0 +1,250 @@ +{ + "main": { + "id": "c6ad48c4d87faead", + "type": "split", + "children": [ + { + "id": "dd3e919d5adca5d6", + "type": "tabs", + "dimension": 75.6, + "children": [ + { + "id": "ca9ae29dd35549a6", + "type": "leaf", + "state": { + "type": "markdown", + "state": { + "file": "Engine/Engine Overview.md", + "mode": "source", + "source": false + }, + "icon": "lucide-file", + "title": "Engine Overview" + }, + "group": "994c0f9c38f6b8e7" + } + ] + }, + { + "id": "81ff5c2ddea79443", + "type": "tabs", + "dimension": 24.4, + "children": [ + { + "id": "3ffd1b71ff5031fb", + "type": "leaf", + "state": { + "type": "graph", + "state": {}, + "icon": "lucide-git-fork", + "title": "Graph view" + }, + "group": "994c0f9c38f6b8e7" + } + ] + } + ], + "direction": "vertical" + }, + "left": { + "id": "c526f838c3013812", + "type": "split", + "children": [ + { + "id": "eb2dfb1df8634a0c", + "type": "tabs", + "children": [ + { + "id": "52a36e40b9c1e252", + "type": "leaf", + "state": { + "type": "file-explorer", + "state": { + "sortOrder": "alphabetical", + "autoReveal": false, + "showSearch": false, + "searchQuery": "" + }, + "icon": "lucide-folder-closed", + "title": "Files" + } + }, + { + "id": "2c43a3b8b250ec4b", + "type": "leaf", + "state": { + "type": "search", + "state": { + "query": "", + "matchingCase": false, + "explainSearch": false, + "collapseAll": false, + "extraContext": false, + "sortOrder": "alphabetical" + }, + "icon": "lucide-search", + "title": "Search" + } + }, + { + "id": "bef1b4e0dcac47ac", + "type": "leaf", + "state": { + "type": "bookmarks", + "state": { + "showSearch": false, + "searchQuery": "" + }, + "icon": "lucide-bookmark", + "title": "Bookmarks" + } + } + ] + } + ], + "direction": "horizontal", + "width": 200 + }, + "right": { + "id": "165c68de881d9c62", + "type": "split", + "children": [ + { + "id": "56bb9a9be0aad677", + "type": "tabs", + "children": [ + { + "id": "2d2d24ac04d84dfa", + "type": "leaf", + "state": { + "type": "backlink", + "state": { + "file": "GDD/GDD.md", + "collapseAll": false, + "extraContext": false, + "sortOrder": "alphabetical", + "showSearch": false, + "searchQuery": "", + "backlinkCollapsed": false, + "unlinkedCollapsed": true + }, + "icon": "links-coming-in", + "title": "Backlinks" + } + }, + { + "id": "9b473e8ba1177409", + "type": "leaf", + "state": { + "type": "outgoing-link", + "state": { + "file": "GDD/GDD.md", + "linksCollapsed": false, + "unlinkedCollapsed": true + }, + "icon": "links-going-out", + "title": "Outgoing links" + } + }, + { + "id": "aa2f1e787db366cd", + "type": "leaf", + "state": { + "type": "tag", + "state": { + "sortOrder": "frequency", + "useHierarchy": true, + "showSearch": false, + "searchQuery": "" + }, + "icon": "lucide-tags", + "title": "Tags" + } + }, + { + "id": "29c62914f1935eb6", + "type": "leaf", + "state": { + "type": "all-properties", + "state": { + "sortOrder": "frequency", + "showSearch": false, + "searchQuery": "" + }, + "icon": "lucide-archive", + "title": "All properties" + } + }, + { + "id": "8dc46f1b185ecc04", + "type": "leaf", + "state": { + "type": "outline", + "state": { + "file": "GDD/GDD.md", + "followCursor": false, + "showSearch": false, + "searchQuery": "" + }, + "icon": "lucide-list", + "title": "Outline" + } + } + ] + } + ], + "direction": "horizontal", + "width": 300, + "collapsed": true + }, + "left-ribbon": { + "hiddenItems": { + "switcher:Open quick switcher": false, + "graph:Open graph view": false, + "canvas:Create new canvas": false, + "daily-notes:Open today's daily note": false, + "templates:Insert template": false, + "command-palette:Open command palette": false, + "bases:Create new base": false + } + }, + "active": "ca9ae29dd35549a6", + "lastOpenFiles": [ + "Engine/sedb6yZpr", + "Engine/Main Loop and Time.md", + "Engine/Randomness.md", + "GDD/GDD.md", + "Home.md", + "Game/Game Constraints.md", + "Open Questions.md.tmp.234529.84c632e447bb", + "Home.md.tmp.234529.043e8195cd1a", + "GDD/Inspiration.md", + "GDD/Inspiration.md.tmp.234529.bae427cc494d", + "GDD/Units.md", + "GDD/Units.md.tmp.234529.78abac70c7e3", + "GDD/Characters.md", + "GDD/Characters.md.tmp.234529.9a90cdbaf210", + "GDD/Ideas/Enemy Archetypes.md", + "GDD/Ideas/Enemy Archetypes.md.tmp.234529.be6735876c7b", + "GDD/Ideas/Unit Archetypes.md", + "GDD/Ideas/Unit Archetypes.md.tmp.234529.e5a9149ef6cc", + "GDD/Ideas/Characters with own Card Pools.md", + "GDD/Ideas/Characters with own Card Pools.md.tmp.234529.42ebd48e29e2", + "GDD/Ideas/Resources.md", + "GDD/Ideas/Resources.md.tmp.234529.a8ac0f0ee74e", + "GDD/Ideas/Card Types.md", + "GDD/Ideas/Card Types.md.tmp.234529.13bf9d1c7f6f", + "GDD/Ideas/Gameplay Loop.md", + "GDD/Discussions/Stages und Mapgröße.md", + "GDD/Discussions/Einheiten Karten oder Spawn Gebäude.md", + "GDD/Discussions/Grundlegende Gamedesign Fragen.md", + "GDD/Discussions/GDD Workflow.md", + "Open Questions.md", + "Decision Log.md", + "Engine/Build Order.md", + "Engine/Debug and Tooling.md", + "Engine/Audio.md", + "Engine/Input.md", + "Engine/Scripting.md" + ] +} \ No newline at end of file diff --git a/Docs/SiegeDeck/Decision Log.md b/Docs/SiegeDeck/Decision Log.md new file mode 100644 index 0000000..9046426 --- /dev/null +++ b/Docs/SiegeDeck/Decision Log.md @@ -0,0 +1,51 @@ +--- +tags: + - decisions +--- + +# Decision Log + +Newest at the bottom. Status is one of: **accepted**, **proposed**, **rejected**, **superseded**. + +## Phased time model with a fixed-step simulation +- **Date:** 2026-09-23 · **Status:** accepted +- **Context:** rounds are a paused planning phase followed by a real-time wave ([[Game Constraints]]). +- **Decision:** a fixed 60 Hz `SimClock` (pausable, speed via extra steps) and a separate real-time `FrameClock` for UI; interpolated rendering. +- **Consequences:** planning is just speed 0; combat stays stable at every speed. See [[Main Loop and Time]]. + +## Seeded run generation, non-deterministic combat +- **Date:** 2026-09-23 · **Status:** accepted +- **Decision:** named RNG streams with our own distributions; no requirement for combat to replay bit-exactly. +- **Consequences:** floats are allowed in the simulation, and there's no lockstep constraint. See [[Randomness]]. + +## Grid with fixed lanes +- **Date:** 2026-09-23 · **Status:** accepted +- **Decision:** enemies follow predefined lanes; towers are placed on buildable tiles and never block paths. +- **Consequences:** no pathfinding system; lane following is a waypoint or spline walk. + +## Rigid-part 3D on SDL_GPU +- **Date:** 2026-09-23 · **Status:** accepted +- **Context:** we want 3D presentation without the engine and art cost of skeletal animation. +- **Decision:** render with SDL_GPU (not SDL_Renderer); models are rigid node hierarchies animated by glTF node clips plus procedural overrides; a `Renderer2D` overlay for the UI. +- **Consequences:** a shader build step (SPIR-V, Vulkan on Linux and Windows); instancing from the start; skinning deferred. See [[Rendering]], [[Rigid-Part Animation]]. + +## The simulation stays 2D +- **Date:** 2026-09-23 · **Status:** accepted +- **Decision:** gameplay positions are 2D on the ground plane; height is visual only. +- **Consequences:** gameplay code and scripts are unaffected by the 3D presentation. + +## C# not used for scripting +- **Date:** 2026-09-23 · **Status:** rejected +- **Reason:** CoreCLR hosting, an interop layer, fragile hot reload and runtime distribution cost too much for event-only content hooks. It would only fit as the main game language, which isn't the goal. + +## Scripting language shortlist +- **Date:** 2026-09-23 · **Status:** proposed +- **Decision:** the candidates are Lua (5.4 or Luau) and AngelScript, to be decided by a spike. See [[Scripting]]. + +## Error handling split +- **Date:** 2026-09-24 · **Status:** accepted +- **Context:** principle 6 of the [[Engine Overview]] ("errors as values") was written for loaders, then stretched to platform startup. There, it forced static `Create()` factories, private constructors, and move constructors with a "moved-from" flag, just to return non-movable things like the SDL context through `std::expected`. +- **Decision:** errors you can recover from are values; fatal errors are exceptions. + - `std::expected` for failures the caller really handles on the spot: loading assets, compiling scripts, parsing definitions. The caller falls back and keeps running, which hot reload depends on. + - Exceptions (`std::runtime_error` for now) for failures with nothing to fall back to: SDL/window/GPU startup, broken invariants. Thrown from constructors and caught once in `main`, which logs and exits with 1. +- **Consequences:** platform types are plain RAII classes: a constructor that throws, non-movable when they mean "exactly one" (`SdlContext`, `Window`), and no empty state. The STL throws anyway, so `-fno-exceptions` was never an option. Exceptions must not cross C callbacks (SDL, the script VM): script bindings need a catch boundary. diff --git a/Docs/SiegeDeck/Engine/Assets.md b/Docs/SiegeDeck/Engine/Assets.md new file mode 100644 index 0000000..6199f59 --- /dev/null +++ b/Docs/SiegeDeck/Engine/Assets.md @@ -0,0 +1,45 @@ +--- +tags: + - engine + - assets +--- + +# Assets + +## Handles, not shared pointers + +- Every asset is referenced by a typed `Handle` (index plus generation), **not** `Ref` / `shared_ptr`. +- Ownership stays with the `AssetManager`, so it's always clear when an asset is freed. +- **Hot reload** swaps the resource behind a handle, and every holder sees the new version automatically. + +## Asset types + +| Type | Source | Loader | +|---|---|---| +| `Texture` | PNG, JPG | SDL_image → GPU upload | +| `Model` | glTF 2.0 (`.glb`/`.gltf`) | cgltf or fastgltf (TBD) | +| `AnimationClip` | glTF node animations | same as Model | +| `Material` | parameters + textures | glTF material or script data | +| `Shader` / `Pipeline` | SPIR-V built from `Assets/Shaders` | see [[Rendering#Shaders]] | +| `Font` | TTF | SDL_ttf | +| `Sound`, `Music` | WAV, OGG | SDL_mixer | +| Script modules | see [[Scripting]] | script backend | + +## Paths + +- Assets resolve relative to `SDL_GetBasePath()/Assets`, which matches the existing post-build copy step. +- Saves and settings go to `SDL_GetPrefPath()`. + +## Hot reload (debug builds only) + +- Poll file modification times about twice a second; reload textures, models, shaders, sounds and scripts. +- Failed reloads keep the previous version and report the error in the debug UI. + +## Definition databases + +- `DefinitionDB` maps a `StringId` to a definition (`CardDef`, `TowerDef`, `EnemyDef`, …). +- Definitions are filled by the script loader (see [[Scripting]]). +- Instances store only the ID, so reloaded definitions take effect immediately. + +> [!question] Open +> glTF loader choice: cgltf (a single C header, simple) or fastgltf (C++20, faster, needs simdjson). Check nixpkgs availability under the same-version rule. See [[Open Questions]]. diff --git a/Docs/SiegeDeck/Engine/Audio.md b/Docs/SiegeDeck/Engine/Audio.md new file mode 100644 index 0000000..4a2876c --- /dev/null +++ b/Docs/SiegeDeck/Engine/Audio.md @@ -0,0 +1,15 @@ +--- +tags: + - engine + - audio +--- + +# Audio + +Built on SDL_mixer 3. + +- **Buses:** master, music, sfx, ui. Each has its own volume, saved with settings. +- **Voice limiting:** a per-sound maximum of concurrent voices plus a minimum retrigger interval, so twenty towers firing in the same tick don't produce twenty overlapping sounds. +- **Pause behaviour:** gameplay sounds follow `SimClock` (paused during planning); UI sounds and music don't. +- **Spatialisation:** simple pan and distance attenuation from the camera focus point is enough for a top-down tower defense. Full 3D audio isn't needed. +- Sounds and music are `Handle` assets (see [[Assets]]). diff --git a/Docs/SiegeDeck/Engine/Build Order.md b/Docs/SiegeDeck/Engine/Build Order.md new file mode 100644 index 0000000..1ad648a --- /dev/null +++ b/Docs/SiegeDeck/Engine/Build Order.md @@ -0,0 +1,18 @@ +--- +tags: + - engine + - roadmap +--- + +# Build Order + +- [ ] **1. Skeleton:** split CMake into `siege_engine` and `siege_deck`; write `Application`, `FrameClock`, `SimClock` and the main loop. `--frames N` keeps working. See [[Main Loop and Time]]. +- [ ] **2. RenderDevice:** SDL_GPU device and swapchain, the GLSL → SPIR-V build step, clear the screen, ImGui on `imgui_impl_sdlgpu3`. See [[Rendering]]. +- [ ] **3. Renderer2D:** sprite batch, text, debug overlay. +- [ ] **4. SceneRenderer3D:** glTF loading, instanced static meshes, camera, a ground-plane picking ray to a tile. +- [ ] **5. Scenes and ECS:** `SceneStack`, `World`, interpolated entities walking a hardcoded lane. See [[Scenes and ECS]]. +- [ ] **6. Scripting spike:** the same three test items in Lua/Luau and AngelScript, then pick one. See [[Scripting#Decision spike]]. +- [ ] **7. Content loading:** `DefinitionDB`, one tower and one enemy defined in script. **This completes the vertical slice.** +- [ ] **8. Card-hand UI:** input actions, tweens, drag and drop. +- [ ] **9. Rigid animation:** glTF node clips plus procedural aim and recoil. See [[Rigid-Part Animation]]. +- [ ] **10. Polish:** audio, hot reload, debug panels. diff --git a/Docs/SiegeDeck/Engine/Debug and Tooling.md b/Docs/SiegeDeck/Engine/Debug and Tooling.md new file mode 100644 index 0000000..656c612 --- /dev/null +++ b/Docs/SiegeDeck/Engine/Debug and Tooling.md @@ -0,0 +1,27 @@ +--- +tags: + - engine + - tooling +--- + +# Debug and Tooling + +## ImGui layer +Debug only; the game UI is built separately on `Renderer2D`. Subsystems register panels: + +- Entity inspector (components per entity) +- Simulation controls: pause, single-step, speed +- Script console and script error list (see [[Scripting]]) +- Asset list with hot-reload status (see [[Assets]]) +- Frame timings and draw and instance counts (see [[Rendering]]) +- RNG stream states (see [[Randomness]]) + +## Logging +spdlog with per-subsystem loggers (`engine`, `render`, `script`, `game`) and levels adjustable at runtime. + +## Profiling +Scoped CPU timers feed the timings panel. Tracy can be added later if needed. + +## Headless and smoke runs +- `--frames N` renders N frames and exits (already supported). +- Later: a headless mode with no window that runs the simulation only, for `siege_tests`. diff --git a/Docs/SiegeDeck/Engine/Engine Overview.md b/Docs/SiegeDeck/Engine/Engine Overview.md new file mode 100644 index 0000000..9d9ad4c --- /dev/null +++ b/Docs/SiegeDeck/Engine/Engine Overview.md @@ -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
cards · deck · towers · enemies · lanes · waves · run map] --> Engine + Scripts[Content scripts
Assets/Scripts] -. bound via .-> Game + Engine[siege_engine
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, 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` (index plus generation), not `Ref`. 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]] diff --git a/Docs/SiegeDeck/Engine/Input.md b/Docs/SiegeDeck/Engine/Input.md new file mode 100644 index 0000000..ffffc6e --- /dev/null +++ b/Docs/SiegeDeck/Engine/Input.md @@ -0,0 +1,15 @@ +--- +tags: + - engine + - input +--- + +# Input + +- **`InputState`:** per frame, it tracks keys (pressed, held, released), the mouse position and buttons, wheel and drag deltas. It's rebuilt from SDL events in `PumpSdlEvents`. +- **`ActionMap`:** maps keys and buttons to named actions (`Cancel`, `EndTurn`, `SpeedUp`, `RotateCamera`, …). Rebindable and saved with settings. +- **ImGui gating:** when ImGui wants the mouse or keyboard, game input sees nothing. +- **Picking helpers:** screen → ray → ground plane. See [[Rendering#Picking]]. Converting a hit to a tile is game code. +- **Card drag and drop and hover** are game UI built on `InputState` plus tweens ([[Main Loop and Time#Timers and tweens]]). + +Input runs on `FrameClock`, so it works during the paused planning phase. diff --git a/Docs/SiegeDeck/Engine/Main Loop and Time.md b/Docs/SiegeDeck/Engine/Main Loop and Time.md new file mode 100644 index 0000000..838f2f9 --- /dev/null +++ b/Docs/SiegeDeck/Engine/Main Loop and Time.md @@ -0,0 +1,58 @@ +--- +tags: + - engine + - time +--- + +# Main Loop and Time + +The simulation runs on a **fixed timestep**, and rendering, UI and tweens run at a **variable rate**. This directly supports the phased game (see [[Game Constraints]]). + +## The loop + +```cpp +while (running) { + frameClock.Tick(); // real dt, clamped to 0.25 s + input.BeginFrame(); PumpSdlEvents(); // ImGui sees events first and may capture them + + scenes.Update(frameClock.Dt()); // UI, tweens, card hand, camera: real time + + simClock.Accumulate(frameClock.Dt() * simClock.Speed()); + int steps = 0; + while (simClock.ConsumeStep() && steps++ < kMaxStepsPerFrame) // spiral-of-death guard + scenes.FixedUpdate(kSimDt); // 1/60 s: movement, targeting, projectiles, damage + + renderer.BeginFrame(); + scenes.Render(renderer, simClock.Alpha()); // interpolate between the previous and current transform + debugUi.Render(); + renderer.EndFrame(); +} +``` + +## Two clocks + +| Clock | Drives | Pausable | Scaled by game speed | +|---|---|---|---| +| `FrameClock` | UI, card hand, menus, camera, UI tweens | no | no | +| `SimClock` | combat simulation, gameplay tweens | **yes** (speed 0 = planning phase) | **yes** | + +The planning phase is simply `simClock.SetSpeed(0)`. Cards still animate and hover because they run on `FrameClock`. + +## Game speed + +At 1×, 2× or 3× the loop runs **more fixed steps per frame, never bigger ones**. A 3× frame runs three 1/60 s steps, not one 1/20 s step, so fast projectiles can't skip past enemies at high speed. + +`kMaxStepsPerFrame` caps the catch-up work after a stall (window drag, breakpoint). The simulation slows down rather than freezing the frame. + +## Interpolation + +- A `PrevTransform` component is copied from `Transform3D` before each fixed step. +- Rendering blends the two with `SimClock::Alpha()`, so motion stays smooth on high-refresh monitors while the simulation runs at 60 Hz. +- Entities that teleport (spawns, snaps) reset `PrevTransform` to avoid a one-frame smear. + +## Timers and tweens + +- `Timer` and `TweenSystem` let you choose which clock they run on. +- Tweens are engine-level because a deck-builder's feel is mostly tweens: fanning the hand, drawing, cards flying to targets, damage popups. + +Related: [[Scenes and ECS]], [[Rigid-Part Animation]] diff --git a/Docs/SiegeDeck/Engine/Randomness.md b/Docs/SiegeDeck/Engine/Randomness.md new file mode 100644 index 0000000..9739834 --- /dev/null +++ b/Docs/SiegeDeck/Engine/Randomness.md @@ -0,0 +1,31 @@ +--- +tags: + - engine + - rng +--- + +# Randomness + +Goal: **the same seed gives the same run** (map, rewards, deck shuffles) on Linux and Windows. Combat does not need to replay exactly. See [[Game Constraints]]. + +## Rng + +- Our own PCG32 (or xoshiro) generator, **plus our own range and float mapping**. +- **Never use `std::uniform_int_distribution` or `std::uniform_real_distribution`.** Their output is implementation-defined, so libstdc++ and MSVC produce different values from the same seed. Using them would silently break seed reproducibility across platforms. + +## RngStreams + +Independent named streams are derived from the run seed: + +| Stream | Used for | +|---|---| +| `map` | run map generation | +| `shuffle` | deck shuffles, draws | +| `rewards` | card, relic and gold rewards | +| `events` | map events, shops | +| `combat` | crits, procs, random targets | + +Because the streams are independent, extra combat randomness can't shift which rewards a seed gives. + +- Stream states are saved with the run. +- Scripts get RNG only through bound stream accessors; the language's own random function is removed in the sandbox (see [[Scripting]]). diff --git a/Docs/SiegeDeck/Engine/Rendering.md b/Docs/SiegeDeck/Engine/Rendering.md new file mode 100644 index 0000000..f0d9d65 --- /dev/null +++ b/Docs/SiegeDeck/Engine/Rendering.md @@ -0,0 +1,63 @@ +--- +tags: + - engine + - rendering +--- + +# Rendering + +The target is **rigid-part 3D** on **SDL_GPU**, with a 2D overlay for the card hand and HUD. See [[Decision Log#Rigid-part 3D on SDL_GPU]]. + +## Layers + +```mermaid +flowchart TD + Scene[Scene::Render] --> S3D[SceneRenderer3D] + Scene --> R2D[Renderer2D] + S3D --> Dev[RenderDevice] + R2D --> Dev + Dev --> GPU[SDL_GPU → Vulkan / D3D12 / Metal] +``` + +### RenderDevice +A thin wrapper over SDL_GPU: buffers, textures, samplers, pipelines, command buffers, upload staging and per-frame uniform data. Nothing outside `Render/` calls SDL_GPU directly. + +### SceneRenderer3D +- **Instanced meshes are required.** The render queue batches by (pipeline, material, mesh) and draws instances. +- Lighting: one directional sun with a single shadow map, plus a few point lights. +- Materials: PBR-lite or toon (art direction open, see [[Open Questions]]). +- Opaque objects are sorted by pipeline and material; transparent objects back to front. + +### Renderer2D +- A command-and-sort-key sprite batch: `DrawSprite`, `DrawQuad`, `DrawText`, `DrawLine`. +- Used for the card hand, HUD, menus, health bars, range indicators and damage numbers. +- Draws after the 3D pass in screen space. + +## Shaders + +SDL_GPU consumes **precompiled bytecode per backend**. + +1. Write GLSL or HLSL in `Assets/Shaders`. +2. Compile to SPIR-V at build time with `glslang`. +3. Use the **Vulkan backend on both Linux and Windows**. +4. Add SDL_shadercross (for DXIL and MSL) only if D3D12 or macOS becomes a target. + +Shaders are hot-reloadable in debug builds (see [[Assets]]). + +## Text and ImGui + +- Text: SDL_ttf 3's GPU text engine (`TTF_CreateGPUTextEngine`), with cached text objects for numbers that change constantly. +- ImGui: the `imgui_impl_sdlgpu3` backend. + +## Camera + +- A **fixed-pitch perspective** camera (about 50°) with limited zoom and optional 90° rotation steps. No free orbit: a tower defense must stay readable. +- The alternative, an orthographic isometric camera, is noted in [[Open Questions]]. + +## Picking + +- **Tiles:** cast a ray from the mouse onto the ground plane (y = 0) and convert the hit to a tile. No physics engine. +- **Enemies** (for targeted cards): a ray test against bounding spheres. +- **World-space UI** (health bars, range circles): project world positions to the screen and draw them with `Renderer2D`. + +Related: [[Rigid-Part Animation]], [[Assets]] diff --git a/Docs/SiegeDeck/Engine/Rigid-Part Animation.md b/Docs/SiegeDeck/Engine/Rigid-Part Animation.md new file mode 100644 index 0000000..1e465d1 --- /dev/null +++ b/Docs/SiegeDeck/Engine/Rigid-Part Animation.md @@ -0,0 +1,43 @@ +--- +tags: + - engine + - animation +--- + +# Rigid-Part Animation + +Models are **hierarchies of separate rigid meshes**, with no skinning and no bones. See [[Decision Log#Rigid-part 3D on SDL_GPU]]. + +## Two sources of motion + +1. **Authored clips.** glTF supports node (translation, rotation, scale) animation without any skinning. Artists animate parts in Blender (a turret yawing, a barrel recoiling, legs swinging) and export glTF. + - The engine samples keyframes for each node, walks the node hierarchy and draws each part as an instance. +2. **Procedural overrides.** C++ systems write to named parts *after* the clip is applied, for example turret aim toward the target, hit recoil, idle bob and death tumble. + +## Data + +```cpp +struct Model { // asset, see Assets + Vector nodes; // parent index, local bind TRS, optional mesh + material + Map nodeByName; + Vector> clips; +}; + +struct Animator { // component + Handle clip; float time; float speed; bool loop; + Vector nodeWorld; // recomputed each frame +}; +``` + +## Per-frame order + +1. Advance clip time (on `SimClock` for gameplay entities, so it pauses and speeds up with the simulation). +2. Sample clip → local TRS per node. +3. Apply procedural overrides by node name. +4. Compute world matrices down the hierarchy. +5. Push one instance per mesh-bearing node to the [[Rendering]] queue. + +## Later + +- **Vertex animation textures:** if we need thousands of animated enemies. +- **Skeletal skinning:** only for a few bosses or heroes, as a separate milestone. diff --git a/Docs/SiegeDeck/Engine/Scenes and ECS.md b/Docs/SiegeDeck/Engine/Scenes and ECS.md new file mode 100644 index 0000000..3b3d64d --- /dev/null +++ b/Docs/SiegeDeck/Engine/Scenes and ECS.md @@ -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) diff --git a/Docs/SiegeDeck/Engine/Scripting.md b/Docs/SiegeDeck/Engine/Scripting.md new file mode 100644 index 0000000..c43ada1 --- /dev/null +++ b/Docs/SiegeDeck/Engine/Scripting.md @@ -0,0 +1,103 @@ +--- +tags: + - engine + - scripting +status: undecided +candidates: + - Lua 5.4 / Luau + - AngelScript +--- + +# Scripting + +> [!warning] Language not chosen yet +> The shortlist is **Lua (5.4 or Luau)** and **AngelScript**. Keep the boundary language-agnostic until a spike settles it. Don't add a script runtime to CMake before then. + +## The core rule + +**Scripts run on events, never per entity per tick.** + +- **Scripted hooks:** card play, tower placed, hit, kill, wave start, turn start, relic triggers. +- **Stays in C++:** movement, targeting scans, projectile integration and damage application. + +Towers are *configured* by scripts (targeting mode, attack stats, an `on_hit` hook) and *executed* by C++ systems. + +## Language-agnostic boundary + +1. **Definitions are C++ structs.** A loader's only job is to fill them in. The rest of the engine never sees a script value. + ```cpp + struct CardDef { + StringId id; int cost; TargetSpec target; + ScriptHook onPlay; // opaque: a Lua function ref or an asIScriptFunction* + }; + ``` +2. **The game API is defined once in C++** (`PlayContext::DamageArea`, `ApplyStatusArea`, `Draw`, …). Each backend binds the same surface; only the binding code is language-specific. +3. **One small backend interface:** + ```cpp + class IScriptBackend { + public: + virtual ~IScriptBackend() = default; + virtual Result LoadModule(const Path& file) = 0; // fills DefinitionDBs + virtual void Invoke(ScriptHook hook, PlayContext& ctx, const Tile& tile) = 0; + virtual void Reload(const Path& file) = 0; + }; + ``` + Once a language is picked, collapse this into a concrete class. A permanent two-language abstraction isn't worth keeping. + +## Host responsibilities (either language) + +- Sandbox: no file or OS access; randomness only through engine RNG streams (see [[Randomness]]). +- Module loading from `Assets/Scripts`. +- Errors are caught, logged and shown in the debug UI. A broken script never crashes the game. +- Hot reload refills the `DefinitionDB`s (see [[Assets#Definition databases]]). + +## Candidates + +### Lua 5.4 / Luau +Lua tables are the data format, so data and behaviour live in one file. +```lua +--!strict (Luau only) +local fireball: Card = { + id = "fireball", cost = 2, target = Target.tile(1), + on_play = function(ctx: PlayContext, tile: Tile) + ctx:damage_area(tile, 1, 12, "fire") + ctx:apply_status_area(tile, 1, "burn", 3) + end, +} +return fireball +``` +- **Lua 5.4:** tiny and well known; sol2 bindings; dynamic typing. +- **Luau:** gradual static types, a type checker and language server, a built-in sandbox, faster than 5.4. Its C API is close to Lua 5.1's, and sol2 would need adapting. It ships its own CMake build. + +### AngelScript +C++-like syntax with static types. C++ functions are registered directly with native calling conventions, so there's very little glue. +```cpp +class Fireball : ICard { + string id() const { return "fireball"; } + int cost() const { return 2; } + void onPlay(PlayContext@ ctx, const Tile &in tile) { + ctx.damageArea(tile, 1, 12, DamageType::Fire); + ctx.applyStatusArea(tile, 1, "burn", 3); + } +} +``` +```cpp +engine->RegisterObjectMethod("PlayContext", + "void damageArea(const Tile &in, int, int, DamageType)", + asMETHOD(PlayContext, DamageArea), asCALL_THISCALL); +``` +- There's no table literal, so pure stat blocks (enemy HP, wave lists) need TOML or JSON, or have to be written as classes. + +## Decision spike + +Implement the same three things in each candidate: + +1. **Fireball card:** a targeted area effect. +2. **"When an enemy dies, draw 1" relic:** event subscription. +3. **Tower `on_hit` hook:** called at high frequency during a wave. + +Compare authoring ergonomics, lines of binding code, hot-reload behaviour and error messages. + +## Considered and dropped +- **C#:** hosting CoreCLR, maintaining an interop layer, reload through `AssemblyLoadContext` and shipping the runtime cost too much for event-only hooks. It would only make sense as the *main game language*, which isn't the goal. See [[Decision Log]]. +- **Wren, Squirrel, QuickJS/TypeScript, pocketpy, Daslang, WebAssembly, C++ hot-reload DLLs:** reviewed and not shortlisted. diff --git a/Docs/SiegeDeck/GDD/Characters.md b/Docs/SiegeDeck/GDD/Characters.md new file mode 100644 index 0000000..9656115 --- /dev/null +++ b/Docs/SiegeDeck/GDD/Characters.md @@ -0,0 +1,40 @@ +--- +tags: + - gdd + - characters +hacknplan: "#4 (folder), #9, #37, #38, #61" +--- + +# Characters +*HacknPlan folder #4 · GDD* + +Playable characters or commanders. Each one determines the card pool ([[Characters with own Card Pools]]). + +## Siege Engineer +*#9 · Erik Simon · no description yet* + +Mentioned in [[Characters with own Card Pools]]: e.g. +10% damage with catapults. + +## Trapper +*#37 · Fabian Nette · no description yet* + +## Wizard +*#38 · Fabian Nette · no description yet* + +Mentioned elsewhere: +- Resource: **Aether** ([[Resources#Material]], [[Card Types#Resource]]) +- Special unit: **Dragon** ([[Unit Archetypes#Special]]) + +## Necromancer +*#61 · Fabian Nette* + +> hat selber keine Einheiten die er spielen kann. +> +> Kann aber die Leichen der Gegner wiederbeleben mit Karten um diese für sich kämpfen zu lassen + +Mentioned elsewhere: +- Resource: **Knochen / Bones** ([[Resources#Material]], [[Card Types#Resource|Scavenge the Dead]]) +- Commander card: **Raise the Dead**, "Spawnt Zombies" ([[Card Types#Commander]]) + +> [!warning] Engine impact +> Enemy corpses must persist as entities, or at least as recorded positions and enemy types, so they can be raised later. Raised enemies become friendly units. diff --git a/Docs/SiegeDeck/GDD/Discussions/Einheiten Karten oder Spawn Gebäude.md b/Docs/SiegeDeck/GDD/Discussions/Einheiten Karten oder Spawn Gebäude.md new file mode 100644 index 0000000..3ba6d30 --- /dev/null +++ b/Docs/SiegeDeck/GDD/Discussions/Einheiten Karten oder Spawn Gebäude.md @@ -0,0 +1,43 @@ +--- +tags: + - gdd + - discussion + - open +hacknplan: "task #2" +stage: planned +status: blocked +--- + +# Einheiten Karten oder Spawn Gebäude? +*HacknPlan task #2 · Story [[GDD]] (#4) · Category: Ideas · Planned · Blocked by [[GDD Workflow]] (#3)* + +> Sollten Einheiten eigene Karten sein welche platziert werden oder wollen wir dafür Gebäude Karten haben welche regelmäßig Einheiten Spawnen? +> +> Bspl. +> - Archery Range → Bogenschützen +> - Barracks → Soldiers +> - Academy → Mages + +Related: [[Card Types#Deploy]], [[Card Types]] (#14 mentions the Archery Range idea), [[Units]] + +## Comments + +> [!quote] Max Jagielski · 22/08/2024 14:53 +> Wäre für erstmal eher für Einheiten-Karten, das würde uns mehr Freiheit im Mapdesign geben, wenn der Faktor Spawn-Punkt rausfällt? Aber ich bin da offen, kommt auch drauf an wie viel Platz in den Bases sein soll + +> [!quote] Fabian Nette · 22/08/2024 17:16 +> PRO KARTEN und pro Einheiten bleiben bestehen über Runden hinweg +> +> Ich finde, dass es ein bisschen davon abhängt ob die Einheiten über die Runden hinweg bestehen bleiben, oder jede Runde neu kommen. +> +> Wenn das Low Health Einheiten sind, die jede Runde wieder kommen mit Full HP, dann finde ich Tower die jede Runde eine feste anzahl generieren besser. +> +> Sollten es aber einheiten sein, mit mehr HP, die über Runden hinweg bleiben und sich nicht automatisch heilen (das könnte zum Beispiel auch ein Tower sein, der einen regen Effekt jede runde hat), dann macht für meinen Kopf mehr Sinn, wenn das Karten sind. Dann könnte man zwar immer noch Tower haben, die würden dann aber die Karten verstärken (zb. mehr Einheiten, stärkere Einheiten, verschiedene Schadenstypen etc) +> +> Zudem wäre es cool weil die Einheiten, wenn sie bestehen bleiben, dann auch leveln könnten. + +## Current leaning +Both comments lean towards **unit cards**, with units that persist across rounds and can level up. Not formally decided. + +> [!warning] Engine impact +> Persistent, levelling units that fight in an RTS-style siege phase need unit AI, movement for friendly units and melee combat. The engine design so far assumes towers and enemies walking fixed lanes. See [[Open Questions#From the GDD import]]. diff --git a/Docs/SiegeDeck/GDD/Discussions/GDD Workflow.md b/Docs/SiegeDeck/GDD/Discussions/GDD Workflow.md new file mode 100644 index 0000000..f44f9c8 --- /dev/null +++ b/Docs/SiegeDeck/GDD/Discussions/GDD Workflow.md @@ -0,0 +1,24 @@ +--- +tags: + - gdd + - discussion +hacknplan: "task #3" +stage: in progress +author: Erik Simon +--- + +# GDD Workflow +*HacknPlan task #3 · Story [[GDD]] (#4) · In progress* + +> Vorschlag für unseren Workflow: +> +> Wenn Fragen ausstehen, z.B. [[Einheiten Karten oder Spawn Gebäude|#2 Einheiten Karten oder Spawn Gebäude?]], dann machen wir ein Ticket auf und diskutieren das. +> Das Ergebnis dieser Tickets sollte dann ein fester Eintrag im GDD sein, also keine Idea mehr. +> +> Wenn wir das so machen würde ich vorschlagen, dass wir erstmal alles im Ideas Ordner anlegen und die Sachen dann nach und nach ins eigentliche GDD einpflegen über den Ticket Workflow. Also sollte alles was in den GDD Ordnern ist quasi fix sein, zumindest für den Prototypen. + +**Blocks:** [[Einheiten Karten oder Spawn Gebäude]] (#2) + +## Applied to this vault +- Notes in `GDD/Ideas/` are proposals (`status: idea` in frontmatter). +- Once a discussion is resolved, record the result in the matching GDD note, set `status: fixed`, and add an entry to the [[Decision Log]] if it affects the engine. diff --git a/Docs/SiegeDeck/GDD/Discussions/Grundlegende Gamedesign Fragen.md b/Docs/SiegeDeck/GDD/Discussions/Grundlegende Gamedesign Fragen.md new file mode 100644 index 0000000..e7affa4 --- /dev/null +++ b/Docs/SiegeDeck/GDD/Discussions/Grundlegende Gamedesign Fragen.md @@ -0,0 +1,43 @@ +--- +tags: + - gdd + - discussion + - decided +hacknplan: "task #5" +stage: completed +importance: high +decision: B (tower defense loop) +--- + +# Grundlegende Gamedesign Fragen +*HacknPlan task #5 · Design: Gameplay · Completed · Importance: High* + +> [!success] Result: **B**. All three (Fabian, Erik, Max) voted for B. + +> Zuerst sollten wir klären wo unser Fokus liegt. +> +> **A:** Wollen wir eine Card-Engine haben, wo man durch spielen der Karten die Gameplayloop konstant am laufen gehalten wird. +> **B:** Oder wollen wir eher eine Tower defense Gameplayloop haben man Sachen baut und dann einfach laufen lässt. +> +> Beispiele: +> **A:** Spiele wie Heat, Dominion, slay the spire, magic etc. wo das Spiel nur Dinge tun kann indem man Karten spielt. In unserem spiel: ich spiele Karten, um Einheiten zu bekommen und um Tower zu aktivieren und zu bauen etc. +> Grundlegende Spielmechanik: starker Fokus auf Karten spielen +> +> **B:** man spielt Karten aus und dann lässt man das Spiel laufen. +> In unserem Spiel: man bekommt Karten, man baut damit Tower und beendet seinen Zug. +> Dann läuft das klassische Tower defense ab. (Hier wäre dann auch die Möglichkeit RTS Elemente einzubauen) + +## Comments + +> [!quote] Fabian Nette · 22/08/2024 03:03 (edited) +> Während des Schreibens tendiere ich stark zu B +> Hab da ganze trotzdem stehen lassen für euch + +> [!quote] Erik Simon · 22/08/2024 13:41 +> Wäre hier auch bei B + +> [!quote] Max Jagielski · 22/08/2024 14:45 +> Wäre auch für B! + +## Engine relevance +This matches the phased time model in [[Main Loop and Time]]: planning with the simulation paused, then a wave running in real time. diff --git a/Docs/SiegeDeck/GDD/Discussions/Stages und Mapgröße.md b/Docs/SiegeDeck/GDD/Discussions/Stages und Mapgröße.md new file mode 100644 index 0000000..29c67a5 --- /dev/null +++ b/Docs/SiegeDeck/GDD/Discussions/Stages und Mapgröße.md @@ -0,0 +1,58 @@ +--- +tags: + - gdd + - discussion + - open +hacknplan: "task #6" +stage: planned +--- + +# Stages und Mapgröße +*HacknPlan task #6 · Category: Ideas · Planned* + +> Wie groß soll die Burg/Base im Verhältnis zum Rest der Map sein, wo soll die Action stattfinden? +> Eine Überlegungen wären z.B. verschiedene Stages: +> +> - Vor der Mauer +> - Auf der Mauer/vor dem Tor +> - In der Base +> +> So hätte man vielleicht ein Early-Game-Late Game-Äquivalent in dem verschiedene Commander glänzen können? Der Ritter-Commander z.B. mit Kavallerie vor den Toren / Ein Commander mit Bogenschützen-Fokus mehr im Midgame an den Burgmauern. +> +> Was meint ihr? + +> [!note] Attachments not imported +> IMG_2398.jpeg, IMG_2399.jpeg, IMG_2400.jpeg, IMG_2401.jpeg, IMG_2402.jpeg (castle and map sketches). They're still in HacknPlan. + +## Comments + +> [!quote] Fabian Nette · 22/08/2024 17:32 (edited) +> die genaue Größe der Burg und den dementsprechenden Platz für Tower und Einheiten lässt wahrscheinlich erst während des Testens genau einschätzen. +> +> Es kommen jetzt ein Haufen Fragen statt Antworten, sorry :D +> +> Wird das ein Spiel mit mehreren Leveln? oder Rogue-like/lite mit einem Endlos/lange Belagerung mit einem Ende? +> Das ändert auch noch ein paar Dinge bezüglich der Map. +> +> Und: wollen wir ein Schlauchlevel haben oder eher eine Ebene in der wir den Lauf der Gegner mit zb. Mauern lenken können? (gefühlt sind das die beiden Haupt-Designansätze bei TD) +> +> Wenn das mehrere Stages sind, gibt es dann Arten von Tower /Einheiten die begrenzt sind auf bestimmte Bereiche? +> +> ——— +> +> Meine Vorlieben sind: +> +> - Endlos Map oder lange Belagerung mit einem finalen Boss +> - Ich find Ebenen wo man selber den Flow der der Gegner steuern kann/muss besser +> - Stages sind cool, hat weniger den Charakter von hier ist mein Schloss und alles andere ist Schlachtfeld und mehr wir kämpfen in er Stadt (Progression System für mehr Stages?) +> - und De-/Buff tower könnte man so gestalten, dass sie nur in einer Stage ihr Ding machen +> - Begrenzungen, wo man Tower hinsetzen kann, bin ich neutral gerade. Könnte man zum Balancen von starken Towern oder Einheiten nehmen) + +## Open questions raised here +1. Size of the castle/base relative to the map +2. Multiple levels, or a roguelike/lite with an endless or long siege and a final boss? +3. **Fixed paths ("Schlauchlevel") or an open field where the player steers enemies with walls?** +4. Are some towers or units restricted to certain stages? + +> [!warning] Engine impact +> Question 3 conflicts with the current engine assumption of a *grid with fixed lanes* ([[Game Constraints]], [[Decision Log#Grid with fixed lanes]]). An open field with walls needs flow-field pathfinding and re-pathing. See [[Open Questions#From the GDD import]]. diff --git a/Docs/SiegeDeck/GDD/GDD.md b/Docs/SiegeDeck/GDD/GDD.md new file mode 100644 index 0000000..9d5e7af --- /dev/null +++ b/Docs/SiegeDeck/GDD/GDD.md @@ -0,0 +1,79 @@ +--- +tags: + - gdd + - index +source: HacknPlan project "SiegeDeck" (209030), Design Model + board "Prototype #1 / Ideen Auswertung" +imported: 2026-09-24 +--- + +# Game Design Document + +> [!info] Source +> Recreated from the HacknPlan project **SiegeDeck** on 2026-09-24: the Design Model (91 elements) and the discussion tasks on the board *Prototype #1 / Ideen Auswertung*. Text is kept in its original wording (German/English). `#N` refers to the HacknPlan element or task ID. +> Authors: Erik Simon, Fabian Nette, Max Jagielski. + +## Vision +*From Story #4 "Game Design Document"* + +> Wir wollen ein vollständiges GDD haben. +> +> **Fokus auf Tower Defense** +> +> Gameplay Loop: +> 1. Karten ziehen, ausspielen (Einheiten/Tower bauen) +> 2. Gegner greifen an, RTS Phase für die Einheiten +> 3. Loot/Draft Phase +> 4. Repeat + +The fundamental direction was decided in [[Grundlegende Gamedesign Fragen]]: **B, a tower defense loop** (play cards, end the turn, then the tower defense runs), not a pure card engine. + +## Workflow +See [[GDD Workflow]]. Everything under **Ideas** is a proposal. Topics are discussed in tickets, and their results become fixed GDD entries. + +## Status overview + +| Area | Status | Notes | +|---|---|---| +| Core loop | ✅ decided | [[Grundlegende Gamedesign Fragen]] → B | +| Game phases | 💡 idea | [[Gameplay Loop]] | +| Card types and cards | 💡 idea | [[Card Types]] | +| Resources | 💡 idea | [[Resources]] | +| Characters / Commanders | 🟡 names only; Necromancer described | [[Characters]], [[Characters with own Card Pools]] | +| Units | 🟡 first stats | [[Units]], [[Unit Archetypes]] | +| Enemies | 💡 archetypes only | [[Enemy Archetypes]] | +| Units as cards or spawn buildings? | ❓ open | [[Einheiten Karten oder Spawn Gebäude]] | +| Stages and map size | ❓ open | [[Stages und Mapgröße]] | +| Levels, Technical | empty in HacknPlan | – | + +## Contents + +### GDD (fixed entries) +- [[Characters]]: Siege Engineer, Trapper, Wizard, Necromancer +- [[Units]]: Ritter, Soldat, Zauberer, Bogenschütze, Armbrustschütze, Drache, Bauer + +### Ideas +- [[Gameplay Loop]]: phases (Preparation/Build → Siege → Loot), card draw, loot +- [[Card Types]]: Build, Buff/Debuff, Commander, Deploy, Recycle, Resource, with all card ideas +- [[Resources]]: Mana (main resource) plus secondary resources (money, materials) +- [[Characters with own Card Pools]] +- [[Unit Archetypes]] +- [[Enemy Archetypes]] + +### Discussions (board tickets) +- [[Grundlegende Gamedesign Fragen]] (#5, completed) +- [[GDD Workflow]] (#3, in progress) +- [[Einheiten Karten oder Spawn Gebäude]] (#2, planned) +- [[Stages und Mapgröße]] (#6, planned) + +### References +- [[Inspiration]]: Cataclismo, Hellcard, Diplomacy Is Not An Option, Rogue Tower, Slay the Spire + +## Not imported +- **Image attachments** were not downloaded: + - `Cards` folder (#8): 4 JPGs + - Task #6 *Stages und Mapgröße*: IMG_2398–IMG_2402 + - The castle-sketch image on the board card #6 +- Empty HacknPlan template folders (*Gameplay*, *Levels*, *Technical*) contain only HacknPlan's default placeholder text. + +## Impact on the engine +Some GDD ideas touch engine decisions that were made before this import. They're collected in [[Open Questions#From the GDD import]]. diff --git a/Docs/SiegeDeck/GDD/Ideas/Card Types.md b/Docs/SiegeDeck/GDD/Ideas/Card Types.md new file mode 100644 index 0000000..1fc80a9 --- /dev/null +++ b/Docs/SiegeDeck/GDD/Ideas/Card Types.md @@ -0,0 +1,115 @@ +--- +tags: + - gdd + - idea + - cards +status: idea +hacknplan: "#14, #21, #22, #23, #35, #36, #81 and cards" +--- + +# Card Types +*HacknPlan #14 "Karten Typen" · Ideas* + +> Verschiedene Arten von Karten: +> +> - Build Karten → Bauen Tower/Belagerungswaffen/Einheiten +> - Attack Karten → Single Use Angriffe/Special Move für Tower/Einheit +> - Special/Commander Karten → Single Use Commander Fähigkeit +> +> Eventuell Special Versionen der Karten die sich verbrauchen (Pro Runde/Wave/Game)? +> +> Einheiten könnten auch keine eigenen Karten sein sondern von Gebäuden gespawnt werden. +> Dann hätte man z.B. eine Archery Range Karte welche in einem bestimmten Interval Bogenschützen spawnt. + +→ This last point is discussed in [[Einheiten Karten oder Spawn Gebäude]]. + +> [!quote] Fabian Nette · 21/08/2024 22:35 (comment on the *Ideas* folder, #12) +> Charakter/Commander mit eigenem Deck → slay the spire +> +> Gibt es verschiedene Himmelsrichtungen? → Hellcard +> +> Karten(build) erzeugen Tower bei ausspielen +> Karten(build Special) erzeugen einmaligen Tower beim ausspielen (karte verbraucht sich) +> Karten(Attack) lassen Tower des selben typens einen Special move machen +> Karten(Special) lassen den Commander einen Angriff in einen Quadranten machen (Karte verbraucht sich) + +--- + +## Build +*#21 · Fabian Nette* + +> Karten, die Tower bauen. +> +> Ausspielen, Ort auswählen → neuer Tower + +| Card | # | Description | +|---|---|---| +| Frost Tower | #50 | Slows enemies by X% and deals frost DMG | +| Lightning Tower | #41 | short range / slow / high dmg | +| Flamethrower/Fire Tower | #39 | low DPS, DMG over Time, mid Range | +| Trap | #40 | *(no description)* | +| Catapult | #11 | *(no description)* | + +## Buff/Debuff +*#22 · Fabian Nette* + +> statischer Effekt, der bestimmte Ziele (Charaktere, Towertypen, Gegner(?)) stärkt/schwächt +> +> siehe Powerkarten bei Slay the Spire + +| Card | # | Description | +|---|---|---| +| Shield Wall | #64 | Defense Buff for Knights (maybe other melee units) | +| Blizzard | #62 | Slow (Damage?) enemy units | +| Bane | #59 | Damage Debuff for enemy units | +| Flaming Arrows | #51 | Buff for Archers. Fire DMG? | + +## Commander +*#23 · Fabian Nette* + +> Special Builds, Buffs oder Attacks, die Characterabhängig sind +> +> Verbrauchen sich? Bleiben auf der Hand? + +| Card | # | Description | +|---|---|---| +| Call to Arms! | #44 | spawnt x Soldaten / increase spawn rate of buildings if we go that route | +| Net Thrower | #48 | Captures Enemies and holds them in Place for x seconds | +| Alchemist Fire | #47 | short Range, High DPS fire, DMG over time | +| Smite Thee! | #46 | Strike an area with the wrath of gods | +| Healing Word | #49 | Heals unit / units in range? | +| Dragon Lair | #42 | Legendary Card, verbraucht sich nach benutzen. Spawnt nach X Runden eine Drachen Einheit? (see [[Unit Archetypes#Special]]) | +| Raise the Dead | #77 | Commander: [[Characters#Necromancer]]. Spawnt Zombies | + +## Deploy +*#35 · Fabian Nette* + +> RTS Einheiten werden erzeugt + +| Card | # | Description | +|---|---|---| +| Knights of the Order | #45 | spawnt x Ritter (see [[Units]]) | +| Bogenschützen | #43 | *(no description)* | + +## Recycle +*#36 · Fabian Nette* + +> Tower/Einheiten werden recycelt für Resourcen und extra Effekte + +## Resource +*#81 · Fabian Nette* + +> Zb. Necromancer +Knochen +> Zb Wizard +Aether + +| Card | # | Description | +|---|---|---| +| Scavenge the Dead | #82 | Get X Bones, where X is the Amount of fallen enemies in target area // Get X Bones | +| Raise Moral | #83 | Get X Moral, where X is amount of killed monster in target area // Get X Moral | +| Convert to Aether | #84 | Get X Aether, where X is the amount of killed enemies in target area. // Get X Aether | +| Recycle the Weak | #85 | Destroy target unit and gain (targets cost of resource) +X (character specific resource) | + +See [[Resources#Material]] for the character-specific resources. + +> [!tip] Engine note +> Most of these effects map directly onto the script hooks planned in [[Scripting]]: area damage and slow (`on_play` with a tile target), buffs as status effects, spawns, and "X = enemies killed in target area", which needs per-tile kill tracking in the game layer. diff --git a/Docs/SiegeDeck/GDD/Ideas/Characters with own Card Pools.md b/Docs/SiegeDeck/GDD/Ideas/Characters with own Card Pools.md new file mode 100644 index 0000000..c7124a0 --- /dev/null +++ b/Docs/SiegeDeck/GDD/Ideas/Characters with own Card Pools.md @@ -0,0 +1,17 @@ +--- +tags: + - gdd + - idea +status: idea +hacknplan: "#13" +--- + +# Characters with own Card Pools +*HacknPlan #13 "Charaktere mit eigenen Karten Pools" · Ideas · Erik Simon* + +> Es gibt verschiedene Charactere zur Auswahl ala Slay the Spire welche den verfügbaren Karten Pool bestimmen, dadurch sollen verschiedene Playstyles ermöglicht werden. + +> [!quote] Erik Simon · 22/08/2024 00:30 +> Ich denke, es sollte allgemeine Karten geben die Characterübergreifend sind, z.B. Bogenschützen/Ritter/Katapulte usw. Die Character Archetypen könnten dann aber bestimmten Karten Boni geben. z.B. der Siege Engineer hat +10% Dmg mit Katapulten. + +Related: [[Characters]], [[Card Types#Commander]], [[Gameplay Loop#Cards]] (draft from the character pool) diff --git a/Docs/SiegeDeck/GDD/Ideas/Enemy Archetypes.md b/Docs/SiegeDeck/GDD/Ideas/Enemy Archetypes.md new file mode 100644 index 0000000..4a6cfa0 --- /dev/null +++ b/Docs/SiegeDeck/GDD/Ideas/Enemy Archetypes.md @@ -0,0 +1,21 @@ +--- +tags: + - gdd + - idea + - enemies +status: idea +hacknplan: "#86–#91" +--- + +# Enemy Archetypes +*HacknPlan #86 · Ideas · Fabian Nette* + +| Archetype | # | Description | +|---|---|---| +| Normal | #87 | durchschnittseinheit. | +| Fast | #88 | faster but more fragile | +| Tanky | #89 | slow, but high hp | +| High DMG | #90 | High DMG Variants | + +> [!note] +> The GDD folder **Enemies** (#91) exists but only contains the description "Enemies". No concrete enemies are defined yet. diff --git a/Docs/SiegeDeck/GDD/Ideas/Gameplay Loop.md b/Docs/SiegeDeck/GDD/Ideas/Gameplay Loop.md new file mode 100644 index 0000000..8432323 --- /dev/null +++ b/Docs/SiegeDeck/GDD/Ideas/Gameplay Loop.md @@ -0,0 +1,88 @@ +--- +tags: + - gdd + - idea +status: idea +hacknplan: "#15, #16, #17, #18, #19, #24, #25, #26, #27, #28" +--- + +# Gameplay Loop +*HacknPlan #15 · Ideas* + +> Wie sieht der grundsätzliche Gameplay Loop aus? + +The overall direction is decided: a tower defense loop ([[Grundlegende Gamedesign Fragen]] → B). + +```mermaid +flowchart LR + P[Preparation/Build Phase
Karten ziehen & ausspielen] --> S[Siege Phase
Gegner greifen an, RTS für Einheiten] + S --> L[Loot Phase
Karten draften, Items] + L --> P +``` + +## Game Phases +*#16* + +> Aufteilung in einzelne Phasen: +> - Preparation/Build Phase +> - Siege Phase +> - Loot Phase + +### Preparation/Build Phase +*#17* + +> Hier werden neue Einheiten, Gebäude oder Belagerungswaffen Platziert. +> +> Eigene Kartenhand mit nur Build Cards oder Phasenübergreifende Kartenhand mit allen Kartentypen? +> +> Bei zweitem eventuell mindestanzahl an Build Karten pro Hand festlegen. + +#### Card Draw +*#24* + +> Wieviele Handkarten? 5-7? +> +> Handkarten werden am Ende der Runde ausgetauscht wie StS? + +### Siege Phase +*#18* + +> In dieser Phase beginnt der Angriff der Gegner. +> +> Hier können Attack Cards und Specials gespielt werden um die Platzierten Einheiten zu unterstützen. +> +> Auch hier die Frage, eigene Kartenhand mit passenden Kartentypen oder Phasenübergreifend. + +> [!quote] Fabian Nette · 26/08/2024 19:04 +> ich glaube eine zweite Kartenhand könnte das Spiel zu komplex machen? +> vllt ein bestimmter Kartentyp der auf der Hand bleibt oder der produziert wird für die Siege Phase? dadurch könnte ein Archetype-Deck Fokus auf Manaproduktion und token-cards setzen um mehr über starke einzelne RTS Einheiten zu spielen. +> Andere Decks könnten anstatt dessen mehr über Tower oder Masse an einheiten gehen. + +> [!warning] Engine impact +> Playing cards **during** the Siege Phase means card play also happens while the simulation is running, not only in the paused planning phase. [[Main Loop and Time]] already allows this (card UI runs on `FrameClock`), but targeting and effects must work against a moving simulation. + +### Loot Phase +*#19* + +> Hier können neue Karten gewählt werden, eventuell auch Karten abgelegt oder andere arten von Items gelootet werden (Artifacts von Slay the Spire). + +#### Cards +*#25* + +> Neue Karten werden gedraftet +> +> 3 Karten zur Auswahl aus dem Character Pool +> +> geringe Wahrscheinlichkeit auf eine seltene Karte + +#### Special Items +*#26* + +> sowas wie Relics bei Slay the Spire +> +> vllt kosmetische Items, die in der Burg platziert werden können, die dann bestimmte Effekte haben + +- **Upgrades for one Tower** (#27): ein extra starkes Upgrade für einen einzelnen Tower +- **Static Effect** (#28): statische Effekte wie Buff Karten ([[Card Types#Buff/Debuff]]) + +Related: [[Card Types]], [[Resources]], [[Characters with own Card Pools]], [[Randomness]] (the `rewards` RNG stream) diff --git a/Docs/SiegeDeck/GDD/Ideas/Resources.md b/Docs/SiegeDeck/GDD/Ideas/Resources.md new file mode 100644 index 0000000..e773108 --- /dev/null +++ b/Docs/SiegeDeck/GDD/Ideas/Resources.md @@ -0,0 +1,65 @@ +--- +tags: + - gdd + - idea +status: idea +hacknplan: "#20, #78, #79, #92, #93, #94" +--- + +# Resources +*HacknPlan #20 "Resourcen/Mana" · Ideas* + +> Soll eine Resource z.B. Mana/Action Points für das Spielen einer Karte verwendet werden? + +## Hauptresource (main resource) +*#78 · Fabian Nette* + +> Hauptresource, die zu Beginn jeder Runde erstellt werden (meistens Mana) +> +> Notwendig für das spielen von karten + +### Mana +*#92* + +> man bekommt jede Runde eine feste Menge an Mana und kann damit Karten spielen + +## Nebenressourcen (secondary resources) +*#79 · Fabian Nette* + +> Nebenressourcen, die durch Kartenspielen erzeugt werden. +> +> Notwendig für das spielen von Tower/Einheiten +> +> Bread and Butter des Kartenspielens. Sonst ist's kein wirklicher Deckbuilder/enginebuilder +> +> Hatte an Geld oder Materialen (die können dann zb Charakterabhängig sein). +> Diese werden mit Karten produziert und können über runden hinweg gesammelt werden. (In Hellcard hat der tinkerer zb cores und scraps die er ausgeben kann für andere Karten, um zb Dinge zu bauen) + +> [!quote] Fabian Nette · 26/08/2024 18:48 +> Vllt werden die auch durch das töten von Gegnern erzeugt und man kann sich durchs karten spielen, noch mehr beschaffen. → so kann man recht gut festlegen, wieviele dinge man in den ersten runden bauen kann (macht balancing übersichtlicher) + +### Geld +*#93* + +> durch das Ausspielen von Karten produziert +> +> durch das töten von Gegner produziert (wieviel für welchen Gegner?) + +### Material +*#94* + +> unterschiedlich für jeden Character +> → Necromancer (Knochen) +> +> notwendig für Upgrades? +> notwendig für special Cards? + +Character-specific materials mentioned so far: + +| Character | Material | Source | +|---|---|---| +| [[Characters#Necromancer\|Necromancer]] | Knochen / Bones | #81, #82, #94 | +| [[Characters#Wizard\|Wizard]] | Aether | #81, #84 | +| *(unassigned)* | Moral | #83 | + +Related: [[Card Types#Resource]], [[Card Types#Recycle]] diff --git a/Docs/SiegeDeck/GDD/Ideas/Unit Archetypes.md b/Docs/SiegeDeck/GDD/Ideas/Unit Archetypes.md new file mode 100644 index 0000000..6665925 --- /dev/null +++ b/Docs/SiegeDeck/GDD/Ideas/Unit Archetypes.md @@ -0,0 +1,28 @@ +--- +tags: + - gdd + - idea + - units +status: idea +hacknplan: "#65–#76" +--- + +# Unit Archetypes +*HacknPlan #65 · Ideas · Erik Simon* + +> Wir könnten Einheiten in Archetypen unterteilen und innerhalb dieser verschiedene Upgrade Stufen haben, hier drunter ein paar Beispiele. + +| Archetype | Tier 01 | Tier 02 | +|---|---|---| +| **Melee** (#66) | Soldier (#69): Basic Melee Unit | Knight (#70): Advanced Melee Unit | +| **Ranged** (#67) | Archer (#71): Basic Ranged Unit | Crossbow Men (#72): Advanced Ranged Unit | +| **Magic** (#68) | Mage (#73): Basic Magic Unit | Archmage (#74): Advanced Magic Unit | + +## Special +*#75* + +> Special Units, maybe per Commander? + +- **Dragon** (#76): Special Unit of Character: [[Characters#Wizard|Wizard]] (?) Commanders. See also [[Card Types#Commander|Dragon Lair]]. + +Concrete stats: [[Units]] diff --git a/Docs/SiegeDeck/GDD/Inspiration.md b/Docs/SiegeDeck/GDD/Inspiration.md new file mode 100644 index 0000000..2cde023 --- /dev/null +++ b/Docs/SiegeDeck/GDD/Inspiration.md @@ -0,0 +1,51 @@ +--- +tags: + - gdd + - inspiration +hacknplan: "#29 (folder), #30–#34" +--- + +# Inspiration +*HacknPlan folder #29 "Inspo"* + +## Cataclismo +*#30 · Steam · Fabian Nette* + +> RTS Elemente, coole Welt, Style, Building +> +> Gameplayloop ist mehr RTS als Towerdefense, bauen ist etwas umständlich + +## Hellcard +*#31 · Steam · Fabian Nette* + +> Deckbuilder, Multiplayer, Pie-spaces → Karteneffekte zielen auf diese Bereiche +> +> Upgraden der Karten ist linear und macht eine Karte nicht besser sondern zu einer anderen Karte +> +> Alleine nicht so spannend, Style ist geschmacksache +> +> Tinkerer ist ähnlich zum Defect in StS, aber es gibt die Gameplaymechanik, dass Karten die Geschütze (der Tinkerer kann diese bauen) aktivieren, verschrotten etc. Ganz Spannend für unser Spiel + +## Diplomacy Is Not An Option +*#32 · Steam · Erik Simon* + +> Burg vor großen Mengen an Gegnern verteidigen. +> +> Geht mehr in Richtung Stronghold Crusader → Burgen bau/Resourcen Sammeln und langfristige Verteidigung + +## Rogue Tower +*#33 · Steam · Fabian Nette* + +> Rouge-like Tower Defense, Draft for upgrade new towers +> +> die draft mechanik ist etwas nervig, wenn man bestimmte builds spielen möchte. +> +> Nach jeder runde muss man sich entscheiden welcher Weg verlängert wird → man könnte sowas benutzen um ne Karte aufzudecken + +## Slay the Spire +*#34 · Steam · Fabian Nette* + +> DAS Deckbuilder spiel. +> +> Archetypen wie in SlaytheSpire könnten als Template dienen. +> Gameplay unseres Spiels wird allerdings eher wie der Defect (Orbs werden zu Towern?) diff --git a/Docs/SiegeDeck/GDD/Units.md b/Docs/SiegeDeck/GDD/Units.md new file mode 100644 index 0000000..655733a --- /dev/null +++ b/Docs/SiegeDeck/GDD/Units.md @@ -0,0 +1,23 @@ +--- +tags: + - gdd + - units +hacknplan: "#10 (folder), #52–#55, #60, #95, #96" +--- + +# Units +*HacknPlan folder #10 · GDD* + +| Unit | # | HP | Type | DMG | Attack speed | Notes | +|---|---|---|---|---|---|---| +| Ritter | #52 | 20 | Nahkampf | 3 | 2/s | | +| Soldat | #53 | 15 | Nahkampf | 2 | 2/s | | +| Bauer | #96 | 5 | Nahkampf | 1 | 1/s | marked *Idea* in HacknPlan; last updated 14/12/2025 | +| Bogenschütze | #55 | 6 | Fernkampf | 2 | 3/s | | +| Armbrustschütze | #60 | 10 | Nahkampf ⚠️ | 7 | 1/s | listed as *Nahkampf* in HacknPlan, probably meant *Fernkampf* | +| Zauberer | #54 | – | – | – | – | "LVL 2 Range Unit" | +| Drache | #95 | – | – | – | – | no description ([[Unit Archetypes#Special]]) | + +Archetypes and upgrade tiers: [[Unit Archetypes]] +Spawned by: [[Card Types#Deploy]], [[Card Types#Commander]] +Open question: [[Einheiten Karten oder Spawn Gebäude]] diff --git a/Docs/SiegeDeck/Game/Game Constraints.md b/Docs/SiegeDeck/Game/Game Constraints.md new file mode 100644 index 0000000..21652c7 --- /dev/null +++ b/Docs/SiegeDeck/Game/Game Constraints.md @@ -0,0 +1,23 @@ +--- +tags: + - game + - design +--- + +# Game Constraints + +These answers about the game drive the engine design. If one changes, re-check the notes linked from it. + +| Question | Answer | Engine consequence | +|---|---|---| +| How does a round play out in time? | **Phased**: plan (paused, play cards, place towers), then a real-time wave | Two clocks; the simulation can be paused and sped up. See [[Main Loop and Time]] | +| Reproducibility? | **Seeded map and deck generation only.** Combat does not need to replay bit-exactly | Named RNG streams and our own distributions. Floats are fine in the simulation. See [[Randomness]] | +| Placement and pathing | **Tile grid with fixed enemy lanes**. Towers block nothing | No flow fields or re-pathing. Lane following is a spline or waypoint walk | +| Presentation | **Rigid-part 3D** | SDL_GPU renderer; the simulation stays 2D on the ground plane. See [[Rendering]], [[Rigid-Part Animation]] | +| Content | **Data plus scripting** | Scripts run on events only. See [[Scripting]] | + +## Consequences in one line each + +- **The simulation is 2D.** Gameplay positions are `glm::vec2` on the world X/Z plane. Height (projectile arcs, flyers, muzzle offsets) is visual only. +- **The planning phase is simply `SimClock` speed = 0.** The engine has no concept of "phases"; the game owns that state machine. +- **Run state** (deck, relics, gold, map) is plain C++ data owned by the game, not ECS data. diff --git a/Docs/SiegeDeck/Home.md b/Docs/SiegeDeck/Home.md new file mode 100644 index 0000000..8df401c --- /dev/null +++ b/Docs/SiegeDeck/Home.md @@ -0,0 +1,30 @@ +--- +tags: + - index +--- + +# Siege Deck + +A from-scratch tower defense deck-builder in C++26 on SDL3. + +## Game +- [[GDD]]: the Game Design Document (imported from HacknPlan) +- [[Game Constraints]]: the gameplay assumptions the engine is designed around + +## Engine +- [[Engine Overview]]: scope, layering, source layout, principles +- [[Main Loop and Time]]: fixed-step simulation, UI clock, game speed +- [[Scenes and ECS]]: scene stack, per-scene worlds, events +- [[Rendering]]: SDL_GPU, 3D scene renderer, 2D overlay, cameras, picking +- [[Rigid-Part Animation]]: glTF node clips and procedural part motion +- [[Assets]]: handles, loaders, hot reload +- [[Scripting]]: the language-agnostic boundary; candidates are Lua/Luau and AngelScript +- [[Randomness]]: seeded runs and named RNG streams +- [[Input]] +- [[Audio]] +- [[Debug and Tooling]] +- [[Build Order]]: the implementation roadmap + +## Decisions +- [[Decision Log]] +- [[Open Questions]] diff --git a/Docs/SiegeDeck/Open Questions.md b/Docs/SiegeDeck/Open Questions.md new file mode 100644 index 0000000..42f0b4a --- /dev/null +++ b/Docs/SiegeDeck/Open Questions.md @@ -0,0 +1,27 @@ +--- +tags: + - decisions + - open +--- + +# Open Questions + +- [ ] **Scripting language:** Lua 5.4, Luau or AngelScript? To be settled by the spike in [[Scripting#Decision spike]]. +- [ ] **Data format for stat blocks:** only needed if AngelScript wins (TOML or JSON). +- [ ] **glTF loader:** cgltf or fastgltf? Check nixpkgs availability and versions. See [[Assets]]. +- [ ] **Camera projection:** fixed-pitch perspective (current default) or orthographic isometric? See [[Rendering#Camera]]. +- [ ] **Art direction:** PBR-lite or toon shading? This affects the material model in [[Rendering]]. +- [ ] **Modding:** will user-made content be supported? This affects how strict the script sandbox must be. +- [ ] **Target platforms beyond Linux and Windows:** macOS would require SDL_shadercross (MSL). +- [ ] **Save model:** save at map nodes only (seed, stream states, deck), or mid-combat too? + +## From the GDD import +Found while importing the [[GDD]] (2026-09-24). Each one touches an engine decision made before the import. None have been changed yet. + +- [ ] **Fixed lanes vs. an open field with walls.** [[Stages und Mapgröße]] prefers an open field where the player steers enemies with walls. That conflicts with [[Decision Log#Grid with fixed lanes]]. If adopted, it needs flow-field pathfinding and re-pathing when walls are placed. +- [ ] **RTS units in the siege phase.** [[Card Types#Deploy]], [[Units]] and [[Einheiten Karten oder Spawn Gebäude]] describe friendly units that fight, persist across rounds and level up. The engine currently has no unit AI, friendly movement or melee combat. +- [ ] **Card play during the wave.** [[Gameplay Loop#Siege Phase]] allows attack and special cards while enemies attack. The loop supports this, but card targeting and effects must work against a running simulation. +- [ ] **Stages** (before the wall / on the wall / inside the base) and towers limited to certain stages. See [[Stages und Mapgröße]]. +- [ ] **Quadrants / "Himmelsrichtungen"** (Hellcard-style pie spaces) as card target areas. See the comment in [[Card Types]]. +- [ ] **Corpses as entities** for the Necromancer's raise mechanics. See [[Characters#Necromancer]]. +- [ ] **Run structure:** multiple levels, or a roguelike/lite with an endless or long siege and a final boss? See [[Stages und Mapgröße]]. This affects the save model and [[Randomness]].