Altstand nach old_version/ eingefroren (untracked). Monolith ersetzt durch main.py + Paket loader_game/. Neu: run.sh/run.command mit venv+requirements, .gitignore, docs/ANALYSE.md, 35 Tests. Secrets entfernt. Gelöscht: loader_game.py, qr_scan*.py, INSTALL_README.txt.

2026-11-01 10:25:13 +00:00
1 parent 6a2c891c3e
commit de550e1d4d
@@ -1,2 +1,131 @@
-# Habegger_loader_game
+# Habegger Trailer Load

+Kofferlager-Spiel für Messe-/Eventbetrieb: Koffer laufen von rechts ein und
+müssen im Auflieger möglichst dicht gestapelt werden. Ziel ist eine hohe
+Beladung in Prozent.
+
+Neu aufgesetzt für macOS (Apple Silicon) mit Controller-Unterstützung.
+Die Analyse des Altstands und die Liste der behobenen Fehler stehen in
+[`docs/ANALYSE.md`](docs/ANALYSE.md).
+
+## Voraussetzungen
+
+* Python 3.10 oder neuer (getestet: 3.12)
+* macOS oder Linux – sonst nichts. `pygame` bringt SDL2 selbst mit,
+  Kamera-, Brew- oder Systembibliotheken werden **nicht** gebraucht.
+
+## Start
+
+```bash
+./run.sh                 # Fenster
+./run.sh --fullscreen    # Vollbild (Eventbetrieb)
+```
+
+`run.sh` legt beim ersten Start `.venv/` an und installiert `requirements.txt`
+automatisch. Ändert sich `requirements.txt`, wird neu installiert.
+
+Auf macOS lässt sich das Spiel auch per Doppelklick auf **`run.command`**
+starten (beim ersten Mal ggf. Rechtsklick → Öffnen wegen Gatekeeper).
+
+Optionen:
+
+| Option | Bedeutung |
+| --- | --- |
+| `--fullscreen` | Vollbild starten (F11 schaltet jederzeit um) |
+| `--name "Anna"` | Spielername setzen (sonst der zuletzt gespeicherte) |
+| `--seed 42` | feste Zufallsfolge, reproduzierbare Koffer-Sequenzen |
+| `--smoke 10` | Selbsttest: bestätigt das Intro automatisch, spielt 10 s ohne Eingaben und beendet sich |
+
+## Steuerung
+
+| Aktion | Tastatur | Controller (Xbox-Layout) |
+| --- | --- | --- |
+| Einrasten an der Barriere | `Space` / `Enter` | A |
+| Koffer drehen (wenn er passt) | `←` | X / D-Pad links |
+| Auf einen Koffer obendrauf setzen | `↑` | Y / D-Pad hoch |
+| Spiel beenden | `Esc` | B |
+| Vollbild umschalten | `F11` | – |
+
+Stick und D-Pad werden beide ausgewertet, Controller-Hotplug funktioniert
+(der Name des erkannten Controllers steht beim Start im Terminal).
+
+## Projektstruktur
+
+```
+main.py                 Einstiegspunkt (Fenster, Hauptschleife, CLI)
+run.sh / run.command    Start inkl. venv + Installation
+requirements.txt        pygame
+case_sequences.txt      Koffersequenzen (Datenbestand)
+loader_game/
+  config.py             Masse, Tempi, Farben, Texte, Pfade
+  assets.py             Bilder/Sounds/Fonts laden und cachen
+  sequences.py          Einlesen und Validieren der Sequenzdatei
+  case.py               Koffer: Geometrie und Einlaufbewegung
+  trailer.py            Stapelregeln im Auflieger (reine Logik)
+  input_map.py          Tastatur/Controller → Action
+  scene.py              Zeichnen
+  intro.py              Tutorialbild, Ampel, Reissverschluss
+  game.py              Zustandsmaschine des Spiels
+  storage.py            Laufzeitdaten (letzter Spielername)
+  net.py                optionaler Punkte-Upload
+tests/test_logic.py     35 Tests (ohne Fenster)
+docs/ANALYSE.md         Analyse Altstand + Fehlerliste
+old_version/            eingefrorener Altstand (nicht versioniert)
+runtime/                Laufzeitdaten (nicht versioniert)
+```
+
+## Konfiguration
+
+Alle Werte stehen in `loader_game/config.py` – Auflösung, Bänder, Auflieger,
+Tempo, Farben, Texte. Gezeichnet wird immer in der virtuellen Auflösung
+1920×1080; `pygame.SCALED` skaliert automatisch auf die tatsächliche
+Fenstergrösse (Retina, 1440×900, 4K …).
+
+Punkte-Upload (standardmässig aus):
+
+```bash
+export HAG_SCORE_URL="https://…/api/submit_points.php"
+export HAG_SCORE_API_KEY="…"
+```
+
+Zugangsdaten gehören in die Umgebung, **nicht** in den Quellcode.
+
+## Sequenzdatei
+
+`case_sequences.txt`: Sequenzen durch Leerzeilen getrennt, pro Zeile ein
+Koffer als `breite,höhe,rotiert` in Einheiten von 100×100 Pixeln.
+`rotiert=True` dreht den Koffer beim Einlaufen um 90°.
+
+```
+3,1,False
+1,2,True     # effektiv 2 Einheiten breit, 1 hoch
+```
+
+Ungültige Zeilen werden beim Start mit Meldung übersprungen.
+
+## Tests
+
+```bash
+.venv/bin/python -m unittest discover -s tests -v
+```
+
+Getestet werden Sequenz-Parsing, Layout-Invarianten, Kofferbewegung,
+Stapelregeln, komplette Spieldurchläufe (bis Spielende) und die
+Laufzeitdaten. Kein Fenster, kein Ton nötig.
+
+## Laufzeitdaten
+
+`runtime/` (in `.gitignore`): zuletzt verwendeter Spielername. Per
+`HAG_RUNTIME_DIR` umlenkbar (nutzen die Tests).
+
+## Eingefrorener Altstand
+
+`old_version/` enthält die Dateien vor dem Umbau – ebenfalls in `.gitignore`,
+also **nicht** versioniert. Details: `old_version/FROZEN.md`.
+
+## Nächste Schritte
+
+1. Namenseingabe direkt am Controller (Buchstabe für Buchstabe, alternativ
+   Tastatur) – ersetzt QR-Scanner und `last_user.txt`.
+2. Mehrere Durchgänge ohne Neustart des Programms (zurück zur Namenseingabe).
+3. Entscheiden, ob und wohin die Punkte gesendet werden.