Getting Started

This guide walks you through installing plotknot, writing your first story, and running it in a game.

Requirements

Installation

Clone the repository and build:

git clone https://github.com/your-org/plotknot.git
cd plotknot
nim c -d:release src/plotknot.nim

This produces a plotknot binary in the project root. You can add it to your PATH or reference it directly.

Verify the build

./plotknot --version
# plotknot 0.1.0

./plotknot --help

Your first story

Create a file called hello.plotknot:

# The Forest

You stand at the edge of a dark forest. The path ahead splits in two.

choice:
- Take the left path -> left_path
- Take the right path -> right_path

## Left Path

You follow the mossy trail deeper into the woods.

-> ending

## Right Path

The right path leads to a sunlit clearing.

-> ending

## Ending

Your journey continues...

Compile it

./plotknot compile hello.plotknot --output output/
# compiled: hello.plotknot -> output/hello.lua

The compiler produces output/hello.lua — a human-readable Lua table describing your story.

Validate without compiling

./plotknot validate hello.plotknot
# valid: hello.plotknot

Validation checks for broken references (goto/choice targets that don't match any section), duplicate section IDs, and undeclared variables.

Run it in Lua

Copy the runtime into your project:

cp runtime/defold/plotknot.lua your_project/

Load and run:

local plotknot = require("plotknot")
local data = require("hello")  -- the compiled output

local story = plotknot.load(data)
story:start()

-- Get current lines
local lines = story:current()
for _, line in ipairs(lines) do
  if line.type == "text" then
    print(line.text)
  elseif line.type == "choice" then
    for i, choice in ipairs(line.choices) do
      print(i .. ". " .. choice.text)
    end
  end
end

-- Player picks choice 1
story:advance(1)

Watch mode

During development, use watch mode to recompile automatically when you save:

./plotknot watch hello.plotknot --output output/
# watching: hello.plotknot (press Ctrl+C to stop)

Project structure

A typical plotknot project:

my_game/
  stories/
    main.plotknot
    sidequest.plotknot
  output/          -- compiled .lua files
  plotknot.lua     -- runtime library
  main.lua         -- your game code

Next steps