Subterrâneo

A 2D top-down cave adventure built in Godot 4.3 — explore nine connected mine levels, fight your way through, ride minecarts between sections and destroy the monster blocking the crystal at the bottom.

English · Português (Brasil)

_{Made for a Computer Graphics course. Game text is in Brazilian Portuguese.}

Regular level	Minecart traversal

• Nine hand-drawn levels connected by exits and rails, from the mine entrance to the Crystal Core.
• Melee combat — a short-range strike that hits every enemy within 72 px of the point in front of the player.
• Enemies that hunt you — they chase within a detection radius and strike on a cooldown; the boss sees you from much farther and enters a faster, harder-hitting second phase at half health.
• Progression gates — exits and minecarts only unlock once every enemy in the current area is down.
• Minecarts — board a cart with E and it carries you along a rail path into the next section, with the arrival handled on the other side.
• HUD — health, the current objective, control hints, warnings when a gate is still locked, and a pause menu.
• Save & continue — health and position persist across scene changes, and the main menu offers Continue when a save exists.
• Data-driven collisions — each map's interior walls come from a JSON file in data/collisions/, with a generated fallback.

gabesilvadev.github.io/Subterraneo — the Web export, no install needed. Desktop browser with keyboard recommended.

Grab the build for your system from Releases:

Both are single-file builds with the game data embedded.

1. Install Godot 4.3 (standard build, no .NET required).
2. Clone the repository and open project.godot in the editor — or run it headless:

git clone https://github.com/GabeSilvaDev/Subterraneo.git
cd Subterraneo
godot --path .            # runs the main scene (res://scenes/MainMenu.tscn)

export_presets.cfg ships with three presets. With the 4.3 export templates installed:

godot --headless --path . --export-release "Windows Desktop" build/subterraneo-windows.zip
godot --headless --path . --export-release "Linux"           build/subterraneo-linux.zip
godot --headless --path . --export-release "Web"             build/web/index.html

The Web preset has thread support disabled, so the export runs on plain static hosting (GitHub Pages included) without cross-origin isolation headers. The published site is the build/web folder pushed to the gh-pages branch.

flowchart LR
    MM[MainMenu] -->|Play / Continue| STM[SceneTransitionManager]
    STM -->|fade + change_scene| MAP[Map_01 … Map_09<br/>extends MapBase]
    MAP --> P[Player<br/>Attack · Health · Animator]
    MAP --> E[Enemy / Boss<br/>Health · Animator]
    MAP --> X[ExitInteractArea]
    MAP --> C[Minecart<br/>RailPath · RailConfig]
    X & C -->|all enemies dead?| STM
    P & E --> GM[(GameManager<br/>autoload)]
    GM --> HUD
    GM --> SM[(SaveManager<br/>user://save_game.json)]

• Autoloads — GameManager holds the global state (player reference, current map and spawn target, saved health, cart arrival, boss and crystal flags) and emits the gameplay signals the HUD listens to; SceneTransitionManager fades out, switches scenes and fades back in; SaveManager reads and writes user://save_game.json; MapCollisionConfig is the generated fallback for map walls.
• Maps — every level scene extends MapBase, which spawns the player at the right marker (default, "from cart", or the saved position on Continue), configures the camera limits, loads the map's interior collision rectangles from JSON and restores health after a transition.
• Player — Player handles movement, PlayerAttack collects damageable nodes from the enemy groups inside the attack range, PlayerHealth tracks HP and dispatches death, PlayerAnimator swaps direction-based textures.
• Enemies — Enemy chases the player inside detection_radius (160 px), attacks every attack_cooldown (1.5 s) and fades out on death; Boss extends it with a 400 px radius, 100 HP, and a phase 2 at 50 % HP that adds speed and cuts the cooldown to 0.7 s. Killing the boss triggers the win.
• Rails — Minecart moves the player along a RailPath using the per-cart RailConfig (destination map and spawn); the destination map's MapBase finishes the ride on arrival.

Map_01 → Map_02 → Map_03 → Map_04 → Map_05 → Map_06 → Map_07 → Map_08 → Map_09 (Crystal Core)

Exits and minecarts are the two ways forward. Where an area has enemies, both stay locked until the area is cleared — the HUD tells you when you try too early.

Subterraneo/
├── Maps/                  base map images (nine levels)
├── player/ playerCart/    player sprites, on foot and in the cart
├── enemy/ cart/           enemy and empty-cart sprites
├── data/collisions/       Map_XX_collisions.json — interior walls per level
├── docs/images/           screenshots used here
├── scenes/
│   ├── MainMenu.tscn      main scene
│   ├── maps/              Map_01 … Map_09
│   └── ui/                HUD
├── scripts/
│   ├── core/              GameManager · SaveManager · SceneTransitionManager ·
│   │                      MapBase · MapLoader · MapCollisionConfig · ExitInteractArea
│   ├── player/            Player · PlayerAttack · PlayerHealth · PlayerAnimator
│   ├── enemies/           Enemy · Boss · EnemyHealth · EnemyAnimator
│   ├── rails/             Minecart · RailPath · RailConfig · CartAnimator
│   └── ui/                MainMenu · HUD
├── export_presets.cfg     Windows · Linux · Web
└── project.godot          Godot 4.3, GL Compatibility renderer, 1280×720

Developed as the practical assignment of a Computer Graphics course: sprites, tile-based maps, a 2D camera, scene transitions and a small set of gameplay systems in a shape that can be presented and evaluated.

The source code (GDScript, scenes and project files) is released under the MIT License © Gabriel Silva.

Gabriel Silva