Add game framework and whitebox level

game/docs/ARCHITECTURE.md

@@ -0,0 +1,112 @@
+# Game Architecture
+
+This project keeps the game layer separate from the Frostbite2D engine. The
+engine remains in `Frostbite2D/`; game-specific code lives under `game/`.
+
+## Directory Layout
+
+```text
+game/
+├─ assets/
+│  ├─ character/        Runtime character spritesheets.
+│  └─ shaders/          Runtime shaders used by the game target.
+├─ docs/
+│  └─ ARCHITECTURE.md   This document.
+└─ src/
+   ├─ actor/            Game actors such as player, enemy, projectile.
+   ├─ combat/           Hitbox, hurtbox, damage and combat resolution types.
+   ├─ core/             Shared config, input snapshots and asset paths.
+   ├─ data/             Level and gameplay data definitions.
+   ├─ movement/         Reusable movement and collision helpers.
+   ├─ scene/            Game scenes and level orchestration.
+   └─ main.cpp          Game executable entry point.
+```
+
+## Runtime Flow
+
+```text
+main.cpp
+  -> Application::init()
+  -> SceneManager::ReplaceScene(WhiteboxScene)
+  -> WhiteboxScene::onEnter()
+      -> CreateWhiteboxLevel()
+      -> create PlayerActor
+      -> pass PlatformWorld to PlayerActor
+  -> every frame:
+      -> PlayerActor samples InputState
+      -> PlayerActor moves through PlatformMover
+      -> PlayerActor updates animation
+      -> WhiteboxScene updates camera
+      -> WhiteboxScene draws whitebox level
+```
+
+## Module Responsibilities
+
+`core`
+
+- `game_config.h` stores shared tuning constants such as virtual resolution,
+  gravity, player speed and attack duration.
+- `asset_paths.h` stores stable runtime asset paths.
+- `input_state.*` converts raw SDL keyboard state into an engine-independent
+  `InputState` snapshot. Player logic consumes this snapshot instead of reading
+  SDL directly.
+
+`movement`
+
+- `PlatformWorld` owns level boundaries and platform rectangles.
+- `MovementBody` is a reusable position/size/velocity container.
+- `PlatformMover` applies gravity, clamps horizontal bounds and resolves basic
+  top-side platform landing.
+
+`data`
+
+- `LevelDefinition` groups collision and whitebox props.
+- `CreateWhiteboxLevel()` currently returns the first hard-coded blockout level.
+  Later this can be replaced by JSON, Tiled, LDtk, or a custom editor export
+  without changing `PlayerActor`.
+
+`actor`
+
+- `PlayerActor` owns player sprites, player state and animation.
+- It depends on `InputStateProvider` and `PlatformMover`, so input and movement
+  can be reused for enemies or changed independently.
+
+`scene`
+
+- `WhiteboxScene` orchestrates the current level: it loads level data, creates
+  actors, draws whitebox geometry and controls the camera.
+
+`combat`
+
+- `hitbox.h` defines early `Hitbox` and `Hurtbox` structs plus team filtering.
+  Full ACT combat should build from this instead of embedding hit detection in
+  actors.
+
+## Current Build Target
+
+`xmake.lua` defines `Frostbite2DGame` for Windows. It compiles all
+`game/src/**.cpp` files, links against `Frostbite2D`, and copies `game/assets`
+next to the executable after build.
+
+Build command:
+
+```powershell
+xmake -b Frostbite2DGame
+```
+
+Output:
+
+```text
+build/windows/x64/release/Frostbite2DGame.exe
+```
+
+## Next Architecture Steps
+
+1. Add `actor/enemy_actor.*` and reuse `PlatformMover`.
+2. Add a `combat/CombatSystem` that collects active hitboxes and hurtboxes each
+   frame, resolves hits, and emits damage events.
+3. Replace hard-coded animation timing in `PlayerActor` with data definitions.
+4. Move `CreateWhiteboxLevel()` to an external level format once the first
+   whitebox loop is stable.
+5. Add a `scene/gameplay_scene` base if multiple levels share spawn, camera,
+   combat and pause logic.