Using the Loreline CLI
The Loreline CLI is a small command-line tool that works with your .lor files. With it, you can play a story right in your terminal, prepare translation files, and give your story an identifier for interactive fiction archives.
Looking for a place to write your stories? The recommended app is Loreline Writer, and the VS Code extension is a good choice if you already use VS Code. The CLI is there to play your stories and to automate a few tasks around them.
Installing the CLI
Download the archive for your system (v0.11.0):
Unzip it. The tool is the loreline file (loreline.exe on Windows), at the root of the archive. The archive also holds a cpp folder, which is only needed to use Loreline from C++: you can ignore it.
Open a terminal in the folder where you unzipped it, and check that it works:
# macOS and Linux
./loreline version
# Windows
loreline.exe version
It prints the version of Loreline.
The examples below are written as
loreline .... If you run the tool from its folder, type./loreline ...on macOS and Linux. You can also add that folder to yourPATH, so thatlorelineworks from anywhere.
Using haxelib
If you already have Haxe installed, you can get the CLI through haxelib instead:
haxelib install loreline
haxelib run loreline play CoffeeShop.lor
Any command from this guide works the same way, with haxelib run loreline in place of loreline.
Playing a story
To play a story in your terminal:
loreline play CoffeeShop.lor
The story starts at its first beat. Narration and dialogue appear line by line, and when the story reaches a choice, the options are numbered:
The smell of coffee fills the room.
Barista: Hi! What can I get you?
1. An espresso, please.
2. Just water, thanks.
>Type the number of an option and press Enter to pick it. The story goes on until it ends.
Options whose condition is false are hidden, like in a game. To see them anyway, add --show-disabled: they are shown in gray and can be picked, which helps when you want to check a branch without setting up the state that unlocks it.
loreline play CoffeeShop.lor --show-disabled
Translating a story
loreline translate adds translation keys to your script and creates the translation files:
loreline translate CoffeeShop.lor --auto-ids
loreline translate CoffeeShop.lor --lang fr
The whole workflow is explained in the localization guide.
Giving your story an IFID
An IFID is the unique identifier of a work of interactive fiction. Archives and catalogs like the IFDB use it to tell stories apart. Loreline keeps it in the metadata block of your script.
To give your story a new IFID:
loreline ifid CoffeeShop.lor
Loreline creates the IFID, writes it in the metadata block (and adds the block at the top of the file if there isn't one yet), then prints it. The rest of the file stays as you wrote it.
If your story already has an IFID, for example from an earlier version made with another tool, give it to keep it:
loreline ifid CoffeeShop.lor 448E73DF-2D2F-47E7-A494-A46B40D4CFB3
And to just print a new IFID, without changing any file:
loreline ifid
For developers
A few commands are meant for those who build tools or games around Loreline.
Exporting a script to JSON
To print the script as Loreline reads it (beats, choices, lines and so on) in JSON, for tools that need the structure of a story:
loreline json CoffeeShop.lor
Running the language server
To start the Loreline language server, which lets you add suggestions, error checks and hovers to any editor that supports the Language Server Protocol:
loreline lsp
Going further
- Writer's Guide: learn the Loreline scripting language from the ground up.
- Localization: translate your stories into other languages.
- Using Loreline with VS Code: write your scripts with live preview and error checks.