dungeoncraft/README.md

<p align="center">
  <img src="docs/img/logo.png" width="128" alt="DungeonCraft - the soul core">
</p>

<h1 align="center">DungeonCraft</h1>

<p align="center"><b>Dig. Build. Defend. Conquer.</b><br>
An evil little dungeon game for the browser - in glorious pixels, in 3D, for free.</p>

<p align="center">
  <img src="https://img.shields.io/badge/Rust-macroquad-b7410e?logo=rust&logoColor=white" alt="Rust">
  <img src="https://img.shields.io/badge/WebAssembly-runs%20in%20the%20browser-654ff0?logo=webassembly&logoColor=white" alt="WebAssembly">
  <img src="https://img.shields.io/badge/made%20with-Claude%20Code-d97757?logo=anthropic&logoColor=white" alt="Made with Claude Code">
  <img src="https://img.shields.io/badge/made%20with-Qwen%20%2B%20OpenCode-7b6cf6" alt="Made with qwen3.8-flash-next-iq3xxs and Strata in OpenCode">
  <img src="https://img.shields.io/badge/license-MIT-2ea44f" alt="MIT License">
  <img src="https://img.shields.io/badge/languages-18-555" alt="18 languages">
</p>

<p align="center">
  <a href="https://dungeon.familie-zink.org/"><b>▶ Play now - open it in your browser, or download the standalone file on the title screen</b></a><br>
  <a href="BESTIARY.md">Bestiary</a> · <a href="INSTALL.md">Run your own server</a> · <a href="DESIGN.md">Design notes</a>
</p>

<p align="center">
  <img src="docs/screenshots/title-battle.png" width="820" alt="The title screen: the endless battle between a lava river and an underground river">
</p>

---

## Wake up, master.

Yes, you. Don't look around, there's nobody else down here - just you, four imps and me, old **Crookfinger**.

A hundred years ago the Order of the Lightwatch smashed your soul core into shards and carried them off like trophies.
They polished their boots, sang songs about the sun and forgot about you. **Big mistake.**

Your heart still beats. Hear that? *Lub-dub. Lub-dub.* That's the sound of a grudge.

So pick up the pickaxe - well, point at the rock, the imps carry the pickaxes - and let's dig ourselves a realm.
Gold is in the walls, creatures are waiting behind the portal, and the knights... the knights are about to have
a very bad century.

<p align="center">
  <img src="docs/screenshots/dungeon-heart.png" width="820" alt="The beating crystal heart, the demon gate and the dark towers">
  <br><i>Your heart, master, held in chains on its obsidian throne. And the demon gate. I polished it myself.</i>
</p>

## What awaits you down here

**🕳 Dig your realm.** Mark the rock and your imps dig, claim the ground, carry gold, gems and diamonds to the
treasury and hang torches on the walls. Up to five imps help each other with one job. Every tile you claim is *yours*.

**🏰 Build rooms that bring the right guests.** A lair and a mushroom garden open the portal. A library brings
shadow mages, a training hall stone ogres, a temple the flame priestess, an aerie giant bats, gargoyles, arcane
owls - and maybe, one day, an **ember wyrm**. Fourteen rooms in total, from the forge to the sacrifice altar.

**👹 Keep them happy, or they leave.** Every creature wants a bed, food and its wage on payday - and it walks to the
treasury to fetch it. Each has a favourite room, and some of them simply cannot stand each other.
Put a mage next to an ogre and watch the fur fly. (Nobody dies. Probably.)

**⚔ Train them into legends.** Ten ranks from Recruit to Warlord, with chevrons, bars and stars - and gear that grows
with them, up to golden armour, a crown and a halo. With the level come abilities: the ogre learns to *stomp*, the mage
to *step through shadows*, the chainbreaker to spin like a *whirlwind*.

<p align="center">
  <img src="docs/screenshots/bridge-battle.png" width="820" alt="A battle on a tongue of rock between lava and water">
  <br><i>The knights brought a bridge. How thoughtful. Now they're bringing it back, one piece at a time.</i>
</p>

**🔥 Defend with towers, traps and doors.** Arrow spires, hellmouth cannons and dark spires on the walls. In the
**forge** your creatures build spike pits, poison vents, fire jets, stone rollers, alarm bells, rune mines and
frost glows - and doors of wood, iron and magic. Lock them, and nobody gets through. Not even the giant. Well. Not for a while.

**✨ Cast nasty spells.** Lightning, healing, seer's eye, cave-in, haste, stoneskin, gold rain, invisibility,
plague and quake. Your scholars **research** them in the library - one discovery after another.

**🌫 Explore the dark.** Everything beyond your walls is black until your creatures go there.
Somewhere out there: a cave of neutral **dwarves** guarding gold and gems - and sometimes a chest with the plans
of a dwarven **rune forge tower**. Islands in lava rivers. Mana springs. Creatures in chains, waiting to be freed.

<p align="center">
  <img src="docs/screenshots/forge-and-traps.png" width="400" alt="The forge with coglings and every kind of trap and door">
  <img src="docs/screenshots/dark-rooms.png" width="400" alt="Prison, graveyard, arena, altar and guard posts">
  <br><i>Left: the forge and its little coglings. Right: prison, graveyard, arena, guard posts and the altar. Cosy.</i>
</p>

**👑 Other masters want your realm, too.** Mossgrim the Mouldy (green, smells like a wet cellar) and Lady Nightwell
(blue, writes threatening letters on scented paper) dig their own dungeons in free play and in the campaign.
And the humans attack *everybody*. Let them bite each other first.

**📜 A campaign of thirty missions.** Take back the shards of your soul core - from the first little outpost by the
border brook to the citadel of Grand Master Valerian Brightshield. Rivers, fortresses, treasure islands, sealed
caves, rival masters, and me, telling you the story. With tea.

<p align="center">
  <img src="docs/screenshots/dwarf-cave.png" width="400" alt="A dwarf cave with a rune chest">
  <img src="docs/screenshots/fog-of-war.png" width="400" alt="The start of a game in the fog of war">
  <br><i>A dwarf cave, master. Nice dwarves. Don't go too close. - And this is where every game begins: in the dark.</i>
</p>

<p align="center">
  <img src="docs/screenshots/lava-light.png" width="820" alt="Lava lights up the dungeon, torches on stands in a big hall">
  <br><i>Lava glows ten tiles wide, master, and my imps put torches on stands where the walls are too far away.</i>
</p>

## Build your own campaigns

> *You want to torment heroes your own way? Fine. The* **campaign editor** *is right in the title menu - in the same
> graphics as the game, no tools needed.*

<p align="center">
  <img src="docs/screenshots/editor-campaign.png" width="400" alt="The campaign graph: missions as cards, linked by next missions and branches">
  <img src="docs/screenshots/editor-map.png" width="400" alt="The map editor on the 3D map with the zone tool">
  <br>
  <img src="docs/screenshots/editor-triggers.png" width="400" alt="Triggers of a mission: zone entered, line crossed, zone claimed, ...">
  <img src="docs/screenshots/editor-blocks.png" width="400" alt="The block editor with message, objective, variable and spawn blocks">
</p>

- **Campaign graph**: missions as cards; drag arrows for the next mission and for branches (another goal reached
  first leads elsewhere). Save as a file, online, and publish for every player on the server.
- **Maps**: a random map rolled once per run of the campaign, or a painted one - start from the generator and paint
  ground, rooms, veins, the core, portals, the hero gate, units, towers, traps, knight fortresses and rival masters,
  with brush, rectangle, fill, mirroring and undo. Trigger zones are drawn right on the map.
- **Scripts as blocks**, no code: a start script, victory and defeat checks, a clock, and triggers - zone entered or
  left, line crossed, zone claimed or dug, units in a zone, timers, a unit or tower falls, values, rooms, spells,
  slaps, research. Problems are marked red while you build.
- **Test play** right from the editor, with the trigger log and the variables on screen; **co-op** for editor
  campaigns. *Open the demo* in the editor shows every trigger at work. Details: [docs/CAMPAIGN_EDITOR.md](docs/CAMPAIGN_EDITOR.md),
  [docs/MISSION_SCRIPTING.md](docs/MISSION_SCRIPTING.md).

## Together

- **Versus** for 2-4 masters, with teams, gold for allies and fallen masters watching the rest of the match.
- **Co-op**: the 20-mission campaign *League against the Lightwatch*, the built-in missions or any editor campaign,
  each master with an own dungeon; empty seats are played by the AI. Hero waves march on the strongest master.
- **Offline with an AI partner**: every co-op mission also runs without the server - the partner builds his own
  dungeon, follows your attack flag and helps out with gold. Interrupted runs go on with *Continue*.
  Details: [docs/MULTIPLAYER.md](docs/MULTIPLAYER.md).

<p align="center">
  <img src="docs/screenshots/coop-league.png" width="400" alt="The Match page with the co-op league and the AI partner">
  <img src="docs/screenshots/languages.png" width="400" alt="The language dropdown with pixel flags for 18 languages">
</p>

## Meet the household

<p align="center">
  <img src="docs/img/units/worker_5.png" width="56" alt="Pit imp">
  <img src="docs/img/units/kobold_5.png" width="56" alt="Kobold">
  <img src="docs/img/units/spider_5.png" width="56" alt="Cave spider">
  <img src="docs/img/units/mage_5.png" width="56" alt="Shadow mage">
  <img src="docs/img/units/ogre_5.png" width="56" alt="Stone ogre">
  <img src="docs/img/units/jailer_5.png" width="56" alt="Jailer">
  <img src="docs/img/units/priestess_5.png" width="56" alt="Flame priestess">
  <img src="docs/img/units/cogling_5.png" width="56" alt="Cogling">
  <img src="docs/img/units/revenant_5.png" width="56" alt="Revenant">
  <img src="docs/img/units/bat_5.png" width="56" alt="Giant bat">
  <img src="docs/img/units/gargoyle_5.png" width="56" alt="Chain gargoyle">
  <img src="docs/img/units/owl_5.png" width="56" alt="Arcane owl">
  <img src="docs/img/units/wyrm_5.png" width="56" alt="Ember wyrm">
  <img src="docs/img/units/chainbreaker_5.png" width="56" alt="Chainbreaker">
</p>

> *Fourteen kinds of wonderful creatures, master, and eight kinds of humans in shiny tin. I wrote everything down for
> you - who loves what, who hates whom, who learns what - in* **[Crookfinger's Bestiary](BESTIARY.md)**.
> *The same book is in the game, by the way - on the title screen and in the pause menu.*

## How to play

1. **Open the game online**: <https://dungeon.familie-zink.org/>. It runs on desktop and on phones (touch controls switch on by themselves).
   Logged-in players can download the whole game as one HTML file from the title screen (*Download Standalone*);
   it then runs offline, and downloaded savegame files load there too.
2. Or **run your own server** with Docker - with user accounts, savegames on the server and the game as an
   installable app: see **[INSTALL.md](INSTALL.md)**.

**The basics, master:**

| | |
|---|---|
| Left click / drag | use the tool - dig, build rooms (drag a rectangle), cast, place towers and traps |
| Right click | drop what your hand holds (creatures, prisoners - or a sacrifice on the altar) |
| Shift + click | slap your own creatures (faster for a while) or punch a hero |
| Right drag, WASD, screen edge | move the camera · middle drag, Q/E, R/F: rotate and tilt · wheel: zoom |
| Esc | pause menu: save, load, settings, bestiary |

On phones: tap to use a tool, drag to mark or move, two fingers to zoom and turn, long press for information.

## Under the hood

- **Rust**, compiled to **WebAssembly**, with [macroquad](https://github.com/not-fl3/macroquad) - one small module, no engine, no plugins.
- A real 3D isometric world in pixel art: chunked meshes, flickering point lights, a glow pass, particles,
  billboard sprites with eight viewing directions, every frame of it drawn by code - **no image files** except the font.
- Procedural chiptune soundtrack as FastTracker 2 modules with its own XM replayer and synthesised sound effects.
- A tiny Rust savegame server (axum, Argon2 passwords) - optional; without it the game uses savegame files.
- 18 languages: German, English, Spanish, Portuguese, Dutch, Danish, Norwegian, Swedish, Finnish,
  Russian, Croatian, Hungarian, Serbian, Romanian, Slovak, Czech, Italian and Greek – chosen from a
  dropdown with pixel flags; another language is one text file away.

## Made with Claude Code

<p><img src="docs/img/claude-mark.png" width="72" alt="Claude Code mark" align="left"> &nbsp;DungeonCraft was developed with the help of
<a href="https://claude.com/claude-code"><b>Claude Code</b></a>, Anthropic's AI coding assistant - the code, the graphics,
the music, the texts and this page. Claude, Claude Code and Anthropic are trademarks of Anthropic; the pixel mark only
credits the tool.</p>
<br clear="left">

## Made with qwen3.8-flash-next-iq3xxs, Strata and OpenCode

Parts of DungeonCraft were also developed with the language model qwen3.8-flash-next-iq3xxs, run with Strata in
<a href="https://opencode.ai"><b>OpenCode</b></a>. Qwen and OpenCode are trademarks of their respective owners; the pixel
marks on the title screen only credit the tools.

## License

DungeonCraft is released under the **[MIT License](LICENSE)** - © 2026 Richard Zink. It covers the code, the generated
music in `assets/music/` and the procedural graphics.

The **Dinowyde** and **DINOBYTE** fonts (`assets/dinowyde_1x.png`, `assets/dbyte_1x.png`) by [mby](https://mby.itch.io/) are licensed separately under
**CC BY 4.0**. Details in [CREDITS.md](CREDITS.md).

---

<p align="center"><i>"The underworld is yours, master. Now - tea?"</i><br>- Crookfinger</p>