Crisis System

Crises are dynamic events that modify state metrics, government approval, and corporate profit margins across affected regions. They can be one-time shocks (flat effects) or ongoing situations (tick effects).

Overview#

• Purpose: Create dynamic economic/political events that challenge players and alter the game world
• Scope: Global, country-wide, or region-specific
• Duration: Fixed (N turns) or indefinite (manual resolution)
• Effects: State metrics, government approval, corporate profit margins
• Turn Processing: Runs inside the stateEffectsAndNationalAggregation adapter (src/simulation/phases/stateEffectsPhase.ts7d ago), via runtime.runPhase("crisisTurn", ...)

Crisis Structure#

Core Fields (crises collection)#

Crisis Effect Structure#

Each effect defines what changes and how often it applies:

Scope Resolution#

Crises resolve their geographic scope to a list of target state IDs:

Effect Types#

Flat Effects#

Applied once on the turn the crisis starts (turn === crisis.startTurn):

// Example: Sudden unemployment spike
{
  effectType: "flat",
  targetType: "metric",
  metricCategory: "economic",
  metricField: "unemploymentRate",
  value: 2.5, // +2.5% unemployment
  label: "Job losses"
}

Tick Effects#

Applied every turn while the crisis is active:

// Example: Ongoing economic recession
{
  effectType: "tick",
  targetType: "metric",
  metricCategory: "economic",
  metricField: "gdpGrowth",
  value: -0.1, // -0.1% GDP growth per turn
  label: "Economic contraction"
}

Tick Decay#

Tick effects don't hold full strength for the crisis's whole life, for crises with a finite durationTurns, tickDecayFactor() (src/lib/turn/crisisTurn.ts1d ago) linearly ramps the applied value from 1.0x at startTurn down to 0x at expiry (50% at the midpoint):

export function tickDecayFactor(turn: number, startTurn: number, duration: number | null): number {
  if (duration === null || duration <= 0) return 1;
  const elapsed = turn - startTurn;
  return Math.max(0, Math.min(1, 1 - elapsed / duration));
}

Indefinite crises (durationTurns null or <= 0) never decay, they apply their tick effects at full strength every turn until manually resolved.

Target Types#

Metric Effects#

Modify state metrics in the stateMetrics collection:

• Path: stateMetrics.${metricCategory}.${metricField}.value
• Applies to: All states in the resolved scope
• Example categories: economic, social, infrastructure
• Example fields: unemploymentRate, gdpGrowth, crimeRate

Approval Effects#

Modify government approval rating at the country level:

• Collection: governmentApproval
• Field: approvalRating
• Deduplication: Region-scoped crises derive the affected country from the region's parent country

// Example: National crisis reduces government approval
{
  effectType: "tick",
  targetType: "approval",
  value: -0.5, // -0.5% approval per turn
  label: "Public discontent"
}

Profit Margin Effects#

Modify corporate sector profit margins in the corporateSectors collection:

• Collection: corporateSectors
• Field: profitMargin (clamped to [0, 100])
• Filtering: Can target specific sectorType and/or strategyId
• Example: Energy crisis hits energy-intensive sectors

// Example: Power grid failure hits all sectors
{
  effectType: "tick",
  targetType: "profitMargin",
  sectorType: null, // all sectors
  strategyId: null, // all strategies
  value: -5, // -5% profit margin per turn
  label: "Power outage costs"
}

Inflation Effects#

Modify country-level inflation via applyInflationEffects().

GDP Loss Effects#

One-time, real output destruction (physical-destruction disasters), applied only at startTurn regardless of effectType: value is the fraction of the affected region's GDP destroyed (e.g. 0.03 = 3%), applied as a $mul on state.gdp so the economy regrows from the reduced base afterward, the loss persists across turns, unlike a metric effect on economic.gdpGrowth which only drags the growth rate.

Stat Effects#

Target a specific character stat (statKey: charisma, debate, energy, etc.) via applyStatEffects().

Crisis Catalog and Bloc-Alignment Crisis Chains#

There is a second, distinct crisis subsystem for the bloc-alignment game (src/lib/alignment/crisisCatalog.ts10d ago, src/lib/alignment/crisisTurn.ts10d ago, src/lib/alignment/crisis.ts10d ago), Cold War flashpoints that raise a target nation's alignment-movement ceiling while open, rather than mutating stateMetrics/governmentApproval/corporateSectors directly. It stores its documents in a separate alignmentCrises collection (getAlignmentCrisesCollection), not crises.

Catalog#

AUTHORED_CRISES (crisisCatalog.ts) is a fixed list of historical anchors, each gated to an inclusive era window (minYear-maxYear) and a preferred targetEntityId: Hungarian Rising (HU, 1956-58), Suez Intervention (EG, 1956-58), Berlin Flashpoint (DD, 1958-63), Missile Standoff (CU, 1962-64), Prague Spring (CS, 1968-70). authoredCrisesForYear(year) filters the catalog to crises whose window contains the current year.

EMERGENT_CRISES defines two world-condition-driven kinds instead of calendar-driven ones: emergent.defection (a bloc member visibly trying to leave) and emergent.tugOfWar (a country two blocs are both heavily invested in).

Per-Turn Chain Resolution#

Each turn, openDueCrises() and closeDueCrises() (src/lib/alignment/crisisTurn.ts10d ago) run the crisis lifecycle:

1. Close due crises, any crisis with status: "open" and closesTurn <= currentTurn resolves.
2. Open new flashpoints, up to MAX_OPEN_CRISES = 3 concurrently, in strict precedence order:
   • Authored anchors fire once each per world, gated by era window. If the anchor's preferred target is not movable (already at ALIGNMENT_GATES.locked) or already claimed this turn, it retargets to the most contested movable nation instead of fizzling (retargetedFrom records the original target). Egypt and Cuba are deliberately kept in the catalog though neither is an implemented country, an authored crisis targeting them retargets to a real flashpoint.
   • Defection crises open for any bloc member that has wanted out for at least SUSTAIN_TURNS / 2 turns (DEFECTION_CRISIS_AT).
   • Tug-of-war crises open for any nation two poles are both contesting (tugOfWarCandidate()).
3. Each opened crisis gets a closesTurn of currentTurn + CRISIS_WINDOW_TURNS.

A crisis itself pays out nothing directly, while open, it raises its target's movement ceiling (openCrisisTargets() feeds CRISIS_TURN_CAP elsewhere in the alignment turn phase), so ordinary sphere-projection plays against that nation can move further than anywhere else. A crisis nobody acts on changes nothing.

See bloc-alignment-and-spheres.md for the surrounding bloc-stress/sphere-projection system this feeds into.

Turn Processing#

Handled by processCrisisTurn() in src/lib/turn/crisisTurn.ts1d ago:

Wire Event Integration#

Crises emit wire events for real-time notifications:

// On activation (start turn only)
logWireEvent("crisis_start", crisis.wireMessageOnStart, {
  href: `/world/crises/${crisis._id.toString()}`,
});

// On resolution (auto or manual)
logWireEvent("crisis_end", crisis.wireMessageOnEnd, {
  href: `/world/crises/${crisis._id.toString()}`,
});

Lifecycle#

1. Creation: Admin creates crisis via admin panel or API
2. Activation: Crisis effects apply immediately on next turn processing
3. Duration: Tick effects apply each turn; flat effects only on start turn
4. Resolution:
   • Auto: When turn >= startTurn + durationTurns (if durationTurns is set)
   • Manual: Admin marks as resolved via admin panel
5. Cleanup: Resolved crises remain in database for historical reference

Admin Management#

Crises are created and managed via admin routes (not yet documented in public API):

• Create: Admin panel → World → Crises → Create
• Resolve: Mark active crisis as resolved
• Edit: Modify effects, duration, scope

Database#

crises collection#

Example Crises#

Financial Crisis (Country-wide, tick effects)#

{
  name: "Financial Crisis",
  description: "A severe banking crisis spreads across the nation",
  scope: "country",
  countryIds: ["US"],
  status: "active",
  startTurn: 480,
  durationTurns: 96, // 2 years
  effects: [
    {
      effectType: "tick",
      targetType: "metric",
      metricCategory: "economic",
      metricField: "gdpGrowth",
      value: -0.2,
      label: "Economic contraction"
    },
    {
      effectType: "tick",
      targetType: "metric",
      metricCategory: "economic",
      metricField: "unemploymentRate",
      value: 0.05,
      label: "Job losses"
    },
    {
      effectType: "tick",
      targetType: "approval",
      value: -0.25,
      label: "Government blame"
    }
  ],
  wireMessageOnStart: "A financial crisis has gripped the nation",
  wireMessageOnEnd: "The financial crisis has ended"
}

Regional Drought (Region-specific, flat + tick)#

{
  name: "California Drought",
  description: "Severe drought conditions impact agriculture",
  scope: "region",
  regionIds: ["CA", "NV", "AZ"],
  status: "active",
  startTurn: 500,
  durationTurns: 48, // 1 year
  effects: [
    {
      effectType: "flat",
      targetType: "metric",
      metricCategory: "infrastructure",
      metricField: "waterSupply",
      value: -20,
      label: "Water shortage"
    },
    {
      effectType: "tick",
      targetType: "profitMargin",
      sectorType: "agriculture",
      value: -3,
      label: "Crop failure costs"
    }
  ]
}

Key Files#

Related Documentation#

• Policy System, State metrics that crises can modify
• Corporations, Profit margin effects on corporate sectors
• National Metrics, Government approval affected by crises