A multi-crate Cargo workspace with strict dependency layering, a deterministic tick engine, and pluggable backends for CLI and WASM.
The scenario TOML is the product. Configs are human-readable, version-controllable, and designed to be shared and forked. The engine takes no position on what is likely — it enforces internal consistency and shows what the premises imply.
All stochastic choices use a ChaCha-based RNG seeded from the scenario config. Same seed + same config = identical output on native and WASM. Reproducibility is guaranteed so runs can be shared for inspection.
Single-run narrative replay is available for inspection, but the primary output is statistical. Thousands of runs produce probability distributions, time-to-outcome histograms, and sensitivity rankings.
Pure simulation logic compiles to both wasm32-unknown-unknown (browser) and native targets (CLI). The CLI adds rayon for parallelism; WASM uses single-threaded async. Backends are isolated in their own crates.
faultline-types is the leaf crate with no internal deps. All domain crates depend only on types. The engine assembles all domain crates, and the two backends sit at the top.
Each simulated time step executes nine phases in order. All phases are deterministic given the same seeded RNG state.
Evaluate pending event triggers. Fire events whose conditions are satisfied. Apply immediate effects and enqueue chained events for future ticks.
Each faction AI runs a utility-based decision function. Evaluates strategic objectives, available orders, and current world state to select actions for this tick.
Execute ordered force movements. Pathfinding respects terrain movement modifiers, supply lines, and contested corridors. Forces may be intercepted before arriving.
Resolve engagements between opposing forces in the same region. Applies Lanchester attrition rates modified by terrain, tech cards, and force composition.
Apply non-combat losses: supply shortfalls, morale decay, equipment degradation, and logistics strain. Forces out of supply degrade faster.
Update political climate variables. Process loyalty shifts, defection probability rolls, and institutional support changes. Infrastructure state feeds into political stability.
Update each faction's intelligence picture. Recon assets, signals intelligence, and cyber operations alter which forces and events are visible to each faction's decision model.
Evaluate all victory conditions defined in the scenario config. A condition that is satisfied locks in the winning faction. The simulation halts when a terminal condition is met.
Record the full world state for this tick. Snapshots are used to compute output statistics, generate narrative replays, and feed the WASM visualization layer.
Combat uses Lanchester's equations as the attrition substrate, with variant selection driven by scenario parameters.
For targeted engagements where each unit can select its own target — precision weapons, snipers, guided munitions. Loss rate is proportional to the product of force sizes.
dA/dt = -β · B
dB/dt = -α · A
// A beats B when:
α · A² > β · B²For mass attrition where firepower concentrates on an area — artillery, air strikes, suppression. Loss rate is proportional to opposing force size only.
dA/dt = -β · B
dB/dt = -α · A
// A beats B when:
α · A > β · BRaw Lanchester rates are multiplied by stacked modifiers drawn from the scenario config before each combat resolution. Modifiers are sampled from distributions, not point estimates.
Each faction runs an independent utility-based decision model each tick. The AI scores all available actions and selects the highest-utility option with noise.
Each possible action (advance, defend, hold, withdraw, request support) is evaluated against the faction's strategic objectives. Utility scores are weighted sums of expected regional control, supply security, and political costs.
Factions have objective hierarchies defined in the scenario config: primary objectives (must-hold regions), secondary objectives (desired control), and avoid conditions (collateral damage thresholds, political red lines).
Faction AIs only see world state that their intelligence picture allows. Units in low-visibility terrain or covered by opposing EW/SIGINT cards may be unknown to the deciding faction, producing fog-of-war effects.
Technologies are named bundles of statistical modifiers. They capture capability without simulating hardware internals.
Each TechCard specifies a named set of multiplier distributions applied to simulation parameters. A card for drone swarms might boost ISR visibility while increasing logistics cost; a C-UAS card counters airborne attack modifiers.
// Simplified TechCard structure
TechCard {
id: "drone_swarm_v2",
effects: [
{ param: IsrVisibility, mult: Normal(1.4, 0.1) },
{ param: AttackModifier, mult: Normal(1.2, 0.15) },
{ param: LogisticsCost, mult: Normal(1.1, 0.05) },
]
}Cards are assigned to factions in the scenario config. During simulation, the engine queries the tech system before each phase that uses a modifiable parameter. Each relevant card contributes a sampled multiplier that stacks multiplicatively.
A card can specify counters fields that reference other card IDs. When an opposing faction holds a counter-card, the effect distributions are modified — reducing or negating the original card's advantages. This models technological competition without explicit hardware detail.
| Example Card | Affected Parameters | Typical Effect |
|---|---|---|
drone_swarm | ISR visibility, air attack modifier | +20-40% recon coverage, +10-30% strike effectiveness |
c_uas | Counters drone_swarm air attack | Reduces opposing drone attack modifier by 60-90% |
ew_jamming | Communications, command latency | +1-3 tick decision delay for opponent factions |
cyber_offense | Infrastructure operational status | Degrades target infra nodes by 10-40% per tick |
sigint | Intelligence picture fidelity | Reveals low-visibility units to owning faction |
precision_munitions | Combat variant selection | Shifts toward Linear (aimed fire) model |
The faultline-stats crate wraps the engine and runs hundreds or thousands of independent simulations, then aggregates results into probability distributions.
For each defined victory condition, the runner reports the fraction of runs in which that condition was met. Provides direct probability estimates with confidence intervals across the run batch.
For each terminal condition, the distribution of ticks elapsed before resolution. Reports median, mean, standard deviation, and percentile bands (10th, 25th, 75th, 90th).
Pearson and Spearman correlations between input parameters and outcome measures. Identifies which scenario assumptions most strongly drive outcome variance — the key analytical output.