A seeded dungeon crawler built with Godot and GDScript. Every run builds a new dungeon that you can explore and finish. Descend three floors. Every floor grows harder. The final floor is a boss fight.
####.D.############
##.........####..###
#######.#####.#..#E#
##...##......##.#..#
##.D.###.####.#####.
##......##.....#...#
##########.D..######
Dungeonwright generates a connected dungeon on every run. You explore rooms and corridors. You find keys, open locked doors, and reach the exit. Some monsters fight from a distance. You can throw bombs you loot from monsters. Sound and music are generated in code. The exit leads to the next floor. After three floors, the run ends in victory. The same seed always builds the same dungeon.
- A new map for every run, driven by a seed.
- Three floors per run with a depth counter.
- Rooms, corridors, locked doors, and keys.
- Five biomes with different generation rules.
- Monsters with simple combat and balanced drops.
- Ranged monsters that fire dodgeable projectiles.
- A bomb item that blasts a crowd of monsters.
- A boss floor guarded by the Warden.
- The Warden fires bolt volleys and enrages below half health.
- A relic that ends the run when the Warden falls.
- An emblem item that boosts the hero's sword damage.
- Monsters grow stronger on deeper floors.
- Procedural pixel art with no bundled image files.
- Procedural sound and music with no bundled audio files.
- A minimap, a health bar, and run summary overlays.
- Deterministic generation for replayable runs.
- Full gamepad support with analog movement.
This release ships a playable demo. The generator guarantees the exit is always reachable. You can walk, fight, collect loot, and finish a run. You can replay any run from its seed.
This release adds the Tidebound Archive. Flooded galleries use winding corridors and larger rooms. Extra loops create more route choices. Teal and amber tiles give the biome a clear identity. Its procedural music theme uses a matching chord set.
The final floor still holds the Warden boss.
This release adds a boss floor. The final floor is a sealed arena. The Warden guards the exit. It slams in melee and fires bolt volleys. Below half health, it enrages and fights faster. It drops a relic when it falls. Collect the relic to win the run. Monsters can now drop damage emblems. Each emblem raises the hero's sword damage. A tense theme plays while the Warden lives.
Release 0.6 added procedural audio. Every sound effect is generated in code at run time. Sword swings, hits, deaths, and explosions all have cues. Each pickup has a distinct sound. Every biome has its own looping music theme. The menu plays a quiet theme of its own. No audio files ship with the game.
Release 0.5 added a fourth biome and a bomb item. The Frost Vault is a hall of blue ice. Its corridors wind between vast frozen chambers. A new monster, the Hollow Wraith, rushes the hero with speed. It falls quickly once cornered. Monsters can now drop bombs. A thrown bomb lands, waits, and then blasts every monster in a radius. The blast never hurts the hero. The HUD shows the shards and bombs you carry.
Release 0.4 added ranged combat. The Bone Archer fires bolts at the hero. Archers hold their ground and shoot when they can see you. Bolts fly straight until a wall stops them. The hero can dodge a bolt by moving off its line.
Release 0.3 added multi-floor descent. A run spans three floors. Each floor is a new solvable dungeon. Monsters grow stronger with depth. The hero keeps health and loot between floors. Keys reset when the hero descends. The hero heals a little on each descent. The HUD shows the current floor.
- Godot 4.6 or newer.
- Install Godot 4.6 from the official site.
- Clone this repository.
- Set
GODOT_BINto the Godot executable. - Run
tools/run_game.ps1on Windows. - Run
tools/run_game.shon Linux or macOS.
The scripts find Godot on PATH automatically. On Windows they also search common install locations.
Type a seed in the menu to replay a run. Leave the field empty for a random seed.
Move with WASD or the arrow keys. Attack with Space, J, or a mouse click. Throw a bomb with B. Press N for a new run. Press M to toggle the minimap. Press Escape to pause.
A gamepad works too. Move with the left stick or the d-pad. Attack with A or the right shoulder button. Throw a bomb with X. Press Y for a new run. Press Select to toggle the minimap. Press Start to pause.
Run tools/run_tests.ps1 on Windows.
Run tools/run_tests.sh on Linux or macOS.
The script installs GUT, imports the project, and runs the suite. Tests run headless, so no window opens.
GUT is a test addon for Godot.
The tool scripts can download and install it.
The version and checksum are pinned in tools/gut.version.json.
The tests run from the copy in addons/gut.
The generator has a fixed pipeline. It places rooms, connects them with corridors, and carves the map. It picks the farthest room as the exit. It places doors on corridors and puts each key on the safe side. A solver then proves the dungeon can be completed.
The generation code is pure data. It has no scene nodes, so tests run fast and deterministic. The scene controller turns the map into a live game.
Five biomes ship with the demo. Each biome changes map dimensions, room rules, monster pressure, palette, and music. The Tidebound Archive uses winding galleries, larger rooms, and frequent shortcut loops.
A run descends through three floors.
RunRules sets the floor count and the difficulty curve.
Each floor uses a seed derived from the run seed.
Floor one uses the run seed itself.
Deeper floors mix the run seed with the floor number.
The hero keeps health and loot between floors.
Monsters use scaled stats on deeper floors.
The run ends on the final floor.
Ranged monsters add a second combat layer.
An archer fires when the hero is in range and visible.
A Combat helper checks line of sight between tiles.
Bolts carry a speed, a direction, and a range.
Walls and locked doors stop a bolt.
The hero can sidestep a bolt because bolts take time to arrive.
Bombs give the hero an area attack. A monster drop can carry a bomb. The hero throws a bomb two tiles ahead. Walls stop a thrown bomb. After a short fuse, the bomb blasts every monster in a square radius. The blast damage scales with the hero's sword.
Audio is generated, never recorded.
The Waveform class synthesizes tones and noise bursts.
It applies attack and release so sounds do not click.
The SoundBank class builds every effect cue from these parts.
The MusicTheme class builds a looping pad for each biome.
An AudioController node plays effects and music.
It reuses a small pool of effect players.
Every stream is cached after its first build.
The same cue always produces the same sound.
The final floor is a boss floor. The generator marks a tile next to the exit for the Warden. The Warden chases the hero and slams in melee. At range, it fires a fan of three bolts. Below half health, it enrages. An enraged Warden moves and attacks faster. The exit stays sealed while the Warden lives. When it falls, it drops a relic. Collecting the relic wins the run. The HUD shows a boss bar while the Warden lives.
Emblems are a rare monster drop. Each emblem adds two points of sword damage. The bonus lasts for the whole run. It carries between floors.
scripts/dungeonholds the generator and map logic.scripts/combatholds stats, monsters, and loot tables.scripts/audioholds the sound synthesis and music themes.scripts/coreholds run rules and shared run state.scripts/inputholds the controls helper.scripts/worldrenders tiles and builds the minimap.scripts/actorsholds the hero, monsters, pickups, and projectiles.scripts/uibuilds the HUD and overlays.scenesholds the scene tree.testsholds the GUT suite.toolsholds the setup, test, and CI scripts.
Read docs/architecture.md for the system design.
A seed always produces the same map. A seed always produces the same floor sequence. Doors never block the exit permanently. Every key sits on the reachable side of its door. Monsters never cross a locked door. Bolts stop at walls and locked doors. Monsters never fire through a solid wall. A cue always produces the same sound. Every biome has a music theme. A boss floor seals the exit until the Warden falls. The Warden always drops a relic when it dies.
The suite has 205 tests and 5,004 assertions. All 205 tests pass in a headless run. It covers generation, all five biomes, combat, drops, pathfinding, input, floors, projectiles, bombs, and audio. It also covers the boss floor, bolt volleys, enrage, and the relic win. Run the full suite before release. A smoke test loads the game and spawns a fixed-seed run. The smoke test passes with seed 12345. The smoke test checks the hero descends after reaching the exit. The smoke test checks the boss floor spawns a Warden and a relic. The smoke test checks every action has a gamepad binding. The smoke test checks every monster and every drop item has art. The smoke test checks every sound cue and every music theme builds audio.
The smoke test prints this success line:
Smoke test passed: seed 12345 spawned a solvable dungeon across floors.
Done in this release:
- The Tidebound Archive, a fifth biome with winding galleries.
- A matching procedural music theme.
- A boss floor that seals the exit.
- The Warden, with melee slams, bolt volleys, and enrage.
- A relic that drops when the Warden falls.
- An emblem item that boosts sword damage.
- A boss music theme and a boss health bar.
Done in an earlier release:
- Procedural sound effects for combat, pickups, doors, and results.
- A distinct looping music theme for every biome.
- A fourth biome, the Frost Vault.
- The Hollow Wraith monster.
- A bomb item with a blast radius.
- Ranged monsters and dodgeable projectiles.
- Multi-floor descent with a depth counter.
- Full gamepad support.
Next up:
- A new item type with a focused use.
- A short in-game biome gallery.
Read the full release plan in docs/roadmap.md.
The demo has five biomes. Each run spans three floors. One boss type guards the final floor. The hero has one melee attack and one thrown item. Audio is instrumental, with no voice lines.
MIT. See the LICENSE file for details.