300 lines
8.9 KiB
Markdown
300 lines
8.9 KiB
Markdown
# 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:
|
||
|
||
```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.
|
||
*Blinkt* der Controller am Kabel nur, ist es meist ein reines **Ladekabel**
|
||
ohne Datenleitungen – dann ein Datenkabel verwenden. Prüfen, ob der Mac ihn
|
||
überhaupt sieht:
|
||
|
||
```bash
|
||
system_profiler SPUSBDataType | grep -i -A 6 xbox
|
||
```
|
||
|
||
Bleibt die Ausgabe leer, liegt es an Kabel oder Port, nicht am Spiel.
|
||
* **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.
|
||
|
||
---
|
||
|
||
<sub>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.</sub>
|