{"id":32477191,"url":"https://github.com/statico/godot-roguelike-example","last_synced_at":"2025-10-26T22:59:47.880Z","repository":{"id":320679652,"uuid":"1082316583","full_name":"statico/godot-roguelike-example","owner":"statico","description":"🧙‍♂️👾 Unfinished roguelike game made with Godot 4 with vision, inventory, BSP dungeon generation, behavior trees, and more","archived":false,"fork":false,"pushed_at":"2025-10-25T06:43:31.000Z","size":299,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-25T08:24:35.243Z","etag":null,"topics":["behavior-tree","dungeon-generation","game-development","gamedev","games","gdscript","godot","godot4","nethack","procedural-generation","procgen","roguelike","roguelike-game"],"latest_commit_sha":null,"homepage":"https://roguelike.statico.io","language":"GDScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/statico.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-24T04:08:45.000Z","updated_at":"2025-10-25T07:58:51.000Z","dependencies_parsed_at":"2025-10-25T08:34:44.877Z","dependency_job_id":null,"html_url":"https://github.com/statico/godot-roguelike-example","commit_stats":null,"previous_names":["statico/godot-roguelike-example"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/statico/godot-roguelike-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statico%2Fgodot-roguelike-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statico%2Fgodot-roguelike-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statico%2Fgodot-roguelike-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statico%2Fgodot-roguelike-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/statico","download_url":"https://codeload.github.com/statico/godot-roguelike-example/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statico%2Fgodot-roguelike-example/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281185456,"owners_count":26457747,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-26T02:00:06.575Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["behavior-tree","dungeon-generation","game-development","gamedev","games","gdscript","godot","godot4","nethack","procedural-generation","procgen","roguelike","roguelike-game"],"created_at":"2025-10-26T22:59:42.157Z","updated_at":"2025-10-26T22:59:47.861Z","avatar_url":"https://github.com/statico.png","language":"GDScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Statico's Godot Roguelike Example\n\nThis is an incomplete, copyable roguelike game made with Godot 4. It was originally going to be a sci-fi roguelike, but I decided to open-source it as a learning example. You can use it as a base for your own roguelike game. Play it [here](https://roguelike.statico.io), or play my original sci-fi themed roguelike [here](https://vesta.statico.io).\n\nAll code and assets are licensed permissively. The code is MIT licensed, the font is CC0, and the tileset is [Dawnlike from DawnBringer](https://opengameart.org/content/16x16-dawnhack-roguelike-tileset) and has its own license.\n\nQuestions? Ping me as `@statico` on the [Roguelikes Discord server](https://discord.gg/QATuUBAuQS).\n\n[![](https://github.com/user-attachments/assets/c326179c-dd2f-4e97-bc69-a18296267a67)](https://roguelike.statico.io/)\n\n**Tips:** Click to move or attack. Right-click to use ranged weapon. WASD and QEZC work as movement. Use the inventory button or \u003ckbd\u003ei\u003c/kbd\u003e key to pick up and manage items. Yes, there's a delay when you click the \"Play\" button while assets load.\n\n## Features\n\n- ✅ Turn-based roguelike mechanics (movement, vision, combat)\n- ✅ Inventory and equipment system with modular components\n- ✅ BSP-based dungeon generation with procedural content\n- ✅ Monster AI with behavior trees and factions\n- ✅ Combat system with D20-based mechanics, damage types, and status effects\n- ✅ Nutrition system affecting healing and survival\n- ✅ Field of view with fog of war\n- ✅ Throwable items with area-of-effect damage\n- ✅ Data-driven item and monster definitions\n- ✅ Dungeon generator preview tool inside Godot\n- ✅ Sprite toolchain for [Dawnlike](https://opengameart.org/content/16x16-dawnhack-roguelike-tileset) tiles that can be adapted to other tilesets\n\n### Missing Features\n\n- 🚫 Scrolls, wands, rings, and amulets\n- 🚫 Shops and economy\n- 🚫 Quests and objectives\n- 🚫 Save/load system\n\n## Development Setup\n\nYou can clone this repo and run it in Godot immediately. However, I recommend VS Code or the Cursor IDE alongside Godot in order to have the best editing experience.\n\n### Suggested Setup\n\n1. Install [gdtoolkit](https://github.com/Scony/gdtoolkit) - I recommend using [uv](https://docs.astral.sh/uv/):\n   1. `uv venv`\n   1. `source .venv/bin/activate`\n   1. `uv pip install gdtoolkit`\n   1. `gdlint --version` and check that it's 4.3.3 or later\n1. Install [VS Code](https://code.visualstudio.com/) or [Cursor](https://www.cursor.com/)\n1. Run `code` or `cursor` from the command line with the `uv` virtual environment activated so that `gdlint` and `gdformat` are accessible in the path. (I don't know a better way to do this.)\n1. Install the [Godot Tools](https://marketplace.visualstudio.com/items?itemName=geequlim.godot-tools) extension\n1. Install the [GDScript Formatter and Linter](https://marketplace.cursorapi.com/items?itemName=EddieDover.gdscript-formatter-linter) extension\n1. Open the project in Godot -- this starts the language server so that the formatter and linter can be used\n1. Open the project in VS Code / Cursor\n1. Run `Tasks: Run Task` and select `Run Godot Project`\n   - I like to bind \"Rerun Last Task\" to `Cmd-R` for a fast way to run the project from VS Code / Cursor\n\n### Editing Data\n\nMonster and item data is stored in CSV files in the `assets/data/` directory. I recommend [LibreOffice](https://www.libreoffice.org/) to edit the CSV files.\n\nCSV data files need their import settings set to \"Keep\" in the project settings in order to not generate translation files. [Read more here.](https://docs.godotengine.org/en/stable/tutorials/assets_pipeline/importing_translations.html#doc-importing-translations)\n\n### Art Pipeline\n\nThe art pipeline is designed to quickly ingest an existing tileset and give them simple names, like `wall-5-nw` and `reptile-10` that can be referenced in the code as [StringNames](https://docs.godotengine.org/en/stable/classes/class_stringname.html#class-stringname). The tools and pipeline are in the `art/` directory.\n\nThe full Dawnlike tileset isn't included in the project because that would be full redistribution, and I want to make sure nobody uses the entire tileset without understanding the author's license. If you want to use all of the Dawnlike tiles, you can:\n\n1. Read [the Dawnlike tileset license](https://opengameart.org/content/16x16-dawnhack-roguelike-tileset)\n1. Unzip the tileset into `art/Dawnlike`\n1. `cd art/`\n1. Read through the `gen_*.py` scripts\n   1. Set all the things like `SET_THIS_TO_FALSE_TO_GET_ALL_ITEMS` to `False`\n   1. Remove the watermark if you want\n1. Run `uv pip install -r requirements.txt`\n1. Run all the `gen_*.py` scripts\n1. Open the `gen_*_tileset.gd` scripts _from within Godot_ (you may have to disable the External Editor checkbox in the project settings) and run them (Cmd-Shift-X on Mac). You may need to reload the project.\n\nYou can also adapt these tools to read other tilesets, like Oryx tiles. They're easily editable with Cursor or Claude Code.\n\n### Map Generator Preview\n\nYou can use the map generator preview tool to test map generation parameters. Open `scenes/debug/map_generator_tool.tscn`, click MapGeneratorTool, and then click the \"Regenerate Map\" button to see the map generated with the current parameters.\n\n[\u003cimg height=\"500\" alt=\"map generator tool screenshot\" src=\"https://github.com/user-attachments/assets/ccdea42a-4813-444d-807e-10ba1fcbd75d\" /\u003e](https://roguelike.statico.io/)\n\n### Item \u0026 Sprite Explorers\n\nUse these tools to quickly reference tile and item names. Open `scenes/debug/sprite_explorer.tscn` and `scenes/debug/item_explorer.tscn` and click Run Current Scene (usually `Cmd-B` on Mac) to run them.\n\n\u003cimg width=\"400\" alt=\"sprite viewer screenshot\" src=\"https://github.com/user-attachments/assets/332db409-0a65-4a67-9270-b05f0808c6e2\" /\u003e\n\u003cimg width=\"400\" alt=\"item explorer screenshot\" src=\"https://github.com/user-attachments/assets/5bffd8d3-cbb3-4f7d-9265-539ce3cfe7c9\" /\u003e\n\n## Architecture Overview\n\n**World Management** ([`src/world.gd`](src/world.gd))\n\n- Central singleton that manages game state, turn progression, and coordinates all systems\n- Handles player actions, monster AI turns, and system updates (nutrition, status effects, healing)\n- Manages map generation and level transitions\n\n**Turn-Based Engine** ([`src/world.gd`](src/world.gd), [`src/actions/`](src/actions/))\n\n- Actions are the fundamental unit of gameplay - every player input and monster decision becomes an `Action`\n- Turn progression: Player acts → All monsters with sufficient energy act → Systems update → Vision updates\n- Energy system determines when monsters can act (faster monsters act more frequently)\n\n**Map Generation** ([`src/map_generators/`](src/map_generators/), [`src/world_plan.gd`](src/world_plan.gd))\n\n- BSP-based dungeon generation with configurable parameters\n- Multiple generator types (dungeon, arena) with different layouts\n- Procedural room placement, corridor connection, and content population\n- World planning system for multi-level dungeon structure\n\n**Combat System** ([`src/combat.gd`](src/combat.gd), [`src/damage.gd`](src/damage.gd))\n\n- D20-based combat with attack rolls, damage calculation, and resistances\n- Multiple damage types with monster-specific resistances\n- Melee and ranged combat with different mechanics\n- Status effects and area-of-effect damage\n\n**Monster AI** ([`src/monster_ai.gd`](src/monster_ai.gd), [`src/monster.gd`](src/monster.gd))\n\n- Behavior tree system for complex AI decision making\n- Different behavior types: aggressive, fearful, curious, passive\n- Pathfinding integration for movement and combat positioning\n- Faction system for monster relationships\n\n**Inventory \u0026 Equipment** ([`src/equipment.gd`](src/equipment.gd), [`src/item.gd`](src/item.gd), [`scenes/ui/inventory_modal.gd`](scenes/ui/inventory_modal.gd))\n\n- Modular equipment system with multiple slots (armor, weapons, accessories)\n- Hierarchical item system supporting containers and modules\n- Drag-and-drop inventory interface\n- Equipment affects combat stats and capabilities\n- Originally there was a sci-fi style power and module system but it was overly complex for this example\n\n**Vision \u0026 Rendering** ([`src/map.gd`](src/map.gd), [`src/map_renderer.gd`](src/map_renderer.gd))\n\n- Field of view calculation using shadowcasting algorithm\n- Fog of war with \"seen but not visible\" tiles\n- Tile-based rendering with sprite management\n- Visual effects system for combat and interactions\n\n**Status Effects \u0026 Nutrition** ([`src/status_effect.gd`](src/status_effect.gd), [`src/nutrition.gd`](src/nutrition.gd))\n\n- Status effect system with duration and magnitude\n- Nutrition system affecting healing and survival\n- Natural healing based on nutrition level\n- Status effects can modify behavior and capabilities\n\n**UI System** ([`src/modals.gd`](src/modals.gd), [`scenes/ui/`](scenes/ui/))\n\n- Modal system with stack-based management and smooth fade transitions\n- Async modal functions like `await Modals.confirm()` and `await Modals.prompt_for_direction()` for TypeScript-like await patterns\n- Comprehensive inventory system with drag-and-drop, equipment slots, and item categorization\n- HUD with health bars, status display, and contextual hover information\n\n### Data Flow\n\n1. **Input**: Player input → Action creation → World processing\n2. **Turn Processing**: Action execution → Monster AI → System updates → Vision update\n3. **Rendering**: World state → Map renderer → Visual effects → UI updates\n4. **Data**: CSV files → Factory classes → Game objects\n\n### Key Files to Explore\n\n- [`src/world.gd`](src/world.gd) - Core game loop and state management\n- [`src/monster_ai.gd`](src/monster_ai.gd) - AI behavior trees and decision making\n- [`src/map_generators/dungeon_generator.gd`](src/map_generators/dungeon_generator.gd) - Dungeon generation algorithm\n- [`src/combat.gd`](src/combat.gd) - Combat resolution and damage calculation\n- [`src/equipment.gd`](src/equipment.gd) - Equipment system and item management\n- [`scenes/game/game.gd`](scenes/game/game.gd) - Main game scene and input handling\n- [`assets/data/`](assets/data/) - CSV files defining items and monsters\n\n## Licenses\n\nSource code is MIT licensed.\n\nArtwork is from [Dawnlike from DawnBringer](https://opengameart.org/content/16x16-dawnhack-roguelike-tileset) and has its own license.\n\nThe font is [Pixel Operator](https://www.dafont.com/pixel-operator.font) and is licensed under [CC0](https://creativecommons.org/publicdomain/zero/1.0/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatico%2Fgodot-roguelike-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstatico%2Fgodot-roguelike-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatico%2Fgodot-roguelike-example/lists"}