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, 35 pieces, composed as .xm by tools/compose_music.py (editable in MilkyTracker): 2 title, 15 build, 7 wave battle, 4 gate assault, 2 boss (Paladin of Light, Gate Warden), 1 torture chamber mood, 1 temple mood, 2 victory, 1 defeat; the title melody is a recognisable leitmotif in every piece
• Most pieces come from a variant generator: the leitmotif is stored as scale degrees and realised in different keys and modes (minor, harmonic minor, dorian, phrygian, lydian), augmented, diminished, inverted or as fragment sequences, with varying accompaniment, drum styles, instruments and forms; title 2, both boss themes and the second victory jingle are hand-written
• 16 chip instruments (pulse, square, saw pad, triangle bass, pluck, kick, snare, hihat, organ, bell, choir, sub bass, tom, crash, harp, timpani); 8-bit samples, each file only contains the instruments it uses
• Music changes with soft crossfades (2.5 s): title → build (rotating through all build pieces) → battle when heroes invade → assault while attacking the gate → boss themes while a Paladin of Light or the Gate Warden is alive → jingles; near a torture chamber or temple the matching room mood plays
• 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 (+ torture chamber, temple)
• The Soul Core starts surrounded by a one tile wide ring of treasury (16 tiles)
• 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