Modding
Discord Wishlist on Steam

Maps and minds

AI brains

How the game's people decide what to do (stand or run, fight or bind a wound, go about their day or pray at Prime) is open to mods. The game's own brain is shipped as graphs, every decision the game's own code written node for node, and a mod changes it with brain files and the same node graphs as everything else.

A highwayman's brain on the Brains page: what it senses, what it believes, its choices, its activities, the decider, and what each sets going.
A highwayman's brain on the Brains page: what it senses, what it believes, its choices, its activities, the decider, and what each sets going.

How a brain decides

A person weighs up, every so often, what each of their activities is worth now, and does the one worth most. An activity under way has to be beaten by a little before it is let go (its stickiness). The activities:

activitywhat it is
Clutchholding a wound shut
Carebinding wounds: drawing back to do it, seeing to their own, helping a friend
Frightrunning from what they can't face
Lawa lawman going after a crime
Engagefighting
Routinetheir day

How much an activity wants to be done is a number from 0 to 1: a day wants 0.05, a fight 0.5 to 0.7, a fright 0.6 to 0.95.

The parts

Every decision is a part, and every part can be stood in for:

  • the decider, Decide: weighing the activities up, how often, and how sticky
  • each activity's Score (how much it wants it), Running (whether it is under way), Begin and End
  • the choices below them:
    • Care.Withdraw, Care.Self, Care.Help: the care choice
    • Whom: which threat to go for, and looking again for someone better
    • FallBack: falling back on friends and calling them in
    • Blows: blows in a string
    • AfterBlow: pressing on or backing off
    • Guard: meeting a blow (guard, parry, step out, dodge, trade blows)
    • Day: which block of their day
    • Bark: what they say

Each part has the game's code, and a stock graph that is that code node for node, fn/brain.<Part>. The stock graphs are held to the code by tests: the same situations give the same choices. The frame-by-frame mechanics (steering, the weapon) stay the game's own.

The Brains page

On the bench, the mod's list has a Brains group. Pick a kind of person (a kit, a side, a role) and its whole brain is drawn as one graph: senses, beliefs, the choices, the activities, the decider, what each sets going, the body. Every activity and choice opens as the graph it is.

Fright's want opened read-only: the game's own decision as nodes.
Fright's want opened read-only: the game's own decision as nodes.

For the picked part, the side offers:

  • Use my own: copies the part into the mod (graphs/brains.graph.json) for the kind, to change as you like
  • The game's: back to ours
  • Switch off: an activity off for the kind
  • An activity of its own
  • the decider's numbers, and the kind's tuning numbers (cornered within, danger range...), which are written as patches of asset/NpcTuning/<preset>

The brain file

json
{
  "brain": 1, "title": "Peasants are cowards",
  "for": { "kits": [ "peasant" ] },
  "use": { "Fright.Score": "CowardFright", "Engage.Score": "CowardFight" }
}

A mod lists its brain files in mod.json, "brains": [ "brains/peasants.brain.json" ]. The bench writes both.

keywhat it is
forwhich people: kits (peasant, highwayman, watchman...), sides, roles (lawman, guard, archer, rider, leader, band, villager, knight, unarmed), tunings, names. Every list given must hold, any one entry of each; nothing given is everybody
usea part to a function of the mod's graphs, by name, or a whole id fn/<mod>.<Name> of a required mod's
offactivities of ours switched off for these people
addactivities of the mod's own (below)
everyhow often they weigh up what to do, 0.05 to 5 seconds (0.2 when not given)
stickinesshow much an activity under way has to be beaten by, 0 to 1 (0.05)

Several files may apply to one person; a later mod wins on the same part. A file with any mistake is left out whole, and told as brains/x.brain.json: ....

A part's function

A function standing in for a part takes who (the one thinking, a thing of type Player.NpcBrain) as its first input, and as its second:

  • running (yes or no) for a Score
  • hour (a number) for Day
  • situation (text) for Bark

It gives back:

  • a number: a Score and the care choices
  • yes or no: Running, FallBack
  • a whole number: Blows, and Day's block
  • text: Bark
  • nothing: Begin, End, Decide, Whom, AfterBlow, Guard

The cheap way to change a part is to keep the game's and change what it gives: the node Fright: how much it wants it (the game's) runs the game's own code, so a graph can multiply it, add to it or zero it. The cowards example makes fright half as strong again this way.

An activity of its own

json
"add": [ { "name": "Pray", "title": "Pray at Prime", "score": "PrayScore", "running": "PrayRunning",
           "begin": "PrayBegin", "end": "PrayEnd", "before": "Routine" } ]
  • Its functions say how much it wants it (score), whether it is under way (running), how it begins and how it lets go.
  • It is named <mod id>.<name> and weighed before the activity named in before.
  • Without running, it is under way while it is what the person is doing.
  • Its nodes are under Brain in the node list: what the person knows (Brain › Who is about, Brain › Itself...) and what it sets going (Brain › What it sets going); and People › Orders.

A whole new brain falls out of the same file: every activity of ours off, activities of its own, and a decider of its own.

Running and cost

  • Only people a brain file names think in graphs; everyone else thinks as the game's own code, at no cost. Only the parts a file names run a graph: the rest of their brain stays the game's.
  • Brain graphs run only where the game is decided. People far off think as seldom as before.
  • There is a budget: 1 ms of graphs per person each time they weigh up, and 2 ms for everyone each frame. Past it the game's own code stands in, and a mod's own activity counts as not wanted.

Watching a brain

F7 in play, Brains near: pick a person, see their kind's brain with the activity they are doing lit, and what each activity is worth, live.

The debugger over play: a villager picked, Pray lit and its want live.
The debugger over play: a villager picked, Pray lit and its want live.

Examples

In Examples/brains:

  • prime_prayers: villagers pray at Prime, then go back to their day
  • cowards: peasants run where the game's would stand, and don't fight alone
  • bandit_looting: bandits loot the dead once the fight is over

The brain nodes have pages under Brain nodes, a page for each of their groups.