# alyare07/practicagamerework architecture

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

- Interactive diagram: https://gitdiagram.com/alyare07/practicagamerework
- Repository: https://github.com/alyare07/practicagamerework

## Overview

#### Purpose and Entry Points
This is a desktop Java 2D game engine/application with playable combat, maps, inventory, UI, sound, and an integrated map editor. Startup and top-level execution are centered on `src/principal/Main.java`, with primary loop/controller variants in `src/principal/GestorPrincipal.java` and `src/principal/GestorPrincipalMultiHilo.java`.

#### Runtime Shell and State Transitions
A state-machine layer selects application modes: gameplay, menus, loading screens, and editor. `src/principal/maquinaestado/GestorEstados.java` coordinates transitions; gameplay is represented by `src/principal/maquinaestado/estados/GestorJuego.java` and `src/principal/maquinaestado/estados/GestorPartida.java`. Menu-driven entry paths live under `src/principal/maquinaestado/estados/menu/MenuPrincipal.java`, while map loading is staged through `src/principal/maquinaestado/estados/pantallaCarga/GestorCargaMapa.java`.

#### World, Scenarios, and Persistence Boundary
The map domain models worlds, terrain, tiles, loaded maps, spawns, and teleport areas. Core abstractions are `src/principal/mapa/Mundo.java`, `src/principal/mapa/Tile.java`, and `src/principal/mapa/mapas/MapaManager.java`. Scenario ingestion is isolated in `src/principal/mapa/escenario/EscenarioLoader.java`, consuming scenario files such as `escenario1.json` and `mundos/escenario1.esc`; saved/generated map artifacts are stored under `mundos/`. Teleport transitions are modeled in `src/principal/mapa/escenario/tps/PuertaTP.java`.

#### Entity, Combat, and Item Model
`src/principal/entes/Ente.java` is the likely common entity boundary, specialized into player/creatures, world objects, particles, and projectiles. Player and enemy gameplay flows pass through `src/principal/entes/criaturas/Jugador.java` and `src/principal/entes/criaturas/enemigos/Enemigo.java`. Attacks produce projectile/melee objects such as `src/principal/entes/proyectil/Proyectil.java` and `src/principal/entes/proyectil/GolpeMele.java`; weapons and consumables are represented by `src/principal/entes/objetos/items/armas/Arma.java` and `src/principal/entes/objetos/items/Consumible.java`. Inventory/equipment is a separate UI-facing aggregate rooted at `src/principal/inventario/Inventario.java`.

#### Update, Input, Events, and AI
The main runtime likely repeatedly gathers keyboard/mouse input, updates the active state and world entities, resolves events/collisions, then renders. Input adapters are `src/principal/controles/Teclado.java` and `src/principal/controles/Raton.java`. Gameplay triggers are represented by `src/principal/eventos/Evento.java` and specialized tile/entity events. Enemy navigation is a distinct algorithm boundary using A* and Dijkstra implementations in `src/principal/ia/aEstrella/AEstrella.java` and `src/principal/ia/dijkstra/DijkstraRework.java`.

#### Rendering, Camera, UI, and Assets
Native Java graphics are wrapped by `src/principal/graficos/Ventana.java` and `src/principal/graficos/SuperficieDibujo.java`. Map/entity rendering and camera clipping are separated in `src/principal/mapa/renderEntidades/MapRender.java` and `src/principal/mapa/renderEntidades/camara/Camara.java`. HUD/UI is managed by `src/principal/igu/MotorIGU.java`, including health/stamina bars. Sprite animation is organized around `src/principal/animaciones/Animacion.java` and player-specific animation definitions.

Assets are local filesystem resources: images under `recursos/`, sounds under `sonidos/`, and MP3 playback utilities in `src/principal/utilidades/SonidoMP3.java`. External JAR dependencies are bundled locally: JSON Simple for scenario/data parsing (`lib/json-simple-1.1.1.jar`) and Jaco MP3 player (`lib/jaco-mp3-player-0.9.3.jar`). No network service or server infrastructure is evident.

#### Editor and Authoring Flow
The application includes an in-process map editor, entered as a state and operating on the same world/tile model used by gameplay. Its core is `src/principal/maquinaestado/estados/editor/EditorMapa.java`, with editable world representation in `src/principal/maquinaestado/estados/editor/MundoEditor.java` and palette selection via `src/principal/maquinaestado/estados/editor/Paleta.java`. This creates a key boundary between authoring/saving map data and the loader-driven runtime map flow.

Main entry points: [`src/principal/maquinaestado/GestorEstados.java`](https://github.com/alyare07/practicagamerework/blob/main/src/principal/maquinaestado/GestorEstados.java) (State manager), [`src/principal/maquinaestado/estados/GestorJuego.java`](https://github.com/alyare07/practicagamerework/blob/main/src/principal/maquinaestado/estados/GestorJuego.java) (Game session), [`src/principal/GestorPrincipal.java`](https://github.com/alyare07/practicagamerework/blob/main/src/principal/GestorPrincipal.java) (Main loop), [`src/principal/mapa/escenario/EscenarioLoader.java`](https://github.com/alyare07/practicagamerework/blob/main/src/principal/mapa/escenario/EscenarioLoader.java) (Scenario loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & States"]
  node_main(("Application entry<br/>Java entry point<br/>[Main.java]"))
  node_loop["Main loop<br/>runtime controller"]
  node_states["State manager<br/>state machine<br/>[GestorEstados.java]"]
  node_menu["Main menu<br/>application state<br/>[MenuPrincipal.java]"]
  node_game["Game session<br/>gameplay states<br/>[GestorJuego.java]"]
  node_input["Input adapters<br/>keyboard and mouse<br/>[Teclado.java]"]
end

subgraph group_world["World &amp; Data"]
  node_loader["Map loading<br/>loading state"]
  node_scenario["Scenario loader<br/>data ingestion"]
  node_maps["Map manager<br/>world aggregate<br/>[MapaManager.java]"]
  node_worldmodel["World &amp; tiles<br/>map domain<br/>[Mundo.java]"]
  node_mapfiles[("Map artifacts<br/>local map data")]
end

subgraph group_gameplay["Gameplay Model"]
  node_entities["Entities<br/>entity hierarchy<br/>[Ente.java]"]
  node_combat["Player &amp; combat<br/>combat model<br/>[Jugador.java]"]
  node_inventory["Inventory<br/>equipment aggregate<br/>[Inventario.java]"]
  node_ai["Enemy pathfinding<br/>navigation algorithms<br/>[AEstrella.java]"]
  node_events["Events &amp; collisions<br/>gameplay events<br/>[Evento.java]"]
end

subgraph group_presentation["Presentation"]
  node_render["Map renderer &amp; camera<br/>2D rendering<br/>[MapRender.java]"]
  node_window["Window surface<br/>Java graphics shell<br/>[Ventana.java]"]
  node_ui["HUD &amp; UI<br/>UI engine<br/>[MotorIGU.java]"]
  node_sound["Sound playback<br/>MP3 utility<br/>[SonidoMP3.java]"]
  node_assets[("Images &amp; sounds<br/>local assets")]
end

subgraph group_editor["Map Authoring"]
  node_editorstate["Map editor<br/>editor state<br/>[EditorMapa.java]"]
  node_editorworld["Editable world<br/>editor model<br/>[MundoEditor.java]"]
  node_palette["Tile palette<br/>editor selection<br/>[Paleta.java]"]
end

node_main -->|"starts"| node_loop
node_loop -->|"updates active state"| node_states
node_input -->|"input"| node_loop
node_states -->|"menu mode"| node_menu
node_states -->|"gameplay mode"| node_game
node_states -->|"loading mode"| node_loader
node_states -->|"editor mode"| node_editorstate
node_loader -->|"loads"| node_scenario
node_scenario -->|"reads"| node_mapfiles
node_scenario -->|"builds"| node_maps
node_maps -->|"manages"| node_worldmodel
node_game -->|"runs in"| node_maps
node_game -->|"updates"| node_entities
node_entities -->|"specializes"| node_combat
node_combat -->|"uses items"| node_inventory
node_ai -->|"navigates"| node_worldmodel
node_game -->|"resolves"| node_events
node_loop -->|"renders"| node_render
node_render -->|"draws to"| node_window
node_ui -->|"overlays"| node_window
node_game -->|"HUD state"| node_ui
node_sound -->|"plays"| node_assets
node_editorstate -->|"edits"| node_editorworld
node_editorworld -->|"shares model"| node_worldmodel
node_palette -->|"selects tiles"| node_editorworld
node_editorstate -->|"saves maps"| node_mapfiles

click node_main "https://github.com/alyare07/practicagamerework/blob/main/src/principal/Main.java"
click node_loop "https://github.com/alyare07/practicagamerework/blob/main/src/principal/GestorPrincipal.java"
click node_states "https://github.com/alyare07/practicagamerework/blob/main/src/principal/maquinaestado/GestorEstados.java"
click node_menu "https://github.com/alyare07/practicagamerework/blob/main/src/principal/maquinaestado/estados/menu/MenuPrincipal.java"
click node_game "https://github.com/alyare07/practicagamerework/blob/main/src/principal/maquinaestado/estados/GestorJuego.java"
click node_loader "https://github.com/alyare07/practicagamerework/blob/main/src/principal/maquinaestado/estados/pantallaCarga/GestorCargaMapa.java"
click node_scenario "https://github.com/alyare07/practicagamerework/blob/main/src/principal/mapa/escenario/EscenarioLoader.java"
click node_maps "https://github.com/alyare07/practicagamerework/blob/main/src/principal/mapa/mapas/MapaManager.java"
click node_worldmodel "https://github.com/alyare07/practicagamerework/blob/main/src/principal/mapa/Mundo.java"
click node_entities "https://github.com/alyare07/practicagamerework/blob/main/src/principal/entes/Ente.java"
click node_combat "https://github.com/alyare07/practicagamerework/blob/main/src/principal/entes/criaturas/Jugador.java"
click node_inventory "https://github.com/alyare07/practicagamerework/blob/main/src/principal/inventario/Inventario.java"
click node_ai "https://github.com/alyare07/practicagamerework/blob/main/src/principal/ia/aEstrella/AEstrella.java"
click node_input "https://github.com/alyare07/practicagamerework/blob/main/src/principal/controles/Teclado.java"
click node_events "https://github.com/alyare07/practicagamerework/blob/main/src/principal/eventos/Evento.java"
click node_render "https://github.com/alyare07/practicagamerework/blob/main/src/principal/mapa/renderEntidades/MapRender.java"
click node_window "https://github.com/alyare07/practicagamerework/blob/main/src/principal/graficos/Ventana.java"
click node_ui "https://github.com/alyare07/practicagamerework/blob/main/src/principal/igu/MotorIGU.java"
click node_sound "https://github.com/alyare07/practicagamerework/blob/main/src/principal/utilidades/SonidoMP3.java"
click node_editorstate "https://github.com/alyare07/practicagamerework/blob/main/src/principal/maquinaestado/estados/editor/EditorMapa.java"
click node_editorworld "https://github.com/alyare07/practicagamerework/blob/main/src/principal/maquinaestado/estados/editor/MundoEditor.java"
click node_palette "https://github.com/alyare07/practicagamerework/blob/main/src/principal/maquinaestado/estados/editor/Paleta.java"

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_loop,node_states,node_menu,node_game,node_input toneBlue
class node_loader,node_scenario,node_maps,node_worldmodel,node_mapfiles toneAmber
class node_entities,node_combat,node_inventory,node_ai,node_events toneMint
class node_render,node_window,node_ui,node_sound,node_assets toneRose
class node_editorstate,node_editorworld,node_palette toneIndigo
```

## Components

### Runtime & States

- [Application entry](https://github.com/alyare07/practicagamerework/blob/main/src/principal/Main.java): Java entry point · `src/principal/Main.java`
- [Main loop](https://github.com/alyare07/practicagamerework/blob/main/src/principal/GestorPrincipal.java): runtime controller · Supports single- and multi-threaded loop variants. · `src/principal/GestorPrincipal.java`
- [State manager](https://github.com/alyare07/practicagamerework/blob/main/src/principal/maquinaestado/GestorEstados.java): state machine · `src/principal/maquinaestado/GestorEstados.java`
- [Main menu](https://github.com/alyare07/practicagamerework/blob/main/src/principal/maquinaestado/estados/menu/MenuPrincipal.java): application state · `src/principal/maquinaestado/estados/menu/MenuPrincipal.java`
- [Game session](https://github.com/alyare07/practicagamerework/blob/main/src/principal/maquinaestado/estados/GestorJuego.java): gameplay states · Coordinates game and match state execution. · `src/principal/maquinaestado/estados/GestorJuego.java`
- [Input adapters](https://github.com/alyare07/practicagamerework/blob/main/src/principal/controles/Teclado.java): keyboard and mouse · `src/principal/controles/Teclado.java`

### World & Data

- [Map loading](https://github.com/alyare07/practicagamerework/blob/main/src/principal/maquinaestado/estados/pantallaCarga/GestorCargaMapa.java): loading state · `src/principal/maquinaestado/estados/pantallaCarga/GestorCargaMapa.java`
- [Scenario loader](https://github.com/alyare07/practicagamerework/blob/main/src/principal/mapa/escenario/EscenarioLoader.java): data ingestion · Parses scenario definitions into runtime maps. · `src/principal/mapa/escenario/EscenarioLoader.java`
- [Map manager](https://github.com/alyare07/practicagamerework/blob/main/src/principal/mapa/mapas/MapaManager.java): world aggregate · `src/principal/mapa/mapas/MapaManager.java`
- [World & tiles](https://github.com/alyare07/practicagamerework/blob/main/src/principal/mapa/Mundo.java): map domain · Shared terrain, tile, spawn, and teleport model. · `src/principal/mapa/Mundo.java`
- **Map artifacts**: local map data · Scenario and generated map files.

### Gameplay Model

- [Entities](https://github.com/alyare07/practicagamerework/blob/main/src/principal/entes/Ente.java): entity hierarchy · Base for creatures, objects, particles, and projectiles. · `src/principal/entes/Ente.java`
- [Player & combat](https://github.com/alyare07/practicagamerework/blob/main/src/principal/entes/criaturas/Jugador.java): combat model · Players, enemies, weapons, consumables, and attacks. · `src/principal/entes/criaturas/Jugador.java`
- [Inventory](https://github.com/alyare07/practicagamerework/blob/main/src/principal/inventario/Inventario.java): equipment aggregate · `src/principal/inventario/Inventario.java`
- [Enemy pathfinding](https://github.com/alyare07/practicagamerework/blob/main/src/principal/ia/aEstrella/AEstrella.java): navigation algorithms · A* and Dijkstra drive enemy navigation. · `src/principal/ia/aEstrella/AEstrella.java`
- [Events & collisions](https://github.com/alyare07/practicagamerework/blob/main/src/principal/eventos/Evento.java): gameplay events · `src/principal/eventos/Evento.java`

### Presentation

- [Map renderer & camera](https://github.com/alyare07/practicagamerework/blob/main/src/principal/mapa/renderEntidades/MapRender.java): 2D rendering · Draws world and entities with camera clipping. · `src/principal/mapa/renderEntidades/MapRender.java`
- [Window surface](https://github.com/alyare07/practicagamerework/blob/main/src/principal/graficos/Ventana.java): Java graphics shell · `src/principal/graficos/Ventana.java`
- [HUD & UI](https://github.com/alyare07/practicagamerework/blob/main/src/principal/igu/MotorIGU.java): UI engine · `src/principal/igu/MotorIGU.java`
- [Sound playback](https://github.com/alyare07/practicagamerework/blob/main/src/principal/utilidades/SonidoMP3.java): MP3 utility · `src/principal/utilidades/SonidoMP3.java`
- **Images & sounds**: local assets

### Map Authoring

- [Map editor](https://github.com/alyare07/practicagamerework/blob/main/src/principal/maquinaestado/estados/editor/EditorMapa.java): editor state · In-process authoring mode sharing the game world model. · `src/principal/maquinaestado/estados/editor/EditorMapa.java`
- [Editable world](https://github.com/alyare07/practicagamerework/blob/main/src/principal/maquinaestado/estados/editor/MundoEditor.java): editor model · `src/principal/maquinaestado/estados/editor/MundoEditor.java`
- [Tile palette](https://github.com/alyare07/practicagamerework/blob/main/src/principal/maquinaestado/estados/editor/Paleta.java): editor selection · `src/principal/maquinaestado/estados/editor/Paleta.java`

## Connections

- Application entry → Main loop: starts
- Main loop → State manager: updates active state
- Input adapters → Main loop: input
- State manager → Main menu: menu mode
- State manager → Game session: gameplay mode
- State manager → Map loading: loading mode
- State manager → Map editor: editor mode
- Map loading → Scenario loader: loads
- Scenario loader → Map artifacts: reads
- Scenario loader → Map manager: builds
- Map manager → World & tiles: manages
- Game session → Map manager: runs in
- Game session → Entities: updates
- Entities → Player & combat: specializes
- Player & combat → Inventory: uses items
- Enemy pathfinding → World & tiles: navigates
- Game session → Events & collisions: resolves
- Main loop → Map renderer & camera: renders
- Map renderer & camera → Window surface: draws to
- HUD & UI → Window surface: overlays
- Game session → HUD & UI: HUD state
- Sound playback → Images & sounds: plays
- Map editor → Editable world: edits
- Editable world → World & tiles: shares model
- Tile palette → Editable world: selects tiles
- Map editor → Map artifacts: saves maps