# 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?"

![Doom Slayer trifft Agent Smith](Wallpaper/doom-slayer-agent-smith-wallpaper-3840x2160.png)

---

## 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 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, 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 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.* 🐇