dungeoncraft/DESIGN.md

DungeonCraft – Design Decisions

An original dungeon management game (genre: dungeon building & defence) that runs as WASM in the browser.

Technology

• Rust + macroquad (WebGL), target wasm32-unknown-unknown
• User interface drawn entirely in the canvas
• Font: DINOBYTE bitmap font (CP437, 6×8 px, CC BY 4.0, see CREDITS.md) for all texts, integer scaled
• All UI windows use CP437 frames (single lines for panels, double lines for dialogs); bars (HP/mana/gate) are pixel bars
• Sound: event system + macroquad audio prepared (volume, mute key M); sounds will be generated later
• Languages: all in-game texts live in language files (lang/*.lang, key = text); English is the reference/fallback, German included, more can be added. The language is chosen on first start and stored in the browser.
• Repository language: English (code, comments, docs, commit messages)

Graphics

• 3D, true isometric (orthographic camera)
• Camera freely rotatable 360° and tiltable
• Walls with an irregular surface (noise displacement of the wall faces, seamless between neighbours)
• Textures: procedural pixel art (tile atlas)
• Units: pixel sprites as billboards (always facing the camera), pulled towards the camera in depth so walls behind a unit never cut into its sprite
• Lighting: dark + torches – dark base level; claimed areas and light sources (torches, core, portal, gate) are bright, flickering light
• Dig marking: a marked block glows yellow along its real irregular shape (tinted top and open sides, outline following the displaced edges)
• Hover: the wall block under the mouse gets a faint version of that highlight (in the colour of the active tool); while dragging a dig rectangle, every block inside is tinted faintly; floor tiles get an outline
• Tile outlines: subtle dark lines around every tile (floors, wall tops, vertical wall edges), following the irregular surface; toggle with G (later in the graphics settings)
• The UI is a 2D layer on top, including a minimap

Controls

• Left click: use the active tool (drag a rectangle for digging/rooms)
• Right click: drop a unit from the hand
• Camera: WASD/arrow keys, right mouse drag, mouse wheel zoom, screen edge
• Rotate/tilt: middle mouse drag, Q/E rotate, R/F tilt
• Spells: 0 lightning, X heal, V summon imp
• Torches: placed automatically when ground is claimed; foreign areas are dimly visible

Menus, savegames, settings

• Title screen (Continue, New Game, Load, Settings, Help) and pause menu on Esc (Resume, Save, Load, Settings, Help, Main Menu)
• Savegames as JSON (*.dcsave, format tag + version, ~300 KB): save = download, load = file picker or drag & drop onto the game window
• Autosave in the browser (localStorage) every 2 minutes and when the tab is hidden/closed; "Continue" on the title screen
• Settings: language + sound, camera (rotation/zoom speed, edge scrolling, invert mouse), graphics (tile outlines, wall detail, light sources, interface size), game (speed 1×/2×, hints), key bindings (conflicts swap keys; Esc and arrow keys are fixed)
• Settings are stored in the browser and in every savegame; loading a savegame always applies its settings

Music & sound

• Own XM/MOD replayer in Rust (src/xm.rs): instruments, envelopes, fadeout, auto-vibrato, linear/Amiga frequencies, common FT2 effects; verified against libopenmpt
• Shared mixer for music + sound effects (src/audio.rs), streamed to the browser by the JS plugin (replaces macroquad audio)
• Soundtrack in classic Amiga chiptune style, composed as .xm by tools/compose_music.py (editable in MilkyTracker): title/menu, 3 build tracks (rotating), 2 battle tracks (wave defence, gate assault), victory/defeat jingles; the title melody is a recognisable leitmotif in every piece
• Music changes with soft crossfades (2.5 s): title → build → battle when heroes invade → storm music while attacking the gate → jingles
• Sound effects are synthesised chip sounds (src/sfx.rs), positioned by distance and stereo panning

Map size

• Chosen in the New Game dialog: width and height separately, 64–256 tiles in steps of 32 (remembered in the settings)
• Content scales with the area: rock, gold veins and caves; the Hero Gate lies on the far side, the grace period grows with the distance to the gate
• One portal per 64×64 tiles; every claimed portal brings creatures (more portals = faster arrivals, still limited by the lair)
• Bigger maps get guarded treasure caves (one less than the number of portals): very rich gold veins, defended by a hero squad that stays at its post
• Savegames store the tiles packed (run-length encoded, base64), so even 256×256 maps stay small (~300 KB); version 1 savegames still load

Game content

• Digging: mark earth/gold → Pit Imps dig, bring gold home and claim ground
• Rooms: treasury, lair, mushroom garden, training hall, library
• Claim the portal → creatures: kobold, cave spider, shadow mage, stone ogre (depending on rooms)
• Needs: sleep, food, wages (payday); unhappy creatures leave
• Hand: pick up / drop own units (max. 8)
• Spells (mana): lightning, heal, summon Pit Imp
• Heroes: knight, archer, priest, dwarf miner, paladin of light (they dig their way to the Soul Core)

Walls, towers, torture, temple

• Reinforced walls: imps reinforce earth walls next to claimed ground automatically (free, lowest priority). Heroes avoid them (path cost ×10) and need ~10× as long to break through; the player's imps need twice as long to dig them out
• Defence towers on claimed floor (one tile, not walkable), three tools; clicking an own tower with the same tool upgrades it (3 levels). Gold for building/upgrading, the magic tower uses mana per shot
  • Arrow tower: cheap, fast; arrows pierce up to two more heroes
  • Cannon tower: slow, long range, splash damage with knockback, minimum range
  • Magic tower: never misses, slows, jumps to a second hero
  • Heroes attack towers; imps repair them; towers count with half their combat value to the army value
• Torture chamber: one prisoner per 2 tiles. Defeated heroes are knocked out (if there is room) and carried in by imps; torture drains their HP over ~100 s, ~40% defect (paladins ~25%) and become own creatures (needs, wage, lair). Attracts the Jailer (6+ tiles): tanky melee that pulls enemies in with a chain
• Temple: creatures pray for mana (more than studying) and mood. Attracts the Flame Priestess (6+ tiles): fireballs with splash damage, heals creatures, heals the Soul Core (~8 HP/s) when it is below 90% and no fight is nearby

Hero wave AI

• Each wave picks an entry point on the border of the realm facing the hero gate: few towers/creatures, no reinforced walls and a short way are attractive, entry points of recent waves are avoided, plus some randomness
• Waves of 6+ heroes split into two groups with different entry points (the paladin goes with the bigger group)
• Heroes first tunnel to their entry point, then go for the core
• Warning 30 s before: scout message with the direction(s) and blinking markers on the minimap

Goal

• Victory: destroy the Hero Gate
• Defeat: the Soul Core is destroyed

Attacking the gate

• Attack flag: the player places a rally flag; free creatures march there and attack everything nearby (including the gate)
• Gate: about 3000 HP, regenerates slowly when not under attack
• Defenders appear at HP thresholds 75% / 50% / 25% (the last squad with a boss), challenging

Hero waves

• Endless while the gate stands
• Strength follows the army value (sum of HP × damage of all creatures incl. levels)
• Wave strength grows from 60% to 100% of the army value, with some randomness
• Grace period of 5 minutes, then a minimum wave (e.g. 2 knights) even with a weak army
• Goal: always beatable, but challenging

Operations / testing

• Build in Docker (multi-stage: Rust → nginx:alpine)
• Test build on port 18093, later additionally a subdomain via Nginx Proxy Manager