# l1tesg/dirty-road-godot architecture

> Architecture diagram of the GitHub repository l1tesg/dirty-road-godot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/l1tesg/dirty-road-godot
- Repository: https://github.com/l1tesg/dirty-road-godot

## Overview

1. **Repository shape**
   - This repo is a two-part project: a **Godot game** under `juego/` and a separate **Astro static website** under `pagina-web/`.
   - There is also a small `documentos/` area for supporting docs. The architecture is mostly **client-side/offline**; no backend or database layer is visible.

2. **Game entry and runtime boundary**
   - The game is rooted in `juego/project.godot`, which defines the Godot runtime configuration.
   - The likely startup flow is `menu_ui/MAIN.tscn` → menu scripts → gameplay scenes such as `mapas/level_1.tscn` or `sewer/sewer_nivel.tscn`.
   - Scene transitions are the main composition mechanism: Godot scenes and scripts orchestrate the game instead of a central application server.

3. **Menu and front-end game flow**
   - `juego/menu_ui/` holds the main menu and save/load-style UI flow:
     - `main.gd` / `MAIN.tscn` as the top-level menu entry.
     - `menus/menu_inicio.*` for the start menu.
     - `partidas/selector_partida.*` and `partidas/partida.*` for save-slot or profile selection.
   - This is a clear boundary between **presentation/navigation** and actual gameplay scenes.

4. **Gameplay scene layer**
   - `juego/mapas/` and `juego/sewer/` contain world scenes and their level logic:
     - `mapas/level_1.tscn` with `level_1.gd` is the main level implementation.
     - `mapas/game/prueba_level1.tscn` appears to be a test or variant scene.
     - `sewer/sewer_nivel.tscn` is another standalone level/environment.
   - These scenes are the integration points where level geometry, enemies, props, and player nodes are assembled.

5. **Player subsystem**
   - The player is isolated in `juego/player/leroy.tscn` with `leroy.gd`.
   - This likely owns movement, combat/action handling, animation control, and interaction with environment objects.
   - The player subsystem feeds events into the level world: collecting items, triggering doors, interacting with save points, and reacting to hazards.

6. **World interaction/content model**
   - The asset catalog strongly suggests the world is built from interactable content such as:
     - **Doors**, **keys**, **ladders**, **save points**, **usable items**, **traps**, **props**, and **enemies**.
   - These are not separate services; they are content-driven scene objects imported into level scenes.
   - The gameplay loop appears to be exploration plus interaction with environment triggers and enemy encounters.

7. **Art/content pipeline**
   - Most of the repository is asset-heavy and organized around **Aseprite source files**:
     - `assets/…/*.aseprite` for sprites and animation frames.
     - `assets/music/*.mp3` for audio.
     - `assets/fonts/`, `assets/images/`, and `assets/gif/` for supplemental media.
   - This means the game’s visual/content pipeline is asset-first: art is authored externally, then imported into Godot scenes/resources.

8. **UI and presentation assets**
   - UI is split between scene logic and art resources:
     - `assets/User Interface/` and `assets/themes/` hold HUD and styling assets.
     - `assets/mobile-controls-1.0/` provides mobile on-screen control art.
     - `addons/phantom_camera/panel` and related theme files support editor-facing UI for the addon.
   - In diagram terms, UI is a separate presentation layer on top of gameplay scenes, with theme resources applied by Godot.

9. **Camera and editor addon boundary**
   - `juego/addons/phantom_camera/` is an embedded third-party plugin, not core game code.
   - It includes runtime camera classes plus editor plugins, gizmos, and example scenes for 2D/3D camera behaviors.
   - Architectural role: it acts as an external subsystem used to manage camera following, framing, noise, tweening, and editor tooling, while remaining decoupled from the game’s own gameplay scripts.

10. **Testing and sample scenes**
   - `juego/nodes/` contains generic scenes such as `mapa.tscn` and `test_Movimiento_jugador.tscn`, which look like reusable test harnesses or prototyping scenes.
   - The `addons/phantom_camera/examples/` tree is also present, showing the repo carries vendor examples alongside the actual game.
   - These areas are useful for development but should be treated as **supporting/prototyping boundaries**, not primary gameplay flow.

11. **Web presence**
   - `pagina-web/` is a separate Astro project with its own `package.json`, `astro.config.mjs`, and `src/pages/index.astro`.
   - This is a static site boundary, likely used for project presentation or documentation rather than game runtime.
   - It does not appear to share runtime code with the Godot game; it is an independent deployment unit.

12. **Documentation and asset versioning**
   - `documentos/APA.docx` and `assets/UPDATES/…` indicate the repo also stores planning/reference material and multiple asset-update drops.
   - The duplicated asset trees under `assets/` and `assets/Another Metroidvania Asset Pack Vol. 1 ver. 1.7/` suggest imported third-party art packs plus evolving revisions.
   - For an architecture diagram, this is important as a content-management boundary: the game consumes a large prebuilt asset library rather than generating content procedurally.

13. **Overall data flow**
   - The main flow is: **menu selection → level scene load → player/world interaction → UI feedback and scene progression**.
   - Within gameplay, Godot scenes bind together scripted behavior and imported resources, while the camera addon and UI themes shape presentation.
   - There is no visible remote service or persistence backend; state is likely maintained locally by the Godot game and its scene/resource system.

Main entry points: [`juego/mapas/level_1.tscn`](https://github.com/l1tesg/dirty-road-godot/blob/main/juego/mapas/level_1.tscn) (Level 1), [`juego/menu_ui/MAIN.tscn`](https://github.com/l1tesg/dirty-road-godot/blob/main/juego/menu_ui/MAIN.tscn) (Main menu), [`juego/player/leroy.tscn`](https://github.com/l1tesg/dirty-road-godot/blob/main/juego/player/leroy.tscn) (Player), [`juego/addons/phantom_camera/plugin.cfg`](https://github.com/l1tesg/dirty-road-godot/blob/main/juego/addons/phantom_camera/plugin.cfg) (Camera addon)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_godot["Godot game"]
  node_project["Project<br/>godot config<br/>[project.godot]"]
  node_main_menu["Main menu<br/>ui scene<br/>[MAIN.tscn]"]
  node_menu_inicio["Start menu<br/>ui flow<br/>[menu_inicio.tscn]"]
  node_partidas["Save select<br/>ui flow"]
  node_level_1["Level 1<br/>game level<br/>[level_1.tscn]"]
  node_sewer_level["Sewer level<br/>game level<br/>[sewer_nivel.tscn]"]
  node_test_level["Test level<br/>prototype scene<br/>[prueba_level1.tscn]"]
  node_player["Player<br/>character controller<br/>[leroy.tscn]"]
  node_world_content["World content<br/>scene objects"]
  node_enemies["Enemies<br/>combat content"]
  node_ui_assets["UI assets<br/>art assets"]
  node_audio["Audio<br/>music assets"]
  node_art_pipeline["Art pipeline<br/>aseprite assets"]
  node_camera_addon["Camera addon<br/>embedded plugin<br/>[plugin.cfg]"]
  node_camera_runtime["Camera runtime<br/>addon runtime"]
  node_camera_editor["Editor tools<br/>addon editor<br/>[editor.tscn]"]
  node_camera_examples["Examples<br/>addon samples"]
end

subgraph group_web["Website"]
  node_site["Website<br/>astro app<br/>[index.astro]"]
end

subgraph group_docs["Docs"]
  node_docs["Docs<br/>documentation<br/>[APA.docx]"]
end

node_project -->|"launches"| node_main_menu
node_main_menu -->|"navigates to"| node_menu_inicio
node_main_menu -->|"opens"| node_partidas
node_main_menu -->|"starts"| node_level_1
node_partidas -->|"loads"| node_level_1
node_level_1 -->|"spawns"| node_player
node_level_1 -->|"assembles"| node_world_content
node_level_1 -->|"populates"| node_enemies
node_level_1 -->|"overlays"| node_ui_assets
node_level_1 -->|"plays"| node_audio
node_sewer_level -->|"assembles"| node_world_content
node_sewer_level -->|"populates"| node_enemies
node_player -->|"interacts with"| node_world_content
node_player -->|"engages"| node_enemies
node_art_pipeline -->|"feeds"| node_level_1
node_art_pipeline -->|"feeds"| node_player
node_camera_addon -->|"contains"| node_camera_runtime
node_camera_addon -->|"contains"| node_camera_editor
node_camera_addon -->|"ships"| node_camera_examples
node_camera_runtime -->|"follows"| node_level_1
node_site -.->|"complements"| node_docs

click node_project "https://github.com/l1tesg/dirty-road-godot/blob/main/juego/project.godot"
click node_main_menu "https://github.com/l1tesg/dirty-road-godot/blob/main/juego/menu_ui/MAIN.tscn"
click node_menu_inicio "https://github.com/l1tesg/dirty-road-godot/blob/main/juego/menu_ui/menus/menu_inicio.tscn"
click node_partidas "https://github.com/l1tesg/dirty-road-godot/blob/main/juego/menu_ui/partidas/selector_partida.tscn"
click node_level_1 "https://github.com/l1tesg/dirty-road-godot/blob/main/juego/mapas/level_1.tscn"
click node_sewer_level "https://github.com/l1tesg/dirty-road-godot/blob/main/juego/sewer/sewer_nivel.tscn"
click node_test_level "https://github.com/l1tesg/dirty-road-godot/blob/main/juego/mapas/game/prueba_level1.tscn"
click node_player "https://github.com/l1tesg/dirty-road-godot/blob/main/juego/player/leroy.tscn"
click node_world_content "https://github.com/l1tesg/dirty-road-godot/blob/main/juego/assets/Props/chests/aseprite files/brown_chest_opening.aseprite"
click node_enemies "https://github.com/l1tesg/dirty-road-godot/blob/main/juego/assets/Enemies/Zombie/going left animations/aseprite files/zombie_attack_left_anim.aseprite"
click node_ui_assets "https://github.com/l1tesg/dirty-road-godot/blob/main/juego/assets/User Interface/char hud/health bar/aseprite files/health_bar.aseprite"
click node_audio "https://github.com/l1tesg/dirty-road-godot/blob/main/juego/assets/music/Glint_of_the_Falls.mp3"
click node_art_pipeline "https://github.com/l1tesg/dirty-road-godot/blob/main/juego/assets/Another Metroidvania Asset Pack Vol. 1 ver. 1.7/read me (or not).txt"
click node_camera_addon "https://github.com/l1tesg/dirty-road-godot/blob/main/juego/addons/phantom_camera/plugin.cfg"
click node_camera_runtime "https://github.com/l1tesg/dirty-road-godot/blob/main/juego/addons/phantom_camera/scripts/phantom_camera/phantom_camera_2d.gd"
click node_camera_editor "https://github.com/l1tesg/dirty-road-godot/blob/main/juego/addons/phantom_camera/panel/editor.tscn"
click node_camera_examples "https://github.com/l1tesg/dirty-road-godot/blob/main/juego/addons/phantom_camera/examples/example_scenes/2D/2d_example_scene.tscn"
click node_site "https://github.com/l1tesg/dirty-road-godot/blob/main/pagina-web/src/pages/index.astro"
click node_docs "https://github.com/l1tesg/dirty-road-godot/blob/main/documentos/APA.docx"

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_project,node_main_menu,node_menu_inicio,node_partidas,node_level_1,node_sewer_level,node_test_level,node_player,node_world_content,node_enemies,node_ui_assets,node_audio,node_art_pipeline,node_camera_addon,node_camera_runtime,node_camera_editor,node_camera_examples toneBlue
class node_site toneAmber
class node_docs toneMint
```

## Components

### Godot game

Core game runtime, scenes, scripts, and embedded addon

- [Project](https://github.com/l1tesg/dirty-road-godot/blob/main/juego/project.godot): godot config · Godot project configuration and runtime entry boundary · `juego/project.godot`
- [Main menu](https://github.com/l1tesg/dirty-road-godot/blob/main/juego/menu_ui/MAIN.tscn): ui scene · Top-level menu scene and navigation script · `juego/menu_ui/MAIN.tscn`
- [Start menu](https://github.com/l1tesg/dirty-road-godot/blob/main/juego/menu_ui/menus/menu_inicio.tscn): ui flow · Start screen logic and scene · `juego/menu_ui/menus/menu_inicio.tscn`
- [Save select](https://github.com/l1tesg/dirty-road-godot/blob/main/juego/menu_ui/partidas/selector_partida.tscn): ui flow · Save-slot/profile selection screens · `juego/menu_ui/partidas/selector_partida.tscn`
- [Level 1](https://github.com/l1tesg/dirty-road-godot/blob/main/juego/mapas/level_1.tscn): game level · Primary gameplay level and its script boundary · `juego/mapas/level_1.tscn`
- [Sewer level](https://github.com/l1tesg/dirty-road-godot/blob/main/juego/sewer/sewer_nivel.tscn): game level · Standalone sewer environment scene · `juego/sewer/sewer_nivel.tscn`
- [Test level](https://github.com/l1tesg/dirty-road-godot/blob/main/juego/mapas/game/prueba_level1.tscn): prototype scene · Reusable test or prototype scene for level work · `juego/mapas/game/prueba_level1.tscn`
- [Player](https://github.com/l1tesg/dirty-road-godot/blob/main/juego/player/leroy.tscn): character controller · Player scene and movement/combat script boundary · `juego/player/leroy.tscn`
- [World content](https://github.com/l1tesg/dirty-road-godot/blob/HEAD/juego/assets/Props/chests/aseprite%20files/brown_chest_opening.aseprite): scene objects · Doors, keys, ladders, save points, props, traps, and interactables · `juego/assets/Props/chests/aseprite files/brown_chest_opening.aseprite`
- [Enemies](https://github.com/l1tesg/dirty-road-godot/blob/HEAD/juego/assets/Enemies/Zombie/going%20left%20animations/aseprite%20files/zombie_attack_left_anim.aseprite): combat content · Hostile character and boss asset families used by levels · `juego/assets/Enemies/Zombie/going left animations/aseprite files/zombie_attack_left_anim.aseprite`
- [UI assets](https://github.com/l1tesg/dirty-road-godot/blob/HEAD/juego/assets/User%20Interface/char%20hud/health%20bar/aseprite%20files/health_bar.aseprite): art assets · HUD and theme resources for in-game presentation · `juego/assets/User Interface/char hud/health bar/aseprite files/health_bar.aseprite`
- [Audio](https://github.com/l1tesg/dirty-road-godot/blob/main/juego/assets/music/Glint_of_the_Falls.mp3): music assets · Imported music used by the game · `juego/assets/music/Glint_of_the_Falls.mp3`
- [Art pipeline](https://github.com/l1tesg/dirty-road-godot/blob/HEAD/juego/assets/Another%20Metroidvania%20Asset%20Pack%20Vol.%201%20ver.%201.7/read%20me%20(or%20not).txt): aseprite assets · Large imported Aseprite source pack and update drops feeding Godot scenes · `juego/assets/Another Metroidvania Asset Pack Vol. 1 ver. 1.7/read me (or not).txt`
- [Camera addon](https://github.com/l1tesg/dirty-road-godot/blob/main/juego/addons/phantom_camera/plugin.cfg): embedded plugin · Third-party Phantom Camera plugin boundary used for following/framing · `juego/addons/phantom_camera/plugin.cfg`
- [Camera runtime](https://github.com/l1tesg/dirty-road-godot/blob/main/juego/addons/phantom_camera/scripts/phantom_camera/phantom_camera_2d.gd): addon runtime · Core camera manager and camera host classes · `juego/addons/phantom_camera/scripts/phantom_camera/phantom_camera_2d.gd`
- [Editor tools](https://github.com/l1tesg/dirty-road-godot/blob/main/juego/addons/phantom_camera/panel/editor.tscn): addon editor · Inspector, panel, and gizmo tooling for the camera addon · `juego/addons/phantom_camera/panel/editor.tscn`
- [Examples](https://github.com/l1tesg/dirty-road-godot/blob/main/juego/addons/phantom_camera/examples/example_scenes/2D/2d_example_scene.tscn): addon samples · Vendor example scenes and sample scripts shipped with the addon · `juego/addons/phantom_camera/examples/example_scenes/2D/2d_example_scene.tscn`

### Website

Independent Astro static site

- [Website](https://github.com/l1tesg/dirty-road-godot/blob/main/pagina-web/src/pages/index.astro): astro app · Independent static website project · `pagina-web/src/pages/index.astro`

### Docs

Supporting documentation

- [Docs](https://github.com/l1tesg/dirty-road-godot/blob/main/documentos/APA.docx): documentation · Supporting repository documentation · `documentos/APA.docx`

## Connections

- Project → Main menu: launches · Godot runtime starts in the main menu flow
- Main menu → Start menu: navigates to · Menu scene hands off to the start menu
- Main menu → Save select: opens · Menu flow leads into save/profile selection
- Main menu → Level 1: starts · Menu can transition directly into gameplay
- Save select → Level 1: loads · Selected slot enters the main level
- Level 1 → Player: spawns · Gameplay level composes the player scene
- Level 1 → World content: assembles · Level scene places doors, keys, ladders, props, traps, and save points
- Level 1 → Enemies: populates · Level scene includes hostile encounters
- Level 1 → UI assets: overlays · Gameplay renders HUD and theme resources
- Level 1 → Audio: plays · Level can attach music and sound assets
- Sewer level → World content: assembles · Sewer scene uses the same content-driven object model
- Sewer level → Enemies: populates · Sewer environment includes combatants and hazards
- Player → World content: interacts with · Player actions trigger doors, keys, save points, and usable items
- Player → Enemies: engages · Player movement and combat respond to enemy encounters
- Art pipeline → Level 1: feeds · Imported art packs are turned into level-ready content
- Art pipeline → Player: feeds · Character animations and variants support the player scene
- Camera addon → Camera runtime: contains · Addon runtime classes and manager logic
- Camera addon → Editor tools: contains · Addon editor panels and gizmos
- Camera addon → Examples: ships · Example scenes demonstrate addon behavior
- Camera runtime → Level 1: follows · Gameplay levels use the camera system for framing
- Website → Docs: complements · Static website sits beside repository documentation
