Technische Dokumentation¶

Architektur-Überblick¶

IfRPG ist eine browserbasierte Single-Page-Application auf Basis von:

• React
• Vite
• TypeScript
• Zustand für globalen Spielzustand
• Monaco Editor für die IDE
• external/java-ide als extern gepflegte Java-Compiler-/Interpreter-Komponente
• PHP + SQLite für den optionalen Cloud-Speicherserver

Das Spiel selbst läuft lokal im Browser. Der Server ist nur für Editor-APIs und die optionale Cloud-Speicherung notwendig.

Für die praktische Arbeit mit dem Projekt ergänzen diese technischen Hintergründe vor allem das Benutzerhandbuch, das Level Editor Handbuch und das Handbuch zu den World- und Global-Settings.

Hauptsysteme im Frontend¶

App und Modi¶

Die App hat im Wesentlichen drei größere Laufzeitmodi:

• Startbildschirm mit lokalem Save-Menü, Cloud-Login und Cinematic-Hintergrund
• Spielmodus mit Canvas-Renderer, HUD, Quest-/Journal-/Achievement-Menüs und Systemmenü
• Editor-Modus unter ?editor mit Level-, Quest-, Journal-, Tileset-, H5P- und Settings-Bereichen

Zentral orchestriert wird das aus src/App.tsx.

Globaler Zustand¶

Der meiste Runtime-Zustand liegt in src/state/useGameStore.ts:

• Weltname, Level und Spielerposition
• Variablen, Switches und Queststatus
• Journal- und Achievement-Freischaltungen
• UI-Status und Modale
• Cloud-Session
• globale Defaults und Interaktionen
• Skin-, Pet-, Template- und Treasure-Definitionen

Der Persistenzpfad ist klar getrennt:

• abgeleitete Werte werden nicht mehr blind gespeichert
• Questcode bleibt erhalten
• globale Textdaten werden nicht mehr unnötig mitpersistiert
• Cloud-Session-Daten werden getrennt vom eigentlichen Savegame gehalten

Die inhaltliche Sicht auf diese Datenstrukturen liegt vor allem in den Handbüchern zu Quests, Journalen, Leveln und den World- und Global-Settings.

Content- und World-Layer¶

Registry¶

src/data/Registry.ts ist die zentrale Laufzeit-Registry für:

• Leveldaten
• Quests
• Journaleinträge
• Audio-Discovery
• Weltwechsel
• Templates, Treasures und Erfolge

Die Inhalte liegen zur Laufzeit unter public/data/worlds/<world>/.... Zusätzlich werden Manifest- und World-Content-Dateien generiert, damit Welten rekursiv geladen werden können.

Rich-Content¶

Quest- und Journaltexte laufen über einen gemeinsamen Rich-Content-Pfad:

• HTML-Sanitizing
• Variablensubstitution
• Syntax-Highlighting
• Tabellen-Wrapping
• Mermaid-Rendering
• Mermaid-Objektdiagramm-Nachbearbeitung
• NSD-Rendering über benutzerdefinierte Tags

Das sitzt zentral in src/ui/HighlightedContent.tsx, src/utils/RichHtmlUtils.ts und src/utils/NsdUtils.ts.

Die Autorenperspektive dazu beschreiben das Quest Editor Handbuch, das Journal Editor Handbuch und die Quest-Design-Konzepte.

Rendering und Spielwelt¶

GameView und Renderer¶

Die eigentliche Spielwelt wird aus src/game/GameView.tsx und src/game/hooks/useWorldRenderer.ts gerendert.

Wesentliche Bausteine:

• Tile-Layer
• Spieler, Pet, NPCs, Template-Entities und Treasures
• Licht- und Effektlayer
• Debug-Overlay und Interaktionsindikatoren
• separater Top-Pass für States mit drawOnTop

Die dazugehörigen editorseitigen Arbeitsabläufe stehen im Level Editor Handbuch und in den Level-Design-Konzepten.

Interaktionen und Kollisionen¶

Interaktionen werden zentral über src/game/hooks/useInteractionEngine.ts abgewickelt. Dazu gehören:

• Interaktionsqueue
• Busy-Locks für asynchrone Aktionen
• Dialoge, Variablen, Switches, Teleports und Schleifen
• Pfadfindung für move_player und move_npc
• H5P-Callbacks und Queststarts

Kollisionen und logische Hitboxen sitzen in src/game/CollisionManager.ts und src/game/GameUtils.ts. Die Implementierung unterscheidet sauber zwischen:

• logischen Fuß-Hitboxen
• größeren oder kleineren Displaygrößen
• Template-States
• Interaktionsindikatoren

Java-IDE und Aufgabenruntime¶

IDE¶

Die IDE liegt in src/ide/IDEView.tsx. Sie lädt lazy und trennt den normalen UI-Pfad vom schweren Java-Runtime-Chunk.

Wesentliche Teile:

• Monaco Editor
• Multi-File-Verwaltung
• Questbeschreibung, Ziele, Hinweise und Test-/Run-Workflow
• H5P-Ansicht als alternativer Aufgabenmodus
• Game-API-Dokumentation in der IDE

Java-Runtime¶

Die eigentliche Ausführung läuft über src/ide/runtime.ts, src/ide/JavaRunner.ts, src/ide/IfRPGModule.ts und src/ide/GameIOModule.ts.

Wichtig für die Wartbarkeit:

• external/java-ide bleibt bewusst eine externe, updatefähige Komponente
• die App kapselt nur die Brücke zur Spielwelt
• GameIO und IfRPG sind die öffentlichen Java-Bibliotheken für Aufgaben
• grafische Ausgabe wird appseitig in ein vorgeschaltetes Modal geroutet, nicht direkt in die externe Komponente hinein verändert
• grafische Questziele werden über Runtime-Snapshots und graphics_assert in der App ausgewertet

Für Grafikprogramme erzeugt die App beim Beenden oder Schließen des Fensters einen Snapshot des Grafikzustands. Dieser enthält:

• aktive Grafikmodi wie world2d, processing oder world3d
• Laufzeitobjekte mit Klassenname, Feldern und sichtbaren Eigenschaften
• bei Bedarf Canvas-Pixeldaten für Pixel- und Regionsprüfungen

Damit lassen sich Grafikquests auswerten, ohne external/java-ide selbst für questspezifische Prüfregeln umzubauen.

Die Autoren- und Nutzersicht dazu ergänzen das Quest Editor Handbuch, die Quest-Design-Konzepte und die Game-API-Referenz.

Savegames und Integrität¶

Lokale Savegames¶

Lokale Savegames werden signiert und beim Laden geprüft. Das ist bewusst kein manipulationssicheres Anti-Cheat-System, sondern ein Hürdenmodell für Unterricht und Alltagsbetrieb.

Wesentliche Punkte:

• Savegames erhalten Metadaten, Nonce und Snapshot
• grob unplausible Werte werden erkannt
• abgeleitete Werte wie Level oder gelöste Quests werden normalisiert
• erkannte Manipulation führt in den Cheat-Pfad

Cheaterkennung¶

Manipulierte Savegames können lokal, per Import oder aus der Cloud erkannt werden. Daraus entstehen:

• harter Cheat-Status im Client
• das persistente Achievement cheating_piggy
• optional accountweite Persistenz auf dem Cloudserver

Die sichtbaren Folgen im Spiel erklärt das Benutzerhandbuch. Die inhaltlichen Einstellungen dazu liegen in den World- und Global-Settings.

Cloud-Speicherserver¶

Der optionale Cloudserver liegt unter server/php/ und nutzt:

• PHP
• SQLite
• Session-Token per Authorization: Bearer
• CORS-Whitelist für ifrpg.de und lokale Entwicklungsumgebungen

Der Server bietet unter anderem:

• Registrierung und Login
• Spielstandliste
• Laden, Speichern, Löschen, Anpinnen
• accountweite Achievement-IDs
• Admin-Endpunkte für den Savegame-Editor

Die Authentifizierung ist vollständig headerbasiert; URL-Token werden nicht verwendet.

Editor-Backend¶

Im Dev-Betrieb stellt Vite die Editor-APIs bereit. Dazu gehören unter anderem:

• Level, Quest und Journal lesen und speichern
• Welten anlegen, umbenennen, schützen oder verstecken
• H5P-Pakete importieren
• Medienlisten und Sprites discovery

Build, Bundles und Assets¶

Der Build läuft über npm run build.

Relevante Punkte:

• Startpfad und IDE wurden weiter entkoppelt
• Monaco und Java-Runtime bleiben die größten Chunks
• Welt-Manifest, World-Content und Audio-Indizes werden automatisch erzeugt
• große Medienassets können über Git LFS verwaltet werden
• ein Build-Guard prüft buildkritische LFS-Dateien, damit keine Pointer-Dateien im Arbeitsbaum landen