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

Feature	Description
Syntax highlighting	Keywords, headings, choices, comments, strings
Diagnostics	Errors and warnings from the validator
Completions	Keywords, section names, variable names
Hover	Information about keywords and sections
Go to definition	Jump to section definitions from references

TextMate grammar scopes

Scope	Elements
markup.heading.plotknot	Section headings (#, ##)
keyword.control.plotknot	choice:, set, call, if, else
comment.line.plotknot	// comments
string.quoted.double.plotknot	String literals
entity.name.section.plotknot	Section titles
variable.other.plotknot	Variable names
keyword.operator.plotknot	->, operators

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

Method	Capability
initialize	Returns server capabilities
textDocument/didOpen	Triggers diagnostics
textDocument/didChange	Triggers diagnostics
textDocument/didSave	Triggers diagnostics
textDocument/completion	Keyword and section completions
textDocument/hover	Keyword documentation
textDocument/definition	Section reference resolution
shutdown / exit	Clean shutdown

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 section 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 section reference (in -> targets or choice targets) jumps to the section 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