Modding
Discord Wishlist on Steam

Graphs

Graphs

A graph is behaviour drawn as nodes and wires: when a blow lands, if it was struck with a longsword, set the one struck alight. There is no code to write. Graphs are drawn on the Mod bench's graph page and kept as plain JSON files in the mod, listed in mod.json:

json
"graphs": [ "graphs/fire_sword.graph.json" ]

Graphs are format 4. The example mod Examples/graphs rings the bells at Prime and gives every player bread.

A graph on the bench: robbers coming out of the willows at the ford when the carter passes at night.
A graph on the bench: robbers coming out of the willows at the ford when the carter passes at night.

Events, runs and wires

  • An event node is where a run starts: something happened in the game (a blow landed, the hour struck, a player joined) or the graph's own start (a scene loaded, a timer, a signal). Its head is deep red, with a run arrow.
  • The run goes from node to node along white wires, from a then out of one node into the in of the next. Each node it reaches does its thing, then passes the run on.
  • Value wires carry what nodes give and take: the one struck, a number, a position. A node asks for its inputs' values when the run reaches it.
  • A value node (green head, or drawn small with just a symbol) has no run pins. It works its answer out when a node wired to it asks: +, =, Position of.
  • Flow nodes steer the run: Branch goes one way or the other, Sequence does several things in turn, For each goes over a list, Wait waits.

Pins and their colours

Every pin is coloured by what it carries, and shaped too, so colour-blind eyes tell them apart as well:

kindcolourshape
the runwhitean arrow
yes or noreda circle
whole numberteala circle
numberlime greena circle
textmagentaa circle
positiongolda circle
colourblue-violeta circle
a thing of the game'ssky blue, tinted apart for people, items and thingsa circle
a choicedark teala circle
a listits items' coloura small grid
anything (until something is wired)greya diamond

A pin's mark is hollow until something is wired to it. Only fitting kinds join: a whole number goes into a number, and anything goes into text, but a number can't go into a position. Dragging a wire onto a pin that doesn't fit says why.

Every kind of pin and wire on one graph.
Every kind of pin and wire on one graph.

Node heads

rolehead
eventsdeep red, with a run arrow
actionssteel blue
valuesgreen
flowslate
the library's and required mods' functionsviolet
the mod's own functionsamber

What is typed in

An input with no wire takes what is typed into the box beside it: a tick, a number, words, a position, a colour, a choice. Things of the game's are picked: an item, a sound, a thing. In the file, a picked thing is written by its address, as patches name them: "thing/Longsword", "item/BreadSlice".

An event's own inputs (Every so often's seconds, When signalled's name) are read once as the graph loads, so they are typed in, never wired.

The file

json
{
  "graph": 1, "name": "FireSword", "title": "Fire sword",
  "vars": [ { "name": "burns", "kind": "Int", "value": 0 } ],
  "nodes": [
    { "id": "hit", "node": "event/WeaponDamage.LandedOn", "x": 0, "y": 0 },
    { "id": "what", "node": "get/Game.ThingId", "x": 0, "y": 160 },
    { "id": "is", "node": "math/Equals", "x": 220, "y": 160, "values": { "b": "thing/Longsword" } },
    { "id": "br", "node": "flow/Branch", "x": 420, "y": 0 },
    { "id": "burn", "node": "fn/game.SetOnFireFor", "x": 640, "y": 0, "values": { "seconds": 4 } }
  ],
  "wires": [
    { "from": "hit", "out": "then", "to": "br", "in": "in" },
    { "from": "hit", "out": "weapon", "to": "what", "in": "of" },
    { "from": "what", "out": "address", "to": "is", "in": "a" },
    { "from": "is", "out": "result", "to": "br", "in": "condition" },
    { "from": "br", "out": "true", "to": "burn", "in": "in" },
    { "from": "hit", "out": "victim", "to": "burn", "in": "who" }
  ],
  "notes": [ { "text": "Then the one struck burns", "x": 600, "y": -40, "w": 300, "h": 160 } ]
}
  • nodes: each with its own id, the kind of node (node), its place, and what is typed into it (values).
  • wires: from a node's output to another's input.
  • vars: the graph's variables (Variables and scopes).
  • notes: comment boxes.
  • functions: functions the file makes (Functions and library mods).

Node kinds are named by id: event/..., call/... (actions), get/... (values), flow/..., math/..., text/..., list/..., var/get/<name>, var/set/<name>, fn/<mod id>.<Name>, and flow/Reroute (a dot on a wire). Every node's id is on its page in the node book. "off": true switches a node off: a run passes straight through it.

How a graph runs

  • A graph is read once as the mod loads, into a form ready to run. Nothing is read while it runs.
  • A graph with a mistake (a node the game hasn't got, a wire between pins that don't fit) is left out whole, and the mistake is told on the Mods page.
  • A run takes at most 10,000 steps before a Wait. A loop that never ends is stopped, and told once.
  • Wait pauses the run in the game's time (it stops while the game is paused) and goes on later. Runs started by other runs go at most 16 deep.
  • A node that fails stops its run, and the problem is told once.
  • Every node says where it runs online. Each machine runs its own copy of a graph, and an action that changes the game runs only where the game is decided (Online sides).

Safety

Graphs reach only the nodes the game offers. None of them touch files, saves, the network or the web, Steam, the Workshop, reports, settings, chat or commands, the mod system, or dev roles.

Where to next