Tools

Palantír (the inspector), Westmarch (the log), Irulan (the narrator), Voight-Kampff (behavior tests) and Rocinante (the sample town). To try them all at once on a town, live, there’s Eros, Tycho’s sandbox in the terminal (npm run eros): it runs Rocinante or any setup file, tells its story with every one of Irulan’s settings, shows Palantír’s account of anyone, and keeps the living documentation of every kind of thing a town can declare.

• Palantír
• Westmarch
• Irulan
• Voight-Kampff
• Rocinante

Palantír

The inspector, named for the seeing-stones of The Lord of the Rings. Every decision is kept (the last config.decisions, 12, per person) with every option, its rank, its weight and what the weight was made of, so “why did she go to the bar?” and “why didn’t she?” both have answers.

const d = world.why('kofi');
console.log(d.reason);                        // 'need at rank 0; beat read, walk'
for (const c of d.candidates) console.log(c.id, c.place, c.rank, c.weight, c.blocked ?? world.palantir.parts(c));
console.log(world.whyNot('kofi', 'drink'));
console.log(world.describe('kofi'));

A Decision is { t, who, picked, candidates, reason }. The candidates kept are the first 16 by rank and weight, plus every required one (routine, job, story, break). A Candidate is { id, kind, place, target?, rank, weight, layer, parts, blocked?, slot?, until? }; parts is [name, value] pairs, the base first; blocked is the reason it was ruled out.

whyNot weighs the action now, at every place it could be done, as if it were a free choice. Its answers look like:

• cafe: cafe is closed then; diner: no free seat
• drink at bar weighs 0.12 (base 0.2 x travel 0.6); chat weighed 0.4 (base 0.4)
• serve outranks it (job, rank 2 against 0)
• bar: needs the job 'bartender', drink isn't declared, Kofi is doing it now, Kofi is away

Decisions aren’t part of the world’s state: they don’t save, they aren’t recorded while Esper replays, and a seek or a load clears them. Each decision also emits decided ({ who, picked, place }, with picked the id or null).

whyNot and describe change nothing: they evaluate conditions as a look, so a chance: condition draws from a stream that leaves the person’s own alone.

Westmarch

The log of what happened, named for the Red Book of Westmarch, where the story was written down. It’s part of the world’s state (so it saves and rewinds), bounded to config.logSize entries (1000 by default; the oldest go first), and every entry is also emitted as a log event.

world.westmarch.find({ k: 'started', who: 'ruth', since: world.now - 1440 });
world.westmarch.since(world.now - 60, ['told', 'report']);
world.westmarch.chronicle('ruth', world.now - 1440);
// ['08:10 set out for market', '08:14 got to market', '08:14 shopping at market', ...]
world.on('log', (e) => console.log(world.westmarch.describe(e)));
// 'set out for The Market', 'got to The Market', 'told Kofi about did:sam:theft', ...

A LogEntry is { t, k, who?, d? }. Kinds written by the engine and modules:

The log:<kind> effect writes your own entries from inside the simulation. world.log(kind, who, data) writes one from the game: it’s an input, so the entry is recorded and comes back after a rewind (inside the simulation it writes at once).

The log is in every snapshot and every save, so its size is the biggest lever on Esper’s memory (see Time).

Irulan

The narrator, named for the Princess Irulan of Dune, who wrote the histories of Muad’Dib. Westmarch keeps the log a line at a time; Irulan tells it as a story: for an inspector’s “their day so far”, a town journal, a recap after time away, the storylines running through the town, a notice when something happens, what someone says when asked what’s new, or reading a Voight-Kampff run.

const kept = [];
world.on('log', (e) => kept.push(e));   // (or tell from the log itself: a time instead of a list)
world.advance(2 * 1440);

world.irulan.beats(kept, { min: 0.3 });
// [{ t: 548, who: ['sam'], with: ['dev'], place: 'market', score: 0.97, kinds: [...], entries: [...],
//    text: "Sam went to The Market and pocketed some food, with Dev there.",
//    parts: [{ text: 'Sam', person: 'sam' }, { text: ' went to ' }, { text: 'The Market', place: 'market' }, ...] }, ...]
world.irulan.tell(kept, { min: 0.3 });     // ['Day 0, morning. Sam went to The Market and ...', ...]
world.irulan.day('ruth', kept);            // 'Ruth went to Tomas\'s Workshop and had the radio fixed, with Tomas there. ...'
world.irulan.recap(kept, { limit: 3 });    // the three beats that matter most, in order
world.irulan.recount('tomas', kept);     // ['Early yesterday, I was caught in a snare at The Old Barn, ...', 'Yesterday evening, I was poisoned and was hurt by tainted food.']
world.irulan.feed((beat) => notify(beat.parts), { min: 0.6 });   // each beat that matters, as it happens
world.irulan.threads(kept);
// { threads: [{ title: "Sam's nightshade", people: ['tomas', 'sam', ...], keys: ['harm:5', 'taint:x4'], beats: [
//     "Sam slipped nightshade into the stew at Mara's Cafe.", "Tomas was poisoned and was hurt by what Sam put in the food.",
//     "Tomas ... blamed Mara, who served it, ...", "Mara suspected Sam, who was about, ..."] }, ...],
//   rest: [...the beats in no storyline] }

Beats

It folds the entries into beats:

• An action from start to finish, with the walk there, the company kept, how a social act went and a feeling it brought: “Lena showered at home for half an hour, with Kofi home too, and felt fresh.” Company is only being at the same place, not doing it together (it’s in around, apart from those who took part, in with), so at someone’s home it’s told as being home (“with Pip and Tomas home too”, “with Kofi there too” for a visitor), and elsewhere as being there (“with Mara and Kofi there”). The same action taken up again straight after is more of it, so a shift worked an hour at a time is one beat (“Mara went to Mara’s Cafe and baked bread for eight hours”). One still going when the entries end is told as it was (“was reading”).
• A talk (Bree) from its first word to its last, through what it turned into: “Dev argued with Lena at Mara’s Cafe, which turned into a fight, and it ended in a row.”
• Whatever happened to someone in the same minute, as one sentence: what happened, then how they felt, then what they did. “Kofi gave up on dinner at home (no way to get food) and was frustrated.”
• The same beat for several people at once, told once: “Mara, Ruth and Kofi wished for some fresh air.”

A deed told by the action it came of isn’t told again, nor a chat both sides started, nor a suspicion of the person someone blamed. Places are named as the person would say them: home for their own, “Mara’s place” for someone else’s home with no name.

Every beat is scored for how much it matters, 0 to 1: the weight of its kinds (IRULAN_WEIGHTS: routine low, the day’s turns in the middle, what a story is made of high; a feeling by how strongly it moves the mood; a job’s work lower still, a crime done, a hostile talk or one that went badly higher), up to twice that for what’s rare among the entries told, and focus for the people who matter more to the game. min leaves out what scores under it, a clause at a time, so what matters isn’t told with the routine around it.

Varied words

Each telling varies its words: a tell given as a list is variants (did: ['read', 'curled up with a book', 'sat and read']), and Irulan’s own phrases have theirs (“went”, “headed”, “made their way”; “told Ines about”, “told Ines of”, “mentioned … to Ines”; “with Kofi there”, “with Kofi around”, “in the company of Kofi”). One is drawn for each telling from the world’s seed and what’s told, so the same entries read the same every time, another seed reads differently, and nothing in the world changes. The draw never depends on who it’s about, so the same thing done by several people still reads alike and is told once. vary: false always takes the first.

Parts

Every beat’s sentence also comes in parts: its words, and each person and place in them tagged with its id ({ text: 'Sam', person: 'sam' }, { text: 'home', place: 'apt_5' }), so a game can make names links, color places or put a portrait by a name without searching the text. Joined, the parts’ text is the sentence. A thread’s title comes in parts too. The names words gets from its context (name, place) carry their tags into its words: put them in as they are. Words left to Westmarch’s describe come untagged.

Point of view

as tells only what one person knows, as they know it: what they did, what was done to them or in front of them, and what they were told. Not what others felt, wished, planned or thought of them (their feelings, wishes, grudges, suspicions, even folded into what they did); not a crime done in front of them they didn’t catch (Wormtongue’s witnesses); not who did something to them they couldn’t have seen (a quiet harm: poisoned food is “tainted food”, not “Sam’s”). voice: 'first' tells it in their words: “I”, “me”, “my” (“Officer Vance told me about Sam’s theft”, “Tomas was hurt by my tainted food”, “Kofi and I”), and the subject’s “they” becomes “I” (“as I’d wished”). For gossip, for what someone says when asked, for a journal kept by the player’s character.

recount(id, entries, opts?) is what they’d say when asked what’s new: the few beats they know that matter most (limit, default 3, scoring min, default 0.4), in order, in their words, with when from now (default the world’s): “Yesterday evening, I was poisoned and was hurt by tainted food.” ago(t, now?) is when on its own: “this morning”, “last night”, “yesterday afternoon”, “three days ago”.

Threads

threads finds the storylines running through the entries:

• A matter: a crime (what was done, who saw it, who was told and who reported it), a trap (set, sprung, disarmed, warned of, gossiped about), a taint and whom it poisoned, a harm (and whom it was blamed on and who was suspected). A crime seen or told of without knowing who did it belongs to the latest crime of its kind before it.
• What passed between two people, for what’s about no matter: their talks, grudges, feuds, making up, deeds for each other, harm. A pair becomes a storyline only when something with consequences passed between them (not a chat that went fine, nor a kind word alone).

Matters are one story only when a single log entry links them (a quarrel that came to blows, a trap and the cut it gave), never for happening in the same minute: someone telling gossip as they start a chat doesn’t tie the chat to the gossip. A beat about two stories is in both. What a thread’s people felt in its course (after something in it that mattered, that they were in) comes with it: the thief’s guilty conscience, the victim’s breakdown. Everything about a thread’s matters is in it whatever it scores; a thread needs two beats and one scoring min (default 0.4). They come the one that matters most first, each { id, keys, title, parts, people, beats, t, end, score, active } (people the most involved first; id the same from one telling to the next, the first of its keys to turn up; active while something in it is within a day of now), with rest, the beats in no thread scoring min. Two with the same title (Sam poisoning the stew twice in a week) are told apart by the day each began: “Sam’s nightshade, day 2”.

The story kept

The log keeps its last config.logSize entries, a day or so of a busy town, too little to follow a feud for a week. With config.storySize, Irulan keeps the entries that matter in a story of their own (world.s.story), as Westmarch writes them: whatever weighs config.storyMin (0.3) or more, a crime or a deed done and how it ended, a feeling that moves the mood by 0.1 or more, a talk with where it was. Walks, company and routine actions aren’t kept. Past storySize, the least that matters goes, the oldest of it first. It’s part of the world’s state, so it saves, loads, rewinds and replays with the world; off (0, the default), a world has no story and hashes as before. Every call takes its entries from it when given none (world.irulan.threads()), and book() returns it. Each entry is about 100 bytes, in every save and every time-walk snapshot: a story of 1,000 is about 100 KB a snapshot.

As it happens

feed(fn, opts?) tells the story as it happens: it calls fn with each beat once it’s complete (its action or talk over, its last minute gone by, so it won’t grow) and scores min, for a notice when something that matters happens. Each beat is judged once, when it completes, and told at most once; each call has what completed since the last, in the order it began. Beats are worked out every every game minutes (default 10) from the entries of the last window (default 12 hours), from the log events, so it costs a little time as the world runs and nothing in it. A rewind (Esper) forgets what came after the time gone back to, so the new course is told as it happens. It returns a function that stops it.

Words

The words are the game’s: an action’s tell ({ did: 'took a walk in {place}', doing: 'was walking in {place}' }: see actions), a feeling’s ('enjoyed a good meal': see Reverie), a breakdown’s ('broke down and went on a bender'), a wish’s ('dreamed of becoming an expert baker'), an illness’s ({ on: 'caught a cold', over: 'shook off the cold' }: see Athelas), a kind of interaction’s ('argued with {with}': see Bree), and words for any kind of entry (Rocinante’s rain: 'rain set in'). The built-in feelings, Bree’s starter kinds and Morgul’s feelings have theirs. Without them, an action is told by its label ('spent an hour juggling', 'had a kip'), a feeling as 'felt <label>', an illness as 'came down with <label>', and the rest in Irulan’s own words: gossip by what it’s about (“told Ines about Sam’s theft”), grudges by how deep they run and what they’re over (“bore Dev a deep grudge over a fight”), harm by how it came (“was hurt in Pip’s trap”), blame by why (“blamed Mara, who served it”); or, for what Irulan has no words of its own for, Westmarch’s (describe). A person is told by their name; where Irulan’s own words need a pronoun for them, they say “they” (“as they’d wished”). Like Palantír it’s a look: it reads the state and changes nothing.

Telling a rewound world: if the game keeps entries from the log events and the player goes back in time (Esper), entries past the point it went back to no longer happened. Drop those on the seek event, or tell from the log itself (tell(since)), which rewinds with the world.

Voight-Kampff

The behavior tests, named for Blade Runner’s test that tells a person from a machine. It runs a world headless for seeded days and checks that people still behave like people.

const report = Tyrell.VoightKampff.run({
  build: (seed) => buildMyTown(Tyrell, { seed }),
  days: 7,
});
if (!report.passed) console.log(report.failures);

VKOptions:

Built-in checks:

A custom check:

const noStrandedKids = {
  name: 'no-stranded-kids',
  sample(w, acc, fail) {
    for (const p of w.people()) if (p.def.tags?.includes('child') && w.hour >= 22 && !w.ring.within(p.place, p.def.home)) fail(`${p.id} is out at ${w.hour}`);
  },
};
Tyrell.VoightKampff.run({ build: (seed) => buildMyTown(Tyrell, { seed }), checks: ['capacity', noStrandedKids] });

start(w, acc, fail) is called once, when the world is built (to listen for events), sample(w, acc, fail) at every sample, end(w, acc, fail) once at the end; acc is a scratch object shared across calls.

VKReport:

Tyrell.VoightKampff.compare(report, baseline, tolerance = 0.05) returns the differences between two reports: action shares and mean mood further apart than the tolerance. An empty list means they match. Keep a baseline report from a run you’re happy with, and compare after changes to catch behavior drifting.

The command line

node vendor/tycho/tyrell/bin/voight-kampff.mjs my-town.js --days 7
node vendor/tycho/tyrell/bin/voight-kampff.mjs my-town.js --days 7 --save baseline.json
node vendor/tycho/tyrell/bin/voight-kampff.mjs my-town.js --days 7 --baseline baseline.json --tolerance 0.03

day 0 09:44  Ruth           got to The Market
day 0 09:44  Ruth           shopping at The Market
day 0 09:50  Dev            felt Saw something bad · at The Market
day 0 09:50  Dev            saw theft by Sam · at The Market
day 0 10:44  Dev            told Kofi about did:sam:theft · at The Market

$ node bin/voight-kampff.mjs examples/rocinante.js --days 2 --seed voight-kampff --with harm --story 0.5 --story-by thread

11 storylines, the one that matters most first

▌ Pip's snare  (still going)
▌ Pip, Mara, Tomas, Officer Vance and others · day 0 12:20 to day 1 19:27
day 0 12:20 !! Pip set a snare at The Old Barn, then went home and read for an hour.
day 1 07:37 !! Tomas was caught in a snare at The Old Barn, was cut, was hurt in Pip's trap, was in
               pain, was shaken and was furious.
day 1 08:00    Pip told Tomas about a trap, then sulked at home for two hours, with Tomas there.
...
▌ Sam's nightshade  (still going)
▌ Sam, Tomas, Mara, Pip · day 1 16:53 to day 2 00:19
day 1 16:53 !! Sam slipped nightshade into the stew at Mara's Cafe, then went home and showered, and
               felt fresh.
day 1 20:56 !! Tomas was poisoned and was hurt by what Sam put in the food.
...

Only the run’s own world is watched: the deterministic and save-load checks build more worlds with the same seed, and those would tell it all again. The esper check goes back six hours and runs forward again; what that tells a second time is left out. Nothing is printed past the run’s last minute (the checks run the world on a little after it), and listening changes nothing in the world: the report and its hash are the same with or without --log.

It prints the decisions and time taken, whether it passed (and the failures), the ten most chosen actions, the mean mood by day, and, when people interacted or harmed each other, what passed between them. It exits with 0 when everything passes (and matches the baseline), 1 when something fails or differs, and 2 when no setup file is given. In Tyrell’s own repository, npm run vk runs a week of Rocinante, npm run vk:bree a week of it with Bree’s interactions and the interactions check, npm run vk:harm a week of it with harm (Morgul) and the harm check, npm run vk:log one day of it printed in full (--log all), and npm run vk:story one day of it, with Bree’s interactions, told as a story (--story).

Rocinante

The sample town that ships with Tyrell, named for the ship in The Expanse: examples/rocinante.js. Every part of the engine appears in it at least once, the tests and the runner use it, and it’s the worked example to read next to these docs.

Run it:

// Node
const Tyrell = require('./vendor/tycho/dist/tyrell.cjs');
const buildRocinante = require('./vendor/tycho/tyrell/examples/rocinante.js');
const world = buildRocinante(Tyrell, { seed: 'my-seed', start: 6 * 60 });
world.advance(24 * 60);
console.log(world.describe('ruth'));

<!-- the browser: it defines buildRocinante -->
<script src="vendor/tycho/dist/tyrell.js"></script>
<script src="vendor/tycho/tyrell/examples/rocinante.js"></script>
<script>const world = buildRocinante(Tyrell, {});</script>

Options: seed (default 'rocinante'), start (default 6:00 on day 0), modules (default all), config, esper, moduleConfig (merged over Rocinante’s own, module by module), tuned (a town tuned to taste: the headline knobs for everyone and a few people’s own tune; see Tuning), bree (Bree’s interactions between the townsfolk: see Bree), harm (harm between them, with Bree: see Morgul), and together (now and then, Mara and Tomas shower together: room for two in their shower, and an action done together; mostly they shower alone, with the others only home). Couples don’t form on their own in Rocinante (autoPair: null); Mara and Tomas are partners from the start.