# Habegger Trailer Load – Start auf dem Mac Kofferlager-Spiel für Messe- und Eventeinsätze. Diese Anleitung führt von null bis zum laufenden Spiel – und zeigt am Ende, wie man das Projekt übernimmt und weiterentwickelt. * **Repository:** (öffentlich) * **Stand:** November 2026 --- ## 1. Schnellstart Wenn auf dem Mac schon Python 3.9 oder neuer installiert ist: ```bash git clone https://git.carabella.ch/putschgi/habegger_loader_game.git cd habegger_loader_game ./run.sh ``` Das ist alles – kein Login, keine Zugangsdaten. Beim ersten Start legt `run.sh` automatisch eine lokale Python-Umgebung an und installiert `pygame` (dauert ein paar Sekunden, braucht einmalig Internet). Vollbild für den Eventbetrieb: ```bash ./run.sh --fullscreen ``` Beenden: **Esc**. --- ## 2. Wenn Python fehlt oder zu alt ist Version prüfen: ```bash python3 --version ``` Steht dort **3.9 oder höher**, weiter mit Abschnitt 1. Steht dort `3.9.6` (das Python aus den Xcode Command Line Tools), läuft es zwar, empfohlen ist aber ein aktuelles Python 3.12. ### 2.1 Homebrew installieren (falls nicht vorhanden) ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" ``` Prüfen: ```bash brew --version ``` Am Ende der Installation zeigt Homebrew zwei Zeilen an, die man in `~/.zprofile` eintragen soll – auf Apple Silicon ist das: ```bash echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile eval "$(/opt/homebrew/bin/brew shellenv)" ``` Danach das Terminal einmal schliessen und neu öffnen. ### 2.2 Python 3.12 installieren ```bash brew install python@3.12 ``` Prüfen: ```bash python3.12 --version # -> Python 3.12.x ``` Danach wie in Abschnitt 1 starten – `run.sh` sucht sich automatisch das beste vorhandene Python (3.12 vor 3.13 vor 3.11 vor `python3`). Auch der Doppelklick auf `run.command` nutzt es. --- ## 3. Projekt holen Das Repository ist **öffentlich**, du kannst es direkt klonen: ```bash cd ~/Documents git clone https://git.carabella.ch/putschgi/habegger_loader_game.git cd habegger_loader_game ``` Alternativ das ZIP von der Repo-Seite herunterladen, entpacken und einmalig ausführbar machen: ```bash chmod +x run.sh run.command ``` Zum Mitentwickeln (eigener Branch, eigene Version, Fork) siehe Abschnitt 10. --- ## 4. Starten | Befehl | Zweck | | --- | --- | | `./run.sh` | Spiel im Fenster starten | | `./run.sh --fullscreen` | Vollbild (Messe-/Eventbetrieb), `F11` schaltet jederzeit um | | `./run.command` | Doppelklick im Finder; beim ersten Mal **Rechtsklick → Öffnen** | | `./run.sh --smoke 10` | Selbsttest: spielt 10 s ohne Eingaben und beendet sich | | `./run.sh --seed 42` | feste Zufallsfolge (immer dieselben Koffersequenzen) | Im Terminal erscheint beim Start eine kurze Auskunft, z. B.: ``` Python 3.12.6, pygame 2.6.1 Controller: Xbox Wireless Controller Zielauflösung 1920x1080, 60 fps Audio: 44100 Hz, 2 Kanäle, 7 Sounds geladen Runde 1: Sequenz 4/6 (16 Koffer, Start: 3x2, 3x1, 2x2 …), Stufe Normal ``` Steht dort „Controller: keiner erkannt", ist kein Controller verbunden – das Spiel läuft dann mit der Tastatur weiter. --- ## 5. Steuerung | Aktion | Tastatur | Controller (Xbox-Layout) | | --- | --- | --- | | Stufe wählen | `←` / `→` | D-Pad bzw. linker Stick | | Bestätigen (Weiter, Stufe starten, neue Runde) | `Space` / `Enter` | A | | Koffer einrasten | `Space` | A | | Koffer drehen | `←` | X / D-Pad links | | Koffer obendrauf setzen | `↑` | Y / D-Pad hoch | | Vollbild umschalten | `F11` | – | | Beenden | `Esc` | B | --- ## 6. Controller anschliessen * **Kabel (empfohlen):** Xbox-One-/Series-Controller per USB-C bzw. micro-USB anstecken. Läuft ohne Treiber, ohne Pairing, und der Controller braucht keine Batterien. * **Bluetooth:** Systemeinstellungen → Bluetooth → Controller koppeln. Geht, ist am Stand aber störanfälliger (Akku, Reconnects). * **Microsofts Xbox-Funk-Dongle** funktioniert auf macOS **nicht**. * Der Controller muss vor dem Spielstart verbunden sein. Wird er später verbunden, erkennt das Spiel ihn automatisch und schreibt es ins Terminal (`Controller: Xbox Series X Controller`). ### Wenn der Controller erkannt wird, aber keine Taste reagiert Diagnose starten: ```bash .venv/bin/python tools/controller_check.py ``` Dann A, X, Y und das D-Pad drücken. Das Fenster zeigt jede Taste, die ankommt: * **Es erscheinen Zeilen** wie `Taste 0 gedrückt` und `→ Spiel-Aktion: PRIMARY` → die Eingabe kommt an; dann bitte die Ausgabe melden, es liegt dann an der Tastenbelegung. * **Es erscheint gar nichts** → macOS reicht die Controller-Eingabe nicht an das Terminal weiter. Prüfen unter *Systemeinstellungen → Datenschutz & Sicherheit → Eingabeüberwachung* (bei älteren macOS-Versionen *Bedienungshilfen*), ob **Terminal** (bzw. iTerm / VS Code) erlaubt ist – danach das Terminal neu starten. * Bei Bluetooth zusätzlich: Controller entkoppeln, neu verbinden, oder einfach das USB-Kabel verwenden. --- ## 7. Aktualisieren ```bash cd habegger_loader_game git pull ./run.sh ``` `run.sh` installiert bei Bedarf automatisch nach. Wurde Python inzwischen aktualisiert, baut es die lokale Umgebung selbst neu auf. --- ## 8. Wenn etwas klemmt | Meldung / Problem | Lösung | | --- | --- | | `zsh: permission denied: ./run.sh` | `chmod +x run.sh run.command` | | `✗ Python 3.9 oder neuer wird benötigt` | `brew install python@3.12`, dann `rm -rf .venv` | | `No module named pygame` | `./run.sh` erneut starten (installiert nach) | | „Programm kann nicht geöffnet werden" (Gatekeeper) | Rechtsklick auf `run.command` → **Öffnen** | | Kein Ton | Im Terminal muss `Audio: 44100 Hz, 2 Kanäle, 7 Sounds geladen` stehen; sonst Ausgabegerät (Kopfhörer/Dock) prüfen | | Fenster grösser als der Bildschirm | Spiel skaliert automatisch; `F11` für Vollbild | | Alles hängt / seltsame Fehler nach Python-Update | `rm -rf .venv && ./run.sh` | --- ## 9. Was man ohne Programmieren ändern kann | Datei | Inhalt | | --- | --- | | `case_sequences.txt` | Koffersequenzen: pro Zeile `breite,höhe,rotiert`, Leerzeile trennt Sequenzen | | `loader_game/difficulty.py` | Tempo der Stufen Easy / Normal / Hard | | `loader_game/sayings.py` | Sprüche am Ende, nach Prozent gestuft | | `loader_game/config.py` | Layout, Texte, Farben, Dauer des Cooldowns (10 s) | Nach Änderungen genügt ein Neustart mit `./run.sh`. --- ## 10. Projekt übernehmen und weiterentwickeln Das Projekt darf geklont, geforkt und weiterentwickelt werden. Der Aufbau ist bewusst klein gehalten: ``` main.py Einstiegspunkt, Ablauf der Phasen loader_game/ Spiellogik (ein Modul pro Aufgabe) config.py Masse, Farben, Texte, Pfade difficulty.py Stufen Easy / Normal / Hard assets.py Bilder, Sounds, Fonts sequences.py Einlesen von case_sequences.txt case.py Koffer (Geometrie, Textur, Bewegung) trailer.py Stapelregeln im Auflieger (reine Logik) input_map.py Tastatur/Controller → Aktionen scene.py Zeichnen menu.py Stufenauswahl intro.py Anleitung + Startsequenz game.py Zustandsmaschine einer Runde sayings.py Sprüche zum Ergebnis tests/test_logic.py 57 Tests, laufen ohne Fenster docs/ANALYSE.md Analyse des Altstands + Changelog old_version/ eingefrorener Altstand (nicht versioniert) ``` **Einzige Abhängigkeit:** `pygame` (in `requirements.txt`). Python 3.9+. **Tests laufen lassen:** ```bash .venv/bin/python -m unittest discover -s tests -v ``` **Selbsttest ohne Eingabegeräte** (spielt eine Runde durch, ohne Fenster): ```bash SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy ./run.sh --smoke 20 ``` **Eigene Version pflegen:** ```bash git checkout -b meine-aenderung # ... ändern ... .venv/bin/python -m unittest discover -s tests git commit -am "Beschreibung der Änderung" git push origin meine-aenderung ``` Kein Schreibrecht auf dem Hauptrepo? Dann auf Gitea einfach **forken** und dort weiterarbeiten – der Fork lässt sich jederzeit wieder als Pull-Request zurückgeben. --- ## 11. Netzwerk und Daten Das Spiel läuft vollständig offline: keine Anmeldung, keine Punkteserver, keine gespeicherten Spielernamen. Internet braucht nur der erste `git clone` und spätere Updates. --- Entstanden im Rahmen der Arbeitszeit bei der Habegger AG. Spiel, Quellcode und Grafiken gehören der Habegger AG. Das Repository ist öffentlich: Klonen, Forken und Weiterentwickeln sind ausdrücklich willkommen – eine Weitergabe unter fremdem Namen nicht. Ergänzungen und Korrekturen an dieser Anleitung sind jederzeit willkommen.