{"id":23178404,"url":"https://github.com/lorandil/tinydungeon","last_synced_at":"2025-08-18T12:30:48.302Z","repository":{"id":203197249,"uuid":"321124595","full_name":"Lorandil/TinyDungeon","owner":"Lorandil","description":"Fully featured dungeon crawler for ATtiny85 with SSD1306 (e.g. TinyJoypad platform)","archived":false,"fork":false,"pushed_at":"2025-08-09T20:29:51.000Z","size":402,"stargazers_count":8,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-09T22:13:37.283Z","etag":null,"topics":["3d-graphics","attiny85","dungeon-crawler","dungeonmaster","game-development","oled","rpg","ssd1306","tinyjoypad"],"latest_commit_sha":null,"homepage":"","language":"C","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/Lorandil.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}},"created_at":"2020-12-13T17:48:53.000Z","updated_at":"2025-08-09T20:29:55.000Z","dependencies_parsed_at":null,"dependency_job_id":"4858b9c4-a974-49b3-8246-99270aa883aa","html_url":"https://github.com/Lorandil/TinyDungeon","commit_stats":null,"previous_names":["lorandil/tinydungeon"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Lorandil/TinyDungeon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lorandil%2FTinyDungeon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lorandil%2FTinyDungeon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lorandil%2FTinyDungeon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lorandil%2FTinyDungeon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Lorandil","download_url":"https://codeload.github.com/Lorandil/TinyDungeon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lorandil%2FTinyDungeon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270994984,"owners_count":24681852,"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-08-18T02:00:08.743Z","response_time":89,"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":["3d-graphics","attiny85","dungeon-crawler","dungeonmaster","game-development","oled","rpg","ssd1306","tinyjoypad"],"created_at":"2024-12-18T07:11:01.945Z","updated_at":"2025-08-18T12:30:47.776Z","avatar_url":"https://github.com/Lorandil.png","language":"C","readme":"# Tiny Dungeon\nThis is my implementation of a simple *Dungeon Master* \"clone\" for the ATtiny85 with an 128x64 OLED display (especially for the TinyJoypad platform).\u003cbr\u003e\n\n![Oh, I see!](./screenshots/gallery.png)\n\u003cbr\u003eSome impressions of the dangerous journey into the dungeon!\u003cbr\u003e\n\n\n---\n## The Idea\nWhen I discovered Daniel C's TinyJoypad project I was stunned by all the cool retro like games Daniel had created. \n\nI started to play with the code of Tiny invaders and decided to try to make it even a little more fun ([TinyInvader v4.2](https://github.com/Lorandil/Tiny-invaders-v4.2)).\nWhen I had finished most of my ideas on that project, I thought of a game project of my own.\n\nI always loved games like *The Bard's Tale* or *Dungeon Master* in the 80s and early 90s.\nWhy don't develop something like a 3D dungeon crawler on the TinyJoypad platform?\nOr die trying?\n\n**The dungeon is the limit!**\n\n---\n## The Goal of the Game\nFind the Foutain of Life to save your true love!\n\n*A more elaborate version of the story will follow later :)*\n\n***Let me tell you a story:***\n\n---\n## Game Features (February 2023)\n* 3D graphics (ok - it's only pseudo 3D)\n* Large dungeon size of 16x16 tiles\n* Four different monster types\n* Treasure chests\n* Teleporters\n* Magical items\n* Spinners\n* Compass\n* Doors\n* Bars\n* Switches\n* Sound effects\n\n---\n## Combat System\nThe health state of the player and the monsters are persistent, so damaged monsters will stay damaged (as will the player until healed by a potion). \u003cbr\u003e\n\n### Initiative\nSome monsters are faster than the player and will attack first.\nOthers like undead are slower but deadly nonetheless.\u003cbr\u003e\n\n### Attack or Run\nIf it's the player's turn, the player can chose to attack by pressing the button or run away by moving back.\u003cbr\u003e\nIf the monster survives the attack, it will retaliate immediately.\n\n### Damage System\nThe monster's damage is determined by a roll of a D8 plus/minus some monster specific value. The damage value will be reduced by the player's armour (if present) and then subtracted from the players hit points. The player's damage is determined by a D8 and a weapon bonus (if a weapon is equipped) and subtracted from the monster's hit points.\n\n### Rewards on Dead Monsters\nSome monsters may leave items which will be automatically added to the player's inventory.\n\n---\n## Losing the game\nThe player loses the game, if the hit points drop to 0.\u003cbr\u003e\nWhen the game is lost, the game will restart after pressing the button.\n\n---\n## Winning the Game\nThe goal of the game is reaching the Fountain of Life, gaining the desperately needed remedy for the player's lover.\n\n---\n# *** SPOILERS AHEAD ***\n\n## List of Objects\n* Compass - always points north\n* Wooden shield - massively reducing damage taken\n* Sword  - increases damage of attacks substantially\n* Amulet of True Sight - displayed as an eye, lets the player see through fake walls\n* Ring of Orientation - displayed as a ring, lets the screen flash when teleporting or spinning\n* Healing Potions - granting additional hit points\n\n---\n## Engine Features\n* real-time rendering in 96x64 pixels\n* real-time bitmap scaling in up to three sizes (full, half, quarter) with a variable threshold for each view distance to optimize the visuals\n* all bitmaps have a mask to keep the background from shimmering through\n* view distance is up to three tiles (depending on the object)\n* convincing movement illusion when walking through tunnels (done by mirroring left and right wall bitmap on every step)\n* different sound effects\n* some magic items\n* easily expandle scripted interactions (monsters, switches, chests, teleporters, spinners)\n* extensible design (levels, bitmaps, interactions, ...)\n* highly opimized for size (target system is an ATtiny85 with 512 bytes of RAM and 8kB of flash)\n* code compiles for ATtiny85 with xled1306 library\n* code compiles for Arduino Uno R3, Leonardo, Mega 2560, Zero and many boards more using the Adafruit SSD1306 library (encapsuled in `\"TinyJoypadUtils.h\"`)\n* Screenshot functionality: Dump screen content to serial port as a hex dump.\n  *This feature is only available on MCUs with serial port, so not on ATtiny85 ;)*\n\n---\n## Engine Limitations\n* some objects don't look good when scaled (even with the variable threshold)\n* on-wall objects (switches, doors) aren't rendered correctly when seen from the side -\u003e architectural measures required (e.g. doors need to be set back by at least one field)\n* at the moment non-wall objects like monsters, chests or doors are only rendered in front of the player.\n* no floor or ceiling for now (mostly because of lack of memory)\n* max. dungeon size is 256 tiles\n\n---\n## Technical Details\nIt soon became clear, that regarding the limited flash capacity (8kB) of the ATtiny85, a data driven approach was required. All walls, monsters and encounters/events are organized in tables which makes the game easy to extend, yet saving a lot of space.\n\n### Flash Memory Requirements for the Graphics Data\n* all walls require ~1600 bytes\n* monsters require ~900 bytes\n* the status window requires 256 bytes\n* the compass requires 20 bytes\n* other objects require ~1200 bytes\nThis sums up to nearly 4000 bytes - meaning half the flash memory is used to store the game's graphics!\n\n---\n## Current Size\nSketch uses **7760 bytes (94%)** of program storage space. Maximum is 8192 bytes **(432 bytes left)**.\nGlobal variables use **326 bytes (63%)** of dynamic memory, leaving **186 bytes** for local variables. Maximum is 512 bytes.\n\n---\n## Historical Notes\nI started the project in December 2020 with a small 8x8 level and the first *Dungeon Master* inspired wall bitmaps. During a creative blockade regarding game mechanics and the goal of the game, I created a simple *Mine Sweeper*ish game to let my brain relax a bit. That's how [TinyMinez](https://github.com/Lorandil/TinyMinez) was born ;)\n\nAfter that I decided to polish and publish the [Cross Development Framework](https://github.com/Lorandil/Cross-Development-for-TinyJoypad) I developed during the work on TinyDungeon and TinyMinez.\n\nIn the meantime I exchanged the first *Dungeon Master* like walls with some more *Eye of the Beholder* like walls (well, that's how I called them) with rough round stones instead of the plain brick walls.\n\nI realized that my first implementation of the 3D projection felt somehow wrong. That was because it was wrong. I fixed a stupid bug with the diagonal walls (there are two pairs required, not only one) and suddenly even the halls looked like they should :)\n\nIn early 2023 I optimized some bitmaps for better scaling (especially the chest images and the skeleton) and updated the README.md.\n\n---\n## Some Early Screenshots from April 2021\n\n![Oh, I see!](./screenshots/compass_found!.png)\n\u003cbr\u003eThe player has opened a chest and found a compass!\n\u003cbr\u003e\n\n![Tunnel is blocked](./screenshots/the_tunnel_is_blocked.png)\n\u003cbr\u003eNo trespassing here...\n\u003cbr\u003e\n\n![Meet Joey!](./screenshots/meet_Joey!.png)\n\u003cbr\u003eHi folks (first skeleton design with a simple wooden shield)!\n\u003cbr\u003e\n\n![The Boss](./screenshots/the_boss.png)\n\u003cbr\u003eUh oh...\n\n---\n## Credits/Resources\n* an older version of [ssd1306xled](https://github.com/tinusaur/ssd1306xled) library by tinusaur/Neven Boyanov - a small and fast library for I2C communication with SSD1306 compatible boards (I will try to use the current version in a later release)\n* [ATTinyCore 1.5.2](https://github.com/SpenceKonde/ATTinyCore) by Spence Konde - in my opinion the best ATtiny core available!\n* [Arduino IDE 2.0](https://github.com/arduino/arduino-ide) the official IDE\n* the [TinyJoypad](https://www.tinyjoypad.com/tinyjoypad_attiny85) project which inspired me to develop TinyDungeon - thanks Daniel C!\n* [image2cpp](http://javl.github.io/image2cpp/) a great online bitmap converting tool\n\n---\n## License\nTinyDungeon is published under the MIT license.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Florandil%2Ftinydungeon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Florandil%2Ftinydungeon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Florandil%2Ftinydungeon/lists"}