Using Loreline with JavaScript

Loreline provides a JavaScript module that works in both the browser and Node.js. This guide shows how to set up a project, load a .lor script, and handle dialogue, choices, and script completion.

Installing the library

Install via npm:

npm install loreline

This gives you loreline.js (ES module) and loreline.d.ts (TypeScript types).

You can also download loreline-js.zip from the GitHub releases page. It contains js/loreline.js and js/loreline.d.ts. Copy them into your project and import 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:

import { Loreline } from 'loreline';

const response = await fetch('story/CoffeeShop.lor');
const content = await response.text();

function handleFile(path, callback) {
  fetch('story/' + path)
    .then(r => r.ok ? r.text() : '')
    .then(data => callback(data))
    .catch(() => callback(''));
}

Loreline.parse(content, 'CoffeeShop.lor', handleFile, function(script) {
  // Script parsed successfully, ready to play
  Loreline.play(script, onDialogue, onChoice, onFinish);
});

When the file handler is asynchronous (like fetch), parse() returns null and delivers the parsed script via the fourth argument (callback). If your file handler is synchronous (e.g. in Node.js using fs.readFileSync), parse() returns the script directly:

import { Loreline } from 'loreline';
import { readFileSync } from 'fs';

const content = readFileSync('story/CoffeeShop.lor', 'utf-8');

function handleFile(path, callback) {
  callback(readFileSync('story/' + path, 'utf-8'));
}

const script = Loreline.parse(content, 'CoffeeShop.lor', handleFile);
Loreline.play(script, onDialogue, onChoice, onFinish);

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

const script = Loreline.parse(content);

Handling dialogue

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

function onDialogue(interpreter, character, text, tags, callback) {
  if (character) {
    // Resolve display name from character definition
    var name = interpreter.getCharacterField(character, 'name');
    console.log((name || character) + ': ' + text);
  } else {
    // Narrative text (no character)
    console.log(text);
  }
  callback();
}

In a browser UI, you would typically append the text to the DOM and call callback() after a delay to let the player read it.

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:

function onChoice(interpreter, options, callback) {
  options.forEach(function(opt, i) {
    if (opt.enabled) {
      console.log('  [' + (i + 1) + '] ' + opt.text);
    }
  });

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

Handling script completion

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

function onFinish(interpreter) {
  console.log('--- The End ---');
}

Complete example

Here is a complete browser example that loads and plays a Loreline script:

import { Loreline } from 'loreline';

var output = document.getElementById('output');

function handleFile(path, callback) {
  fetch('story/' + path)
    .then(function(r) { return r.ok ? r.text() : ''; })
    .then(function(data) { callback(data); })
    .catch(function() { callback(''); });
}

function onDialogue(interpreter, character, text, tags, callback) {
  var line = document.createElement('p');
  if (character) {
    var name = interpreter.getCharacterField(character, 'name');
    line.innerHTML = '<strong>' + (name || character) + ':</strong> ' + text;
  } else {
    line.textContent = text;
  }
  output.appendChild(line);
  setTimeout(callback, 600);
}

function onChoice(interpreter, options, callback) {
  var container = document.createElement('div');
  options.forEach(function(opt, i) {
    if (!opt.enabled) return;
    var btn = document.createElement('button');
    btn.textContent = opt.text;
    btn.addEventListener('click', function() {
      container.remove();
      callback(i);
    });
    container.appendChild(btn);
  });
  output.appendChild(container);
}

function onFinish(interpreter) {
  var p = document.createElement('p');
  p.textContent = '--- The End ---';
  output.appendChild(p);
}

fetch('story/CoffeeShop.lor')
  .then(function(r) { return r.text(); })
  .then(function(content) {
    Loreline.parse(content, 'CoffeeShop.lor', handleFile, function(script) {
      Loreline.play(script, onDialogue, onChoice, onFinish);
    });
  });

Going further

For a polished browser-based example with animations, smooth scrolling, and styled output, download loreline-web.zip from the GitHub releases page.