Using Loreline with Python

Loreline provides a Python package that works with Python 3.8 and later. This guide shows how to set up a project, load a .lor script, and handle dialogue, choices, and script completion.

Installing the library

Download loreline-python.zip from the GitHub releases page. The archive contains:

• loreline/: the Python package (__init__.py, _core.py, py.typed)
• sample/: a complete sample application with story files

Copy the loreline/ folder into your project and import it directly.

Loading a script

Use Loreline.parse() to parse a .lor string. The third argument is a file handler for resolving import statements in your 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)

If your script has no import statements, you can omit the file handler:

script = Loreline.parse(content)

Handling dialogue

The dialogue handler receives the interpreter, a character identifier (or None for narrative text), the dialogue text, any tags, and a callback to advance the script:

def on_dialogue(interpreter, character, text, tags, advance):
    if character is not None:
        # Resolve display name from character definition
        name = interpreter.get_character_field(character, "name")
        print(f"{name or character}: {text}")
    else:
        # Narrative text (no character)
        print(text)
    advance()

In a UI application, you would typically display the text and call advance() when the player is ready to continue.

Handling choices

The choice handler receives a list of options. Each option has a text field and an enabled field. Call the callback with the index of the selected choice:

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

    # In a real app, you would show buttons and call select(index) on click
    select(0)  # select first option

Handling script completion

The finish handler is called when the script reaches its end:

def on_finish(interpreter):
    print("--- The End ---")

Complete example

Here is a complete console application that loads and plays a Loreline script:

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("  Please enter a valid choice number.")

def on_finish(interp):
    print("\n--- The End ---")

story_path = os.path.join(os.path.dirname(__file__), "story", "CoffeeShop.lor")
source = read_file(story_path)
if not source:
    print(f"Error: could not read {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)

Going further

The loreline-python.zip download includes a complete working sample with a story that uses character definitions and imports. Download it from the GitHub releases page.