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
- 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