Faultline

Philosophy

What is Faultline?

Supply scenario configurations — factions, force compositions, tech modifiers, political climates, geographic constraints — and the engine simulates the logical consequences of those premises across many runs, producing probability distributions of outcomes. Faultline is not a predictive model. It is a tool for exploring the consequence space of user-defined assumptions.

Config-as-Input

Scenarios are declarative TOML files: shareable, forkable, diffable. Post a .toml on GitHub, change one assumption and compare distributions, git diff two scenarios to see exactly which premises diverge.

Monte Carlo First

A single run is a story. Thousands of runs with the same config produce a distribution. All outputs are statistical: outcome probabilities, time-to-outcome distributions, and sensitivity analysis showing which inputs drive the most variance.

Technology Cards

Technologies (drone swarms, C-UAS, EW, cyber, SIGINT) are modeled as named bundles of statistical effects. This avoids simulating individual hardware protocols while preserving the ability to model how capabilities shift outcomes.

Deterministic

Same config plus the same seed produces identical output on native and WASM targets. Reproducibility is guaranteed: share a seed alongside a scenario to share an exact run for inspection or debugging.

Workspace

Nine Crates, One Engine

A multi-crate Cargo workspace with strict dependency layering. Leaf crates carry no internal deps; the engine assembles them all.

Crate	Purpose	Key Dependencies
`faultline-types`	Shared data structures, zero logic — the lingua franca of the workspace	serde, toml (leaf crate)
`faultline-geo`	Geography, map loading, pathfinding, terrain modifiers	types, geo, geojson
`faultline-tech`	Technology capability card system; applies statistical modifiers to simulation parameters	types
`faultline-politics`	Political climate modeling, institutional loyalty, defection probability	types
`faultline-events`	Event system: triggers, effects, chains, and conditional branching	types
`faultline-engine`	Core simulation loop; assembles all domain crates and runs tick phases	types, geo, tech, politics, events
`faultline-stats`	Monte Carlo runner, statistical aggregation, sensitivity analysis, JSON/CSV output	engine, types, rayon, statrs
`faultline-backend-wasm`	Browser UI: Canvas/WebGL scenario editor and outcome visualization	engine, stats, types, wasm-bindgen
`faultline-cli`	Headless batch runner for Monte Carlo evaluation; JSON and CSV output	engine, stats, types, clap

Quick Start

Run Your First Simulation

Install the CLI, point it at a scenario, and get a probability distribution in seconds.

Build

# Clone and build the CLI
git clone https://github.com/AndrewAltimit/faultline
cd faultline
cargo build --release

Run Monte Carlo

# Run 1000 simulations on the tutorial scenario
faultline run \
  --scenario scenarios/tutorial_symmetric.toml \
  --runs 1000 \
  --output results.json

Reproduce a Run

# Pin a seed for deterministic replay
faultline run \
  --scenario scenarios/tutorial_asymmetric.toml \
  --runs 1 \
  --seed 42 \
  --output replay.json

Validate a Scenario

# Validate config without running
faultline validate \
  --scenario my_scenario.toml