Editor Integration

plotknot provides editor support through a Language Server Protocol (LSP) implementation, a VSCode extension, and a Defold editor script.

VSCode Extension

The vscode-plotknot/ directory contains a complete VSCode extension with:

• Syntax highlighting via TextMate grammar
• Language registration for .plotknot files
• LSP client connecting to the plotknot language server

Installation

cd vscode-plotknot
npm install
npm run compile

Then install as a local extension in VSCode (F5 to launch a development host, or package with vsce).

Features

TextMate grammar scopes

Language Server (LSP)

The LSP server is a standalone Nim binary at editor/lsp/plotknot_lsp.nim.

Building

nim c editor/lsp/plotknot_lsp.nim

Protocol

The server communicates via JSON-RPC 2.0 over stdio (stdin/stdout), following the LSP specification.

Supported methods

Diagnostics

On every open/change/save, the server:

1. Lexes the document
2. Parses to AST (reports parse errors as diagnostics)
3. Validates (reports broken references, duplicates, undeclared variables)

Diagnostics include line, column, severity, and message.

Completions

The server provides:

• Keywords: choice:, set, call, if, else, and, or, not, true, false
• Section names: all stage IDs in the document (for goto/choice targets)
• Variable names: all variables seen in set statements

Hover

Hovering over a keyword shows its documentation:

• choice: — “Begin a choice block with - text -> target items”
• set — “Assign a value to a variable”
• call — “Invoke a game function”
• if — “Conditional branch”

Go to definition

Clicking a stage reference (in -> targets or choice targets) jumps to the stage heading that defines it.

Defold Editor Script

The editor/plotknot.editor_script file adds a menu command to the Defold editor:

local M = {}

function M.get_menu()
  return {
    label = "Plotknot",
    children = {
      {
        label = "Compile Stories",
        command = "plotknot_compile",
        query = {},
      }
    }
  }
end

function M.run_command(command, args)
  if command == "plotknot_compile" then
    -- Runs the plotknot compiler on all .plotknot files
    os.execute("plotknot compile assets/stories/*.plotknot --output assets/")
  end
end

return M

Setup

1. Place plotknot.editor_script in your Defold project root
2. Reference it in game.project under [editor_script]
3. The “Plotknot → Compile Stories” menu item appears in the editor

Limitations

The Defold editor script API supports:

• Menu commands
• Build hooks

It does not support:

• Syntax highlighting (use VSCode alongside Defold)
• Inline diagnostics
• LSP integration

For full editing features, use VSCode with the plotknot extension and Defold for building/running.

Recommended workflow

1. Write stories in VSCode with the plotknot extension (full LSP support)
2. Compile via CLI watch mode or the Defold editor menu
3. Test in Defold with the Lua runtime
4. Iterate — watch mode recompiles on save