Référence de l'API C#
L'API publique complète du runtime Loreline.
Vous débutez avec Loreline en C# ? Commencez par le guide d'intégration. Cette page est la référence exhaustive.
Vue d'ensemble
Engine
L'API publique principale du runtime Loreline. Donne accès simplement aux fonctionnalités de base pour analyser et exécuter des scripts Loreline.
La classe statique d'entrée est
Loreline.Engine: tout ce que les autres cibles placent surLorelineest ici une méthode statique deEngine.
Parse
public static Script Parse(string input, string filePath = null, ImportsFileHandler handleFile = null, ParseCallback callback = null)
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 est requis également.
optionnel: null
|
handleFile |
ImportsFileHandler |
Handler de fichiers optionnel pour lire les imports. Si ce handler est asynchrone, parse() renverra null et l'argument callback devra être utilisé
optionnel: null
|
callback |
ParseCallback |
S'il est fourni, sera appelé avec le script résultant en argument. Utile surtout quand les imports de fichiers sont lus de façon asynchrone
optionnel: null
|
Retourne
Script
Le script analysé, sous forme d'instance AST Script (s'il a été chargé de façon synchrone)
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
public static Interpreter Play(Script script, Interpreter.DialogueHandler handleDialogue, Interpreter.ChoiceHandler handleChoice, Interpreter.FinishHandler handleFinish, string beatName = null)public static Interpreter Play(Script script, Interpreter.DialogueHandler handleDialogue, Interpreter.ChoiceHandler handleChoice, Interpreter.FinishHandler handleFinish, Interpreter.InterpreterOptions options)public static Interpreter Play(Script script, Interpreter.DialogueHandler handleDialogue, Interpreter.ChoiceHandler handleChoice, Interpreter.FinishHandler handleFinish, string beatName, Interpreter.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 |
Interpreter.DialogueHandler |
Fonction appelée quand un texte de dialogue doit être affiché |
handleChoice |
Interpreter.ChoiceHandler |
Fonction appelée quand le joueur doit faire un choix |
handleFinish |
Interpreter.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: null
|
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
public static Interpreter Resume(Script script, Interpreter.DialogueHandler handleDialogue, Interpreter.ChoiceHandler handleChoice, Interpreter.FinishHandler handleFinish, string saveData, string beatName = null)public static Interpreter Resume(Script script, Interpreter.DialogueHandler handleDialogue, Interpreter.ChoiceHandler handleChoice, Interpreter.FinishHandler handleFinish, string saveData, Interpreter.InterpreterOptions options)public static Interpreter Resume(Script script, Interpreter.DialogueHandler handleDialogue, Interpreter.ChoiceHandler handleChoice, Interpreter.FinishHandler handleFinish, string saveData, string beatName, Interpreter.InterpreterOptions options)
Reprend un script Loreline précédemment sauvegardé depuis son état enregistré.
| Paramètre | Type | Description |
|---|---|---|
script |
Script |
Le script analysé (résultat de parse())
|
handleDialogue |
Interpreter.DialogueHandler |
Fonction appelée quand un texte de dialogue doit être affiché |
handleChoice |
Interpreter.ChoiceHandler |
Fonction appelée quand le joueur doit faire un choix |
handleFinish |
Interpreter.FinishHandler |
Fonction appelée quand l'exécution du script se termine |
saveData |
string |
Les données de sauvegarde (typiquement issues de interpreter.save())
|
beatName |
string |
Nom de beat optionnel pour choisir où reprendre
optionnel: null
|
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
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 Translations
À partir d'un fichier de traduction analysé avec Parse, renvoie une table de traductions qui peut être passée comme Translations à Play() ou Resume().
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
LoadLocale
public static object LoadLocale(string locale, Script script, string filePath = null, ImportsFileHandler handleFile = null)
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é (il doit avoir été analysé avec un chemin de fichier, ou filePath doit être fourni)
|
filePath |
string |
Emplacement de remplacement 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: null
|
handleFile |
ImportsFileHandler |
Handler de fichiers utilisé pour lire les fichiers de traduction
optionnel: null
|
Retourne
object
Un objet de traductions à passer comme Translations
Pour chaque fichier concerné par le script (racine + imports transitifs), recherche le fichier de traduction correspondant en insérant .<locale> avant l'extension (par exemple characters.lor -> characters.fr.lor). Les fichiers de traduction absents sont ignorés silencieusement. Passez le résultat à Translations.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
TranslationFormat
public static void TranslationFormat(string name, bool 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 |
bool |
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" (.po), "xliff" (.xliff, .xlf), "csv" (.csv, .tsv). Les noms inconnus sont acceptés silencieusement, par compatibilité ascendante.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
LastError
public static Runtime.Error LastError()
Renvoie l'erreur du dernier appel échoué à Parse ou LoadLocale, ou null en cas de succès.
Retourne
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.
Print
public static string Print(Script script, string indent = " ", string newline = "\n")
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: "\n"
|
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 (par exemple Update dans Unity). Le premier appel fait passer wait() du Thread.Sleep bloquant à un mode différé non bloquant. Pour éviter le cas limite de la première frame, appelez Engine.Update(0) une fois avant Engine.Play().
| Paramètre | Type | Description |
|---|---|---|
delta |
double |
Temps écoulé depuis la frame précédente, en secondes |
Retourne
void
Interpreter
Classe principale d'interprétation des scripts Loreline. Cette classe exécute un script Loreline analysé, gère l'état d'exécution et dialogue avec l'application hôte via des fonctions de handler.
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 à 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 |
Start
public void Start(string beatName = null)
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: null
|
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
public string 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
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 depuis un état précédemment sauvegardé. Cela permet de reprendre l'exécution 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
public void Resume()
Reprend l'exécution après la restauration de l'état. À appeler après Restore() pour poursuivre l'exécution.
Retourne
void
GetCharacter
public object GetCharacter(string name)
Récupère 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 si le personnage n'existe pas
GetCharacterField
public object GetCharacterField(string character, string name)
Récupère un champ précis d'un personnage.
| Paramètre | Type | Description |
|---|---|---|
character |
string |
Le nom du personnage |
name |
string |
Le nom du champ à lire |
Retourne
object
La valeur du champ, ou null si le personnage ou le champ n'existe pas
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
GetStateField
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 si elle est introuvable
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
SetStateField
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
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 si elle est introuvable
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
SetTopLevelStateField
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
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.
FromJson
public static new 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
Script
public Script(Runtime.Script runtimeScript) : base(runtimeScript)
Crée une nouvelle instance de Script à partir du script runtime fourni.
| Paramètre | Type | Description |
|---|---|---|
runtimeScript |
Runtime.Script |
Le script runtime analysé à envelopper |
Node
Représente un nœud dans un AST Loreline.
Id
public readonly NodeId Id
L'identifiant de ce nœud (unique au sein d'une même hiérarchie de script)
Retourne
NodeId
Type
public readonly string Type
Le type du nœud, sous forme de chaîne
Retourne
string
Représentation textuelle du type de nœud
ToJson
public string ToJson(bool pretty = false)
Convertit le nœud en représentation JSON. Utile pour le débogage ou la sérialisation.
| Paramètre | Type | Description |
|---|---|---|
pretty |
bool |
optionnel: false
|
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
Line
public readonly int Line
Le numéro de ligne dans le code source où ce nœud apparaît (à partir de 1).
Retourne
int
Column
public readonly int Column
Le numéro de colonne dans le code source où ce nœud apparaît (à partir de 1).
Retourne
int
Offset
public readonly int Offset
La position absolue du caractère depuis le début du code source.
Retourne
int
Length
public readonly 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
Node
public Node(Runtime.Node runtimeNode)
| Paramètre | Type | Description |
|---|---|---|
runtimeNode |
Runtime.Node |
Interpreter.InterpreterOptions
Options de configuration du comportement de l'interpréteur Loreline
Functions
public Dictionary<string, Function> Functions
Table optionnelle de fonctions supplémentaires à rendre disponibles au script
Retourne
Dictionary<string, Function>
StrictAccess
public bool 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
bool
CustomCreateFields
public CreateFields CustomCreateFields
Un instanciateur personnalisé pour créer les objets de champs.
Retourne
CreateFields
Translations
public object Translations
Table de traductions optionnelle pour la localisation. Construite depuis un fichier de traduction analysé avec Engine.ExtractTranslations().
Retourne
object
Default
public static InterpreterOptions Default()
Récupère les options d'interpréteur par défaut
Retourne
InterpreterOptions
Interpreter.ChoiceOption
Représente une option de choix présentée à l'utilisateur.
Text
public string Text
Le texte de l'option de choix.
Retourne
string
Tags
public TextTag[] Tags
Les tags éventuellement associés au texte du choix.
Retourne
TextTag[]
Enabled
public bool Enabled
Indique si cette option de choix est actuellement activée.
Retourne
bool
Interpreter.TextTag
Représente un tag dans un contenu textuel, utilisable pour la mise en forme ou à d'autres fins.
Closing
public bool Closing
Indique s'il s'agit d'un tag fermant.
Retourne
bool
Value
public string Value
La valeur ou le nom du tag.
Retourne
string
Offset
public int Offset
La position dans le texte où ce tag apparaît.
Retourne
int
Interpreter.DialogueHandler
public delegate void DialogueHandler(Dialogue dialogue)Type de handler pour la sortie de texte avec callback. Appelé quand le script doit afficher du texte à l'utilisateur.
Contrairement aux autres cibles, les handlers C# reçoivent une seule structure plutôt que des paramètres positionnels :
void OnDialogue(Interpreter.Dialogue dialogue), où l'on litdialogue.Character,dialogue.Textet où l'on appelledialogue.Callback().
Interpreter.ChoiceHandler
public delegate void ChoiceHandler(Choice choice)Type de handler pour la présentation des choix avec callback. Appelé quand le script doit présenter des choix à l'utilisateur.
Interpreter.FinishHandler
public delegate void FinishHandler(Finish finish)Type de handler appelé quand l'exécution se termine.
Engine.ImportsFileHandler
public delegate void ImportsFileHandler(string path, ImportsFileCallback callback)Fonction de handler pour le chargement des imports de fichiers
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
public override string ToString()
Convertit le NodeId en représentation textuelle.
Retourne
string
Chaîne au format "section.branch.block.node"
operator NodeId
public NodeId(long value)public static implicit operator NodeId(long value)
| Paramètre | Type | Description |
|---|---|---|
value |
long |
Retourne
NodeId
operator long
public static explicit operator long(NodeId id)
| Paramètre | Type | Description |
|---|---|---|
id |
NodeId |
Retourne
long
operator string
public static explicit operator string(NodeId id)
| Paramètre | Type | Description |
|---|---|---|
id |
NodeId |
Retourne
string
IFields
Interface de base pour contenir des valeurs loreline. Cette interface permet de relier les champs d'objets loreline à des objets propres au jeu.
LorelineCreate
void LorelineCreate(Interpreter interpreter)
Appelé quand l'objet a été créé depuis un interpréteur
| Paramètre | Type | Description |
|---|---|---|
interpreter |
Interpreter |
Retourne
void
LorelineGet
object LorelineGet(Interpreter interpreter, string key)
Lit la valeur associée à la clé de champ donnée
| Paramètre | Type | Description |
|---|---|---|
interpreter |
Interpreter |
|
key |
string |
Retourne
object
La valeur associée à la clé
LorelineSet
void LorelineSet(Interpreter interpreter, string key, object value)
Écrit la valeur associée à la clé de champ donnée
| Paramètre | Type | Description |
|---|---|---|
interpreter |
Interpreter |
|
key |
string |
|
value |
object |
Retourne
void
LorelineExists
bool LorelineExists(Interpreter interpreter, string key)
Vérifie si une valeur existe pour la clé donnée
| Paramètre | Type | Description |
|---|---|---|
interpreter |
Interpreter |
|
key |
string |
Retourne
bool
True si la clé existe, false sinon
LorelineFields
string[] LorelineFields(Interpreter interpreter)
Récupère tous les champs de cet objet
| Paramètre | Type | Description |
|---|---|---|
interpreter |
Interpreter |
Retourne
string[]
Un tableau de clés de champs
LorelineRemove
bool LorelineRemove(Interpreter interpreter, string key)
Supprime le champ associé à la clé donnée
| Paramètre | Type | Description |
|---|---|---|
interpreter |
Interpreter |
L'instance d'interpréteur |
key |
string |
La clé du champ à supprimer |
Retourne
bool
True si la clé a été trouvée et supprimée, false sinon
C# Haxe
Engine.ImportsFileCallback
public delegate void ImportsFileCallback(string data)Transmet le contenu d'un fichier importé à l'analyseur.
Engine.ParseCallback
public delegate void ParseCallback(Script script)Reçoit le script analysé quand les imports ont été résolus de façon asynchrone.
Se déclenche avec null si l'analyse a échoué ; Engine.LastError() indique alors pourquoi.
Interpreter.Function
public delegate object Function(Interpreter interpreter, object[] args)Type de delegate pour les fonctions appelables depuis le script.
Interpreter.DialogueCallback
public delegate void DialogueCallback()Type de callback pour la continuation d'un dialogue.
Interpreter.Dialogue
Contient les informations d'un dialogue à afficher à l'utilisateur.
Interpreter
public Interpreter Interpreter
L'instance d'interpréteur.
Retourne
Interpreter
Character
public string Character
Le personnage qui parle (null pour un texte de narration).
Retourne
string
Text
public string Text
Le contenu textuel à afficher.
Retourne
string
Tags
public TextTag[] Tags
Les tags éventuels présents dans le texte.
Retourne
TextTag[]
Callback
public DialogueCallback Callback
Fonction à appeler une fois le texte affiché.
Retourne
DialogueCallback
Interpreter.ChoiceCallback
public delegate void ChoiceCallback(int index)Type de callback pour la sélection d'un choix.
Interpreter.Choice
Contient les informations des choix à présenter à l'utilisateur.
Interpreter
public Interpreter Interpreter
L'instance d'interpréteur.
Retourne
Interpreter
Options
public ChoiceOption[] Options
Les options de choix disponibles.
Retourne
ChoiceOption[]
Callback
public ChoiceCallback Callback
Fonction à appeler avec l'indice du choix sélectionné.
Retourne
ChoiceCallback
Interpreter.CreateFields
public delegate object CreateFields(Interpreter interpreter, string type, Node node)Un instanciateur personnalisé pour créer les objets de champs.
Interpreter.Finish
Contient les informations de fin d'exécution du script.
Interpreter
public Interpreter Interpreter
L'instance d'interpréteur.
Retourne
Interpreter
Générée depuis Loreline v0.10.0.