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
Loreline
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
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è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 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
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è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
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è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 (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
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 les traductions, à passer dans options.translations de play() ou de resume().
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
loadLocale
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ètre | Type | Description |
|---|---|---|
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
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è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 sans erreur, pour rester compatible avec les versions futures.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
lastError
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
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
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
Interpreter
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
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 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
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 le script ne contient aucun beat
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
save
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
public void restore(String savedData)
Restaure l'état de l'interpréteur à partir d'une sauvegarde.
| 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
public void resume()
Reprend l'exécution une fois l'état restauré.
Retourne
void
JavaScript TypeScript C# Java PHP Python Lua Haxe
getCharacter
public Object getCharacter(String name)
Renvoie les propriétés d'un personnage par son nom.
| Paramètre | Type | Description |
|---|---|---|
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
public Object getCharacterField(String character, String field)
Renvoie une propriété précise d'un personnage.
| Paramètre | Type | Description |
|---|---|---|
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
public void setCharacterField(String character, String field, Object value)
Modifie une propriété d'un personnage.
| Paramètre | Type | Description |
|---|---|---|
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
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ètre | Type | Description |
|---|---|---|
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
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ètre | Type | Description |
|---|---|---|
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
public Object getTopLevelStateField(String name)
Renvoie directement une propriété de l'état de premier niveau.
| Paramètre | Type | Description |
|---|---|---|
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
public void setTopLevelStateField(String name, Object value)
Modifie directement une propriété de l'état de premier niveau.
| Paramètre | Type | Description |
|---|---|---|
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
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
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
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 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
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
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
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
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
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
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
public final int offset
La position absolue du caractère depuis le début du code source.
Retourne
int
length
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
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
Options de configuration d'un interpréteur Loreline.
functions
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
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
public CreateFieldsHandler customCreateFields
Un instanciateur personnalisé pour les objets qui contiennent les propriétés.
Retourne
CreateFieldsHandler
JavaScript TypeScript C# Java Haxe
translations
public Object translations
Traductions optionnelles, pour la localisation.
Retourne
Object
JavaScript TypeScript C# GDScript C++ Java Haxe
InterpreterOptions
public InterpreterOptions()
ChoiceOption
Représente une option de choix présentée au joueur.
text
public final String text
Le texte de l'option de choix.
Retourne
String
JavaScript TypeScript C# C++ Java PHP Python Haxe
tags
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
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
public ChoiceOption(String text, List<TextTag> tags, boolean enabled)
| Paramètre | Type | Description |
|---|---|---|
text |
String |
|
tags |
List<TextTag> |
|
enabled |
boolean |
TextTag
Représente un tag dans un contenu textuel, utilisable pour la mise en forme ou à d'autres fins.
closing
public final boolean closing
Indique s'il s'agit d'un tag fermant.
Retourne
boolean
JavaScript TypeScript C# C++ Java PHP Python Haxe
value
public final String value
La valeur ou le nom du tag.
Retourne
String
JavaScript TypeScript C# C++ Java PHP Python Haxe
offset
public final int offset
La position de ce tag dans le texte.
Retourne
int
JavaScript TypeScript C# C++ Java PHP Python Haxe
TextTag
public TextTag(boolean closing, String value, int offset)
| Paramètre | Type | Description |
|---|---|---|
closing |
boolean |
|
value |
String |
|
offset |
int |
DialogueHandler
Type de handler pour l'affichage de texte, avec callback. Appelé quand le script doit afficher du texte au joueur.
handle
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 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
Type de handler pour la présentation des choix, avec callback. Appelé quand le script doit présenter des choix au joueur.
handle
void handle(Interpreter interpreter, List<ChoiceOption> options, IntConsumer select)
Appelé quand un choix doit être présenté au joueur.
| 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 de l'option choisie |
Retourne
void
FinishHandler
Type de handler appelé quand l'exécution se termine.
handle
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
Handler qui charge les fichiers importés
handle
void handle(String path, Consumer<String> callback)
Appelé pour charger un fichier importé.
| 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
create
Object create(Interpreter interpreter, String type)
| Paramètre | Type | Description |
|---|---|---|
interpreter |
Interpreter |
|
type |
String |
Retourne
Object
LorelineFunction
call
Object call(Interpreter interpreter, Object[] args)
Exécuté quand le script appelle la fonction.
| 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.