Game API Referenz¶

Diese Seite dokumentiert die komplette Java-API, die Quest-Autoren im Spiel nutzen können.

Sie ergänzt das Quest Editor Handbuch und die Quest-Design-Konzepte.

Überblick¶

Es gibt drei relevante API-Ebenen:

GameIO Diese API ist immer erlaubt, auch in sichtbaren und bearbeitbaren Dateien.
Game Die bevorzugte Quest-API für Variablen, Switches, NPCs, Objekte und globale Effekte.
IfRPG Legacy- und Spezial-API für Player, UI, Medien und Debugging.

Dazu kommen die NRW-Datenstrukturen:

NRWList, NRWQueue, NRWStack
NRWBinaryTree, NRWBinarySearchTree, NRWComparableContent
NRWVertex, NRWEdge, NRWGraph

Diese Klassen sind reine Datenstrukturen und immer verfuegbar.

Wichtig:

In sichtbaren, bearbeitbaren Dateien bleibt nur GameIO erlaubt.
Game, IfRPG, Player, UI, Media und Direction sind nur für Questdateien gedacht.
Game.getNPCList() und Game.getObjectList() liefern immer nur Entities aus dem aktuellen Level.
Die NRW-Klassen mit NRW-Prefix sind ueberall erlaubt.

Laufzeitmodell¶

Die API kennt synchrone und asynchrone Methoden.

Asynchron:

Dialoge und Eingaben über GameIO und IfRPG.UI
Player-Bewegung per walkTo, runTo, walkToRelative, runToRelative, step..., interact
Entity-Bewegung per walkTo, runTo, walkToRelative, runToRelative
playAnimation(..., false) auf GameEntity

Synchron:

Getter und Statusabfragen
lookAt
setX, setY, moveTo
Licht- und Effektmethoden
Medienaufrufe
Variablen- und Switch-Zugriff

Teleport-Methoden:

setX, setY und moveTo teleportieren sofort.
Sie nutzen keine Pfadsuche.
Sie spielen keine Laufanimation.
Sie prüfen keine Kollisionen.

Wichtige Typen¶

`Direction`¶

Direction.UP
Direction.DOWN
Direction.LEFT
Direction.RIGHT

`Color`¶

Für Licht- und Effektmethoden wird die normale Java-Color-Klasse verwendet.

new Color(255, 180, 80)
new Color(255, 180, 80, 0.6)

Listen¶

Game.getNPCList() und Game.getObjectList() liefern Java-Listen:

List<NPC>
List<GameObject>

Game.getNPCNRWList() und Game.getObjectNRWList() liefern stattdessen NRW-Listen:

NRWList<NPC>
NRWList<GameObject>

Live-Handles auf Entities¶

NPC- und GameObject-Instanzen sind Live-Handles auf die Spielwelt.

Ihre Werte beziehen sich immer auf das aktuelle Level.
Nach Levelwechsel oder Zustandswechsel kann ein Handle ungültig werden.
Prüfe bei länger lebenden Referenzen mit exists().

`GameIO`¶

GameIO ist die einfache öffentliche API für Schülercode.

Signaturen¶

static String inputText(String title, String question)
static int inputNumber(String title, String question)
static boolean inputBoolean(String title, String question, String trueLabel, String falseLabel)
static int inputChoice(String title, String question, String[] choices)
static void outputText(String title, String message)

Verhalten¶

Alle input...-Methoden sind asynchron.
outputText(...) ist ebenfalls asynchron und wartet, bis der Dialog bestätigt wurde.
inputChoice(...) liefert einen 1-basierten Index zurück. Die erste Option ist also 1, nicht 0.
Die UI zeigt maximal 8 Auswahloptionen gleichzeitig sinnvoll an.

Beispiel¶

String name = GameIO.inputText("Name", "Wie heißt du?");
int alter = GameIO.inputNumber("Alter", "Wie alt bist du?");
boolean ok = GameIO.inputBoolean("Start", "Weitermachen?", "Ja", "Nein");
int wahl = GameIO.inputChoice("Werkzeug", "Was nimmst du?", new String[]{"Hammer", "Bohrer"});

GameIO.outputText("Info", "Hallo " + name + "!");

`Game`¶

Game ist die empfohlene Quest-API für Weltzustand und Entities.

Variablen und Switches¶

Signaturen:

static boolean hasVariable(String id)

static int getInt(String id)
static double getDouble(String id)
static String getString(String id)
static boolean getBoolean(String id)
static boolean getSwitch(String id)

static void setInt(String id, int value)
static void setDouble(String id, double value)
static void setString(String id, String value)
static void setBoolean(String id, boolean value)
static void setSwitch(String id, boolean value)

Hinweise:

Intern sind Switches boolesche Variablen.
getSwitch(...) und setSwitch(...) sind Kompatibilitätsnamen für boolesche Werte.
Nicht vorhandene Variablen liefern den jeweiligen Default des Laufzeitmodells.

Beispiel:

if (!Game.getBoolean("door_open")) {
    Game.setBoolean("door_open", true);
}

int coins = Game.getInt("coins");
Game.setInt("coins", coins + 5);

Entity-Lookups¶

Signaturen:

static NPC getNPCById(String id)
static List<NPC> getNPCList()
static NRWList<NPC> getNPCNRWList()

static GameObject getObjectById(String id)
static List<GameObject> getObjectList()
static NRWList<GameObject> getObjectNRWList()

Hinweise:

getNPCById(...) und getObjectById(...) liefern null, wenn im aktuellen Level keine passende aktive Entity existiert.
GameObject umfasst alle aktiven Nicht-NPC-Entities, also auch Objekte aus Templates oder Schätze.
Die Listen sind level-lokal, nicht weltweit.
Die ...NRWList()-Varianten liefern dieselben Inhalte, aber als NRWList.

Beispiel:

NPC guard = Game.getNPCById("guard_1");
if (guard != null && guard.exists()) {
    guard.lookAt(Direction.LEFT);
}

Globale visuelle Effekte¶

Signaturen:

static void setMode(String mode)
static void setMode(String mode, double intensity)
static void setMode(String mode, double intensity, Color color)

static void setWeather(String weather)
static void setWeather(String weather, double intensity)

static void setAtmosphere(String atmosphere)
static void setAtmosphere(String atmosphere, double intensity)
static void setAtmosphere(String atmosphere, double intensity, Color color)

static void setTransformation(String transformation)
static void setTransformation(String transformation, double intensity)

static void clearEffects()
static void resetEffects()

Gültige Werte:

Mode: none, night, cave, alert, underwater
Weather: none, rain, snow, thunderstorm, fireworks, explosions
Atmosphere: none, fog, toxic, smoke, forest, demonic
Transformation: none, earthquake, underwater, drunk, muffled

Hinweise:

setMode, setWeather, setAtmosphere und setTransformation wirken sofort.
Ungültige Strings fallen auf none zurück.
clearEffects() setzt Mode, Weather, Atmosphere und Transformation auf none und entfernt benutzerdefinierte Effektfarben.
clearEffects() verändert das Player-Licht nicht.
resetEffects() stellt die vollständigen Level-Defaults wieder her, inklusive Player-Licht.

Beispiel:

Game.setMode("night", 0.8, new Color(20, 40, 90, 0.85));
Game.setWeather("rain", 0.6);
Game.setAtmosphere("fog", 0.5, new Color(180, 190, 210, 0.45));
Game.setTransformation("earthquake", 0.7);

`GameEntity`¶

GameEntity ist die Basisklasse von NPC und GameObject.

Felder¶

String id
String name
double x
double y
String stateId

Die Felder sind direkt lesbar und spiegeln die aktuelle Runtime wieder.

Getter und Status¶

boolean exists()

double getX()
double getY()
String getId()
String getName()
String getStateId()

Sofortige Positionsänderung¶

void setX(double x)
void setY(double y)
void moveTo(double x, double y)

Hinweise:

Diese Methoden teleportieren sofort.
Sie löschen laufende externe Bewegungs-Subpaths der Entity.
Für NPC-artige Entities wird dabei auch die aktuelle Home-/Rückkehrposition aktualisiert.

Bewegung mit Pfadsuche¶

void walkTo(double x, double y)
void runTo(double x, double y)
void walkToRelative(double x, double y)
void runToRelative(double x, double y)

Hinweise:

Diese Methoden sind asynchron.
Relative Methoden beziehen sich auf die aktuelle Position der Entity.
Wenn kein Pfad gefunden wird, wird die Methode ohne Bewegung beendet.

Blickrichtung¶

void lookAt(Direction direction)

Animationen¶

void playAnimation(String animationId, boolean loop)
void stopAnimation()

Hinweise:

playAnimation(..., true) startet eine Schleife und kehrt sofort zurück.
playAnimation(..., false) wartet asynchron auf eine abgeschlossene Schleife.
stopAnimation() beendet nur die explizit gestartete Runtime-Animation.

Licht¶

void lightOn()
void lightOff()
void resetLight()

void setLight(Color color, double radius)
void setLight(Color color, double radius, double intensity)
void setLight(Color color, double radius, double intensity, boolean flicker)
void setLight(Color color, double radius, double intensity, boolean flicker, boolean blink, double blinkFrequency, String blinkPattern)

Hinweise:

lightOn() und lightOff() schalten nur das Runtime-Licht an oder aus.
resetLight() stellt das Licht auf den aktuellen Level-/State-Default der Entity zurück.
setLight(...) überschreibt das aktuelle Runtime-Licht der Entity.

`NPC`¶

NPC ist eine finale Unterklasse von GameEntity.

Keine zusätzlichen Methoden
Vollständige Funktionalität über GameEntity

`GameObject`¶

GameObject ist eine finale Unterklasse von GameEntity.

Keine zusätzlichen Methoden
Vollständige Funktionalität über GameEntity

NRW-Datenstrukturen¶

Die NRW-Abiturklassen sind mit NRW-Prefix immer verfuegbar und kollidieren daher nicht mit den normalen Java-Klassen.

Verfuegbare Klassen¶

NRWList<ContentType>
NRWQueue<ContentType>
NRWStack<ContentType>
NRWBinaryTree<ContentType>
NRWBinarySearchTree<ContentType extends NRWComparableContent<ContentType>>
NRWComparableContent<ContentType>
NRWVertex
NRWEdge
NRWGraph

Kurzuebersicht¶

NRWList bietet die bekannte NRW-Listenlogik mit aktuellem Element (hasAccess, toFirst, next, getContent, append, insert, remove, concat).
NRWQueue bietet enqueue, dequeue, front und isEmpty.
NRWStack bietet push, pop, top und isEmpty.
NRWBinaryTree bietet leeren Baum oder Baum mit Inhalt und Teilbaeumen.
NRWBinarySearchTree arbeitet mit Typen, die NRWComparableContent implementieren.
NRWGraph liefert und verarbeitet NRWVertex- und NRWEdge-Objekte.

Beispiel¶

NRWList<NPC> npcs = Game.getNPCNRWList();
if (npcs.hasAccess()) {
    NPC npc = npcs.getContent();
    npc.lookAt(Direction.LEFT);
}

NRWQueue<String> queue = new NRWQueue<String>();
queue.enqueue("A");
queue.enqueue("B");
System.out.println(queue.front());

`IfRPG`¶

IfRPG bleibt als Legacy- und Spezial-API erhalten.

Signatur:

static void log(String message)

Außerdem stellt IfRPG drei statische Einstiegspunkte bereit:

IfRPG.Player
IfRPG.UI
IfRPG.Media

`IfRPG.Player`¶

Die Player-API steuert direkt die Spielfigur.

Bewegung mit Pfadsuche¶

static void walkTo(double x, double y)
static void runTo(double x, double y)
static void walkToRelative(double x, double y)
static void runToRelative(double x, double y)

Asynchron, mit Pfadsuche und normaler Bewegungslogik.

Teleport¶

static void setX(double x)
static void setY(double y)
static void moveTo(double x, double y)

Hinweise:

Teleportiert sofort.
Löscht den laufenden Script-/Klickpfad des Players.
Nutzt keine Pfadsuche.
Prüft keine Kollisionen.

Schritte¶

static void stepUp()
static void stepDown()
static void stepLeft()
static void stepRight()
static void step(Direction direction)

Asynchron, ein Schritt in die jeweilige Richtung.

Position und Walkability¶

static double getX()
static double getY()

static boolean isWalkable()
static boolean isWalkable(Direction direction)

Hinweise:

isWalkable(Direction direction) prüft das angrenzende Feld in dieser Richtung.
isWalkable() ohne Parameter prüft das aktuelle Spielerfeld.

Aktionen¶

static void lookAt(Direction direction)
static void interact()
static void blockMovement()
static void unblockMovement()
static boolean isBlocked()

Hinweise:

interact() ist asynchron.
blockMovement() und unblockMovement() betreffen die normale Spielersteuerung.

Player-Licht¶

static void lightOn()
static void lightOff()
static void resetLight()

static void setLight(Color color, double radius)
static void setLight(Color color, double radius, double intensity)
static void setLight(Color color, double radius, double intensity, boolean flicker)
static void setLight(Color color, double radius, double intensity, boolean flicker, boolean blink, double blinkFrequency, String blinkPattern)

Hinweise:

lightOn() und lightOff() schalten das Player-Licht nur an oder aus.
resetLight() stellt das Player-Licht auf die Level-Defaults zurück.
setLight(...) ändert nur das Player-Licht, nicht die übrigen globalen Effekte.

`IfRPG.UI`¶

Die UI-API bietet die gleichen Basisdialoge wie GameIO, zusätzlich mit optionaler Sprachdatei.

Signaturen¶

static String inputText(String title, String question)
static String inputText(String title, String question, String voiceFile)

static int inputNumber(String title, String question)
static int inputNumber(String title, String question, String voiceFile)

static boolean inputBoolean(String title, String question, String trueLabel, String falseLabel)
static boolean inputBoolean(String title, String question, String trueLabel, String falseLabel, String voiceFile)

static int inputChoice(String title, String question, String[] choices)
static int inputChoice(String title, String question, String[] choices, String voiceFile)

static void outputText(String title, String message)
static void outputText(String title, String message, String voiceFile)

Hinweise:

Alle Methoden sind asynchron.
inputChoice(...) liefert einen 1-basierten Index zurück.
voiceFile ist optional und wird als Sprachdatei abgespielt.

`IfRPG.Media`¶

Die Medien-API steuert Bilder, Videos und Audio.

Signaturen¶

static void showImage(String filename, boolean fullscreen)
static void showMovie(String filename, boolean fullscreen)

static void playMusic(String filename)
static void playSFX(String filename)
static void playVoice(String filename)

Hinweise:

Diese Methoden sind synchron im Java-Sinn und kehren sofort zurück.
Verwende dieselben Dateipfade wie im Action-Editor bzw. in bestehenden Quests.

Legacy-Aliase¶

In Questdateien stehen die folgenden Typen zusätzlich auch direkt zur Verfügung:

Player
UI
Media
Direction

Das ist Legacy-Kompatibilität. Für neue Dokumentation und neue Inhalte ist diese Schreibweise vorzugsweise:

GameIO für Schülercode
Game für Questlogik
IfRPG.Player, IfRPG.UI, IfRPG.Media für Spezialfälle

Typische Muster¶

Dialog -> Variable setzen -> Welt reagieren lassen¶

String code = GameIO.inputText("Terminal", "Gib den Zugangscode ein:");
if (code.equals("4711")) {
    Game.setBoolean("door_open", true);
    GameIO.outputText("Terminal", "Zugang gewährt.");
} else {
    GameIO.outputText("Terminal", "Zugang verweigert.");
}

NPC im aktuellen Level bewegen und beleuchten¶

NPC guide = Game.getNPCById("guide");
if (guide != null && guide.exists()) {
    guide.moveTo(8.5, 4.0);
    guide.setLight(new Color(255, 220, 150, 0.5), 2.8, 0.9, true);
}

Globale Stimmung umschalten¶

Game.setMode("night", 0.8);
Game.setWeather("rain", 0.6);
IfRPG.Player.setLight(new Color(255, 220, 180, 0.6), 3.0, 1.0, true);

Empfehlungen für Autoren¶

GameIO ist für Aufgaben und sichtbaren Schülercode fast immer der richtige Einstieg.
Game ist die bevorzugte API für Quest- und Weltlogik.
IfRPG sollte nur dort eingesetzt werden, wo direkte Player-, UI- oder Mediensteuerung wirklich nötig ist.
Nutze für langlebige Entity-Referenzen immer exists().
Nutze moveTo, setX und setY nur dann, wenn du wirklich teleportieren willst.

Game API Referenz¶

Überblick¶

Laufzeitmodell¶

Wichtige Typen¶

Direction¶

Color¶

Listen¶

Live-Handles auf Entities¶

GameIO¶

Signaturen¶

Verhalten¶

Beispiel¶

Game¶

Variablen und Switches¶

Entity-Lookups¶

Globale visuelle Effekte¶

GameEntity¶

Felder¶

Getter und Status¶

Sofortige Positionsänderung¶

Bewegung mit Pfadsuche¶

Blickrichtung¶

Animationen¶

Licht¶

NPC¶

GameObject¶

NRW-Datenstrukturen¶

Verfuegbare Klassen¶

Kurzuebersicht¶

Beispiel¶

IfRPG¶

IfRPG.Player¶

Bewegung mit Pfadsuche¶

Teleport¶

Schritte¶

Position und Walkability¶

Aktionen¶

Player-Licht¶

IfRPG.UI¶

Signaturen¶

IfRPG.Media¶

Signaturen¶

Legacy-Aliase¶

Typische Muster¶

Dialog -> Variable setzen -> Welt reagieren lassen¶

NPC im aktuellen Level bewegen und beleuchten¶

Globale Stimmung umschalten¶

Empfehlungen für Autoren¶

`Direction`¶

`Color`¶

`GameIO`¶

`Game`¶

`GameEntity`¶

`NPC`¶

`GameObject`¶

`IfRPG`¶

`IfRPG.Player`¶

`IfRPG.UI`¶

`IfRPG.Media`¶