Headless Export

CLI Usage for Headless Export

The simplest way to export images from the command line.

Quick Start

cd /path/to/stormworks.nvim

./bin/stormworks-export \
  --script my_script.lua \
  --output output.png

Installation

Add the bin directory to your PATH:

export PATH="/path/to/stormworks.nvim/bin:$PATH"

Or create a symlink:

ln -s /path/to/stormworks.nvim/bin/stormworks-export /usr/local/bin/

Usage

stormworks-export [options]

Required Options

• --script <path> - Path to microcontroller script
• --output <path> - Output image path

Optional Options

• --ticks <N> - Number of ticks to run (default: 1)
• --capture <which> - "debug", "game", or "both" (default: "debug")
• --format <fmt> - "png" or "jpg" (auto-detected from extension)
• --inputs <spec> - Inline inputs: "B1=true,N1=0.5,N2=123"
• --inputs-file <path> - JSON file with inputs
• --outputs-file <path> - Write outputs to JSON file
• --result-file <path> - Write result to JSON file
• --tiles <WxH> - Screen tile dimensions (e.g., "3x2")
• --debug-canvas-size <WxH> - Debug canvas size (e.g., "512x512")
• --props <spec> - Properties: "key=val,key2=val2"
• --help - Show help message

Examples

Basic Debug Canvas Export

stormworks-export \
  --script test.lua \
  --output debug.png

With Custom Inputs

stormworks-export \
  --script autopilot.lua \
  --output autopilot.png \
  --ticks 60 \
  --inputs "B1=true,N1=45,N2=100"

Export Game Canvas

stormworks-export \
  --script display.lua \
  --output game.png \
  --capture game \
  --tiles 3x2

Export Both Canvases

stormworks-export \
  --script test.lua \
  --output result.png \
  --capture both
# Creates: result_game.png and result_debug.png

Custom Debug Canvas Size

stormworks-export \
  --script test.lua \
  --output debug.png \
  --debug-canvas-size 800x600

Save Result to JSON

stormworks-export \
  --script test.lua \
  --output output.png \
  --result-file result.json

cat result.json | jq .

Output Format

The command outputs JSON to stdout:

{
  "success": true,
  "image": "/tmp/output.png",
  "images": ["/tmp/output.png"],
  "ticks_run": 10,
  "outputs": {
    "B": {"1": true},
    "N": {"3": 42.5}
  },
  "errors": [],
  "exit_code": 0
}

Parsing Output

Extract JSON result:

result=$(stormworks-export --script test.lua --output out.png 2>&1 | grep -E '^\{')
echo "$result" | jq .

# Check if successful
success=$(echo "$result" | jq -r '.success')
if [ "$success" = "true" ]; then
  echo "Export succeeded!"
fi

# Get output path
image=$(echo "$result" | jq -r '.image')
echo "Image saved to: $image"

Batch Processing

#!/bin/bash
for script in scripts/*.lua; do
  name=$(basename "$script" .lua)
  echo "Exporting $name..."
  
  stormworks-export \
    --script "$script" \
    --output "output/${name}.png" \
    --ticks 1 2>&1 | grep -E '^\{' | jq -c .
done

Exit Codes

• 0 - Success
• 1 - Error (check stderr or JSON result for details)

Troubleshooting

Command not found:

• Make sure the bin directory is executable: chmod +x bin/stormworks-export
• Add to PATH or use full path

Export fails:

• Check the JSON output for error details
• Use --result-file to save full result
• Check stderr output: 2>&1 | tee output.log

Advanced: Direct nvim Usage

If you prefer not to use the wrapper script:

nvim --headless --noplugin -u NONE \
  -S /path/to/stormworks.nvim/bin/stormworks-export.vim -- \
  --script test.lua \
  --output output.png 2>&1 | grep -E '^\{'