Utiliser Loreline avec C#

Loreline fournit une bibliothèque C# compatible avec tout environnement C# prenant en charge .NET Standard 2.1 (y compris Unity). Ce guide montre comment configurer un projet, charger un script .lor, et gérer les dialogues, les choix et la fin du script.

Configuration pour les projets .NET

Téléchargez loreline-csharp.zip depuis la page des releases GitHub. L'archive contient :

• Loreline.dll : bibliothèque pré-compilée ciblant netstandard2.1 (compatible avec .NET Core 3.0+, .NET 5+ et .NET Framework 4.7+)
• Loreline.sln, Loreline.csproj et le code source C# complet

Vous pouvez soit référencer la DLL directement dans votre .csproj :

<Reference Include="Loreline">
  <HintPath>chemin/vers/Loreline.dll</HintPath>
</Reference>

Ou ajouter le Loreline.csproj inclus à votre solution si vous préférez compiler depuis les sources :

<ProjectReference Include="chemin/vers/Loreline.csproj" />

Configuration pour Unity

Téléchargez loreline-unity.zip depuis la page des releases GitHub. L'archive contient un projet Unity complet avec le plugin Loreline, utilisable comme point de départ ou comme référence pour intégrer Loreline dans votre propre projet.

Pour ajouter Loreline à un projet Unity existant :

1. Depuis l'archive, copiez le dossier Assets/Plugins/Loreline/ dans Assets/Plugins/Loreline/ de votre propre projet Unity
2. Placez vos fichiers .lor dans Assets/Resources/ avec l'extension .lor.txt (Unity nécessite le suffixe .txt pour le chargement via TextAsset)

Charger un script

Utilisez Engine.Parse() pour analyser une chaîne .lor. Le troisième argument est un gestionnaire de fichiers pour résoudre les instructions import :

using Loreline;
using System.IO;

string content = File.ReadAllText("story/CoffeeShop.lor");

void HandleFile(string path, Engine.ImportsFileCallback callback)
{
    string text = File.ReadAllText("story/" + path);
    callback(text);
}

Script script = Engine.Parse(content, "CoffeeShop.lor", HandleFile);
Engine.Play(script, OnDialogue, OnChoice, OnFinish);

Avec Unity, utilisez Resources.Load<TextAsset>() au lieu des E/S fichier :

using Loreline;
using UnityEngine;

TextAsset mainAsset = Resources.Load<TextAsset>("CoffeeShop.lor");

void HandleFile(string path, Engine.ImportsFileCallback callback)
{
    string name = Path.GetFileNameWithoutExtension(path) + ".lor";
    TextAsset asset = Resources.Load<TextAsset>(name);
    callback(asset != null ? asset.text : null);
}

Script script = Engine.Parse(mainAsset.text, "CoffeeShop.lor", HandleFile);
Engine.Play(script, OnDialogue, OnChoice, OnFinish);

Si votre script n'a pas d'instructions import, vous pouvez omettre le gestionnaire de fichiers :

Script script = Engine.Parse(content);

Gérer les dialogues

Le gestionnaire de dialogue reçoit une struct Interpreter.Dialogue avec des propriétés pour le personnage, le texte, les tags, l'interpréteur et un callback pour faire avancer le script :

void OnDialogue(Interpreter.Dialogue dialogue)
{
    string character = dialogue.Character;

    if (character != null)
    {
        // Résoudre le nom d'affichage depuis la définition du personnage
        string displayName = (string)dialogue.Interpreter.GetCharacterField(character, "name");
        if (displayName != null) character = displayName;
        Console.WriteLine(character + " : " + dialogue.Text);
    }
    else
    {
        // Texte narratif (pas de personnage)
        Console.WriteLine(dialogue.Text);
    }

    dialogue.Callback();
}

Gérer les choix

Le gestionnaire de choix reçoit une struct Interpreter.Choice avec un tableau de ChoiceOption. Chaque option a un champ Text et un champ Enabled. Appelez le callback avec l'index du choix sélectionné :

void OnChoice(Interpreter.Choice choice)
{
    for (int i = 0; i < choice.Options.Length; i++)
    {
        if (choice.Options[i].Enabled)
        {
            Console.WriteLine("  [" + (i + 1) + "] " + choice.Options[i].Text);
        }
    }

    // Lire l'entrée du joueur
    string input = Console.ReadLine();
    if (int.TryParse(input, out int selected) && selected >= 1 && selected <= choice.Options.Length)
    {
        choice.Callback(selected - 1);
    }
}

Gérer la fin du script

Le gestionnaire de fin est appelé quand le script atteint sa fin :

void OnFinish(Interpreter.Finish finish)
{
    Console.WriteLine("--- Fin ---");
}

Exemple complet

Voici une application console .NET complète qui charge et exécute un script Loreline :

using System;
using System.IO;
using Loreline;

class Program
{
    static string storyDir = "story/";

    static void Main(string[] args)
    {
        string content = File.ReadAllText(storyDir + "CoffeeShop.lor");
        Script script = Engine.Parse(content, "CoffeeShop.lor", HandleFile);

        if (script != null)
        {
            Engine.Play(script, OnDialogue, OnChoice, OnFinish);
        }
    }

    static void HandleFile(string path, Engine.ImportsFileCallback callback)
    {
        try
        {
            callback(File.ReadAllText(storyDir + path));
        }
        catch
        {
            callback(null);
        }
    }

    static void OnDialogue(Interpreter.Dialogue dialogue)
    {
        string character = dialogue.Character;
        if (character != null)
        {
            string name = (string)dialogue.Interpreter.GetCharacterField(character, "name");
            if (name != null) character = name;
            Console.WriteLine(character + " : " + dialogue.Text);
        }
        else
        {
            Console.WriteLine(dialogue.Text);
        }
        Console.WriteLine();
        dialogue.Callback();
    }

    static void OnChoice(Interpreter.Choice choice)
    {
        for (int i = 0; i < choice.Options.Length; i++)
        {
            if (choice.Options[i].Enabled)
            {
                Console.WriteLine("  [" + (i + 1) + "] " + choice.Options[i].Text);
            }
        }
        Console.Write("> ");
        string input = Console.ReadLine();
        if (int.TryParse(input, out int selected) && selected >= 1 && selected <= choice.Options.Length)
        {
            choice.Callback(selected - 1);
        }
    }

    static void OnFinish(Interpreter.Finish finish)
    {
        Console.WriteLine("--- Fin ---");
    }
}

Aller plus loin

Pour un projet Unity complet avec UI Toolkit, animations et sortie stylisée, le téléchargement loreline-unity.zip depuis les releases GitHub inclut un exemple fonctionnel complet.