# ptidejteam/ecs-survivors architecture

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

- Interactive diagram: https://gitdiagram.com/ptidejteam/ecs-survivors
- Repository: https://github.com/ptidejteam/ecs-survivors

## Overview

##### Project type and purpose
- Project type: A C++ desktop (and optionally WebAssembly) game application demonstrating an Entity Component System (ECS) architecture.
- Purpose: Showcase how to build a survivor-like 2D game with ECS using the Flecs framework and Raylib for rendering, input, audio, and window management.

##### File structure
- Top-level build and config:
- CMakeLists.txt, CMakeSettings.json – root build definitions
- .gitignore, .gitattributes, .clang-format – tooling and style
- README.md, LICENSE – project metadata
- app/ – application entry point (main.cpp)
- src/ – core game code, subdivided by “modules” following ECS modules:
- engine/ (core, input, physics, rendering)
- gameplay/
- player/
- tilemap/
- ai/
- debug/
- / – public headers (raygui wrapper)
- external/ – external dependencies (tmxlite for TMX map parsing)
- resources/ – assets (styles, tiled projects, tilemaps, tilesets)

##### Review README for insights
- Confirms use of Flecs (ECS) and Raylib (rendering & input).
- Mentions separate build instructions for desktop & WebAssembly.
- Points to blog posts describing pipeline and systems.

##### Main components
A. Application Layer
- “ECS_Survivors” executable (app/main.cpp) – initializes Raylib window & Flecs world, loads resources, configures system pipelines, enters game loop.
B. ECS Framework
- Flecs World – central registry for entities & components.
- Systems – grouped into modules (engine.core, engine.input, engine.physics, engine.rendering, gameplay, player, tilemap, ai, debug).
C. External Libraries
- Raylib – window/context creation, input polling, 2D drawing, audio playback.
- tmxlite – TMX map parsing for tilemap system.
D. Resources
- Assets folder – styles (raygui), tilemap data, textures, fonts, sounds (if any).

##### Interactions & data flow
1. App initializes Raylib → creates window & context
2. App initializes Flecs world → registers components & systems
3. Resource loader reads TMX/maps/styles → registers assets in ECS (via tilemap and GUI systems)
4. Game loop (per frame):
a. engine.input systems read user input → write Input components
b. player & ai systems consume Input & AI components → update desired velocities
c. engine.physics systems detect & resolve collisions → update Position/Velocity components
d. gameplay systems (spawn, damage, health, cooldown) → update gameplay state
f. debug systems optionally overlay debug info on screen
g. ecs progress to next frame, clear transient data
5. App finalizes & closes context

##### Architectural patterns & design principles
- Entity Component System (decoupled data & behavior)
- Modular design: each feature group (input, physics, rendering, gameplay, AI, debug) lives in its own module with its own pipeline steps.
- Pipeline steps: ordered phases per frame (e.g., input → update → physics → rendering).
- Data-driven: components are plain data; systems operate only on relevant component combinations via Flecs queries.

##### Step-by-step for the Principal Software Engineer
4. Component flows: which systems read/write which component types.
5. Build-time dependencies: tmxlite nested in external/, raygui.h in include/.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Layer"
        App["ECS_Survivors\napp/main.cpp"]:::app
        CMakeApp["app/CMakeLists.txt"]:::app
    end

    %% Game Orchestration
    GameCore["Game Orchestration\nsrc/game.cpp"]:::app
    GameHdr["src/game.h"]:::app

    %% ECS Framework
    subgraph "ECS Framework"
        World["Flecs World"]:::ecs
        subgraph "Components"
            CPos["Component: Position"]:::comp
            CVel["Component: Velocity"]:::comp
            CRend["Component: Renderable"]:::comp
            CPhys["Component: PhysicsShape"]:::comp
            CAS["Component: AIState"]:::comp
            CGUI["Component: GUIData"]:::comp
            CGame["Component: GameplayStats"]:::comp
        end
        subgraph "Systems"
            subgraph "Engine Core Module"
                CoreModule["Core Module"]:::engine
            end
            subgraph "Engine Input Module"
                InputModule["Input Module"]:::engine
            end
            subgraph "Engine Physics Module"
                PhysicsModule["Physics Module"]:::engine
            end
            subgraph "Engine Rendering Module"
                RenderingModule["Rendering Module"]:::engine
                subgraph "Engine GUI Submodule"
                    GUIModule["GUI Module"]:::engine
                end
            end
            subgraph "Gameplay Module"
                GameplayModule["Gameplay Module"]:::gameplay
            end
            subgraph "Player Module"
                PlayerModule["Player Module"]:::gameplay
            end
            subgraph "Tilemap Module"
                TilemapModule["Tilemap Module"]:::gameplay
            end
            subgraph "AI Module"
                AIModule["AI Module"]:::ai
            end
            subgraph "Debug Module"
                DebugModule["Debug Module"]:::debug
            end
        end
    end

    %% External Libraries
    subgraph "External Libraries"
        Raylib["Raylib"]:::external
        TMX["tmxlite"]:::external
        Raygui["RayGUI"]:::external
        IncCMake["CMakeLists.txt"]:::external
    end

    %% Resources
    subgraph "Resources"
        Styles["styles/"]:::resources
        TiledProj["tiled/"]:::resources
        Maps["tiled/maps/"]:::resources
        Sheets["tiled/sheets/"]:::resources
        Tilemaps["tiled/tilemaps/"]:::resources
        ResCMake["CMakeLists.txt"]:::resources
    end

    %% Connections
    App -->|"initializes"| World
    App -->|"calls"| Raylib
    App -->|"loads maps"| TMX
    App -->|"loads styles"| Styles

    GameCore -->|"/ Frame Loop"| World

    World -->|reads/writes| CoreModule
    World -->|reads/writes| InputModule
    World -->|reads/writes| PhysicsModule
    World -->|reads/writes| RenderingModule
    World -->|reads/writes| GUIModule
    World -->|reads/writes| GameplayModule
    World -->|reads/writes| PlayerModule
    World -->|reads/writes| TilemapModule
    World -->|reads/writes| AIModule
    World -->|reads/writes| DebugModule

    RenderingModule -->|"draw calls"| Raylib
    GUIModule -->|"draw GUI"| Raylib
    TilemapModule -->|"parses TMX"| TMX
    Styles -->|"styled UI"| GUIModule

    %% Click Events
    click App "https://github.com/ptidejteam/ecs-survivors/blob/main/app/main.cpp"
    click CMakeApp "https://github.com/ptidejteam/ecs-survivors/blob/main/app/CMakeLists.txt"
    click CoreModule "https://github.com/ptidejteam/ecs-survivors/blob/main/src/modules/engine/core/core_module.cpp"
    click InputModule "https://github.com/ptidejteam/ecs-survivors/blob/main/src/modules/engine/input/input_module.cpp"
    click PhysicsModule "https://github.com/ptidejteam/ecs-survivors/blob/main/src/modules/engine/physics/physics_module.cpp"
    click RenderingModule "https://github.com/ptidejteam/ecs-survivors/blob/main/src/modules/engine/rendering/rendering_module.cpp"
    click GUIModule "https://github.com/ptidejteam/ecs-survivors/blob/main/src/modules/engine/rendering/gui/gui_module.cpp"
    click GameplayModule "https://github.com/ptidejteam/ecs-survivors/blob/main/src/modules/gameplay/gameplay_module.cpp"
    click PlayerModule "https://github.com/ptidejteam/ecs-survivors/blob/main/src/modules/player/player_module.cpp"
    click TilemapModule "https://github.com/ptidejteam/ecs-survivors/blob/main/src/modules/tilemap/tilemap_module.cpp"
    click AIModule "https://github.com/ptidejteam/ecs-survivors/blob/main/src/modules/ai/ai_module.cpp"
    click DebugModule "https://github.com/ptidejteam/ecs-survivors/blob/main/src/modules/debug/debug_module.cpp"
    click GameCore "https://github.com/ptidejteam/ecs-survivors/blob/main/src/game.cpp"
    click Raygui "https://github.com/ptidejteam/ecs-survivors/blob/main/include/raygui.h"
    click IncCMake "https://github.com/ptidejteam/ecs-survivors/blob/main/include/CMakeLists.txt"
    click TMX "https://github.com/ptidejteam/ecs-survivors/tree/main/external/tmxlite/"
    click Styles "https://github.com/ptidejteam/ecs-survivors/tree/main/resources/styles/"
    click TiledProj "https://github.com/ptidejteam/ecs-survivors/tree/main/resources/tiled/"
    click Maps "https://github.com/ptidejteam/ecs-survivors/tree/main/resources/tiled/maps/"
    click Sheets "https://github.com/ptidejteam/ecs-survivors/tree/main/resources/tiled/sheets/"
    click Tilemaps "https://github.com/ptidejteam/ecs-survivors/tree/main/resources/tiled/tilemaps/"
    click ResCMake "https://github.com/ptidejteam/ecs-survivors/blob/main/resources/CMakeLists.txt"

    %% Styles
    classDef app fill:#E3F2FD,stroke:#42A5F5,color:#0D47A1,stroke-width:2px
    classDef ecs fill:#E8EAF6,stroke:#5C6BC0,color:#1A237E,stroke-width:2px
    classDef comp fill:#FFF3E0,stroke:#FFB74D,color:#E65100,stroke-width:1px
    classDef engine fill:#E1F5FE,stroke:#29B6F6,color:#01579B,stroke-width:1px
    classDef gameplay fill:#E8F5E9,stroke:#66BB6A,color:#1B5E20,stroke-width:1px
    classDef ai fill:#FFF8E1,stroke:#FFCA28,color:#FF6F00,stroke-width:1px
    classDef debug fill:#F3E5F5,stroke:#AB47BC,color:#4A148C,stroke-width:1px
    classDef external fill:#ECEFF1,stroke:#90A4AE,color:#263238,stroke-width:1px
    classDef resources fill:#F1F8E9,stroke:#AEEA00,color:#33691E,stroke-width:1px
```
