8.6 KiB
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: https://git.carabella.ch/putschgi/habegger_loader_game (öffentlich)
- Stand: November 2026
1. Schnellstart
Wenn auf dem Mac schon Python 3.9 oder neuer installiert ist:
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:
./run.sh --fullscreen
Beenden: Esc.
2. Wenn Python fehlt oder zu alt ist
Version prüfen:
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)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Prüfen:
brew --version
Am Ende der Installation zeigt Homebrew zwei Zeilen an, die man in
~/.zprofile eintragen soll – auf Apple Silicon ist das:
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
brew install python@3.12
Prüfen:
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:
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:
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:
.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ücktund→ 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
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:
.venv/bin/python -m unittest discover -s tests -v
Selbsttest ohne Eingabegeräte (spielt eine Runde durch, ohne Fenster):
SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy ./run.sh --smoke 20
Eigene Version pflegen:
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.