NS_unknown_game/game/docs/ARCHITECTURE.md

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

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

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:

xmake -b Frostbite2DGame

Output:

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.