From a088c23a09e5e6e1d06cf7aea0b3f2a00b0aeb1e Mon Sep 17 00:00:00 2001 From: Project Bridge Date: Sun, 1 Nov 2026 13:00:11 +0000 Subject: [PATCH] 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. --- MAC-START.md | 267 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 6 +- run.sh | 69 +++++++++---- 3 files changed, 324 insertions(+), 18 deletions(-) create mode 100644 MAC-START.md diff --git a/MAC-START.md b/MAC-START.md new file mode 100644 index 0000000..b9f801f --- /dev/null +++ b/MAC-START.md @@ -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:** (ö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. + +--- + +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. diff --git a/README.md b/README.md index a650664..f89d299 100644 --- a/README.md +++ b/README.md @@ -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/ diff --git a/run.sh b/run.sh index c0bbf4a..8877c47 100755 --- a/run.sh +++ b/run.sh @@ -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 "$@"