# fm39hz/flappybirdgame architecture

> Architecture diagram of the GitHub repository fm39hz/flappybirdgame, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fm39hz/flappybirdgame
- Repository: https://github.com/fm39hz/flappybirdgame

## Overview

##### Project type and purpose
- This is a single‐player 2D game (Flappy Bird clone) built on the Godot engine, written in C#.
- It follows an Entity-Component-System (ECS) style, with MVVM and Domain-Driven Design influences.
- It uses Godot scenes (`*.tscn`) for UI and game world, and C# classes for logic.

##### Main architectural components
a. Godot Engine / Game Loop
- The underlying engine that drives rendering, input polling, physics, and the scene tree.
b. Game Container & Scenes
- `GameContainer.tscn` (and other `*.tscn` nodes) – orchestrates scene hierarchy.
- `Main.tscn` – initial entry point.
c. ECS Core
- EntityTable (central registry for all entities)
- Entities – containers for Components (`src/Entity/*`, `src/Game/Creature/*`, `src/Game/Environment/*`).
- Components (`src/Component/*`) – discrete behaviors (Movement, Animation, Input, Score, etc.).
- Repositories (`*Repo.cs`) – store component state and data.
- StateMachine (`src/Component/Logic/StateMachine*`) – drives state transitions.
d. Game Modules
- Creature Entities (e.g. `BirdEntity`) and their StateMachine (`BirdStateMachine.g.puml`).
- Environment Entities (e.g. `PipeEntity`, `WorldBoundary`).
- MovementStrategies (FollowPath, SideScrolling, TopDown).
- ScoreCounter & ScoreRegister – track and persist scoring.
e. Utils and Managers (`src/Utils/*`)
- SceneManager – handles scene loading transitions.
- SettingManager, FlagManager – global flags & settings.
- Converters, Generators – helper classes.
f. Persistence / External Services
g. Tests (`test/src/GameTest.cs`) – simple unit tests mocking ECS interactions.

##### Relationships and data flows
1. Godot Game Loop triggers scene loading via `Main → GameContainer`.
2. GameContainer reads level definitions (`GameLevel.tscn`, `GameRepo`) and spawns Entities into the EntityTable.
3. For each Entity:
– EntityTable invokes “scan & initialize” → components are retrieved via `*Repo` and attached.
– Components register to global events (input, update ticks).
4. Every frame:
– Input flows into `ActionInputComponent` → converts key presses to actions → updates entity states.
– MovementComponents fetch a MovementStrategy from `MovementStrategyFactory`, then compute new positions.
– AnimationComponents update sprite frames based on state.
– StateMachineComponents handle transitions (e.g. Flap, Fall, Collide).
– ScoreCounterComponent listens for collision events and updates the score repository.
– UI Components (in `Gui.tscn`) query repositories for current score and high scores.
5. Game over / Leaderboard:
– ScoreRegisterComponent persists the final score to local storage or calls an external API.
– SceneManager switches to leaderboard scene.

##### Architectural patterns and design principles
- ECS: decouples data (repositories) and behavior (components).
- MVVM‐like pattern: View (`*.tscn` + Godot nodes) is separate from Model (component state) and logic in C#.
- Repository pattern: isolates state persistence from behavior.
- DDD influence: clear boundaries between Entities, Value Objects (InputMapping), and Services (SceneManager).
- Strategy pattern: MovementStrategyHierarchy allowing interchangeable movement logic.

##### How to represent this
– Game Modules (green): BirdEntity, PipeEntity, GameLevel, MovementStrategy variants, Score components.
– Scenes & UI (purple): Main.tscn, GameContainer.tscn, Gui.tscn.
– Utils & Managers (yellow): SceneManager, SettingManager.
– External / Persistence (orange): Local file store or Leaderboard API.
– Rectangles for modules/packages.
– Rounded rectangles for classes/components.
d. Grouping
– Place all `src/Component/*` and `src/Contract/*` under the ECS Core group.
– Group scene files (`*.tscn`) at one edge, linking into the GameContainer.
e. Labels

##### Final checklist for the principal software engineer
- [ ] Include all six core ECS classes: EntityTable, Entity, Component, Repository, StateMachine, Factory.
- [ ] Show GameContainer’s role in scene orchestration.
- [ ] Map major game entities (Bird, Pipe, WorldBoundary) to their components.
- [ ] Group related classes by directory/package to reflect the file structure.
- [ ] Optionally annotate external persistence (leaderboard) even if not fully implemented.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Scenes & UI
    subgraph "Scenes & UI"
        direction TB
        Main["Main.tscn / Main.cs"]:::ui
        GameContainerTS["GameContainer.tscn / GameContainer.cs"]:::ui
        Gui["Gui.tscn"]:::ui
    end

    %% ECS Core
    subgraph "ECS Core" 
        direction TB
        EntityTable["EntityTable"]:::core
        EntityLayer["Entity Layer\n(src/Entity)"]:::core
        ComponentLayer["Component Layer\n(src/Component)"]:::core
        Repositories["Repositories\n(*Repo.cs)"]:::core
        StateMachineComp["StateMachineComponent"]:::core
        StateMachineRepo["StateMachineRepo"]:::core
        MovementStrategyFactory["MovementStrategyFactory"]:::core
    end

    %% Game Modules
    subgraph "Game Modules"
        direction TB
        BirdEntity["BirdEntity"]:::module
        BirdStateMachine["BirdStateMachine"]:::module
        PipeEntity["PipeEntity"]:::module
        WorldBoundary["WorldBoundary.tscn"]:::module
        ScoreCounterComp["ScoreCounterComponent"]:::module
        ScoreCounterRepo["ScoreCounterRepo"]:::module
        ScoreRegisterComp["ScoreRegisterComponent"]:::module
        FollowPath["FollowPathMovement"]:::module
        SideScrolling["SideScrollingMovement"]:::module
        TopDown["TopDownMovement"]:::module
    end

    %% Utils & Managers
    subgraph "Utils & Managers"
        direction TB
        SceneManager["SceneManager"]:::util
        SettingManager["SettingManager"]:::util
        FlagManager["FlagManager"]:::util
    end

    %% External / Persistence
    subgraph "External / Persistence"
        direction TB
        LeaderboardAPI["Leaderboard API / Local Storage"]:::external
    end

    %% Tests
    GameTest["GameTest"]:::test

    %% Connections
    Main -->|"loads"| GameContainerTS
    GameContainerTS -->|"spawns entities in"| EntityTable
    EntityTable -->|"initializes from"| EntityLayer
    EntityTable -->|"attaches components from"| ComponentLayer
    ComponentLayer -->|"retrieves repos from"| Repositories
    ComponentLayer -->|"uses state machine"| StateMachineComp
    StateMachineComp -->|"stores state in"| StateMachineRepo
    ComponentLayer -->|"gets strategies from"| MovementStrategyFactory
    MovementStrategyFactory --> FollowPath
    MovementStrategyFactory --> SideScrolling
    MovementStrategyFactory --> TopDown

    %% Game flow
    EntityTable -->|"creates"| BirdEntity
    EntityTable -->|"creates"| PipeEntity
    GameContainerTS -->|"loads scene"| WorldBoundary
    BirdEntity -->|"uses"| BirdStateMachine
    ScoreCounterComp -->|"writes to"| ScoreCounterRepo
    ScoreRegisterComp -->|"persists to"| LeaderboardAPI
    Gui -->|"queries"| ScoreCounterRepo
    SceneManager -->|"switches to"| Gui
    SceneManager -->|"switches to"| WorldBoundary

    %% Utils interactions
    SceneManager --> GameContainerTS
    SettingManager --> EntityTable
    FlagManager --> ComponentLayer

    %% Tests link
    GameTest -->|"mocks"| EntityTable

    %% Click Events
    click Main "https://github.com/fm39hz/flappybirdgame/blob/master/src/Main.cs"
    click Main "https://github.com/fm39hz/flappybirdgame/blob/master/src/Main.tscn"
    click GameContainerTS "https://github.com/fm39hz/flappybirdgame/blob/master/src/Game/GameContainer.cs"
    click GameContainerTS "https://github.com/fm39hz/flappybirdgame/blob/master/src/Game/GameContainer.tscn"
    click EntityLayer "https://github.com/fm39hz/flappybirdgame/tree/master/src/Entity"
    click ComponentLayer "https://github.com/fm39hz/flappybirdgame/tree/master/src/Component"
    click Repositories "https://github.com/fm39hz/flappybirdgame/blob/master/src/Component/Movement/MovementRepo.cs"
    click StateMachineComp "https://github.com/fm39hz/flappybirdgame/blob/master/src/Component/Logic/StateMachineComponent.cs"
    click StateMachineRepo "https://github.com/fm39hz/flappybirdgame/blob/master/src/Component/Logic/StateMachineRepo.cs"
    click BirdEntity "https://github.com/fm39hz/flappybirdgame/blob/master/src/Game/Creature/Bird/BirdEntity.cs"
    click BirdEntity "https://github.com/fm39hz/flappybirdgame/blob/master/BirdEntity.tscn"
    click BirdStateMachine "https://github.com/fm39hz/flappybirdgame/blob/master/src/Game/Creature/Bird/BirdStateMachine.cs"
    click BirdStateMachine "https://github.com/fm39hz/flappybirdgame/blob/master/BirdStateMachine.g.puml"
    click PipeEntity "https://github.com/fm39hz/flappybirdgame/blob/master/src/Game/Environment/Pipe/PipeEntity.cs"
    click WorldBoundary "https://github.com/fm39hz/flappybirdgame/blob/master/src/Game/Environment/WorldBoundary/WorldBoundary.tscn"
    click FollowPath "https://github.com/fm39hz/flappybirdgame/blob/master/src/Component/MovementStrategy/Concrete/FollowPathMovement.cs"
    click SideScrolling "https://github.com/fm39hz/flappybirdgame/blob/master/src/Component/MovementStrategy/Concrete/SideScrollingMovement.cs"
    click TopDown "https://github.com/fm39hz/flappybirdgame/blob/master/src/Component/MovementStrategy/Concrete/TopDownMovement.cs"
    click ScoreCounterComp "https://github.com/fm39hz/flappybirdgame/blob/master/src/Component/ScoreCounter/ScoreCounterComponent.cs"
    click ScoreCounterRepo "https://github.com/fm39hz/flappybirdgame/blob/master/src/Component/ScoreCounter/ScoreCounterRepo.cs"
    click ScoreRegisterComp "https://github.com/fm39hz/flappybirdgame/blob/master/src/Component/ScoreRegister/ScoreRegisterComponent.cs"
    click SceneManager "https://github.com/fm39hz/flappybirdgame/blob/master/src/Utils/Manager/SceneManager.cs"
    click SettingManager "https://github.com/fm39hz/flappybirdgame/blob/master/src/Utils/Manager/SettingManager.cs"
    click FlagManager "https://github.com/fm39hz/flappybirdgame/blob/master/src/Utils/Manager/FlagManager.cs"
    click GameTest "https://github.com/fm39hz/flappybirdgame/blob/master/test/src/GameTest.cs"

    %% Styles
    classDef core fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1;
    classDef module fill:#C8E6C9,stroke:#43A047,color:#1B5E20;
    classDef ui fill:#E1BEE7,stroke:#8E24AA,color:#4A148C;
    classDef util fill:#FFF9C4,stroke:#FDD835,color:#F57F17;
    classDef external fill:#FFE0B2,stroke:#FB8C00,color:#E65100;
    classDef test fill:#CFD8DC,stroke:#546E7A,color:#263238;
```
