# goliasvictor/jogo. architecture

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

- Interactive diagram: https://gitdiagram.com/goliasvictor/jogo.
- Repository: https://github.com/goliasvictor/jogo.

## Overview

##### Project Type and Purpose
- This is a standalone 2D puzzle‐style game written in C# (.NET).
- It follows a lightweight custom engine architecture: a game loop in Program.cs → core Jogo class → scene management → entity‐component‐system (ECS) style updates → rendering & audio → input & UI.
- Assets (audio, sprite atlases, level definitions) are loaded at runtime via a ResourceLoader/AssetManager.

##### File Structure
Top‐level and key directories:
- src/Jogo
– Assets: audio files (mfx-*.wav, sfx-*.wav, audio-credits.txt)
– Entities: domain objects (blocks, floors, items, characters) + interfaces IElemental, IEntity, etc.
– GridVec2, Map, LevelLoader: coordinate/grid & map building from YAML levels.
– Scenes: IScene interface + MainMenu, LevelBuilder, LevelManager, LevelScene, ErrorScene.
– Systems: Audio, Collision, ElementalConflictSolver, ItemCollection, TickUpdate (implements ISystem).
– UI: core UIScene, HUD, LevelBuilderUI + UIComponent library (Container, Button, Text, Image, Flexbox, etc.).
– Sprite, SpriteAtlas: rendering primitives.
– Jogo.cs: main game class, orchestration of loop, initialization, scene manager, asset manager.
– Program.cs: entry point.
- src/Test: unit tests.
- res/: presumably placeholder for static resources (images, fonts, etc.).

##### README
- README contains only project title – no architecture notes.
- Use file structure as primary source for architectural intent.

##### Main Components and Interactions
a. Game Core
– Program.cs → Jogo (initializes subsystems, enters main loop).
– MainLoop: processes input, updates current Scene, renders frame, plays audio.
b. Resource/Asset Management
– ResourceLoader/AssetManager loads YAML (custom-levels.yaml), audio files, sprite atlas.
– Provides in‐memory assets to Systems & Scenes.
c. Scene Management
– SceneManager holds the active IScene (MainMenu, LevelScene, LevelBuilder, etc.).
– Scenes orchestrate Entities and UI for each game state.
d. ECS‐Style Systems
– Entities (blocks, characters, items) each implement IEntity + optional sub‐interfaces.
– Systems (CollisionSystem, TickUpdate, ElementalConflictSolver, ItemCollectionSystem, Audio) operate per frame on sets of Entities.
– Each System reads/writes Entity state; Jogo dispatches these systems every tick.
e. Level Loading
– LevelLoader reads custom‐levels.yaml → constructs Map + populates Entities per layer.
f. Rendering & Audio
– Audio system implements IAudio to play sound effects & music.
g. UI Layer
– UIScene + UIComponent library: containers, buttons, text, images.
– HUD overlays LevelScene; LevelBuilderUI overlays builder.
h. External Resources
– custom‐levels.yaml, audio files, (possible) sprite image files in res/.

##### Architectural Patterns & Principles
- Main loop + scene‐based state machine.
- Lightweight ECS: separation of data (Entities) and behavior (Systems).
- Modular UI component library (flexbox, containers, frames).
- Single Responsibility: ResourceLoader, LevelLoader, each System does one job.
- Dependency inversion for audio (IAudio) and systems (ISystem) for testability.

##### Final Touches
- You capture all directories: Entities, Systems, UI, Scenes, Assets, Levels.
- Use annotations for patterns (e.g., “Implements ISystem interface”).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Game Core
    subgraph "Game Core" 
        Program["Program.cs"]:::core
        Jogo["Jogo.cs"]:::core
        SceneManager["SceneManager"]:::core
    end

    %% Asset Manager
    subgraph "Asset Manager / Resource Loader"
        LevelLoader["LevelLoader.cs"]:::asset
        ResourceLoadException["ResourceLoadException.cs"]:::asset
    end

    %% Scenes
    subgraph "Scene Management & Scenes"
        IScene["IScene.cs"]:::core
        MainMenuScene["MainMenuScene.cs"]:::core
        LevelBuilderScene["LevelBuilderScene.cs"]:::core
        LevelManagerScene["LevelManagerScene.cs"]:::core
        LevelScene["LevelScene.cs"]:::core
        ErrorScene["ErrorScene.cs"]:::ui
    end

    %% Entities
    subgraph "Entities (Data)" 
        IEntity["IEntity.cs"]:::data
        IElemental["IElemental.cs"]:::data
        IItemEntity["IItemEntity.cs"]:::data
        subgraph "Blocks"
            Box["Box.cs"]:::data
            FireEntity["FireEntity.cs"]:::data
            Goal["Goal.cs"]:::data
            WaterEntity["WaterEntity.cs"]:::data
        end
        subgraph "Floors"
            DoorEntity["DoorEntity.cs"]:::data
            WallEntity["WallEntity.cs"]:::data
        end
        subgraph "Items"
            ElementChangerEntity["ElementChangerEntity.cs"]:::data
            Key["Key.cs"]:::data
        end
        subgraph "Characters"
            Enemy["Enemy.cs"]:::data
            Player["Player.cs"]:::data
        end
        subgraph "Support Types"
            GridVec2["GridVec2.cs"]:::data
            Map["Map.cs"]:::data
            Layer["Layer.cs"]:::data
        end
    end

    %% Systems
    subgraph "ECS-Style Systems"
        ISystem["ISystem.cs"]:::system
        IAudio["IAudio.cs"]:::system
        TickUpdateSystem["TickUpdateSystem.cs"]:::system
        CollisionSystem["CollisionSystem.cs"]:::system
        ElementalConflictSolver["ElementalConflictSolver.cs"]:::system
        ItemCollectionSystem["ItemCollectionSystem.cs"]:::system
        AudioSystem["Audio.cs"]:::system
    end

    %% Rendering
    subgraph "Rendering Subsystem"
        Sprite["Sprite.cs"]:::system
        SpriteAtlas["SpriteAtlas.cs"]:::system
    end

    %% UI Layer
    subgraph "UI Layer"
        UIScene["UIScene.cs"]:::ui
        HUD["HUD.cs"]:::ui
        LevelBuilderUI["LevelBuilderUI.cs"]:::ui
        UIComponents["UI Component Library"]:::ui
    end

    %% External Resources
    subgraph "External Resources"
        Levels["custom-levels.yaml"]:::external
    end

    %% Unit Tests
    subgraph "Unit Tests"
        UnitTest1["UnitTest1.cs"]:::external
        TestProject["Test.csproj"]:::external
    end

    %% Connections
    Program -->|"starts"| Jogo
    Jogo -->|"initializes"| SceneManager
    Jogo -->|"loads assets via"| LevelLoader
    Jogo -->|"catches errors"| ResourceLoadException
    LevelLoader -->|"reads"| Levels

    SceneManager -->|"manages"| IScene
    SceneManager -->|"selects"| MainMenuScene
    SceneManager -->|"selects"| LevelBuilderScene
    SceneManager -->|"selects"| LevelManagerScene
    SceneManager -->|"selects"| LevelScene
    SceneManager -->|"handles errors"| ErrorScene

    LevelScene -->|"uses"| LevelLoader
    LevelScene -->|"populates"| IEntity
    MainMenuScene -->|"renders UI via"| UIComponents
    LevelBuilderScene -->|"renders UI via"| UIComponents
    ErrorScene -->|"renders UI via"| UIComponents

    Jogo -->|"dispatches each tick"| TickUpdateSystem
    Jogo -->|"dispatches each tick"| CollisionSystem
    Jogo -->|"dispatches each tick"| ElementalConflictSolver
    Jogo -->|"dispatches each tick"| ItemCollectionSystem
    Jogo -->|"dispatches audio events"| AudioSystem

    TickUpdateSystem -->|"updates"| IEntity
    CollisionSystem -->|"reads/writes"| IEntity
    ElementalConflictSolver -->|"resolves conflicts on"| IEntity
    ItemCollectionSystem -->|"updates inventory on"| IEntity
    AudioSystem -->|"plays via"| IAudio

    Jogo -->|"renders via"| SpriteAtlas
    SpriteAtlas -->|"uses"| Sprite

    Jogo -->|"updates UI"| UIScene
    UIScene -->|"renders"| HUD
    UIScene -->|"renders"| LevelBuilderUI
    UIScene -->|"uses"| UIComponents

    Jogo -->|"built/tested by"| UnitTest1
    UnitTest1 -->|"configured by"| TestProject

    %% Click Events
    click Program "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Program.cs"
    click Jogo "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Jogo.cs"
    click LevelLoader "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/LevelLoader.cs"
    click ResourceLoadException "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/ResourceLoadException.cs"
    click IScene "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Scenes/IScene.cs"
    click MainMenuScene "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Scenes/MainMenuScene.cs"
    click LevelBuilderScene "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Scenes/LevelBuilderScene.cs"
    click LevelManagerScene "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Scenes/LevelManagerScene.cs"
    click LevelScene "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Scenes/LevelScene.cs"
    click ErrorScene "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/UI/ErrorScene.cs"
    click IEntity "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Entities/IEntity.cs"
    click IElemental "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Entities/IElemental.cs"
    click IItemEntity "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Entities/IItemEntity.cs"
    click Box "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Entities/Block/Box.cs"
    click FireEntity "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Entities/Block/FireEntity.cs"
    click Goal "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Entities/Block/Goal.cs"
    click WaterEntity "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Entities/Block/WaterEntity.cs"
    click DoorEntity "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Entities/Floor/DoorEntity.cs"
    click WallEntity "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Entities/Floor/WallEntity.cs"
    click ElementChangerEntity "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Entities/Items/ElementChangerEntity.cs"
    click Key "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Entities/Items/Key.cs"
    click Enemy "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Entities/characters/Enemy.cs"
    click Player "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Entities/characters/Player.cs"
    click GridVec2 "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/GridVec2.cs"
    click Map "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Map.cs"
    click Layer "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Entities/Layer.cs"
    click ISystem "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Systems/ISystem.cs"
    click IAudio "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Systems/IAudio.cs"
    click TickUpdateSystem "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Systems/TickUpdateSystem.cs"
    click CollisionSystem "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Systems/CollisionSystem.cs"
    click ElementalConflictSolver "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Systems/ElementalConflitSolver.cs"
    click ItemCollectionSystem "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Systems/ItemCollectionSystem.cs"
    click AudioSystem "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Systems/Audio.cs"
    click Sprite "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Sprite.cs"
    click SpriteAtlas "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/SpriteAtlas.cs"
    click UIScene "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/UI/UIScene.cs"
    click HUD "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/UI/HUD.cs"
    click LevelBuilderUI "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/UI/LevelBuilderUI.cs"
    click UIComponents "https://github.com/goliasvictor/jogo./tree/main/src/Jogo/UI/Component/"
    click Levels "https://github.com/goliasvictor/jogo./blob/main/src/Jogo/Levels/custom-levels.yaml"
    click UnitTest1 "https://github.com/goliasvictor/jogo./blob/main/src/Test/UnitTest1.cs"
    click TestProject "https://github.com/goliasvictor/jogo./blob/main/src/Test/Test.csproj"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#000,stroke-width:1px
    classDef data fill:#DFFFD0,stroke:#000,stroke-width:1px
    classDef system fill:#FFD8A8,stroke:#000,stroke-width:1px
    classDef asset fill:#DDDDDD,stroke:#000,stroke-width:1px
    classDef ui fill:#E8D0FF,stroke:#000,stroke-width:1px
    classDef external fill:#CCCCCC,stroke:#000,stroke-width:1px
```
