API reference

The complete reference: what Tyrell exports, every option, every World property and method, every event, the main types, and how to write your own module. Module APIs are on their own pages: Reverie, Fellowship, Wormtongue, Cityspeak, Mentat, Gaff, Ceres, Cradle, Joi, Athelas, Delos, Voice, Bree, Morgul. The core’s parts: Ring, Strangers, Esper, Palantír, Westmarch and Irulan.

Throughout, input marks a method that changes the world through world.input: it’s recorded for time walk and safe to call from the game. Engine marks a method that changes state directly: call it only from inside the simulation (effects, storylets, module hooks, custom input handlers).

• Exports
• Options
• World properties
• World methods
• Events
• Inputs by name
• Types
• Writing a module

Exports

dist/tyrell.js defines the global Tyrell; dist/tyrell.mjs and dist/tyrell.cjs export the same names.

Types are exported too (from dist/tyrell.d.ts, or dist/tyrell.global.d.ts for the global): everything in types.ts, SaveData, Module, and the modules’ definition types (FeelingDef, BreakDef, MemoryKindDef, Belief, Memory, PersonFile, Shift, ReverieConfig, GroupDef, Sentiment, FellowshipConfig, CrimeDef, Report, Secret, WormtongueConfig, LineDef, PracticeDef, SocialActDef, Said, CityspeakConfig, MentatConfig, StoryletDef, Phase, GaffConfig, GoodDef, ChainDef, GoodReport, ProductionReport, CeresConfig, CradleConfig, JoiRequest, JoiReply, JoiProvider, Spoken, JoiConfig, CourseDef, CoursePhase, CourseBranch, CourseSeverity, CourseView, AthelasConfig, GeneDef, BlendDef, Genome, Mutation, DelosConfig, ApproachDef, AnswerDef, BeatDef, ThreadDef, PromiseDef, VoiceConfig, TalkLine, TalkOption, TalkView, Acquaintance, LandRules, Outcome, OutcomeKey, OutcomeDo, KindDef, TopicDef, TopicSource, MannerDef, BreeConfig, Exchange, ExchangeView, Turn, Feud, Finished, StarterOptions, ChooseOpts, Intent, MeansUse, MeansDef, WoundDef, TrapDef, TaintDef, Harm, HarmView, Blow, Response, MorgulConfig, StrangerDef, StrangerErrand, VKOptions, VKReport, VKStats, VKCheck, VKInteractions, VKHarm, Requirement, LogFilter).

Options

create(opts) takes CreateOptions:

Config (all optional; see Deciding: config for what each does, and Tuning for every field with its meaning). The headline knobs (plain multipliers, 1 changing nothing) and the finer numbers of the minds:

The decision settings, habits, pastimes and wishes:

EsperConfig (see Time):

World properties

World methods

The clock

Called from a listener (or a storylet, an effect, an input handler), these and load wait until the call that’s running returns, then run in order. | at(t, name, data = {}) | void | Input. A timer: emits timer and timer:<name> at t |

Declaring

All definitions; declare them on every start. Each returns the world, so they chain.

Telling the world things

Asking

Events

With '*', event is always the event’s name. kind is the event’s name too, except for payloads with a kind of their own (witnessed, report and broke), where it’s the payload’s, as it always was:

world.on('*', (e) => { if (e.event === 'report') showToast(`${e.actor} reported for ${e.kind}`); });

Saving

Randomness and inputs

Events

Events are emitted to listeners registered with world.on. None are emitted while Esper replays history.

Listeners run synchronously, in the middle of the engine’s work. Inputs they make are deferred until the engine finishes what it’s handling (see Concepts). Calls that move time or replace the state (tick, advance, advanceTo, seek, rewind, load, esper.seekMark) wait until the call that’s running returns, then run in order. Don’t throw from a listener: an exception propagates out of the call that moved time.

Inputs by name

The names Esper records, for tools that read a history. Each is made by the method shown.

person, promote, say, birth, recollect, social, draw, afflict, voice.start, voice.answer, bree.start, bree.strike, bree.join and morgul.harm apply at once even inside a listener, because they return a value.

Types

Body

A person as the game should show them now. See Integration: bodies.

interface Body {
  id: string; name: string;
  place: string | null;       // null while walking
  slot?: string;
  action: string;             // the action id, 'travel', or 'wait'
  next?: string;              // while walking: the action they're walking to do
  pose: string;               // the action's pose, 'walk', or 'idle'
  target?: string;
  progress: number;           // 0..1 when the body was made
  start: number; end: number;
  travel?: { from: string | null; to: string | null; start: number; end: number; f: number };
  emotion?: string; mood?: number;   // Reverie
  with?: string;              // the routine entry's `with`
  data?: Record<string, unknown>;    // PersonDef.data
}

Doing

What someone is doing (person.doing).

interface Doing {
  kind: 'act' | 'travel' | 'wait';
  action: string;             // for travel: the action they're traveling to do
  place: string | null; slot?: string; target?: string;
  start: number; end: number;
  from?: string | null; to?: string | null;   // travel only
  rank: number;
  layer: string;              // 'story', 'job', 'routine', 'need', 'plan', 'break', 'follow', 'together', 'idle'
  task?: string;              // the plan's task
  seq: number;                // the event that ends it
  until?: number;             // when the routine entry, shift or directive that chose it ends
  fill?: boolean;             // travel only: the action at the end keeps its own length
  minutes?: number;           // travel only: how long the action at the end takes (a plan step's minutes)
}

PersonDef

What the game declares about a person. Plain JSON: it’s saved with them.

PersonState

A person in the state (world.get(id)):

Other definitions

Decisions

interface Candidate {
  id: string; kind: 'action' | 'task';
  place: string | null; target?: string;
  rank: number; weight: number; layer: string;
  parts: Array<[string, number]>;   // what the weight is made of; the base first
  blocked?: string;                 // why it was ruled out
  slot?: string; until?: number;
  fill?: boolean;                   // false: keeps its own length ('*' choices)
  minutes?: number;                 // a plan step's own length, in place of the action's
}
interface Decision { t: number; who: string; picked: Candidate | null; candidates: Candidate[]; reason: string }

State

interface WorldState {
  v: number;                        // schema version
  seed: string; now: number; seq: number;
  people: Record<string, PersonState>;
  places: Record<string, { claims: Record<string, string[]>; stock?: Record<string, number> }>;
  facts: Record<string, Value>;
  q: QueueItem[];                   // the event queue (a heap)
  log: LogEntry[];
  mod: Record<string, any>;         // module state by name ('@strangers': promotions)
  game: Record<string, unknown>;    // world.keep
  n: number;                        // the world's stream counter
  ids: number;                      // ids handed out (promoted strangers)
  tune?: Record<string, Record<string, unknown>>;   // world.tune's overrides by module ('core'), only once something is tuned
}
interface QueueItem { t: number; seq: number; k: 'end' | 'think' | 'hour' | 'timer' | 'module' | 'back'; who?: string; ref?: number | string; data?: object }
interface LogEntry { t: number; k: string; who?: string; d?: Record<string, unknown> }
interface SaveData { tyrell: string; v: number; s: WorldState; history?: unknown }

Writing a module

A module is an object with a name, an attach function and any of the hooks below. Pass your own in create({ extra: [...] }); they run after the built-in ones.

// A curfew: while it's on, people can't go out to the main street after 22:00, unless they're in the Watch.
const curfew = {
  name: 'curfew',
  attach(w) {
    this.w = w;
    w.lang.term('curfew', () => !!w.s.mod.curfew.on);
    w.defineInput('curfew', (on) => { w.s.mod.curfew.on = on; w.log('curfew', undefined, { on }); });
  },
  init() { return { on: false }; },
  block(p, c) {
    const w = this.w;
    if (!w.s.mod.curfew.on || !c.place || w.hour < 22 || p.def.groups?.includes('watch')) return null;
    return w.ring.region(c.place) === 'main' ? 'curfew' : null;
  },
};

const world = Tyrell.create({ seed: 'town', extra: [curfew] });
// ... declare the town ...
world.input('curfew', [true]);
world.module('curfew');   // the module

Rules for a module:

• State lives in world.s.mod[name], plain JSON only. Definitions live on the module object.
• Hooks run inside the simulation: change state directly there. Public methods the game calls should go through inputs (w.defineInput in attach, and w.input(...) in the method), like the built-in modules’ feel and applyFeel.
• Timers: w.clock.schedule({ t, k: 'module', ref: name, who?, data? }) queues an item; at time t the module’s timer(item) is called. Queue items are state, so they save and rewind.
• Randomness: w.stream(person) or w.worldStream(name). Never Math.random or the wall clock.
• Events: w.emit(kind, payload) (silent during replays) and w.log(kind, who, data).
• Stable order: iterate in a stable order (object keys in insertion order, sorted lists), so the same seed gives the same world.