Using Loreline with VS Code
The recommended app for writing Loreline scripts is Loreline Writer, but you can also use the VS Code extension if you're already comfortable working in VS Code.
If you already use Visual Studio Code (VS Code for short), the Loreline extension gives you syntax highlighting, a live preview of your story, and editing tools, all in one place. VS Code is a free text editor available on Windows, Mac, and Linux.
If you just want to try Loreline without installing anything, you can use the online Playground directly in your browser.
Installing VS Code
Head to the official Visual Studio Code website and download the version for your system.
Don't be put off by VS Code's "AI code editor" tagline. You don't need to use any AI features, and we won't be using any here. It's just a free text editor that our Loreline extension runs on.
Open the installer and follow the instructions. Once installed, launch VS Code. You should see a welcome screen.
Installing the Loreline extension
Now let's add Loreline support to VS Code:
- Click the Extensions icon in the left sidebar (it looks like four small squares).
- In the search box at the top, type Loreline.
- Click Install on the Loreline extension.
That's all you need to do. VS Code now knows how to work with .lor files. The extension follows the display language of VS Code, in English or French.
The video above walks you through installing the Loreline extension for VS Code step by step. You can see that before installation, VS Code doesn't recognize the
.lorfile syntax, and once Loreline is installed, syntax highlighting appears, and you can even click the ▶ (Play) icon to play the script!
You can also find the extension on the VS Code Marketplace.
Creating your first .lor file
Let's make sure everything works:
- In VS Code, open a folder where you want to keep your scripts: File → Open Folder.
- In the left sidebar, right-click and choose New File. Name it something like
MyStory.lor. - Type a few lines, for example:
barista: Hi there! How are you doing today?
You should see the text light up with colors. That means the extension is working.
To learn the Loreline language, head to the Writer's Guide. It will walk you through everything step by step.
Features
- Live preview: click the ▶ icon in the top-right corner of the editor to play your script in a side panel. The preview updates in real time. Also available via
Loreline: Previewin the command palette. - Suggestions: names, fields and built-in functions are suggested as you type, with their type.
- Hover for info: hover over a name to see what it is, its type, the comment written right above it, and where it's used. On a line with a translation key, the hover shows the line in every language found next to the script.
- Jump to definition:
Ctrl/Cmd+click to jump to where a name is declared, even from a file imported by another one. - Visual cues: choice lines get a tinted background, narrative text appears in italic, plural pipes are highlighted.
Checking your scripts
While you write, the extension reads your whole script, with the files it imports, and points out mistakes before you even play it: a name declared nowhere, a beat that doesn't exist, a function the app running the story doesn't provide, a beat nothing leads to. Hover the underlined text to see what's wrong. When a fix exists, a light bulb shows up: click it, or press Ctrl+. (Cmd+. on Mac), to apply it. For example, a misspelled $gol offers to change it to $gold, or to declare gol in your state.
Declare what your script uses
The checks rely on a simple rule: whatever your script uses is declared somewhere, in the script, in a file it imports, or in Loreline itself.
- Values the app running the story sets go in a
stateblock, with a starting value:gold: 0. - Functions the app provides are declared without a body:
function playSound(name). - Beats the app starts or calls by name are marked
public beat.
Turning checks off
A comment starting with // @ changes the checks for a line, a file, or a file and everything it imports:
// @ignore-all unreachable-beat
// @ignore-in-file unknown-name
beat Start
// @ignore unknown-name
The app sets $playerName before this line.
@ignore turns a check off, @check turns it on, and @hint, @info, @warn or @error set its level. The name of a check is the one shown with the problem, like unknown-name. Without a name, a directive applies to every check.
Configuration
All settings are under the loreline namespace in VS Code. Open Settings (Ctrl+,) and search for "loreline".
Visual decorations
| Setting | Description |
|---|---|
loreline.enableChoiceDecoration |
Enable visual decorations on choice option lines. |
loreline.enableChoiceBackground |
Show a background color on choice option lines. |
loreline.enableChoiceColor |
Apply a text color to choice option lines. |
loreline.choiceBackgroundColor |
Custom background color for choice options (hex). |
loreline.choiceTextColor |
Custom text color for choice options (hex). |
loreline.enableTextStatementDecoration |
Enable styling on narrative text lines. |
loreline.textStatementItalic |
Render narrative text in italic. |
loreline.textStatementColor |
Color for narrative text lines. |
loreline.pluralPipeColor |
Color for the pipe separator in plural expressions. |
loreline.textStatementEscapeColor |
Color for escapes (\x, $$, ##) in narrative text. |
loreline.textStatementTagColor |
Color for the content of tags in narrative text. |
loreline.choiceMarkupColor |
Color for escapes and the content of tags in choice options. |
loreline.whenBackgroundColor |
Background color for the headers of when rules. |
loreline.whenOncePrefixColor |
Color for the - of when rules played once. |
When a color setting is left empty, the extension picks a default that suits the active theme. A custom value applies to both light and dark themes.
Preview
| Setting | Description |
|---|---|
loreline.previewAutoOpenImportedFiles |
When the preview runs code inside an imported .lor file, that file is automatically opened in the editor. Disable if you prefer not to have files opened automatically. |
loreline.previewLineDelay (coming soon) |
Delay in milliseconds before the preview moves on to the next dialogue or narrative line (600 by default). Set it to 0 to show the text instantly until the next choice. |
loreline.previewWaitForClick |
When enabled, each dialogue and narrative line in the preview waits for a click to continue, instead of auto-advancing. |
Checks
| Setting | Description |
|---|---|
loreline.analysis.enabled |
Check scripts as you write. On by default. |
loreline.analysis.onType |
Check while typing, not only when a file is opened or saved. |
loreline.analysis.strict |
Report names declared nowhere as errors, like // @error-all unknown-name, undeclared-assignment. |
loreline.analysis.translations |
Also check translation keys. |
loreline.analysis.rules |
How each check is shown, by its name, for example { "unreachable-beat": "off" }. Directives in scripts win over this setting. |
Going further
- Writer's Guide: learn the Loreline scripting language from the ground up.
- Built-in Functions: complete reference for functions available in scripts.
- Playground: write and run Loreline scripts directly in the browser.