Make a mod

This page walks you through building a working mod from an empty folder. By the end you will have a small program that shows the state of the current turn in the footer, keeps a short history in a side pane, and posts a note when a turn runs long.

A mod needs only two things: a mod.json that describes it, and a program that reads and writes JSON lines. You can write the program in any language that can read standard input and write standard output. The example here uses plain sh and sed, so it runs on any Unix-like system without extra tools.

Before you start

• Mods only run in interactive sessions. A syntic -p run never starts them.
• Mods are read only from your own config folder, ~/.syntic/mods/. If you have set SYNTIC_CONFIG_DIR to an absolute path, the folder is mods/ inside that path instead.
• A mod is off until you switch it on with syntic mod enable. Changes take effect from the next session.

Build the mod

mkdir -p ~/.syntic/mods/turn-clock
cd ~/.syntic/mods/turn-clock

{
  "name": "turn-clock",
  "version": "0.1.0",
  "description": "Footer clock for the current turn and a pane with recent turn times",
  "command": ["sh", "run.sh"],
  "events": ["turn.start", "turn.end"],
  "ui": ["status", "pane"],
  "permissions": ["notes"]
}

#!/bin/sh
# Show the current turn in the footer, keep the last five turn times
# in a pane, and post a note when a turn takes two minutes or more.
 
LONG=120
history=""
 
say() { printf '%s\n' "$1"; }
num() { printf '%s\n' "$line" | sed -n "s/.*\"$1\":\([0-9][0-9]*\).*/\1/p"; }
 
show_pane() {
  rows=""
  for item in $history; do
    rows="$rows${rows:+,}\"turn ${item%%:*}: ${item#*:}s\""
  done
  say "{\"type\":\"draw\",\"slot\":\"pane\",\"title\":\"Turn times\",\"lines\":[$rows]}"
}
 
while IFS= read -r line; do
  case "$line" in
    *'"type":"hello"'*)
      say '{"type":"draw","slot":"status","text":"turn clock ready"}' ;;
    *'"event":"turn.start"'*)
      say "{\"type\":\"draw\",\"slot\":\"status\",\"text\":\"turn $(num turn) running\"}" ;;
    *'"event":"turn.end"'*)
      t=$(num turn); s=$(num seconds); [ -n "$s" ] || s="?"
      say "{\"type\":\"draw\",\"slot\":\"status\",\"text\":\"turn $t took ${s}s\"}"
      history=$(printf '%s\n' "$t:$s" $history | head -n 5 | tr '\n' ' ')
      show_pane
      if [ "$s" != "?" ] && [ "$s" -ge "$LONG" ]; then
        say "{\"type\":\"call\",\"id\":$t,\"method\":\"note.post\",\"params\":{\"text\":\"Turn $t took ${s}s.\"}}"
      fi ;;
    *'"type":"bye"'*)
      exit 0 ;;
  esac
done

syntic mod list

syntic mod enable turn-clock

How the example works

The note is only shown because the mod was granted notes. Without that grant, the call gets an error result and counts as a message the mod was not allowed to send, but drawing still works.

Pick a language

Any program that can be started from the mod folder works:

Whatever you choose, keep these rules in mind:

• Write whole lines and flush. Each message must be one JSON object followed by a newline. Buffered output that never flushes means nothing is drawn.
• Read all of standard input. Syntic Code keeps a small queue of messages for each mod. If your program stops reading, new events are dropped for it.
• Do not print anything else to standard output. Stray text counts as a bad line. After more than 20 bad lines the mod is stopped for the session.
• Use standard error or a file for logs. Standard error is thrown away, so write debug output to a file in $SYNTIC_MOD_DATA.

Keep working on a mod

Edit the files in place. The running session keeps the old program, so start a new session to pick up changes. You do not need to enable the mod again unless you added to permissions; in that case syntic mod list shows now also asks for: ..., and the new permission stays off until you run syntic mod enable again.

To switch a mod off:

syntic mod disable turn-clock

To remove it completely, disable it and delete its folder. Its private data folder lives at ~/.syntic/mod-data/<name>/; delete that too if you no longer need it.

Share a mod

There is no mod marketplace. To share a mod, share its folder (for example, as a git repository) and ask the other person to copy it into their own ~/.syntic/mods/ and run syntic mod enable themselves. A project repository cannot install or enable a mod for anyone.

Next steps

• Screen areas: sizes and behavior of the footer, band and pane.
• Events: every event and its data.
• Mod API: note.post and session.state.
• Test a mod: drive your program by hand before you enable it.