semesterprojekt: implement full text adventure (phases 1-7)

Walking skeleton through Swing GUI: YAML-driven world (4 rooms,
4 items, 1 NPC), HashMap command dispatch with parser, three-tier
item hierarchy (readable / switchable / plain), and end-to-end
NPC give/receive flow. 67 tests green.

Semesterprojekt/docs/yaml-schemas.md

@@ -0,0 +1,143 @@
+# YAML-Schemas
+
+Alle Dateien liegen unter `src/main/resources/world/` und werden via Classpath geladen.
+
+## `game.yaml`
+
+Spiel-Konfiguration und Startbedingungen.
+
+```yaml
+title: Haunted Manor
+version: 1.0
+startRoom: kitchen
+startGold: 0
+welcomeMessage: |
+  Welcome to the Haunted Manor.
+  Type 'help' to see available commands.
+```
+
+**Felder:**
+- `title` — Anzeigename des Spiels
+- `version` — frei
+- `startRoom` — id eines Raums aus `rooms.yaml`. Validierung: muss existieren.
+- `startGold` — Start-Goldbetrag des Spielers
+- `welcomeMessage` — wird beim Spielstart ausgegeben
+
+## `items.yaml`
+
+Liste aller Items. Items haben Zustand (`state`-Feld, optional), der zur Laufzeit verändert werden kann.
+
+```yaml
+- id: letter
+  name: Letter
+  description: A crumpled piece of paper.
+  readable: true
+  readText: |
+    "Meet me at midnight in the cellar. - A."
+
+- id: lamp
+  name: Oil Lamp
+  description: An old oil lamp.
+  switchable: true
+  initialState: off    # off | on
+
+- id: shovel
+  name: Shovel
+  description: A rusty shovel.
+
+- id: key
+  name: Key
+  description: A small brass key.
+```
+
+**Felder:**
+- `id` — eindeutig, klein geschrieben, ohne Sonderzeichen
+- `name` — Anzeigename
+- `description` — Beschreibung beim `untersuche` / `lies`
+- `readable`, `switchable`, ... — feature-Flags für `Use`-Verhalten
+
+**Hinweis:** Die genauen Felder hängen vom Item-Modell ab. Alternative: alle Items haben dieselben Felder, das Verhalten wird durch eine `behavior`-Discriminator-Property gesteuert (`behavior: readable` / `behavior: switchable`). Pro/Contra in der Implementierung entscheiden.
+
+## `rooms.yaml`
+
+Liste aller Räume. Items und NPCs werden per id referenziert, nicht eingebettet.
+
+```yaml
+- id: kitchen
+  name: Old Kitchen
+  description: |
+    A dusty kitchen. A letter lies on the table.
+    A door leads north.
+  exits:
+    north: hallway
+    east: cellar
+  items: [letter, lamp]
+  npcs: [old_man]
+
+- id: hallway
+  name: Dark Hallway
+  description: |
+    A long, dimly lit hallway. It smells musty.
+  exits:
+    south: kitchen
+    west: library
+  items: []
+  npcs: []
+
+- id: library
+  name: Library
+  description: |
+    Tall shelves full of books. An old chest
+    stands in one corner.
+  exits:
+    east: hallway
+  items: [shovel]
+  npcs: []
+
+- id: cellar
+  name: Damp Cellar
+  description: |
+    It is cold and damp. You need a light source.
+  exits:
+    west: kitchen
+  items: [key]
+  npcs: []
+```
+
+**Felder:**
+- `id`, `name`, `description` — analog Items
+- `exits` — Map von Richtungs-String auf Raum-id. Richtungs-Strings müssen zu `Direction`-Enum parsbar sein.
+- `items`, `npcs` — Listen von ids aus den jeweiligen Registries
+
+## `npcs.yaml`
+
+Liste aller NPCs. Detaillierte Interaktion siehe [npcs.md](npcs.md).
+
+```yaml
+- id: old_man
+  name: Old Man
+  description: A stooped old man with a grey beard.
+  greeting: |
+    "Hello traveller. If you bring me the lamp,
+    I will show you the way to the cellar."
+  reactions:
+    - onReceive: lamp
+      response: |
+        "Thank you! Here, take this key."
+      gives: key
+      consumes: lamp
+```
+
+## Validierungsregeln (zentral)
+
+Beim Loading wird geprüft (siehe [loading-flow.md](loading-flow.md)):
+
+1. Alle ids sind eindeutig innerhalb ihrer Datei.
+2. Jede in `rooms.yaml` referenzierte Item-id existiert in `items.yaml`.
+3. Jede in `rooms.yaml` referenzierte NPC-id existiert in `npcs.yaml`.
+4. Jede `exits`-Ziel-id existiert in `rooms.yaml`.
+5. Jeder `exits`-Richtungs-String ist zu `Direction` parsbar.
+6. `game.yaml.startRoom` existiert.
+7. NPC-Reaktionen: `onReceive`, `gives`, `consumes` referenzieren existierende Item-ids.
+
+Bei Verstoss → Exception, Spielstart bricht ab.