Référence de l'API JavaScript
L'API publique complète du runtime Loreline pour chaque langage supporté.
Vous débutez avec Loreline en JavaScript ? 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. Elle donne un accès simple aux fonctions de base pour analyser et exécuter des scripts Loreline.
parse
parse(input, filePath, handleFile, callback)
Analyse le texte fourni et en crée une instance Script exécutable.
| Paramètre | Type | Description |
|---|---|---|
input |
string |
Le contenu du script Loreline sous forme de chaîne (format .lor)
|
filePath |
string |
Chemin optionnel du fichier analysé. S'il est fourni, handleFile doit l'être aussi.
optionnel
|
handleFile |
ImportsFileHandler |
Handler optionnel qui lit les fichiers importés. S'il est asynchrone, parse() renvoie null : utilisez alors l'argument callback.
optionnel
|
callback |
(script: Script) => void |
S'il est fourni, il est appelé avec le script obtenu. Utile surtout quand les imports sont lus de façon asynchrone. optionnel |
Retourne
Script | null
Le script analysé, une instance Script de l'AST (si le chargement est synchrone)
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
play(script, handleDialogue, handleChoice, handleFinish, beatName, 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 |
beatName |
string |
Nom optionnel d'un beat précis par lequel démarrer (par défaut, le premier beat) optionnel |
options |
InterpreterOptions |
Options supplémentaires optionnel |
Retourne
Interpreter
L'instance d'interpréteur qui exécute le script
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
resume(script, handleDialogue, handleChoice, handleFinish, saveData, beatName, 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 |
SaveData |
Les données de sauvegarde (en général, celles renvoyées par interpreter.save())
|
beatName |
string |
Nom optionnel d'un beat où reprendre, à la place du point sauvegardé optionnel |
options |
InterpreterOptions |
Options de configuration de l'interpréteur (optionnelles) optionnel |
Retourne
Interpreter
L'instance d'interpréteur qui exécute le script
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
extractTranslations(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
Translations
Les traductions, à passer dans 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
loadLocale(locale, script, filePath, handleFile, callback)
Charge les traductions d'une langue donnée, en parcourant tout l'arbre d'imports du script.
| 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)
|
filePath |
string | null |
Emplacement optionnel où chercher les fichiers de traduction (par défaut, script.filePath). Peut être un chemin de fichier .lor/.lor.txt ou un dossier.
optionnel
|
handleFile |
ImportsFileHandler |
Handler de fichiers utilisé pour lire les fichiers de traduction optionnel |
callback |
(translations: Translations) => void |
Appelé avec les traductions fusionnées. Requis si handleFile est asynchrone.
optionnel
|
Retourne
Translations | null
Les traductions fusionnées (renvoyées directement si handleFile est synchrone)
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
translationFormat(name, 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 :
"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 de futurs formats.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
lastError
lastError()
Renvoie l'erreur du dernier appel échoué à parse() ou loadLocale(), ou null en cas de succès.
Retourne
Error | null
En mode asynchrone (avec callback), le callback reçoit 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 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.
print
print(script, indent, 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())
|
indent |
string |
La chaîne d'indentation à utiliser (par défaut, deux espaces) optionnel |
newline |
string |
La chaîne de saut de ligne à utiliser (par défaut "\n") optionnel |
Retourne
string
Le code source régénéré, sous forme de chaîne
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
Interpreter
Exécute un script analysé : garde l'état de l'histoire, décide de la suite et rend la main à votre code à chaque réplique et à chaque choix.
constructor
constructor(script, handleDialogue, handleChoice, handleFinish, 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 |
options |
InterpreterOptions |
Options supplémentaires optionnel |
JavaScript TypeScript C# Java Python Haxe
start
start(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. optionnel |
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
save()
Sauvegarde l'état courant de l'interpréteur. Cela comprend toutes les variables d'état, l'état des personnages et la pile d'exécution, ce qui permet de reprendre l'exécution plus tard exactement au même point.
Retourne
SaveData
Un objet SaveData contenant l'état sérialisé
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
restore
restore(saveData)
Restaure l'état de l'interpréteur à partir d'un objet SaveData, pour reprendre l'exécution là où elle avait été sauvegardée.
| Paramètre | Type | Description |
|---|---|---|
saveData |
SaveData |
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
resume()
Reprend l'exécution après la restauration de l'état. À appeler après restore() pour poursuivre l'exécution.
Retourne
void
getCharacter
getCharacter(name)
Renvoie un personnage par son nom.
| Paramètre | Type | Description |
|---|---|---|
name |
string |
Le nom du personnage à récupérer |
Retourne
any
Les propriétés du personnage, ou null si le personnage n'existe pas
getCharacterField
getCharacterField(character, name)
Renvoie une propriété précise d'un personnage.
| Paramètre | Type | Description |
|---|---|---|
character |
string |
Le nom du personnage |
name |
string |
Le nom de la propriété à lire |
Retourne
any
La valeur de la propriété, ou null si le personnage ou la propriété n'existe pas
Les conteneurs (dictionnaires et tableaux) sont de simples objets et tableaux JS : les accesseurs de propriétés et les fonctions personnalisées échangent des valeurs JS ordinaires dans les deux sens.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
setCharacterField
setCharacterField(character, name, value)
Modifie une propriété d'un personnage.
| Paramètre | Type | Description |
|---|---|---|
character |
string |
Le nom du personnage |
name |
string |
Le nom de la propriété à modifier |
value |
any |
La nouvelle valeur |
Retourne
void
getStateField
getStateField(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
any
La valeur de la propriété, ou null si la propriété est introuvable
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
setStateField
setStateField(name, 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 |
any |
La nouvelle valeur |
Retourne
void
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
getTopLevelStateField
getTopLevelStateField(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
any
La valeur de la propriété, ou null si la propriété est introuvable
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
setTopLevelStateField
setTopLevelStateField(name, 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 |
any |
La nouvelle valeur |
Retourne
void
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
currentNode
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 | null
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
currentNodeFilePath
currentNodeFilePath(rootPath)
Renvoie le chemin du fichier contenant le nœud courant. Résout les chaînes d'imports relativement au chemin racine fourni.
| Paramètre | Type | Description |
|---|---|---|
rootPath |
string |
Le chemin du fichier du script racine |
Retourne
string
Le chemin du fichier contenant le nœud courant, ou rootPath si ce nœud est dans le fichier racine
JavaScript TypeScript Haxe
Script
Représente le nœud racine de l'AST d'un script Loreline.
body
body
Tableau des déclarations de premier niveau du script.
Retourne
Array<Node>
JavaScript TypeScript Haxe
filePath
filePath
Le chemin du fichier d'origine de ce script. Null si le script a été analysé sans chemin de fichier.
Retourne
string | null
JavaScript TypeScript Haxe
fromJson
fromJson(json)
Reconstruit un Script depuis sa représentation JSON.
| Paramètre | Type | Description |
|---|---|---|
json |
any |
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. Contient les informations de position et la conversion JSON de base.
id
id
Un identifiant unique pour ce nœud au sein de l'AST, qui permet de le distinguer des autres nœuds du script.
Retourne
NodeId
JavaScript TypeScript C# Java Haxe
pos
pos
Position de ce nœud dans le code source.
Retourne
Position
JavaScript TypeScript Haxe
type
type()
Renvoie le type de ce nœud.
Retourne
string
Le type du nœud, sous forme de chaîne
toJson
toJson()
Convertit le nœud en représentation JSON.
Retourne
any
Objet contenant le type et la position du nœud
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
fromJson
fromJson(json)
Reconstruit un Node depuis sa représentation JSON.
| Paramètre | Type | Description |
|---|---|---|
json |
any |
L'objet JSON (tel que renvoyé par node.toJson())
|
Retourne
Node
Le Node reconstruit
each
each(handleNode)
Parcourt tous les nœuds enfants de ce nœud.
| Paramètre | Type | Description |
|---|---|---|
handleNode |
(node: Node, parent: Node) => void |
Fonction appelée pour chaque nœud enfant |
Retourne
void
JavaScript TypeScript Haxe
InterpreterOptions
Options de configuration du comportement de l'interpréteur Loreline
functions
functions
Dictionnaire optionnel de fonctions supplémentaires que le script pourra appeler
Retourne
FunctionsMap
strictAccess
strictAccess
Indique si l'accès est strict ou non. Si true, lire ou écrire une variable non définie lève une erreur.
Retourne
boolean
customCreateFields
customCreateFields()
Un instanciateur personnalisé pour les objets qui contiennent les propriétés.
Retourne
(interpreter: Interpreter, type: string, node: Node) => any
JavaScript TypeScript C# Java Haxe
translations
translations
Traductions optionnelles pour la localisation. Construites depuis un fichier de traduction analysé avec Loreline.extractTranslations().
Retourne
Translations
ChoiceOption
Représente une option de choix présentée au joueur.
text
text
Le texte de l'option de choix.
Retourne
string
tags
tags
Les tags éventuellement associés au texte du choix.
Retourne
Array<TextTag>
enabled
enabled
Indique si cette option de choix est actuellement activée.
Retourne
boolean
TextTag
Représente un tag dans un contenu textuel, utilisable pour la mise en forme ou à d'autres fins.
closing
closing
Indique s'il s'agit d'un tag fermant.
Retourne
boolean
value
value
La valeur ou le nom du tag.
Retourne
string
offset
offset
La position de ce tag dans le texte.
Retourne
number
DialogueHandler
Type de handler pour l'affichage de texte, avec callback. Appelé quand le script doit afficher du texte au joueur.
ChoiceHandler
Type de handler pour la présentation des choix, avec callback. Appelé quand le script doit présenter des choix au joueur.
FinishHandler
Type de handler appelé quand l'exécution se termine.
ImportsFileHandler
Handler qui charge les fichiers importés
ImportsErrorHandler
Handler appelé en cas d'erreur d'import
FunctionsMap
Dictionnaire qui associe des noms de fonctions à leur implémentation
Translations
Type opaque qui contient les traductions. Obtenu via Loreline.extractTranslations() et passé à InterpreterOptions.translations.
SaveData
Type opaque pour les données de sauvegarde.
Tokens
Type Tokens
Error
Représente une erreur dans le système Loreline.
message
message
Le message d'erreur qui décrit le problème.
Retourne
string
JavaScript TypeScript
pos
pos
La position de l'erreur dans le code source.
Retourne
Position
JavaScript TypeScript
stack
stack
La pile d'appels de cette erreur
Retourne
Array<any>
JavaScript TypeScript
toString
toString()
Convertit l'erreur en chaîne lisible.
Retourne
string
Message d'erreur formaté, avec la position
JavaScript TypeScript
Position
Représente une position dans le code source, avec le numéro de ligne, la colonne et la position absolue. Utilisée partout dans le compilateur pour situer précisément les tokens, les nœuds et les messages d'erreur.
line
line
Le numéro de ligne dans le code source, à partir de 1.
Retourne
number
JavaScript TypeScript
column
column
Le numéro de colonne dans le code source, à partir de 1. Représente la position du caractère dans la ligne courante.
Retourne
number
JavaScript TypeScript
offset
offset
La position absolue du caractère depuis le début du code source. Sert aux calculs précis de position et d'étendue.
Retourne
number
JavaScript TypeScript
length
length
La longueur de l'étendue de texte source que représente cette position. Une valeur de 0 indique un point plutôt qu'une étendue.
Retourne
number
JavaScript TypeScript
toString
toString()
Convertit la position en chaîne lisible.
Retourne
string
Chaîne de position formatée
JavaScript TypeScript
NodeId
Représente un identifiant unique de nœud au sein de l'AST. Utilise un système d'identifiants structuré en section, branche, bloc et nœud.
toString
toString()
Convertit le NodeId en représentation textuelle.
Retourne
string
Chaîne au format "section.branch.block.node"
JavaScript TypeScript C# Haxe
toInt64
toInt64()
Convertit le NodeId en Int64.
Retourne
Int64
La valeur Int64 de ce NodeId
JavaScript TypeScript Haxe
Int64
Un objet qui stocke un Int64 sous forme de deux nombres, high et low.
high
high
Partie haute de l'Int64
Retourne
number
JavaScript TypeScript
low
low
Partie basse de l'Int64
Retourne
number
JavaScript TypeScript
Fields
Interface de base des objets qui contiennent des valeurs Loreline. Elle permet de relier les propriétés des objets Loreline à des objets propres au jeu.
lorelineCreate
lorelineCreate(interpreter)
Appelé quand l'objet a été créé depuis un interpréteur
| Paramètre | Type | Description |
|---|---|---|
interpreter |
Interpreter |
Retourne
void
JavaScript TypeScript C# Haxe
lorelineGet
lorelineGet(interpreter, key)
Renvoie la valeur associée à la clé de propriété donnée
| Paramètre | Type | Description |
|---|---|---|
interpreter |
Interpreter |
|
key |
string |
Retourne
any
JavaScript TypeScript C# Haxe
lorelineSet
lorelineSet(interpreter, key, value)
Modifie la valeur associée à la clé de propriété donnée
| Paramètre | Type | Description |
|---|---|---|
interpreter |
Interpreter |
|
key |
string |
|
value |
any |
Retourne
void
JavaScript TypeScript C# Haxe
lorelineExists
lorelineExists(interpreter, key)
Vérifie si une valeur existe pour la clé donnée
| Paramètre | Type | Description |
|---|---|---|
interpreter |
Interpreter |
|
key |
string |
Retourne
boolean
JavaScript TypeScript C# Haxe
lorelineFields
lorelineFields(interpreter)
Renvoie toutes les propriétés de cet objet
| Paramètre | Type | Description |
|---|---|---|
interpreter |
Interpreter |
Retourne
string[]
JavaScript TypeScript C# Haxe
Générée depuis Loreline v0.10.0.