Référence de l'API Java

L'API publique complète du runtime Loreline pour chaque langage supporté.

Vous débutez avec Loreline en Java ? Commencez par le guide d'intégration. Cette page est la référence exhaustive.

Vue d'ensemble

TypeMembres
Loreline parse play resume extractTranslations loadLocale translationFormat lastError print update
Interpreter Interpreter start save restore resume getCharacter getCharacterField setCharacterField getStateField setStateField getTopLevelStateField setTopLevelStateField currentNode
Script fromJson
Node id type toJson fromJson line column offset length nodeIdToString
InterpreterOptions functions strictAccess customCreateFields translations InterpreterOptions
ChoiceOption text tags enabled ChoiceOption
TextTag closing value offset TextTag
DialogueHandler handle
ChoiceHandler handle
FinishHandler handle
ImportsFileHandler handle
CreateFieldsHandler create
LorelineFunction call

Loreline

classe

L'API publique principale du runtime Loreline sur la JVM. Elle donne un accès simple aux fonctions de base : analyser et exécuter des scripts Loreline.

parse

méthode

public static Script parse(String input)
public static Script parse(String input, String filePath, ImportsFileHandler handleFile)

Analyse le texte fourni et crée une instance de Script.

ParamètreTypeDescription
input String Le contenu du script Loreline sous forme de chaîne (format .lor)

Retourne Script le script analysé

Lève Si le script contient des erreurs de syntaxe ou d'autres problèmes d'analyse

C'est la première étape pour utiliser un script Loreline. L'objet Script renvoyé se passe ensuite à play() ou à resume().

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

play

méthode

public static Interpreter play(Script script, DialogueHandler handleDialogue, ChoiceHandler handleChoice, FinishHandler handleFinish)
public static Interpreter play(Script script, DialogueHandler handleDialogue, ChoiceHandler handleChoice, FinishHandler handleFinish, String beatName, InterpreterOptions options)

Démarre l'exécution d'un script Loreline depuis le début ou depuis un beat précis.

ParamètreTypeDescription
script Script Le script analysé (résultat de parse())
handleDialogue DialogueHandler Fonction appelée quand un texte de dialogue doit être affiché
handleChoice ChoiceHandler Fonction appelée quand le joueur doit faire un choix
handleFinish FinishHandler Fonction appelée quand l'exécution du script se termine

Retourne Interpreter l'instance d'interpréteur

Cette fonction se charge d'initialiser l'interpréteur et de démarrer l'exécution immédiatement. Vous devrez fournir des handlers pour les dialogues, les choix et la fin du script.

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

resume

méthode

public static Interpreter resume(Script script, DialogueHandler handleDialogue, ChoiceHandler handleChoice, FinishHandler handleFinish, String saveData)
public static Interpreter resume(Script script, DialogueHandler handleDialogue, ChoiceHandler handleChoice, FinishHandler handleFinish, String saveData, String beatName, InterpreterOptions options)

Reprend un script Loreline à partir d'une sauvegarde.

ParamètreTypeDescription
script Script Le script analysé (résultat de parse())
handleDialogue DialogueHandler Fonction appelée quand un texte de dialogue doit être affiché
handleChoice ChoiceHandler Fonction appelée quand le joueur doit faire un choix
handleFinish FinishHandler Fonction appelée quand l'exécution du script se termine
saveData String Les données de sauvegarde (en général, celles renvoyées par interpreter.save())

Retourne Interpreter l'instance d'interpréteur

Cela permet de continuer une histoire exactement là où elle a été sauvegardée, en restaurant toutes les variables d'état, les choix et la progression du joueur.

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

extractTranslations

méthode

public static Object extractTranslations(Script script)

Extrait les traductions d'un script de traduction analysé.

ParamètreTypeDescription
script Script Le script de traduction analysé (résultat de parse() sur un fichier .XX.lor)

Retourne Object un objet de traductions à passer comme InterpreterOptions.translations

À partir d'un fichier de traduction analysé avec parse(), renvoie les traductions, à passer dans options.translations de play() ou de resume().

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

loadLocale

méthode

public static Object loadLocale(String locale, Script script, ImportsFileHandler handleFile)
public static Object loadLocale(String locale, Script script, String filePath, ImportsFileHandler handleFile)

Charge les traductions d'une langue donnée. Parcourt tout l'arbre d'imports du script et charge le fichier .<locale>.lor de chaque fichier. Par défaut, les traductions sont cherchées à côté des fichiers source.

ParamètreTypeDescription
locale String Le code de langue (par exemple "fr")
script Script Le script source analysé (analysé avec un chemin de fichier, sinon fournissez filePath)
handleFile ImportsFileHandler Handler de fichiers utilisé pour lire les fichiers de traduction

Retourne Object un objet de traductions à passer comme InterpreterOptions.translations

Pour chaque fichier du script (le fichier racine et tous ses imports, directs ou non), le fichier de traduction correspondant est cherché en insérant .<locale> avant l'extension (par exemple characters.lor -> characters.fr.lor). Les fichiers de traduction absents sont ignorés sans erreur. Les traductions renvoyées se passent dans InterpreterOptions.translations de play() ou de resume().

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

translationFormat

méthode

public static void translationFormat(String name, boolean enabled)

Active ou désactive la prise en charge d'un autre format de fichier de traduction.

ParamètreTypeDescription
name String L'identifiant de format (voir ci-dessus)
enabled boolean True pour activer le format, false pour le désactiver

Retourne void

Par défaut, loadLocale n'essaie que les fichiers .<locale>.lor. Appelez cette méthode pour activer d'autres formats. Noms connus :

  • "po" : GNU gettext PO (.po)
  • "xliff" : XLIFF 1.2 / 2.x (.xliff, .xlf)
  • "csv" : CSV / TSV (.csv, .tsv)

Les noms inconnus sont acceptés sans erreur, pour rester compatible avec les versions futures.

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

lastError

méthode

public static loreline.runtime.Error lastError()

Renvoie l'erreur du dernier appel échoué à parse() ou loadLocale(), ou null en cas de succès.

Retourne loreline.runtime.Error

En mode asynchrone (avec callback), le callback reçoit null en cas d'échec et cette méthode dit ce qui s'est mal passé. En mode synchrone, l'appel lève une exception, et cette méthode renvoie la même erreur, consultable après le catch.

Pas thread-safe : à lire immédiatement après le retour de l'appel.

JavaScript TypeScript C# C++ Java PHP Python Lua Haxe

print

méthode

public static String print(Script script)
public static String print(Script script, String indent, String newline)

Régénère le code source Loreline à partir d'un script analysé.

ParamètreTypeDescription
script Script Le script analysé (résultat de parse())

Retourne String le code source produit, sous forme de chaîne

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

update

méthode

public static void update(double delta)

Fait avancer les timers wait() en attente. À appeler depuis votre boucle de jeu à chaque frame. Le premier appel active le mode différé non bloquant pour wait() ; avant cet appel, wait() retombe sur une attente bloquante, ce qui convient aux outils en ligne de commande.

ParamètreTypeDescription
delta double Temps écoulé depuis la frame précédente, en secondes

Retourne void

C# C++ Java PHP Python Lua Haxe

Interpreter

classe

Classe principale de l'interpréteur des scripts Loreline. Elle enveloppe l'interpréteur généré par Haxe dans une API adaptée à Java.

Interpreter

constructeur

public Interpreter(Script script, DialogueHandler handleDialogue, ChoiceHandler handleChoice, FinishHandler handleFinish)
public Interpreter(Script script, DialogueHandler handleDialogue, ChoiceHandler handleChoice, FinishHandler handleFinish, InterpreterOptions options)

Crée un nouvel interpréteur de script Loreline.

ParamètreTypeDescription
script Script Le script analysé à exécuter
handleDialogue DialogueHandler Fonction appelée pour afficher un texte de dialogue
handleChoice ChoiceHandler Fonction appelée pour présenter des choix
handleFinish FinishHandler Fonction appelée quand l'exécution se termine

JavaScript TypeScript C# Java Python Haxe

start

méthode

public void start(String beatName)

Démarre l'exécution du script depuis le début ou depuis un beat précis.

ParamètreTypeDescription
beatName String Nom optionnel du beat par lequel démarrer. Si null, l'exécution démarre au premier beat, ou au beat nommé "_" s'il existe.

Retourne void

Lève RuntimeError Si le beat indiqué n'existe pas ou si le script ne contient aucun beat

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

save

méthode

public String save()

Sauvegarde l'état courant de l'interpréteur.

Retourne String une chaîne JSON contenant l'état sérialisé

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

restore

méthode

public void restore(String savedData)

Restaure l'état de l'interpréteur à partir d'une sauvegarde.

ParamètreTypeDescription
savedData String L'objet SaveData contenant l'état sérialisé

Retourne void

Lève RuntimeError Si la version des données de sauvegarde est incompatible

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

resume

méthode

public void resume()

Reprend l'exécution une fois l'état restauré.

Retourne void

JavaScript TypeScript C# Java PHP Python Lua Haxe

getCharacter

méthode

public Object getCharacter(String name)

Renvoie les propriétés d'un personnage par son nom.

ParamètreTypeDescription
name String Le nom du personnage à récupérer

Retourne Object les propriétés du personnage, ou null

JavaScript TypeScript C# Java PHP Python Lua Haxe

getCharacterField

méthode

public Object getCharacterField(String character, String field)

Renvoie une propriété précise d'un personnage.

ParamètreTypeDescription
character String Le nom du personnage
field String Le nom de la propriété à lire

Retourne Object la valeur de la propriété, ou null

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

setCharacterField

méthode

public void setCharacterField(String character, String field, Object value)

Modifie une propriété d'un personnage.

ParamètreTypeDescription
character String Le nom du personnage
field String Le nom de la propriété à modifier
value Object La nouvelle valeur

Retourne void

JavaScript TypeScript GDScript C++ Java PHP Python Lua Haxe

getStateField

méthode

public Object getStateField(String name)

Renvoie une propriété de l'état par son nom, en cherchant d'abord dans la portée courante, puis dans les portées englobantes.

ParamètreTypeDescription
name String Le nom de la propriété à lire

Retourne Object la valeur de la propriété, ou null

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

setStateField

méthode

public void setStateField(String name, Object value)

Modifie une propriété de l'état par son nom, en cherchant d'abord dans la portée courante, puis dans les portées englobantes.

ParamètreTypeDescription
name String Le nom de la propriété à modifier
value Object La nouvelle valeur

Retourne void

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

getTopLevelStateField

méthode

public Object getTopLevelStateField(String name)

Renvoie directement une propriété de l'état de premier niveau.

ParamètreTypeDescription
name String Le nom de la propriété à lire

Retourne Object la valeur de la propriété, ou null

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

setTopLevelStateField

méthode

public void setTopLevelStateField(String name, Object value)

Modifie directement une propriété de l'état de premier niveau.

ParamètreTypeDescription
name String Le nom de la propriété à modifier
value Object La nouvelle valeur

Retourne void

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

currentNode

méthode

public Node currentNode()

Renvoie le nœud en cours d'exécution. Pendant un callback de dialogue, renvoie le nœud de l'instruction de dialogue. Pendant un callback de choix, renvoie le nœud de l'instruction de choix.

Retourne Node le nœud courant, ou null si aucun nœud n'est en cours d'exécution

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

Script

classe

Représente le nœud racine de l'AST d'un script Loreline analysé. C'est le résultat d'un appel à Loreline#parse(String) ou à une méthode d'analyse équivalente.

fromJson

méthode

public static Script fromJson(String json)

Reconstruit un Script depuis une chaîne JSON.

ParamètreTypeDescription
json String L'objet JSON (tel que renvoyé par script.toJson())

Retourne Script le Script reconstruit

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

Node

classe

Classe de base de tous les nœuds de l'AST Loreline. Permet de lire le type et l'identifiant unique du nœud, et de l'exporter en JSON.

id

champ

public final long id

L'identifiant unique de ce nœud au sein d'une même hiérarchie de script, sous forme de valeur Int64 brute. Utilisez nodeIdToString() pour une représentation lisible.

Retourne long

JavaScript TypeScript C# Java Haxe

type

champ

public final String type

Le type du nœud sous forme de chaîne (par exemple "Script", "Beat", "Text", "Dialogue").

Retourne String Le type du nœud, sous forme de chaîne

JavaScript TypeScript C# C++ Java PHP Python Lua Haxe

toJson

méthode

public String toJson(boolean pretty)
public String toJson()

Convertit le nœud en une chaîne JSON. Utile pour le débogage ou la sérialisation.

ParamètreTypeDescription
pretty boolean

Retourne String une représentation JSON du nœud, sous forme de chaîne

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

fromJson

méthode

public static Node fromJson(String json)

Reconstruit un Node depuis une chaîne JSON.

ParamètreTypeDescription
json String L'objet JSON (tel que renvoyé par node.toJson())

Retourne Node le Node reconstruit

JavaScript TypeScript C# Java PHP Python Lua Haxe

line

champ

public final int line

Le numéro de ligne dans le code source où ce nœud apparaît (à partir de 1).

Retourne int

column

champ

public final int column

Le numéro de colonne dans le code source où ce nœud apparaît (à partir de 1).

Retourne int

offset

champ

public final int offset

La position absolue du caractère depuis le début du code source.

Retourne int

length

champ

public final int length

La longueur de l'étendue de texte source que représente ce nœud. Une valeur de 0 indique un point plutôt qu'une étendue.

Retourne int

nodeIdToString

méthode

public String nodeIdToString()

Renvoie l'identifiant du nœud sous une forme lisible (par exemple "1.0.0.0").

Retourne String l'identifiant du nœud sous forme de chaîne, avec des points

InterpreterOptions

classe

Options de configuration d'un interpréteur Loreline.

functions

champ

public Map<String, LorelineFunction> functions

Dictionnaire optionnel de fonctions personnalisées, rendues disponibles dans le script.

Retourne Map<String, LorelineFunction>

JavaScript TypeScript C# GDScript C++ Java Haxe

strictAccess

champ

public boolean strictAccess

Active l'accès strict aux variables : une variable non définie lève alors une erreur.

Retourne boolean

JavaScript TypeScript C# GDScript C++ Java Haxe

customCreateFields

champ

public CreateFieldsHandler customCreateFields

Un instanciateur personnalisé pour les objets qui contiennent les propriétés.

Retourne CreateFieldsHandler

JavaScript TypeScript C# Java Haxe

translations

champ

public Object translations

Traductions optionnelles, pour la localisation.

Retourne Object

JavaScript TypeScript C# GDScript C++ Java Haxe

InterpreterOptions

constructeur

public InterpreterOptions()

ChoiceOption

classe

Représente une option de choix présentée au joueur.

text

champ

public final String text

Le texte de l'option de choix.

Retourne String

JavaScript TypeScript C# C++ Java PHP Python Haxe

tags

champ

public final List<TextTag> tags

Les tags éventuellement associés au texte du choix.

Retourne List<TextTag>

JavaScript TypeScript C# C++ Java PHP Python Haxe

enabled

champ

public final boolean enabled

Indique si cette option de choix est actuellement activée.

Retourne boolean

JavaScript TypeScript C# C++ Java PHP Python Haxe

ChoiceOption

constructeur

public ChoiceOption(String text, List<TextTag> tags, boolean enabled)
ParamètreTypeDescription
text String
tags List<TextTag>
enabled boolean

TextTag

classe

Représente un tag dans un contenu textuel, utilisable pour la mise en forme ou à d'autres fins.

closing

champ

public final boolean closing

Indique s'il s'agit d'un tag fermant.

Retourne boolean

JavaScript TypeScript C# C++ Java PHP Python Haxe

value

champ

public final String value

La valeur ou le nom du tag.

Retourne String

JavaScript TypeScript C# C++ Java PHP Python Haxe

offset

champ

public final int offset

La position de ce tag dans le texte.

Retourne int

JavaScript TypeScript C# C++ Java PHP Python Haxe

TextTag

constructeur

public TextTag(boolean closing, String value, int offset)
ParamètreTypeDescription
closing boolean
value String
offset int

DialogueHandler

interface

Type de handler pour l'affichage de texte, avec callback. Appelé quand le script doit afficher du texte au joueur.

handle

méthode

void handle(Interpreter interpreter, String character, String text, List<TextTag> tags, Runnable advance)

Appelé quand un texte de dialogue doit être affiché.

ParamètreTypeDescription
interpreter Interpreter l'instance d'interpréteur
character String le personnage qui parle (null pour un texte de narration)
text String le texte à afficher
tags List<TextTag> les tags éventuels présents dans le texte
advance Runnable fonction à appeler une fois le texte affiché

Retourne void

ChoiceHandler

interface

Type de handler pour la présentation des choix, avec callback. Appelé quand le script doit présenter des choix au joueur.

handle

méthode

void handle(Interpreter interpreter, List<ChoiceOption> options, IntConsumer select)

Appelé quand un choix doit être présenté au joueur.

ParamètreTypeDescription
interpreter Interpreter l'instance d'interpréteur
options List<ChoiceOption> les options de choix disponibles
select IntConsumer fonction à appeler avec l'indice de l'option choisie

Retourne void

FinishHandler

interface

Type de handler appelé quand l'exécution se termine.

handle

méthode

void handle(Interpreter interpreter)

Appelé quand l'exécution du script se termine.

ParamètreTypeDescription
interpreter Interpreter l'instance d'interpréteur

Retourne void

ImportsFileHandler

interface

Handler qui charge les fichiers importés

handle

méthode

void handle(String path, Consumer<String> callback)

Appelé pour charger un fichier importé.

ParamètreTypeDescription
path String le chemin du fichier à importer
callback Consumer<String> fonction à appeler avec le contenu du fichier (ou null si le fichier est introuvable). Doit être appelée exactement une fois, de façon synchrone ou plus tard.

Retourne void

CreateFieldsHandler

interface

create

méthode

Object create(Interpreter interpreter, String type)
ParamètreTypeDescription
interpreter Interpreter
type String

Retourne Object

LorelineFunction

interface

call

méthode

Object call(Interpreter interpreter, Object[] args)

Exécuté quand le script appelle la fonction.

ParamètreTypeDescription
interpreter Interpreter l'instance d'interpréteur
args Object[] les arguments passés à la fonction

Retourne Object le résultat de la fonction

Générée depuis Loreline v0.10.0.