Skip to content

Home

Jump to bottom
RobertMalczyk edited this page Jun 17, 2026 · 4 revisions

Equilibrium Engine

A deterministic, debuggable engine for NPC character tensions in an RPG, modelled like a control system: a character's visible behaviour emerges from the dynamics of internal states — it is not scripted. Insult someone and their anger spikes; the aftermath slowly raises stress; boredom drives them to seek stimulus; an un-certifiable pile-up of unrelated pressures can trip a bounded outburst that self-extinguishes. Two personas in the same scenario play differently because their dynamics differ — not because of different if branches.

What makes it different

  • States are integrators with decay. Resonance/oscillation is an emergent property of a loop of ≥2 coupled states, not a special case. Linearized loops keep their poles inside the unit circle — stable by construction.
  • One source of truth for the equations. input→state and state→state relations live only in the update step. Clamps after every commit. Synchronous update from one frozen snapshot, so equation order can't change the result. Bit-for-bit deterministic.
  • Topology by hand, constants by calibration. What connects to what is decided deliberately; gains/thresholds/half-lives are not hand-picked — they fall out of calibration as config. No numeric literals in engine code.
  • Generic element, neutral defaults. Every state is one integrator; a "role" is a preset of parameters, not a new type. Missing coupling = neutral. The MVP contains only what does something.

Quickstart

git clone https://github.com/RobertMalczyk/equilibrium-engine
cd equilibrium-engine
pip install -e .
pytest -q          # the test suite

How well does it behave? (validation)

The engine ships with a large believability corpus and a blind LLM-judge harness. The most recent full run blind-judged 2,800 scenarios (700 one-day + 700 multi-day, each with the outburst overlay OFF and ON): 2,731 / 2,799 PASS (97.6%). See Believability Testing for the method and the full reports.

sub-corpus PASS rate
Day · burst OFF 99.1%
Day · burst ON 97.7%
Multiday · burst OFF 98.4%
Multiday · burst ON 95.0%

Pages

  • Architecture — the control-system model: states, channels, the anger↔stress loop, the outburst overlay, determinism.
  • Believability Testing — how behaviour is validated (blind judge + deterministic sanity gate) and where to read the per-test report.
  • Contributing — how to propose changes safely (fork → PR → review).

Reports (in the repo)

Clone this wiki locally