Initial commit: DOOM x MATRIX System Failure text adventure

Modulares Python-Textadventure mit Kampfsystem (Stagger, Bullet Time, Glory Kills, Hacking-Skill-Checks), Hub-Raum-Navigation, prozeduralen Encountern, 3 Charakterklassen, mehreren Enden und Story-Elementen (weißer Hase, Orakel, schwarze-Katze-Deja-vu-Glitch).
2026-07-05 18:56:44 +02:00
commit 46116f7f4b
@@ -0,0 +1,250 @@
+# DOOM × MATRIX: SYSTEM FAILURE
+
+Ein interaktives Text-Adventure in Python, das die Lore von **DOOM** und **The Matrix** zu einer gemeinsamen, düsteren Verschwörung verschmilzt: *Die Matrix läuft nicht neben der Hölle — sie läuft auf ihr.*
+
+> "What if the Matrix was just a very inefficient DOOM engine?"
+
+---
+
+## Inhaltsverzeichnis
+
+- [Schnellstart](#schnellstart)
+- [Story-Prämisse](#story-prämisse)
+- [Charakterklassen](#charakterklassen)
+- [Spielablauf & Layer](#spielablauf--layer)
+- [Kampfsystem](#kampfsystem)
+- [Hacking-System](#hacking-system)
+- [Inventar & Gegenstände](#inventar--gegenstände)
+- [Enden](#enden)
+- [Easter Eggs & Cheat-Codes](#easter-eggs--cheat-codes)
+- [Speicherstände & Loop-Twist](#speicherstände--loop-twist)
+- [Kommandozeilen-Optionen](#kommandozeilen-optionen)
+- [Projektstruktur](#projektstruktur)
+- [Erweitern des Spiels](#erweitern-des-spiels)
+
+---
+
+## Schnellstart
+
+**Voraussetzungen:** Python 3.9+ (getestet mit 3.13). Keine Pflicht-Abhängigkeiten — `colorama` wird automatisch genutzt, falls installiert (für saubere ANSI-Farben in der klassischen Windows-Konsole), ist aber optional.
+
+```bash
+python doom-matrix-adventure.py
+```
+
+Optionale Flags:
+
+```bash
+python doom-matrix-adventure.py --fast          # überspringt alle Tipp-/Dramatik-Verzögerungen
+python doom-matrix-adventure.py --seed=1337      # reproduzierbarer Run (fester Zufalls-Seed)
+python doom-matrix-adventure.py --fast --seed=42 # beides kombiniert
+```
+
+Der Einstieg funktioniert auch direkt über das Paket:
+
+```bash
+python -m doom_matrix.main
+```
+
+---
+
+## Story-Prämisse
+
+Du wachst im **Construct** auf — dem neutralen Trainingsraum der Matrix. Morpheus Hayden begrüßt dich als *Doom Slayer*, doch bevor du dich orientieren kannst, schlägt Alarm: Die Maschinen haben etwas gebaut, das sie **HELL SERVER** nennen.
+
+Die zentrale Wendung: **Argent-Energie treibt die Matrix an.** Die Menschen in den Stasiskapseln sind keine Batterien — sie sind Seelen-Prozessoren, die Dämonen rendern. Die Hölle ist kein Ort neben der Simulation, sie ist deren Fundament. Der Doom Slayer selbst ist ein *Rogue Process*, ein Programm, das sich weigerte gelöscht zu werden — deshalb kann er die Regeln beider Welten brechen.
+
+Auf dem Weg begegnest du dem **weißen Hasen** (ein Fourth-Wall-Break-Moment direkt zu Spielbeginn), dem **Orakel** in ihrer Küche mitten im Matrix-Code, und erlebst einen echten *"Fehler in der Matrix"*: eine schwarze Katze, die exakt zweimal denselben Weg läuft — das untrügliche Zeichen dafür, dass gerade jemand den Code verändert.
+
+---
+
+## Charakterklassen
+
+Zu Beginn wählst du eine von drei Klassen. Sie bestimmen Startwerte, Startwaffe und wie schnell deine **Corruption** steigt (relevant für die Enden):
+
+| Klasse | Fokus | HP | Armor | Focus | Hacking | Strength | Corruption-Rate | Startwaffe |
+|---|---|---|---|---|---|---|---|---|
+| **Slayer** | Doom — Kraft & Ausdauer | 120 | 20 | 60 | 2 | 8 | ×1.0 | Super Shotgun (20 Shells) |
+| **Operator** | Matrix — Hacking & Mobilität | 85 | 10 | 100 | 9 | 3 | ×1.0 | Plasma Rifle (100 Cells) |
+| **Anomalie** (Hybrid) | Ausgewogen, einzigartige Dialoge | 100 | 15 | 80 | 5 | 5 | ×2.0 | Super Shotgun + etwas Plasma |
+
+Zusätzlich wählst du zu Spielbeginn im Construct eine zweite Waffe (Super Shotgun oder Plasma Rifle) — unabhängig von der Klasse.
+
+---
+
+## Spielablauf & Layer
+
+Das Spiel ist in **Layer** unterteilt, die den Fortschritt der Simulation widerspiegeln:
+
+| Layer | Ort |
+|---|---|
+| 4 | Mars UAC Base |
+| 3 | The Matrix (Start) |
+| 2 | Hell Server |
+| 1 | The Architect's Core |
+| 0 | *(geheim)* — nur im wahren Ende erreichbar |
+
+### Ablauf
+
+1. **Construct-Intro** — Aufwachen, Morpheus Hayden, Alarm, Waffenwahl.
+2. **Weißer Hase** — ein Hologramm huscht vorbei. Folgst du ihm, öffnet sich kurz ein "Kaninchenbau" mit einem Blick auf die reale Terminal-Sitzung (inkl. echtem Systembenutzernamen) — das setzt die Weichen für das geheime Ende.
+3. **Agent-Imp-Kampf** — dein erster Gegner, halb Agent, halb Dämon.
+4. **Wegwahl** — drei Portale: Mars UAC Base, tiefer in die Matrix, oder direkt zum Hell Server (Schnellweg, aber weniger Beute).
+5. **Mars UAC Base** (Hub) — Waffenkammer (BFG 10000 + rote Keycard), Kontrollzentrum (Hacking-Check → Crucible-Fragment), Waffentresor (benötigt rote Keycard), prozedural generierte Nebenräume.
+6. **Matrix Deep** — die **schwarze Katze** (Deja-vu-Glitch), das **Orakel** (Dialogszene + Crucible-Fragment), Kampf gegen **Agent Smith** (Dialogwahl beeinflusst, ob er sich vervielfacht).
+7. Mars UAC Base und Matrix Deep sind **beide** vor dem Hell Server erreichbar — welchen Weg du zuerst nimmst, der andere folgt automatisch danach. Nur die dritte Portal-Option ("Schwarzes Loch") überspringt beide.
+8. **Hell Server** (Hub) — Altarraum (drittes Crucible-Fragment), prozedurale Kampf-/Beuteräume, Bosskampf gegen den **Cyberdemon**.
+9. **Der Archi-Lord** (Endboss) — Dialogwahl beeinflusst Corruption und das spätere Ende; bei drei gesammelten Crucible-Fragmenten kannst du sie zum **Crucible Sword** verschmelzen.
+10. **Ending** — abhängig von Entscheidungen, Corruption und ob du den weißen Hasen gefolgt bist plus alle drei Fragmente besitzt.
+
+---
+
+## Kampfsystem
+
+Kämpfe laufen rundenbasiert mit vier (bzw. fünf) Aktionen ab:
+
+- **Schießen** — wählt eine verfügbare Waffe, Schaden hängt vom **Waffen-Dreieck** ab:
+  - Ballistisch (Shotgun, Fäuste) ist stark gegen `demon`, schwach gegen `program`.
+  - Plasma (Plasma Rifle, BFG) ist stark gegen `program`/`hybrid`, etwas schwächer gegen `demon`.
+  - Nahkampf (Crucible Sword) ist ausgeglichen, leicht im Vorteil gegen `hybrid`.
+- **Bullet Time** — kostet 25 Focus, garantiert Ausweichen des nächsten Gegnerangriffs und einen kritischen Treffer (+50% Schaden). Reicht der Focus nicht, verpufft der Versuch als normaler (ungeschützter) Zug.
+- **Glory Kill** — nur nutzbar, wenn ein Gegner **gestaggert** ist (seine Stagger-Leiste ist voll). Tötet ihn sofort und heilt dich um 25 HP. Ohne gestaggerten Gegner schlägt der Versuch fehl und du kassierst einen Konter.
+- **Hack** — ein Skill-Check (`d20 + Hacking` gegen die Firewall des Gegners). Erfolg lässt dich einen Effekt wählen (Einfrieren, Waffen-Jam, HP-Leak, Gegner umdrehen). Misslingt der Hack, erleidest du Rückstoßschaden und sammelst eine **Trace-Marke** — bei drei Marken schickt das System Verstärkung in den Kampf.
+- **Medkit benutzen** — erscheint nur, wenn du ein Medkit im Inventar hast.
+
+Boss-Gegner (Cyberdemon, Archi-Lord) haben mehrere **Phasen**: bei bestimmten HP-Schwellen werden sie aggressiver und ihre Stagger-Leiste wird zurückgesetzt.
+
+---
+
+## Hacking-System
+
+Hacking ist nicht nur eine Kampfoption, sondern auch der Schlüssel zu Umgebungsrätseln:
+
+- **Kontrollzentrum (Mars Base):** ein Hack mit Firewall 10 öffnet ein verstecktes Fach mit einem Crucible-Fragment.
+- **Schwarze-Katze-Glitch (Matrix Deep):** ein optionaler Hack (Firewall 12) lässt dich der Code-Bruchstelle nachspüren und ein Log-Fragment finden — kostet aber etwas Corruption.
+
+Erfolgschance: `Würfelwurf (1-20) + Hacking-Wert ≥ Firewall des Ziels`.
+
+---
+
+## Inventar & Gegenstände
+
+| Item | Wirkung |
+|---|---|
+| Medkit | Heilt 30 HP |
+| Armor-Shard | Gibt 15 Armor |
+| Ammo-Pack | Füllt Munition aller Waffen auf |
+| Backup-Pille | Einmaliges Auto-Revive bei tödlichem Treffer |
+| Rote/Blaue/Gelbe Keycard | Öffnet entsprechend verriegelte Türen in Hub-Räumen |
+| Crucible-Fragment | Sammle 3, um den Crucible Sword zu schmieden — und Voraussetzung für das geheime Ende |
+| Praetor-Token | Skillpunkt (Health, Focus, Hacking oder Strength dauerhaft erhöhen) |
+| Log-Datei | Lore-Fragment, kein Kampfeffekt |
+
+**Waffen:** Fäuste (unbegrenzt), Super Shotgun, Plasma Rifle, BFG 10000 (limitierte Spezialmunition), Crucible Sword (nur nach Verschmelzung aller 3 Fragmente).
+
+---
+
+## Enden
+
+Welches Ende du bekommst, hängt von Corruption, deiner letzten Dialogwahl beim Archi-Lord und ob du den weißen Hasen gefolgt bist **und** alle drei Crucible-Fragmente besitzt:
+
+| Ende | Bedingung |
+|---|---|
+| **Wake Up** *(geheimes, wahres Ende)* | Weißem Hasen gefolgt **und** 3/3 Crucible-Fragmente. Layer 0 wird erreicht — ein Fourth-Wall-Break mit deinem echten Systembenutzernamen. |
+| **Der Dunkle Pakt** | Corruption ≥ 60% — du wirst selbst zum neuen Dark Lord. |
+| **Der neue Architekt** | Dialogwahl "Ich will die Kontrolle übernehmen" beim Archi-Lord. |
+| **...mit Cheats (New Game+)** | Dialogwahl "Ich will einen neuen Spielstand" beim Archi-Lord. |
+| **Rip and Tear** | Standard-Ende, falls keine der obigen Bedingungen zutrifft. |
+| **Game Over → Bluepill** | Bei Tod: die blaue Pille schlucken → ironisches Büro-Ende. |
+| **Game Over → Neu laden** | Bei Tod: Programm beenden. |
+
+> Hinweis zum geheimen Ende: Um alle 3 Fragmente zu sammeln, musst du **sowohl** die Mars UAC Base (Kontrollzentrum-Hack) **als auch** Matrix Deep (Orakel) besuchen, bevor du den Hell Server (Altarraum) betrittst — die dritte Portal-Option ("Schwarzes Loch") überspringt beide und macht das wahre Ende in diesem Run unerreichbar.
+
+---
+
+## Easter Eggs & Cheat-Codes
+
+Cheat-Codes können jederzeit anstelle einer normalen Eingabe (z. B. im Kampfmenü oder in Hub-Räumen) eingegeben werden:
+
+| Code | Effekt |
+|---|---|
+| `IDDQD` | God Mode an/aus (kein Schaden mehr) |
+| `IDKFA` | Alle Waffen + volle Munition |
+| `thereisnospoon` | Senkt Corruption leicht |
+| `xyzzy` | Klassischer Nichts-passiert-Scherz (Referenz auf *Colossal Cave Adventure*, 1977) |
+| `doom` / `knee-deep` / `kneedeepinthedead` | Pixel-Nostalgie-Easter-Egg, gibt einen Bonus-Praetor-Token |
+
+Weitere versteckte Momente:
+- Der weiße Hase erscheint nur **einmal**, direkt vor dem ersten Kampf.
+- Die schwarze Katze läuft zweimal exakt gleich — ein bewusster "Fehler in der Matrix", kein Zufallsevent.
+- Das Orakel reagiert unterschiedlich, je nachdem ob du dem Hasen gefolgt bist und wie hoch deine Corruption ist.
+
+---
+
+## Speicherstände & Loop-Twist
+
+Nach jedem Spielende wird automatisch ein Speicherstand unter `doom_matrix/saves/autosave.json` abgelegt. Zusätzlich führt `doom_matrix/saves/meta.json` Buch über die Gesamtzahl deiner Durchläufe.
+
+Ab dem **zweiten** Durchlauf reagiert Morpheus Hayden mit einer subtil unterschiedlichen Zeile zu Spielbeginn — ein wachsender Hinweis darauf, dass diese Simulation schon öfter gelaufen ist, als dir bewusst ist.
+
+---
+
+## Kommandozeilen-Optionen
+
+| Flag | Beschreibung |
+|---|---|
+| `--fast` | Deaktiviert alle Tipp-Animationen und dramatischen Pausen |
+| `--seed=<zahl>` | Fixiert den Zufalls-Seed für reproduzierbare Durchläufe |
+
+---
+
+## Projektstruktur
+
+```
+Doom-Matrix/
+├── doom-matrix-adventure.py     # Kompatibilitäts-Wrapper / Haupteinstieg
+└── doom_matrix/
+    ├── main.py                  # Alternativer Einstiegspunkt (python -m doom_matrix.main)
+    ├── engine/
+    │   ├── ui.py                 # Farben, Textausgabe, Balken, Glitch-Effekte
+    │   ├── game.py                # Titel-Bildschirm, Klassenwahl, Szenen-Dispatch
+    │   ├── save.py                 # JSON-Speicherstände, Meta-Statistiken, Loop-Twist
+    │   └── cheats.py                # Cheat-Code-Handling
+    ├── entities/
+    │   ├── player.py              # Spieler-Stats, Klassen, Leveling, Corruption
+    │   ├── enemy.py                # Datengetriebene Gegner-Klasse (Stagger-System)
+    │   └── items.py                 # Item/Waffen/Inventar-Klassen, Waffen-Dreieck
+    ├── systems/
+    │   ├── combat.py               # Kampf-Engine (Stagger, Bullet Time, Glory Kill)
+    │   └── hacking.py                # Skill-Check-System, Trace-Marken
+    ├── world/
+    │   ├── rooms.py                 # Room-/Hub-Klassen für Raum-Navigation
+    │   ├── generator.py              # Prozedurale Raum-/Encounter-Generierung
+    │   ├── layers.py                  # Story-Szenen aller Layer (Intro bis Endboss)
+    │   └── endings.py                  # Ending-Logik und Game-Over-Verzweigung
+    ├── data/
+    │   ├── weapons.json              # Waffendaten (Schaden, Munitionstyp, Typ)
+    │   ├── enemies.json               # Gegnerdaten (HP, Stagger, Angriff, Firewall)
+    │   └── items.json                  # Item-Definitionen
+    └── saves/                        # Autosave & Meta-Statistiken (JSON, zur Laufzeit erzeugt)
+```
+
+**Architekturprinzipien:**
+- **Daten von Logik getrennt** — Gegner, Waffen und Items liegen als JSON vor und lassen sich ohne Code-Änderungen erweitern oder neu balancieren.
+- **Room-Graph statt linearer Szenen** — Hub-Bereiche (Mars UAC Base, Hell Server) bestehen aus vernetzten `Room`-Objekten statt fest verdrahteter Szenenfolgen.
+- **Eine generische Kampf-Engine** — dieselbe `run_combat()`-Funktion bedient sowohl einfache Gegner als auch mehrphasige Bosse.
+- **Seed-injizierbarer Zufall** — jede Funktion, die Zufallswerte braucht, nimmt ein `random.Random`-Objekt entgegen, was reproduzierbare Testläufe und den `--seed`-Modus ermöglicht.
+
+---
+
+## Erweitern des Spiels
+
+- **Neue Gegner:** Eintrag in `doom_matrix/data/enemies.json` ergänzen (id, name, type, hp, stagger_max, attack_range, firewall, optional boss/phases).
+- **Neue Waffen:** Eintrag in `doom_matrix/data/weapons.json` ergänzen und in `entities/player.py` bzw. der jeweiligen Szene über `player.add_weapon("<id>")` vergeben.
+- **Neue Räume/Hubs:** `world/rooms.py`s `Room`/`Hub`-Klassen verwenden; siehe `world/layers.py` (`mars_base`, `hell_server`) als Referenz.
+- **Neue Enden:** `world/endings.py::determine_ending()` um eine weitere Bedingung erweitern und einen passenden `_ending_*`-Handler ergänzen.
+- **Neue Cheat-Codes:** in `engine/cheats.py::try_cheat()` ergänzen.
+
+---
+
+*Erstellt von LXC für Andy.* 🐇