Architecture

Architecture

The engine is a small control system. Each tick: read a frozen snapshot of state, map incoming events to per-channel inputs, run one synchronous update of all states, clamp, then let a selector read the post-update state to choose a visible action. Because the update reads a frozen snapshot, equation order never affects the result — the run is bit-for-bit deterministic.

States = integrators with decay

Every state (anger, stress, frustration, boredom, hunger, fatigue, resentment, …) is one generic integrator: it accumulates its inputs and decays toward rest with a per-state half-life. A "persona" is just a preset of parameters over this shared element — not a separate type. A missing coupling or filter is neutral (0 / identity); wiring is sparse and lives in config.

Channels and filtering

Events become inputs through per-channel filters, not per-event:

• Relational channels filter per source (who did it) — an insult from a respected superior lands differently than from a stranger.
• Affinity filters per object (what/where).
• Physiological inputs (hunger, fatigue) take no filter.

The anger ↔ stress loop

An insult feeds anger directly (a dedicated edge); anger and stress form a coupled 2-cycle, so the lingering anger slowly pulls stress up afterward (stress is the slow accumulator, not an instant jump). With fixed edge gains this loop is linear and always stable — anger spikes and decays.

The outburst overlay (burst & saturation)

An optional, off-by-default overlay turns the linear loop into a stability safety-valve:

1. Escalation nonlinearity — each loop edge becomes g·(1 + k_esc·other_state), so the local gain grows with the operating point. A single provocation stays stable; only an un-certifiable coincidence of unrelated pressures (insult and hunger and fatigue and a failed search) lifts the operating point past the stability bound → a spiral to the clamp ceiling = a burst.
2. Burst latch — an integrate-and-fire flip-flop sets only when anger and stress hold above thresholds for several ticks (a plateau, not a spike), with hysteresis on exit.
3. Extinction — while latched, a slow term drags anger/stress toward zero and dominates the escalated coupling, so the burst self-terminates (bounded).
4. Displaced discharge — while latched and very angry, the reactive gate opens to the tick's event source (you can lash out at whoever is in front of you), with a refractory edge that softens repeat hits from the same provoker. Sourceless events (weather) never open it — "you cannot kick the rain."

See docs/diagrams/burst_saturation.md for the control + functional diagrams.

Changing the tick rate

The game tick is derived, not set directly:

dt (seconds per tick) = min(half_life) × time_scale ÷ nyquist_factor
decay = 2 ** (−dt / half_life)        # recomputed at config load

Both knobs live in calibration/defaults.yaml under tick:. Base config: nyquist_factor: 10, time_scale: 1.0, smallest half-life (anger) = 30 s → dt = 3 s.

The easy, behaviour-safe knob is time_scale. It multiplies every half-life, so dt scales with it and the tick-by-tick trace stays bit-identical — only the seconds a tick represents change (anger half-life 30 s → 20 min at time_scale: 40). This is how the believable-day eval reaches ~120 s/tick.

tick:
  nyquist_factor: 10
  time_scale: 40        # 1.0 = base (3 s/tick); 40 → 120 s/tick

Pick a target dt with time_scale = dt_target × nyquist_factor ÷ min(half_life) (= dt_target ÷ 3 in the base config): 1 s/tick → 0.333, 10 s/tick → 3.33, 120 s/tick → 40.

Set it per run without editing files (state is dimensionless [0,1], so you can even rebuild the config at a new time_scale mid-run and keep ticking):

from pathlib import Path
from engine.yaml_io import load_persona

cfg = load_persona(
    Path("data/personas/halgrim.yaml"),
    Path("calibration/defaults.yaml"),
    param_overrides={"tick": {"time_scale": 40}},   # → cfg.dt == 120.0
)

A scenario can also carry its own tick.time_scale (read in engine/yaml_io).

What not to touch: don't retime via nyquist_factor (it changes numerical resolution, so the trace is no longer identical, and below ~10 it risks instability), and don't hand-edit dt or individual half-lives for pacing (that breaks the dt = min(half_life)/nyquist margin and the per-tick input/decay balance). time_scale is the one knob that keeps everything consistent.

Invariants (digest)

• Synchronous update from one frozen snapshot; clamps after every commit ([0,1], signed [−1,1]).
• Equations live in exactly one place. State mutates only in update + the selector's small post-effects.
• Poles of the linearized loops inside the unit circle.
• Tick dt = min(half-life)/10 (engineering Nyquist).
• No numeric literal in engine code — everything comes from config; defaults neutral.

LLM (optional, outside the loop)

An LLM is never in the loop and never mutates state. It wires in only at two seams — perception (text → events) and expression (events → text). Without an LLM there is a deterministic fallback. The believability judge is also an LLM, used only to evaluate runs blind, never to drive them.