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.

Loreline VS Code extension screenshot

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.

Download VS Code →

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:

  1. Click the Extensions icon in the left sidebar (it looks like four small squares).
  2. In the search box at the top, type Loreline.
  3. 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 .lor file 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:

  1. In VS Code, open a folder where you want to keep your scripts: File → Open Folder.
  2. In the left sidebar, right-click and choose New File. Name it something like MyStory.lor.
  3. 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

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.

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