Utiliser Loreline avec Python

Loreline fournit un package Python compatible avec Python 3.8 et versions ultérieures. Ce guide montre comment configurer un projet, charger un script .lor, et gérer les dialogues, les choix et la fin du script.

Installer la bibliothèque

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

• loreline/ : le package Python (__init__.py, _core.py, py.typed)
• sample/ : une application exemple complète avec des fichiers d'histoire

Copiez le dossier loreline/ dans votre projet et importez-le directement.

Charger un script

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

from loreline import Loreline

def handle_file(path, provide):
    with open(path, "r", encoding="utf-8") as f:
        provide(f.read())

with open("story/CoffeeShop.lor", "r", encoding="utf-8") as f:
    content = f.read()

script = Loreline.parse(content, "story/CoffeeShop.lor", handle_file)
Loreline.play(script, on_dialogue, on_choice, on_finish)

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

script = Loreline.parse(content)

Gérer les dialogues

Le gestionnaire de dialogue reçoit l'interpréteur, un identifiant de personnage (ou None pour du texte narratif), le texte du dialogue, les tags éventuels, et un callback pour faire avancer le script :

def on_dialogue(interpreter, character, text, tags, advance):
    if character is not None:
        # Résoudre le nom d'affichage depuis la définition du personnage
        name = interpreter.get_character_field(character, "name")
        print(f"{name or character} : {text}")
    else:
        # Texte narratif (pas de personnage)
        print(text)
    advance()

Dans une application avec interface graphique, vous afficheriez typiquement le texte et appelleriez advance() quand le joueur est prêt à continuer.

Gérer les choix

Le gestionnaire de choix reçoit une liste d'options. Chaque option a un champ text et un champ enabled. Appelez le callback avec l'index du choix sélectionné :

def on_choice(interpreter, options, select):
    for i, opt in enumerate(options):
        if opt.enabled:
            print(f"  [{i + 1}] {opt.text}")

    # Dans une vraie application, vous afficheriez des boutons et appelleriez select(index) au clic
    select(0)  # sélectionner la première option

Gérer la fin du script

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

def on_finish(interpreter):
    print("--- Fin ---")

Exemple complet

Voici une application console complète qui charge et joue un script Loreline :

import os
import sys
from loreline import Loreline

def read_file(path):
    try:
        with open(path, "r", encoding="utf-8") as f:
            return f.read()
    except OSError:
        return ""

def handle_file(path, provide):
    provide(read_file(path))

def on_dialogue(interp, character, text, tags, advance):
    formatted = text.replace("\n", "\n  ")
    if character is not None:
        name = interp.get_character_field(character, "name")
        print(f"  {name or character} : {formatted}")
    else:
        print(f"  {formatted}")
    advance()

def on_choice(interp, options, select):
    print()
    enabled = []
    for i, opt in enumerate(options):
        if opt.enabled:
            enabled.append(i)
            print(f"  {len(enabled)}. {opt.text}")

    while True:
        try:
            raw = input("\n> ").strip()
            choice = int(raw)
            if 1 <= choice <= len(enabled):
                select(enabled[choice - 1])
                return
        except (ValueError, EOFError):
            pass
        print("  Veuillez entrer un numéro de choix valide.")

def on_finish(interp):
    print("\n--- Fin ---")

story_path = os.path.join(os.path.dirname(__file__), "story", "CoffeeShop.lor")
source = read_file(story_path)
if not source:
    print(f"Erreur : impossible de lire {story_path}", file=sys.stderr)
    sys.exit(1)

script = Loreline.parse(source, story_path, handle_file)
print("=== CoffeeShop ===\n")
Loreline.play(script, on_dialogue, on_choice, on_finish)

Aller plus loin

Le téléchargement loreline-python.zip inclut un exemple complet avec une histoire utilisant des définitions de personnages et des imports. Téléchargez-le depuis la page des releases GitHub.