MAC-START.md aktualisiert: Repo ist oeffentlich (kein Login), neuer Abschnitt 10 "Projekt uebernehmen" (Struktur, Tests, Selbsttest, Branch/Fork-Workflow), Footer an Public-Repo angepasst.
This commit is contained in:
Project Bridge committed
1 parent
37aa5c25f6
commit
a088c23a09
3 files changed
+324
-18
No files matched your search
+267
@@ -0,0 +1,267 @@
|
||||
# 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.
|
||||
* **Bluetooth:** Systemeinstellungen → Bluetooth → Controller koppeln. Geht,
|
||||
ist am Stand aber störanfälliger (Akku, Reconnects).
|
||||
* **Microsofts Xbox-Funk-Dongle** funktioniert auf macOS **nicht**.
|
||||
* Der Name des erkannten Controllers steht nach dem Start im Terminal.
|
||||
|
||||
---
|
||||
|
||||
## 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>
|
||||
@@ -4,7 +4,10 @@ Kofferlager-Spiel für Messe-/Eventbetrieb: Koffer laufen von rechts ein und
|
||||
müssen im Auflieger möglichst dicht gestapelt werden. Angezeigt wird am Ende
|
||||
die Stufe und die erreichte Beladung in Prozent.
|
||||
|
||||
Neu aufgesetzt für macOS (Apple Silicon) mit Controller-Unterstützung.
|
||||
Neu aufgesetzt für macOS mit Controller-Unterstützung.
|
||||
|
||||
**Neu am Mac? → [`MAC-START.md`](MAC-START.md)** – Schritt für Schritt von
|
||||
Homebrew über Python bis zum Start, inklusive Fehlerhilfe.
|
||||
Die Analyse des Altstands und die Liste der behobenen Fehler stehen in
|
||||
[`docs/ANALYSE.md`](docs/ANALYSE.md).
|
||||
|
||||
@@ -73,6 +76,7 @@ gezeichnet, nie durch eine andere Textur ersetzt.
|
||||
```
|
||||
main.py Einstiegspunkt (Phasen: Anleitung → Moduswahl → Start → Spiel)
|
||||
run.sh / run.command Start inkl. venv + Installation
|
||||
MAC-START.md Anleitung für macOS (Homebrew, Python, Start)
|
||||
requirements.txt pygame
|
||||
case_sequences.txt Koffersequenzen (Datenbestand)
|
||||
loader_game/
|
||||
|
||||
@@ -1,44 +1,79 @@
|
||||
#!/usr/bin/env bash
|
||||
# Startet das Habegger Loader Game.
|
||||
# Startet das Habegger Loader Game auf macOS und Linux.
|
||||
#
|
||||
# Beim ersten Start wird eine lokale virtuelle Umgebung (.venv) angelegt und
|
||||
# requirements.txt installiert. Ändert sich requirements.txt, wird neu
|
||||
# installiert. Alle Argumente werden an main.py weitergegeben, z. B.:
|
||||
# requirements.txt installiert. Ändert sich requirements.txt oder das Python,
|
||||
# wird neu installiert bzw. die Umgebung neu gebaut. Alles Weitere siehe
|
||||
# MAC-START.md.
|
||||
#
|
||||
# ./run.sh --windowed
|
||||
# ./run.sh --name "Anna" --seed 42
|
||||
#
|
||||
# Getestet auf macOS (arm64) und Linux.
|
||||
# ./run.sh # Fenster
|
||||
# ./run.sh --fullscreen # Vollbild (Eventbetrieb)
|
||||
# ./run.sh --smoke 10 # Selbsttest ohne Eingabegeräte
|
||||
# PYTHON=python3.12 ./run.sh # bestimmtes Python erzwingen
|
||||
set -euo pipefail
|
||||
cd "$(dirname "$0")"
|
||||
|
||||
VENV=".venv"
|
||||
PYTHON="${PYTHON:-python3}"
|
||||
STAMP="$VENV/.requirements.sha256"
|
||||
REQ_STAMP="$VENV/.requirements.sha256"
|
||||
PY_STAMP="$VENV/.python-version"
|
||||
|
||||
if [ ! -x "$VENV/bin/python" ]; then
|
||||
echo "→ Lege virtuelle Umgebung an ($("$PYTHON" --version 2>&1))"
|
||||
"$PYTHON" -m venv "$VENV"
|
||||
# --------------------------------------------------------------------------
|
||||
# 1. Passendes Python finden (neueste zuerst, 3.12 ist die sichere Wahl für
|
||||
# pygame-Wheels; das alte python3 aus den Xcode-Tools bleibt aussen vor)
|
||||
# --------------------------------------------------------------------------
|
||||
if [ -z "${PYTHON:-}" ]; then
|
||||
for candidate in python3.12 python3.13 python3.11 python3.10 python3.9 python3; do
|
||||
if command -v "$candidate" >/dev/null 2>&1; then
|
||||
PYTHON="$candidate"
|
||||
break
|
||||
fi
|
||||
done
|
||||
fi
|
||||
if [ -z "${PYTHON:-}" ]; then
|
||||
echo "✗ Kein Python gefunden."
|
||||
echo " Installiere Python 3.12: brew install python@3.12"
|
||||
echo " (Details siehe MAC-START.md)"
|
||||
exit 1
|
||||
fi
|
||||
PY_VERSION="$("$PYTHON" -V 2>&1)"
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 2. Virtuelle Umgebung anlegen bzw. erneuern
|
||||
# --------------------------------------------------------------------------
|
||||
if [ -d "$VENV" ] && [ -f "$PY_STAMP" ] && [ "$(cat "$PY_STAMP")" != "$PY_VERSION" ]; then
|
||||
echo "→ Python hat sich geändert ($(cat "$PY_STAMP") → $PY_VERSION) – .venv wird neu angelegt"
|
||||
rm -rf "$VENV"
|
||||
fi
|
||||
|
||||
if [ ! -x "$VENV/bin/python" ]; then
|
||||
echo "→ Lege virtuelle Umgebung an ($PY_VERSION)"
|
||||
"$PYTHON" -m venv "$VENV"
|
||||
fi
|
||||
echo "$PY_VERSION" >"$PY_STAMP"
|
||||
|
||||
if ! "$VENV/bin/python" -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 9) else 1)'; then
|
||||
echo "✗ Python 3.9 oder neuer wird benötigt (gefunden: $("$VENV/bin/python" -V 2>&1))"
|
||||
echo " Tipp: neueres Python installieren (z.B. brew install python@3.12) und"
|
||||
echo " die Umgebung neu anlegen: rm -rf .venv"
|
||||
echo "✗ Python 3.9 oder neuer wird benötigt (gefunden: $PY_VERSION)"
|
||||
echo " Tipp: brew install python@3.12, danach: rm -rf .venv"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 3. Abhängigkeiten installieren (nur wenn sich requirements.txt geändert hat)
|
||||
# --------------------------------------------------------------------------
|
||||
if command -v shasum >/dev/null 2>&1; then
|
||||
REQ_HASH="$(shasum -a 256 requirements.txt | cut -d' ' -f1)"
|
||||
else
|
||||
REQ_HASH="$(sha256sum requirements.txt | cut -d' ' -f1)"
|
||||
fi
|
||||
|
||||
if [ ! -f "$STAMP" ] || [ "$(cat "$STAMP")" != "$REQ_HASH" ]; then
|
||||
if [ ! -f "$REQ_STAMP" ] || [ "$(cat "$REQ_STAMP")" != "$REQ_HASH" ]; then
|
||||
echo "→ Installiere Abhängigkeiten aus requirements.txt"
|
||||
"$VENV/bin/python" -m pip install --quiet --upgrade pip
|
||||
"$VENV/bin/python" -m pip install --quiet -r requirements.txt
|
||||
echo "$REQ_HASH" >"$STAMP"
|
||||
echo "$REQ_HASH" >"$REQ_STAMP"
|
||||
fi
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 4. Spiel starten (alle Argumente werden weitergegeben)
|
||||
# --------------------------------------------------------------------------
|
||||
exec "$VENV/bin/python" main.py "$@"
|
||||
Reference in new issue
Block a user