# tahreem7926/subway-surfers-2d architecture

> Architecture diagram of the GitHub repository tahreem7926/subway-surfers-2d, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tahreem7926/subway-surfers-2d
- Repository: https://github.com/tahreem7926/subway-surfers-2d

## Overview

#### Purpose and Entry Point
This is a native C++17/SFML 2D endless-runner game. The executable starts in `main.cpp`, which hands application control to the central game coordinator in `GameEngine.cpp` / `GameEngine.h`. CMake builds the binary and copies runtime assets such as `asset/song.wav`.

#### Game Engine and State Control
`GameEngine.cpp` / `GameEngine.h` owns the SFML window, event polling, frame update loop, rendering, and high-level screens such as menu, active gameplay, pause, and leaderboard. It is the primary boundary between SFML input/window/audio APIs and game-domain objects. `Theme.h` centralizes visual, layout, and gameplay constants consumed across this layer.

#### Player Simulation
`Player.cpp` / `Player.h` models the runner’s three-lane movement and jump/slide state. The engine translates keyboard input into player actions, then updates player physics each frame. Player state is consumed by collision checks, rendering, and temporary power-up behavior.

#### Track Generation and Object Lifecycle
`TrackManager.cpp` / `TrackManager.h` manages the scrolling world: spawning, advancing, culling, and retaining obstacles, coins, and power-ups. It forms the runtime object-lifecycle boundary, coordinating domain entities held through the custom container in `GameList.h`. Spawned objects move toward the player as gameplay speed increases.

#### Interactive World Entities
`Obstacle.cpp` / `Obstacle.h` defines train, barrier, cone, and fence behavior and collision requirements. `Coin.cpp` / `Coin.h` implements collectible scoring objects and magnet attraction. `PowerUp.cpp` / `PowerUp.h` represents timed abilities—magnet, jetpack, shield, double-coin, and score booster—and applies their effects to player, collection, collision, or scoring rules.

#### Scoring and Persistence
`ScoreManager.cpp` / `ScoreManager.h` owns current-score progression, high-score comparison, and local top-three leaderboard persistence. Gameplay events flow from collection, survival, and modifiers into this manager; leaderboard UI reads its stored results through the engine.

#### Presentation, Audio, and Build Runtime
Rendering is SFML-based, with shared text/shape helpers in `UIUtils.cpp` / `UIUtils.h` and menu interactions in `Button.cpp` / `Button.h`. The repository includes a bundled font under `lilita-one/` and music at `asset/song.wav`. `CMakeLists.txt` and `CMakePresets.json` define CMake-based builds against SFML 2.6 graphics, window, audio, and system libraries.

Main entry points: [`GameEngine.cpp`](https://github.com/tahreem7926/subway-surfers-2d/blob/main/GameEngine.cpp) (Game Engine), [`TrackManager.cpp`](https://github.com/tahreem7926/subway-surfers-2d/blob/main/TrackManager.cpp) (Track Manager), [`Player.cpp`](https://github.com/tahreem7926/subway-surfers-2d/blob/main/Player.cpp) (Player), [`PowerUp.cpp`](https://github.com/tahreem7926/subway-surfers-2d/blob/main/PowerUp.cpp) (Power-Ups)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Game Runtime"]
  node_main(("Application Entry<br/>C++ entry point<br/>[main.cpp]"))
  node_engine["Game Engine<br/>runtime coordinator<br/>[GameEngine.cpp]"]
  node_theme["Theme Constants<br/>shared constants<br/>[Theme.h]"]
  node_score[("Score Manager<br/>scoring and persistence<br/>[ScoreManager.cpp]")]
end

subgraph group_world["World Simulation"]
  node_player["Player<br/>runner simulation<br/>[Player.cpp]"]
  node_track["Track Manager<br/>world lifecycle<br/>[TrackManager.cpp]"]
  node_game_list["Game List<br/>custom container<br/>[GameList.h]"]
  node_obstacle["Obstacles<br/>hazards<br/>[Obstacle.cpp]"]
  node_coin["Coins<br/>collectibles<br/>[Coin.cpp]"]
  node_powerup["Power-Ups<br/>timed abilities<br/>[PowerUp.cpp]"]
end

subgraph group_presentation["Presentation"]
  node_ui["UI Utilities<br/>render helpers<br/>[UIUtils.cpp]"]
  node_button["Buttons<br/>menu interaction<br/>[Button.cpp]"]
  node_font["Bundled Font<br/>runtime asset"]
  node_music["Background Music<br/>runtime asset<br/>[song.wav]"]
end

node_build["CMake Build<br/>[CMakeLists.txt]"]
node_sfml{{"SFML 2.6<br/>platform library"}}

node_build -->|"builds"| node_main
node_build -->|"links"| node_sfml
node_build -->|"copies asset"| node_music
node_main -->|"starts"| node_engine
node_engine -->|"uses window/input/audio"| node_sfml
node_engine -->|"uses"| node_theme
node_engine -->|"drives input and updates"| node_player
node_engine -->|"updates and renders"| node_track
node_engine -->|"updates and reads leaderboard"| node_score
node_engine -->|"renders with"| node_ui
node_engine -->|"handles menu actions"| node_button
node_engine -->|"loads"| node_font
node_engine -->|"plays"| node_music
node_track -->|"retains entities"| node_game_list
node_track -->|"spawns and advances"| node_obstacle
node_track -->|"spawns and advances"| node_coin
node_track -->|"spawns and advances"| node_powerup
node_obstacle -->|"collision checks"| node_player
node_coin -->|"collects / attracts"| node_player
node_coin -->|"awards score"| node_score
node_powerup -->|"modifies state"| node_player
node_powerup -.->|"enables magnet"| node_coin
node_powerup -.->|"modifies scoring"| node_score
node_player -->|"survival scoring"| node_score

click node_build "https://github.com/tahreem7926/subway-surfers-2d/blob/main/CMakeLists.txt"
click node_main "https://github.com/tahreem7926/subway-surfers-2d/blob/main/main.cpp"
click node_engine "https://github.com/tahreem7926/subway-surfers-2d/blob/main/GameEngine.cpp"
click node_theme "https://github.com/tahreem7926/subway-surfers-2d/blob/main/Theme.h"
click node_player "https://github.com/tahreem7926/subway-surfers-2d/blob/main/Player.cpp"
click node_track "https://github.com/tahreem7926/subway-surfers-2d/blob/main/TrackManager.cpp"
click node_game_list "https://github.com/tahreem7926/subway-surfers-2d/blob/main/GameList.h"
click node_obstacle "https://github.com/tahreem7926/subway-surfers-2d/blob/main/Obstacle.cpp"
click node_coin "https://github.com/tahreem7926/subway-surfers-2d/blob/main/Coin.cpp"
click node_powerup "https://github.com/tahreem7926/subway-surfers-2d/blob/main/PowerUp.cpp"
click node_score "https://github.com/tahreem7926/subway-surfers-2d/blob/main/ScoreManager.cpp"
click node_ui "https://github.com/tahreem7926/subway-surfers-2d/blob/main/UIUtils.cpp"
click node_button "https://github.com/tahreem7926/subway-surfers-2d/blob/main/Button.cpp"
click node_music "https://github.com/tahreem7926/subway-surfers-2d/blob/main/asset/song.wav"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_engine,node_theme,node_score toneBlue
class node_player,node_track,node_game_list,node_obstacle,node_coin,node_powerup toneAmber
class node_ui,node_button,node_font,node_music toneMint
class node_build,node_sfml toneNeutral
```

## Components

### Game Runtime

- [Application Entry](https://github.com/tahreem7926/subway-surfers-2d/blob/main/main.cpp): C++ entry point · `main.cpp`
- [Game Engine](https://github.com/tahreem7926/subway-surfers-2d/blob/main/GameEngine.cpp): runtime coordinator · Owns the SFML window, frame loop, screens, input, and rendering. · `GameEngine.cpp`
- [Theme Constants](https://github.com/tahreem7926/subway-surfers-2d/blob/main/Theme.h): shared constants · `Theme.h`
- [Score Manager](https://github.com/tahreem7926/subway-surfers-2d/blob/main/ScoreManager.cpp): scoring and persistence · Tracks score and persists the local top-three leaderboard. · `ScoreManager.cpp`

### World Simulation

- [Player](https://github.com/tahreem7926/subway-surfers-2d/blob/main/Player.cpp): runner simulation · Maintains lane movement, jump, slide, and physics state. · `Player.cpp`
- [Track Manager](https://github.com/tahreem7926/subway-surfers-2d/blob/main/TrackManager.cpp): world lifecycle · Spawns, advances, culls, and retains scrolling world objects. · `TrackManager.cpp`
- [Game List](https://github.com/tahreem7926/subway-surfers-2d/blob/main/GameList.h): custom container · Stores active world entities. · `GameList.h`
- [Obstacles](https://github.com/tahreem7926/subway-surfers-2d/blob/main/Obstacle.cpp): hazards · Trains, barriers, cones, and fences with collision behavior. · `Obstacle.cpp`
- [Coins](https://github.com/tahreem7926/subway-surfers-2d/blob/main/Coin.cpp): collectibles · Provide score and support magnet attraction. · `Coin.cpp`
- [Power-Ups](https://github.com/tahreem7926/subway-surfers-2d/blob/main/PowerUp.cpp): timed abilities · Applies magnet, jetpack, shield, and score modifiers. · `PowerUp.cpp`

### Presentation

- [UI Utilities](https://github.com/tahreem7926/subway-surfers-2d/blob/main/UIUtils.cpp): render helpers · `UIUtils.cpp`
- [Buttons](https://github.com/tahreem7926/subway-surfers-2d/blob/main/Button.cpp): menu interaction · `Button.cpp`
- **Bundled Font**: runtime asset
- [Background Music](https://github.com/tahreem7926/subway-surfers-2d/blob/main/asset/song.wav): runtime asset · `asset/song.wav`

### Other components

- [CMake Build](https://github.com/tahreem7926/subway-surfers-2d/blob/main/CMakeLists.txt): build · Builds the C++17 executable with SFML and copies runtime assets. · `CMakeLists.txt`
- **SFML 2.6**: platform library · Graphics, window, audio, and system APIs.

## Connections

- CMake Build → Application Entry: builds
- CMake Build → SFML 2.6: links
- CMake Build → Background Music: copies asset
- Application Entry → Game Engine: starts
- Game Engine → SFML 2.6: uses window/input/audio
- Game Engine → Theme Constants: uses
- Game Engine → Player: drives input and updates
- Game Engine → Track Manager: updates and renders
- Game Engine → Score Manager: updates and reads leaderboard
- Game Engine → UI Utilities: renders with
- Game Engine → Buttons: handles menu actions
- Game Engine → Bundled Font: loads
- Game Engine → Background Music: plays
- Track Manager → Game List: retains entities
- Track Manager → Obstacles: spawns and advances
- Track Manager → Coins: spawns and advances
- Track Manager → Power-Ups: spawns and advances
- Obstacles → Player: collision checks
- Coins → Player: collects / attracts
- Coins → Score Manager: awards score
- Power-Ups → Player: modifies state
- Power-Ups → Coins: enables magnet
- Power-Ups → Score Manager: modifies scoring
- Player → Score Manager: survival scoring