Référence de l'API Java

L'API publique complète du runtime Loreline.

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

Type	Membres
`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 JVM. Donne accès simplement aux fonctionnalités de base pour 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 en crée une instance Script.

Paramètre	Type	Description
`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 du travail avec un script Loreline. L'objet Script renvoyé peut ensuite être passé aux méthodes 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 la lecture d'un script Loreline depuis le début ou depuis un beat précis.

Paramètre	Type	Description
`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 précédemment sauvegardé.

Paramètre	Type	Description
`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 (typiquement issues de `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ètre	Type	Description
`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 une table de traductions qui peut être passée comme options.translations à play() ou 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 un fichier .<locale>.lor pour chacun. Par défaut, cherche les traductions à côté des fichiers source.

Paramètre	Type	Description
`locale`	`String`	Le code de langue (par exemple `"fr"`)
`script`	`Script`	Le script source analysé (il doit avoir été analysé avec un chemin de fichier, ou `filePath` doit être fourni)
`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 concerné par le script (racine + imports transitifs), le fichier de traduction correspondant est recherché en insérant .<locale> avant l'extension (par exemple characters.lor -> characters.fr.lor). Les fichiers de traduction absents sont ignorés silencieusement. La table renvoyée peut être passée comme InterpreterOptions.translations à play() ou 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 format de fichier de traduction alternatif.

Paramètre	Type	Description
`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 silencieusement (compatibilité ascendante).

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 se déclenche avec null en cas d'échec et cette méthode indique ce qui n'a pas fonctionné. En mode synchrone, l'appel lève une exception, et ce champ porte la même erreur pour pouvoir être consulté 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ètre	Type	Description
`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ètre	Type	Description
`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 d'interprétation des scripts Loreline. Enveloppe l'interpréteur runtime généré par Haxe derrière 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ètre	Type	Description
`script`	`Script`	Le script analysé à exécuter
`handleDialogue`	`DialogueHandler`	Fonction à appeler pour afficher un texte de dialogue
`handleChoice`	`ChoiceHandler`	Fonction à appeler pour présenter des choix
`handleFinish`	`FinishHandler`	Fonction à appeler 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ètre	Type	Description
`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 aucun beat n'est trouvé dans le script

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 depuis un état précédemment sauvegardé.

Paramètre	Type	Description
`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 après la restauration de l'état.

Retourne void

JavaScript TypeScript C# Java PHP Python Lua Haxe

`getCharacter`

méthode

public Object getCharacter(String name)

Récupère les champs d'un personnage par son nom.

Paramètre	Type	Description
`name`	`String`	Le nom du personnage à récupérer

Retourne Object les champs du personnage, ou null

JavaScript TypeScript C# Java PHP Python Lua Haxe

`getCharacterField`

méthode

public Object getCharacterField(String character, String field)

Récupère un champ précis d'un personnage.

Paramètre	Type	Description
`character`	`String`	Le nom du personnage
`field`	`String`	Le nom du champ à lire

Retourne Object la valeur du champ, ou null

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

`setCharacterField`

méthode

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

Écrit un champ précis d'un personnage.

Paramètre	Type	Description
`character`	`String`	Le nom du personnage
`field`	`String`	Le nom du champ à écrire
`value`	`Object`	La valeur à écrire

Retourne void

JavaScript TypeScript GDScript C++ Java PHP Python Lua Haxe

`getStateField`

méthode

public Object getStateField(String name)

Lit un champ d'état par son nom, en résolvant depuis la portée courante vers l'extérieur.

Paramètre	Type	Description
`name`	`String`	Le nom du champ à lire

Retourne Object la valeur du champ, ou null

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

`setStateField`

méthode

public void setStateField(String name, Object value)

Écrit un champ d'état par son nom, en résolvant depuis la portée courante vers l'extérieur.

Paramètre	Type	Description
`name`	`String`	Le nom du champ à écrire
`value`	`Object`	La valeur à écrire

Retourne void

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

`getTopLevelStateField`

méthode

public Object getTopLevelStateField(String name)

Lit directement un champ de l'état de premier niveau.

Paramètre	Type	Description
`name`	`String`	Le nom du champ à lire

Retourne Object la valeur du champ, ou null

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

`setTopLevelStateField`

méthode

public void setTopLevelStateField(String name, Object value)

Écrit directement un champ sur l'état de premier niveau.

Paramètre	Type	Description
`name`	`String`	Le nom du champ à écrire
`value`	`Object`	La valeur à écrire

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ètre	Type	Description
`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. Donne accès au type du nœud, à son identifiant unique et à son export 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 Représentation textuelle du type de nœud

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ètre	Type	Description
`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ètre	Type	Description
`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 de nœud lisible (par exemple "1.0.0.0").

Retourne String l'identifiant de nœud sous forme de chaîne pointée

`InterpreterOptions`

classe

Options de configuration d'un interpréteur Loreline.

`functions`

champ

public Map<String, LorelineFunction> functions

Table optionnelle de fonctions personnalisées à rendre disponibles au script.

Retourne Map<String, LorelineFunction>

JavaScript TypeScript C# GDScript C++ Java Haxe

`strictAccess`

champ

public boolean strictAccess

Indique s'il faut activer l'accès strict aux variables (lève une erreur sur une variable non définie).

Retourne boolean

JavaScript TypeScript C# GDScript C++ Java Haxe

`customCreateFields`

champ

public CreateFieldsHandler customCreateFields

Un instanciateur personnalisé pour créer les objets de champs.

Retourne CreateFieldsHandler

JavaScript TypeScript C# Java Haxe

`translations`

champ

public Object translations

Table de traductions optionnelle 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 à l'utilisateur.

`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ètre	Type	Description
`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 dans le texte où ce tag apparaît.

Retourne int

JavaScript TypeScript C# C++ Java PHP Python Haxe

`TextTag`

constructeur

public TextTag(boolean closing, String value, int offset)

Paramètre	Type	Description
`closing`	`boolean`
`value`	`String`
`offset`	`int`

`DialogueHandler`

interface

Type de handler pour la sortie de texte avec callback. Appelé quand le script doit afficher du texte à l'utilisateur.

`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ètre	Type	Description
`interpreter`	`Interpreter`	l'instance d'interpréteur
`character`	`String`	le personnage qui parle (null pour un texte de narration)
`text`	`String`	le contenu textuel à 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 à l'utilisateur.

`handle`

méthode

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

Appelé quand des choix doivent être présentés.

Paramètre	Type	Description
`interpreter`	`Interpreter`	l'instance d'interpréteur
`options`	`List<ChoiceOption>`	les options de choix disponibles
`select`	`IntConsumer`	fonction à appeler avec l'indice du choix sélectionné

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ètre	Type	Description
`interpreter`	`Interpreter`	l'instance d'interpréteur

Retourne void

`ImportsFileHandler`

interface

Fonction de handler pour le chargement des imports de fichiers

`handle`

méthode

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

Appelé pour résoudre un import de fichier.

Paramètre	Type	Description
`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ètre	Type	Description
`interpreter`	`Interpreter`
`type`	`String`

Retourne Object

`LorelineFunction`

interface

`call`

méthode

Object call(Interpreter interpreter, Object[] args)

Appelé quand la fonction est invoquée depuis le script.

Paramètre	Type	Description
`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.

Voir aussi

Java →

Intégrer Loreline dans un projet Java, Kotlin ou JVM.

Référence de l'API →

Toutes les classes et méthodes publiques du runtime Loreline, pour chaque langage cible.

Référence de l'API Java

Vue d'ensemble

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`

`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`