# ramosblk/--hidden-way--- architecture

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

- Interactive diagram: https://gitdiagram.com/ramosblk/--hidden-way---
- Repository: https://github.com/ramosblk/--hidden-way---

## Overview

Hidden Way is a single-player 2D platform-adventure game. The player starts in a tutorial/menu area, enters the first map to collect a key and open a chest/cave route, then progresses through configured platform phases by collecting keys, avoiding hazards and reaching exits; death offers a restart or menu return. The graph separates states, gameplay entities, and supporting systems. Relationships reflect the README and shown source/index references; unsampled modules are represented only where the tree or index supports them.

Main entry points: [`classes/states/mapa1_state.py`](https://github.com/ramosblk/--hidden-way---/blob/main/classes/states/mapa1_state.py) (First map), [`classes/states/fase_state.py`](https://github.com/ramosblk/--hidden-way---/blob/main/classes/states/fase_state.py) (Platform phases), [`classes/states/inicio_state.py`](https://github.com/ramosblk/--hidden-way---/blob/main/classes/states/inicio_state.py) (Start and tutorial), [`classes/entities/player.py`](https://github.com/ramosblk/--hidden-way---/blob/main/classes/entities/player.py) (Player)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_states["Game states"]
  node_map1["First map<br/>[mapa1_state.py]"]
  node_phase["Platform phases<br/>[fase_state.py]"]
  node_start["Start and tutorial<br/>[inicio_state.py]"]
  node_game_state["State interface<br/>[game_state.py]"]
  node_complete_state["Phase-complete state"]
  node_over_state["Game-over state<br/>[game_over_state.py]"]
end

subgraph group_gameplay["Gameplay"]
  node_player["Player<br/>[player.py]"]
  node_key["Key collectible<br/>[chave.py]"]
  node_hazards["Enemies and hazards<br/>[inimigo.py]"]
  node_map_objects["Chest and cave"]
  node_exit_door["Exit door<br/>[porta.py]"]
end

subgraph group_systems["Game systems"]
  node_phase_data["Phase definitions<br/>[fases.py]"]
  node_manager["State manager<br/>[game_manager.py]"]
  node_collision["Collision physics<br/>[colisao.py]"]
  node_scenery["Scene rendering<br/>[cenario.py]"]
  node_hud["HUD<br/>[hud.py]"]
  node_fall["Fall transition<br/>[queda.py]"]
  node_fade["Screen transition<br/>[transicao.py]"]
  node_particles["Particles<br/>[particulas.py]"]
  node_audio["Synthesized audio<br/>[audio.py]"]
  node_assets["Image assets<br/>[assets.py]"]
  node_sprites["Player animation<br/>[sprites_player.py]"]
  node_tutorial["Tutorial prompts<br/>[tutorial.py]"]
end

subgraph group_screens["Result screens"]
  node_complete_screen["Completion screen<br/>[fase_completa.py]"]
  node_over_screen["Game-over screen<br/>[game_over.py]"]
  node_ui["Shared UI<br/>[ui.py]"]
end

node_actor(("Player"))

node_actor -->|"starts game"| node_start
node_start -->|"updates movement"| node_player
node_start -->|"moves and draws"| node_scenery
node_start -->|"updates and draws"| node_tutorial
node_start -->|"enters map"| node_map1
node_map1 -->|"updates movement"| node_player
node_map1 -->|"checks collection"| node_key
node_map1 -->|"handles interaction"| node_map_objects
node_map1 -->|"draws scene"| node_scenery
node_map1 -->|"updates notices"| node_hud
node_map1 -->|"starts fall effects"| node_particles
node_map1 -->|"starts and updates"| node_fall
node_map1 -->|"fades between scenes"| node_fade
node_map1 -->|"requests next phase"| node_phase_data
node_map1 -->|"switches on completion"| node_complete_state
node_phase_data -->|"creates configured phase"| node_phase
node_phase -->|"updates movement"| node_player
node_phase -->|"checks collection"| node_key
node_phase -->|"checks collisions"| node_hazards
node_phase -->|"handles exit"| node_exit_door
node_phase -->|"draws scene"| node_scenery
node_phase -->|"updates notices"| node_hud
node_phase -->|"handles death fall"| node_fall
node_phase -->|"fades transitions"| node_fade
node_phase -->|"starts fall effects"| node_particles
node_phase -->|"switches on death"| node_over_state
node_phase -.->|"switches on exit"| node_complete_state
node_player -->|"delegates collision"| node_collision
node_player -->|"uses animations"| node_sprites
node_player -->|"plays jump sound"| node_audio
node_map1 -->|"plays game sounds"| node_audio
node_phase -->|"plays game sounds"| node_audio
node_start -->|"changes state"| node_manager
node_map1 -->|"changes state"| node_manager
node_complete_state -->|"updates and draws"| node_complete_screen
node_complete_state -->|"continues or returns"| node_manager
node_complete_state -->|"plays victory sound"| node_audio
node_over_state -->|"handles and draws"| node_over_screen
node_over_state -->|"restarts or returns"| node_manager
node_over_state -->|"plays game-over sound"| node_audio
node_over_screen -->|"uses shared UI"| node_ui
node_complete_screen -->|"uses shared UI"| node_ui
node_hud -->|"uses shared UI"| node_ui
node_map1 -->|"loads entity images"| node_assets

click node_player "https://github.com/ramosblk/--hidden-way---/blob/main/classes/entities/player.py"
click node_map1 "https://github.com/ramosblk/--hidden-way---/blob/main/classes/states/mapa1_state.py"
click node_phase "https://github.com/ramosblk/--hidden-way---/blob/main/classes/states/fase_state.py"
click node_phase_data "https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/fases.py"
click node_start "https://github.com/ramosblk/--hidden-way---/blob/main/classes/states/inicio_state.py"
click node_manager "https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/game_manager.py"
click node_game_state "https://github.com/ramosblk/--hidden-way---/blob/main/classes/states/game_state.py"
click node_key "https://github.com/ramosblk/--hidden-way---/blob/main/classes/entities/chave.py"
click node_hazards "https://github.com/ramosblk/--hidden-way---/blob/main/classes/entities/inimigo.py"
click node_map_objects "https://github.com/ramosblk/--hidden-way---/tree/main/classes/entities"
click node_exit_door "https://github.com/ramosblk/--hidden-way---/blob/main/classes/entities/porta.py"
click node_collision "https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/colisao.py"
click node_scenery "https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/cenario.py"
click node_hud "https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/hud.py"
click node_fall "https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/queda.py"
click node_fade "https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/transicao.py"
click node_particles "https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/particulas.py"
click node_audio "https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/audio.py"
click node_assets "https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/assets.py"
click node_sprites "https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/sprites_player.py"
click node_tutorial "https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/tutorial.py"
click node_complete_state "https://github.com/ramosblk/--hidden-way---/blob/main/classes/states/fase_completa_state.py"
click node_complete_screen "https://github.com/ramosblk/--hidden-way---/blob/main/classes/fase_completa.py"
click node_over_state "https://github.com/ramosblk/--hidden-way---/blob/main/classes/states/game_over_state.py"
click node_over_screen "https://github.com/ramosblk/--hidden-way---/blob/main/classes/game_over.py"
click node_ui "https://github.com/ramosblk/--hidden-way---/blob/main/classes/ui.py"

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_map1,node_phase,node_start,node_game_state,node_complete_state,node_over_state toneBlue
class node_player,node_key,node_hazards,node_map_objects,node_exit_door toneAmber
class node_phase_data,node_manager,node_collision,node_scenery,node_hud,node_fall,node_fade,node_particles,node_audio,node_assets,node_sprites,node_tutorial toneMint
class node_complete_screen,node_over_screen,node_ui toneRose
class node_actor toneIndigo
```

## Components

### Game states

- [First map](https://github.com/ramosblk/--hidden-way---/blob/main/classes/states/mapa1_state.py): `classes/states/mapa1_state.py`
- [Platform phases](https://github.com/ramosblk/--hidden-way---/blob/main/classes/states/fase_state.py): `classes/states/fase_state.py`
- [Start and tutorial](https://github.com/ramosblk/--hidden-way---/blob/main/classes/states/inicio_state.py): `classes/states/inicio_state.py`
- [State interface](https://github.com/ramosblk/--hidden-way---/blob/main/classes/states/game_state.py): `classes/states/game_state.py`
- [Phase-complete state](https://github.com/ramosblk/--hidden-way---/blob/main/classes/states/fase_completa_state.py): `classes/states/fase_completa_state.py`
- [Game-over state](https://github.com/ramosblk/--hidden-way---/blob/main/classes/states/game_over_state.py): `classes/states/game_over_state.py`

### Gameplay

- [Player](https://github.com/ramosblk/--hidden-way---/blob/main/classes/entities/player.py): `classes/entities/player.py`
- [Key collectible](https://github.com/ramosblk/--hidden-way---/blob/main/classes/entities/chave.py): `classes/entities/chave.py`
- [Enemies and hazards](https://github.com/ramosblk/--hidden-way---/blob/main/classes/entities/inimigo.py): `classes/entities/inimigo.py`
- [Chest and cave](https://github.com/ramosblk/--hidden-way---/tree/main/classes/entities): `classes/entities`
- [Exit door](https://github.com/ramosblk/--hidden-way---/blob/main/classes/entities/porta.py): `classes/entities/porta.py`

### Game systems

- [Phase definitions](https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/fases.py): `classes/systems/fases.py`
- [State manager](https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/game_manager.py): `classes/systems/game_manager.py`
- [Collision physics](https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/colisao.py): `classes/systems/colisao.py`
- [Scene rendering](https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/cenario.py): `classes/systems/cenario.py`
- [HUD](https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/hud.py): `classes/systems/hud.py`
- [Fall transition](https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/queda.py): `classes/systems/queda.py`
- [Screen transition](https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/transicao.py): `classes/systems/transicao.py`
- [Particles](https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/particulas.py): `classes/systems/particulas.py`
- [Synthesized audio](https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/audio.py): `classes/systems/audio.py`
- [Image assets](https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/assets.py): `classes/systems/assets.py`
- [Player animation](https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/sprites_player.py): `classes/systems/sprites_player.py`
- [Tutorial prompts](https://github.com/ramosblk/--hidden-way---/blob/main/classes/systems/tutorial.py): `classes/systems/tutorial.py`

### Result screens

- [Completion screen](https://github.com/ramosblk/--hidden-way---/blob/main/classes/fase_completa.py): `classes/fase_completa.py`
- [Game-over screen](https://github.com/ramosblk/--hidden-way---/blob/main/classes/game_over.py): `classes/game_over.py`
- [Shared UI](https://github.com/ramosblk/--hidden-way---/blob/main/classes/ui.py): `classes/ui.py`

### Other components

- **Player**

## Connections

- Player → Start and tutorial: starts game (evidence: `README.md`)
- Start and tutorial → Player: updates movement (evidence: `classes/states/inicio_state.py`)
- Start and tutorial → Scene rendering: moves and draws (evidence: `classes/states/inicio_state.py`)
- Start and tutorial → Tutorial prompts: updates and draws (evidence: `classes/states/inicio_state.py`)
- Start and tutorial → First map: enters map (evidence: `classes/states/inicio_state.py`)
- First map → Player: updates movement (evidence: `classes/states/mapa1_state.py`)
- First map → Key collectible: checks collection (evidence: `classes/states/mapa1_state.py`)
- First map → Chest and cave: handles interaction (evidence: `classes/states/mapa1_state.py`)
- First map → Scene rendering: draws scene (evidence: `classes/states/mapa1_state.py`)
- First map → HUD: updates notices (evidence: `classes/states/mapa1_state.py`)
- First map → Particles: starts fall effects (evidence: `classes/states/mapa1_state.py`)
- First map → Fall transition: starts and updates (evidence: `classes/states/mapa1_state.py`)
- First map → Screen transition: fades between scenes (evidence: `classes/states/mapa1_state.py`)
- First map → Phase definitions: requests next phase (evidence: `classes/states/mapa1_state.py`)
- First map → Phase-complete state: switches on completion (evidence: `classes/states/mapa1_state.py`)
- Phase definitions → Platform phases: creates configured phase (evidence: `classes/systems/fases.py`)
- Platform phases → Player: updates movement (evidence: `classes/states/fase_state.py`)
- Platform phases → Key collectible: checks collection (evidence: `classes/states/fase_state.py`)
- Platform phases → Enemies and hazards: checks collisions (evidence: `classes/states/fase_state.py`)
- Platform phases → Exit door: handles exit (evidence: `classes/states/fase_state.py`)
- Platform phases → Scene rendering: draws scene (evidence: `classes/states/fase_state.py`)
- Platform phases → HUD: updates notices (evidence: `classes/states/fase_state.py`)
- Platform phases → Fall transition: handles death fall (evidence: `classes/states/fase_state.py`)
- Platform phases → Screen transition: fades transitions (evidence: `classes/states/fase_state.py`)
- Platform phases → Particles: starts fall effects (evidence: `classes/states/fase_state.py`)
- Platform phases → Game-over state: switches on death (evidence: `classes/states/fase_state.py`)
- Platform phases → Phase-complete state: switches on exit (evidence: `classes/states/fase_state.py`)
- Player → Collision physics: delegates collision (evidence: `classes/entities/player.py`)
- Player → Player animation: uses animations (evidence: `classes/entities/player.py`)
- Player → Synthesized audio: plays jump sound (evidence: `classes/entities/player.py`)
- First map → Synthesized audio: plays game sounds (evidence: `classes/states/mapa1_state.py`)
- Platform phases → Synthesized audio: plays game sounds (evidence: `classes/states/fase_state.py`)
- Start and tutorial → State manager: changes state (evidence: `classes/states/inicio_state.py`)
- First map → State manager: changes state (evidence: `classes/states/mapa1_state.py`)
- Phase-complete state → Completion screen: updates and draws (evidence: `classes/states/fase_completa_state.py`)
- Phase-complete state → State manager: continues or returns (evidence: `classes/states/fase_completa_state.py`)
- Phase-complete state → Synthesized audio: plays victory sound (evidence: `classes/states/fase_completa_state.py`)
- Game-over state → Game-over screen: handles and draws (evidence: `classes/states/game_over_state.py`)
- Game-over state → State manager: restarts or returns (evidence: `classes/states/game_over_state.py`)
- Game-over state → Synthesized audio: plays game-over sound (evidence: `classes/states/game_over_state.py`)
- Game-over screen → Shared UI: uses shared UI (evidence: `classes/game_over.py`)
- Completion screen → Shared UI: uses shared UI (evidence: `classes/fase_completa.py`)
- HUD → Shared UI: uses shared UI (evidence: `classes/systems/hud.py`)
- First map → Image assets: loads entity images
