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