From 213287c43d07754922fc7d431d45e5fd64802b87 Mon Sep 17 00:00:00 2001
From: Frank Tovar <mail@franktovar.de>
Date: Tue, 21 Apr 2026 17:38:20 +0200
Subject: [PATCH] Add difficulty level design

---
 DESIGN.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/DESIGN.md b/DESIGN.md
index 122b9c5..7fbf994 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -44,6 +44,7 @@ Prefer Godot resources or plain C# definition classes for tunable game content.
 - `WeaponDefinition`: firing cadence, projectile count, damage, speed, collision behavior, seeking rules, level scaling.
 - `SquadronMateTypeDefinition`: formation rule, spacing, movement smoothing, targeting behavior, visuals.
 - `SpecialWeaponDefinition`: initial ammo, ammo pickup amount, projectile behavior, damage rule, invulnerability or pull effects.
+- `DifficultyDefinition`: named difficulty preset, gameplay multipliers, survival rules, score modifiers, content overrides.
 
 ## Level System
 
@@ -439,6 +440,40 @@ Scoring sources:
 
 The score system should publish events for UI, highscore, level-up thresholds, and mission results.
 
+## Difficulty Levels
+
+Difficulty should be selected before starting a run and then remain fixed until game over, normal victory, or secret victory. It should be represented by a `DifficultyDefinition` so the final jam topic can rebalance the game without rewriting missions.
+
+Difficulty should affect systems through explicit multipliers and overrides:
+
+- Enemy health multiplier.
+- Enemy projectile speed multiplier.
+- Enemy fire cadence multiplier.
+- Enemy spawn density multiplier.
+- Cluster spawn interval multiplier.
+- Boss health multiplier.
+- Boss phase timing multiplier.
+- Hero starting shield charges.
+- Hero retry count.
+- Collectible drop rate multiplier.
+- Special weapon initial ammo multiplier.
+- Score multiplier.
+- Clear screen pickup strength.
+- Enemy escape rule override for cluster rewards.
+
+Avoid making difficulty depend on hidden rules. The player should be able to understand the broad promise of each difficulty from the menu.
+
+Suggested presets:
+
+- Easy: more shield charges, slower enemy projectiles, fewer spawns, generous drops, no score bonus.
+- Normal: intended baseline for first completion.
+- Hard: faster enemy projectiles, denser clusters, stricter boss timings, moderate score bonus.
+- Expert: highest density and speed, fewer retries or shields, strongest score bonus, intended for highscore runs.
+
+Difficulty should not change core controls, mission order, weapon identity, or story outcome. Secret victory may require a minimum difficulty if the final topic benefits from that, but the requirement should be visible before the run starts.
+
+Difficulty-specific mission overrides can be used when multipliers are not enough. For example, a mission may add an extra enemy cluster on Hard and Expert, or replace a boss projectile pattern on Expert. These overrides should be optional and declared in mission data.
+
 ## Persistence
 
 Persist only what needs to survive across missions or game sessions.
@@ -460,6 +495,7 @@ Run-ending highscore state:
 - Player name or initials.
 - Score.
 - Mission reached.
+- Difficulty.
 
 ## Testing Strategy
 
@@ -475,10 +511,13 @@ High-value unit tests:
 - Game over triggers when retry count is exhausted.
 - Cluster reward is awarded only when completion rules are satisfied.
 - Special weapon ammo pickups replenish the selected special weapon.
+- Difficulty modifiers adjust enemy health, projectile speed, spawn intervals, shield charges, retries, and score.
+- Difficulty-specific mission overrides are applied only for matching difficulties.
 
 High-value play tests:
 
 - Start game and enter first mission.
+- Select each difficulty and verify visible run settings.
 - Pick a special weapon in the shop.
 - Complete a small enemy cluster and receive points.
 - Collect each collectible type.