README: Projektübersicht, Struktur, API, Deployment
This commit is contained in:
Stefan Franke
parent
28b8c3bc5d
commit
b759e04a01
1 changed files with 155 additions and 0 deletions
155
README.md
Normal file
155
README.md
Normal file
|
|
@ -0,0 +1,155 @@
|
||||||
|
# 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.
|
||||||
Loading…
Reference in a new issue