155 lines
5.8 KiB
Markdown
155 lines
5.8 KiB
Markdown
# Edu Boardgame Generator
|
||
|
||
Web-Baukasten, mit dem Schülerinnen und Schüler eigene Lernbrettspiele zusammenstellen: Spielfeld, Story-Elemente, Quiz-Fragen und Mini-Games. Das fertige Spiel läuft direkt im Browser und lässt sich per Link oder sechsstelligem Kurz-Code teilen.
|
||
|
||
**Live:** https://franke-lab.de/edu-boardgame-generator
|
||
**Kontext:** Pädagogische Hochschule Weingarten, BoysDay / Informatik-Unterricht
|
||
|
||
## Features
|
||
|
||
- **Fünf-Schritte-Editor:** Spielidee, Design (Figur, Weltkulisse, Feldanzahl), Spielfeld-Bestückung (Mini-Games pro Feld), Story- und Quiz-Karten, Veröffentlichung.
|
||
- **Player:** Würfel, animierte Figur, Konsequenzen (Felder vor/zurück, Leben, Punkte, Zug aussetzen, nochmal), Sieg-/Verlust-Bildschirm.
|
||
- **Vierzehn Mini-Games:** Snake, Flappy, Memory, Quiz, Reaction, Basketball, Catch, Maze, Simon, Puzzle, Spot-Diff, Typing sowie 2-Spieler-Varianten von Snake und Flappy.
|
||
- **Zwei Wege zum Teilen:** komprimierter URL-Hash (kein Backend nötig) und sechsstelliger Kurz-Code (via API auf dem Server persistiert).
|
||
- **Python-Code-Vorschau:** Die Konfiguration wird als lesbarer Python-Pseudocode ausgegeben – Bindeglied zwischen Baukasten und Programmierunterricht.
|
||
- **PDF-Export** des Spielfelds für den Druck.
|
||
- **QR-Code** zum Aufrufen des Spiels vom Handy.
|
||
|
||
## Architektur
|
||
|
||
Reines Frontend, keine Build-Kette. Ein kleiner Node-HTTP-Server dient nur zum Ablegen und Ausliefern der Kurz-Codes.
|
||
|
||
```
|
||
Browser
|
||
editor.html Editor (Wizard, Vorschau, Sharing)
|
||
game.html Player
|
||
play/ Landing-Seite für Kurz-Code-Aufruf
|
||
|
|
||
| fetch /api/boardgame-play/{code}
|
||
v
|
||
nginx (franke-lab.de) --> Node.js :3009 --> play/codes/{code}.json
|
||
```
|
||
|
||
- Der Editor speichert Zwischenstände in `localStorage`.
|
||
- Beim Teilen wird die Konfiguration mit pako gzip-komprimiert und base64-kodiert. Kleine Spiele passen in einen URL-Fragment (`#z:…`), größere werden über den Kurz-Code-Endpunkt abgelegt.
|
||
- Der Player liest wahlweise Hash-Fragment oder holt sich das JSON per Kurz-Code.
|
||
|
||
## Verzeichnisstruktur
|
||
|
||
```
|
||
edu-boardgame-generator/
|
||
index.html Weiterleitung auf editor.html
|
||
editor.html Editor-Grundgerüst
|
||
editor.css
|
||
game.html Player-Grundgerüst
|
||
game.css
|
||
codegen.js Python-Code-Vorschau
|
||
js/
|
||
state.js globaler Editor-Zustand + localStorage
|
||
data.js Konstanten (Figuren, Welten, Mini-Game-IDs), esc()
|
||
wizard.js Schritt-Navigation, Validierung
|
||
board.js Spielfeld-Editor, Drag&Drop, Story-Karten
|
||
quiz.js Quiz-Editor
|
||
world.js Canvas-Rendering des Spielbretts
|
||
share.js Serialisierung, URL-Hash, Kurz-Code-Request
|
||
minigame-test.js Testlauf einzelner Mini-Games im Editor
|
||
tour.js erste Nutzer-Tour
|
||
game.js Player-Logik (Würfel, Bewegung, Konsequenzen)
|
||
minigames/
|
||
_api.js MGAPI: onResult, Farb-Themes
|
||
snake.js, snake2p.js
|
||
flappy.js, flappy2p.js
|
||
memory.js, quiz.js, reaction.js
|
||
basketball.js, catch.js, maze.js
|
||
simon.js, puzzle.js, spotdiff.js
|
||
typing.js
|
||
play/
|
||
index.html Landing für /play/{CODE}
|
||
codes/*.json persistierte Spiel-Konfigurationen
|
||
```
|
||
|
||
## Kurz-Code-API
|
||
|
||
Node-HTTP-Server, hört auf `127.0.0.1:3009`, wird von nginx unter
|
||
`/api/boardgame-play/*` durchgereicht.
|
||
|
||
| Route | Methode | Beschreibung |
|
||
|---|---|---|
|
||
| `/api/boardgame-play` | POST | Nimmt eine JSON-Konfiguration entgegen, vergibt einen freien Kurz-Code und antwortet mit `{code}` |
|
||
| `/api/boardgame-play/{code}` | GET | Liefert die zugehörige JSON-Konfiguration |
|
||
|
||
- **Alphabet:** `23456789ABCDEFGHJKLMNPQRSTUVWXYZ` (verwechslungsarm, ohne 0/O/1/I/L)
|
||
- **Code-Länge:** 6 Zeichen
|
||
- **Nutzlast:** maximal 50 KB pro Spiel
|
||
- **Speicherort:** flache JSON-Dateien unter `play/codes/`
|
||
|
||
## Abhängigkeiten
|
||
|
||
**Backend:** Node.js (nur Standardbibliothek: `http`, `fs`, `path`) - kein `package.json`, keine externen Pakete.
|
||
|
||
**Frontend (über CDN eingebunden):**
|
||
- pako 2.1.0 - Komprimierung für URL-Hash-Sharing
|
||
- qrcodejs 1.0.0 - QR-Code zum Spiel
|
||
- jsPDF 2.5.1 - PDF-Export des Spielfelds
|
||
|
||
## Entwicklung
|
||
|
||
Es gibt keine Build-Schritte und keine Bundler. Direkt am Live-Server oder lokal editieren.
|
||
|
||
```bash
|
||
# statisch servieren (im Projektordner)
|
||
python3 -m http.server 8000
|
||
|
||
# Kurz-Code-Server lokal
|
||
node server.js
|
||
```
|
||
|
||
Für Test mit lokalem Backend die API-Basis in `js/share.js` anpassen.
|
||
|
||
## Deployment (Produktions-Setup)
|
||
|
||
Datei-Ablage:
|
||
|
||
```
|
||
/var/www/franke-lab/edu-boardgame-generator/ Frontend
|
||
/opt/boardgame-play/server.js Kurz-Code-Server
|
||
```
|
||
|
||
systemd-Unit `boardgame-play.service`:
|
||
|
||
```
|
||
[Service]
|
||
ExecStart=/usr/bin/node /opt/boardgame-play/server.js
|
||
WorkingDirectory=/opt/boardgame-play
|
||
```
|
||
|
||
nginx-Snippet:
|
||
|
||
```
|
||
location ~ ^/api/boardgame-play(/.*)?$ {
|
||
proxy_pass http://127.0.0.1:3009$1;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
}
|
||
```
|
||
|
||
## Sicherheit
|
||
|
||
- Nutzer-Eingaben (Name, Story-Texte, Quiz-Fragen/Antworten, Feld-IDs) werden beim Laden in `sanitizeCfg` gegen Whitelists geprüft und Länge/Bereich geklemmt.
|
||
- Rendering im Player nutzt `textContent` bzw. `esc()` statt roher `innerHTML`-Interpolation.
|
||
- Kurz-Code-Endpunkt akzeptiert nur Codes im definierten Alphabet und lehnt Payloads > 50 KB ab.
|
||
|
||
## Roadmap
|
||
|
||
Kurzfristig geplant (aus Nutzer-Beobachtungen 7./8. Klasse):
|
||
|
||
- Startseite mit „Meine Spiele", Vorlagen und Kurz-Tutorial
|
||
- Zwei-Spieler-Modus für den kompletten Spielablauf (bislang nur pro Mini-Game)
|
||
- Melde-Funktion für problematische Inhalte, IP-Log am Kurz-Code-Endpunkt, Wort-Filter
|
||
- Optionales Nutzerkonto zur Verwaltung eigener Spielcodes
|
||
|
||
## Lizenz
|
||
|
||
Interne Nutzung, PH Weingarten. Klärung mit den Autoren vor Weitergabe.
|