Events¶

Deep dive on the event system — how events fire, surface to the player in the inbox, present choices, and resolve. Events are the primary unit of player decision-making in the game; they are the moments when the simulation surfaces something that wants the player's attention, and a chief reason the player stops advancing time.

→ Parent: GDD.md

Concept¶

Time advances a day at a time: the player ends the current day, or sets the sim running forward to a stop point. Events are the discrete moments when something happens that the player should know about or decide on, and they are a primary reason the sim stops. They surface through:

The inbox — the persistent queue of pending and recent events the player works through.
Stops — events the player has flagged as stop-worthy halt the running sim the moment the player becomes aware of them, demanding attention before the clock moves on.

Which events stop the sim and which simply accumulate quietly in the inbox is a player setting, configured per category (see Stop Settings). The game's job is to fire events; the player's job is to decide how loudly each kind announces itself.

Cadence: how often the world should speak (starting playtest default, 2026-08-08)¶

This document specified lifecycle, structure, choice and time pressure but never volume, and the absence had teeth: M26_C measured 1.8 inbox notices per year against a no-nag ceiling of 200 per decade and could not say whether that was too quiet, because there was no target to measure it against. The michigan_1920s seed carries six events, of which one is repeatable — so after roughly day 90 a ten-year scenario contains no recurring goodwill-bearing event at all (Goodwill — Implementation State).

This target is a starting playtest default, not a pinned truth. It is authored so there is something falsifiable to measure against — the right cadence comes from play. Re-pin it after two milestones of harness data, and treat a miss as a finding rather than a failure.

The unit is a consequential decision — an event presenting ≥ 2 options with a goodwill or cash consequence. Actionless world-voice reactions, contract offers, and routine deadlines are counted separately and are not what this budget governs.

Channel	Target	Ceiling	Floor
Consequential decisions	the footprint curve below — ≈4/yr for a one-county shortline, ≈7/yr mid-size, ≈13/yr for a state-wide system	15/yr — above this the inbox is a chore, not correspondence	3/yr expected, at any network size
Ambient reactions (actionless, world voice)	5–20/yr	200/decade (pinned by M26_C; unchanged)	—

Cadence scales with footprint — sublinearly (restated 2026-08-08, M30_D)¶

A one-county shortline should not receive the same volume of world as a state trunk system: that is Pillar 7 applied to attention — the world speaks about you in proportion to how much of it you have touched.

The first statement of this target got the scaling wrong and is corrected here. It read "~1 consequential decision per operated county per year, i.e. 6–10/yr on a 6–10 county network." The 6–10 county assumption did not survive contact with a measurement: the harness's baseline network operates 68 counties by the end of a ten-year run, which the per-county reading would turn into 68 decisions/yr — four and a half times the ceiling this same target sets two columns to its right. The error was treating the player's attention as if it scaled with their footprint. It does not: the network grows, the executive does not. What footprint changes is what the world says and where it comes from — not linearly how much arrives.

The target, restated scale-free:

target consequential decisions/yr  ≈  clamp( 3 + 1.2 · √(operated counties),  3,  15 )

Operated counties	1	4	9	36	68	83 (all of Michigan)
Target decisions/yr	4.2	5.4	6.6	10.2	12.9	13.9

Sublinear by construction, so footprint alone can never push the channel through the ceiling — the growth the player earns is audible without becoming a chore.

"Operated county," defined. A county in which the company has an operating station or line — the same predicate the drift guard scopes on. The two must resolve it identically; if the engine's answer to "operated" is 68 on the baseline network, that is the number both budgets are sized against, not just this one.

The floor is an expectation, not a per-year guarantee¶

The emergent channel is memoryless — independent per-day rolls, no cooldown — so realised firings per year are Poisson-distributed about the mean, and a mean cannot guarantee an annual minimum. At a mean of 4.7/yr, ~15% of years land below 3 and ~5% are silent (fewer than 2), which puts roughly one decade in eleven in breach of the silent-year test below. So the floor is stated as an expected rate; the distribution is policed by the silent-year diagnostic, which is the number that actually matters. Read them together: set the mean high enough that the silent-year test passes comfortably, not merely high enough that the mean clears 3.

The diagnostic that matters is silence, not the mean. A silent year is a sim year with fewer than two consequential decisions. M26_C measured two fully silent years in ten. The target: no more than one silent year per decade. An average is easy to hit with a clustered opening and a dead second half — which is precisely the failure the seed already exhibits — so the distribution is the measurement, not the total.

Authoring arithmetic¶

The emergent channel has no cooldown field: a repeatable event's cadence is governed entirely by its per-day weight, so expected firings per decade = weight × 3650. Condition-triggered recurring events count against the same budget and must be estimated, not ignored.

Summed per-day weight over the repeatable consequential pool	0.008	0.016	0.022	0.041
Decisions/yr	3 (expected floor)	5.9	8	15 (ceiling)

Setting the scalar for michigan_1920s: k = 1.25 (ruled 2026-08-08, M30_D). The M30_D recurring set is authored as twelve weights times one scalar k, summing to 0.0129 at k = 1.0 (4.7/yr). Ruled k = 1.25 — summed weight ≈ 0.0161, ≈ 5.9/yr. Deliberately below the 12.9/yr the curve asks of a 68-county system, for three reasons:

The trigger is footprint-blind, so one k must serve every network size — and the ceiling binds harder than the floor. A shortline tuned to a state system's volume gets 13 decisions a year about a railroad that runs to one town: a Pillar 7 violation and a chore. Tuned the other way, the state system is merely quieter than its footprint deserves. Under-serving the large network is the recoverable error; drowning the small one is not.
It buys the distribution, which is what the diagnostic measures. From 4.7 → 5.9/yr, below-floor years fall from ~15% to ~7% and silent years from ~5% to ~2%, taking compliance with ≤1 silent year per decade from roughly 91% of runs to roughly 99%.
It does not outrun the content. Twelve definitions with a fixed originRegionId repeat ~5× per decade at this rate. Raising k further before an event can vary its origin turns a system-wide condition into one town with a chronic problem — a content ask, not a cadence dial.

The engine ask this exposes: footprint-scaled emergent weight. The curve above is not implementable in today's schema, which produces a constant rate no matter how large the railroad grows. Making it real means an effective weight of the form weight × f(operated counties), normalised so an authored weight means "at a mid-size network." That is engine work, not scenario authoring, and until it lands the flat k above is the honest approximation.

The ambient budget is spent, not free (pinned 2026-08-08, M30_D)¶

The ambient row sets a volume band and said nothing about what may occupy it — and the shipped seed shows why that was a gap rather than a nicety. regional_rumor is a single-option, log_only notice that names no rival, no contract and no place ("yard talk says a rival operator is moving on a contract you'd hoped to bid on"), authored at weight 0.02 = ~73 firings/decade. That is inside the 5–20/yr ambient band and simultaneously 1.55× the entire goodwill-bearing corpus M30_D adds. Volume-compliant, content-empty.

So the band gets a companion rule: an ambient reaction must name a specific entity and report a state change. A settlement that tiered up, a county whose band moved, a corridor that turned cash-positive — those are the world reporting. "A rival operator" and "a contract" are Pillar 3's red flag stated in prose: the world as an undifferentiated mass. The ambient channel draws on the same finite attention the consequential channel does; generic atmosphere spends it and returns nothing, and it spends it first, because it fires more cheaply than anything with consequences.

Ruling — regional_rumor weight 0.02 → 0.005 (≈18/decade, 1.8/yr), wherever it appears (michigan_1920s, michigan_lp_1920s, michigan_squeeze_1920s all carry it at 0.02). It is capped rather than retired because low-frequency yard talk is fine texture and the ambient band has room for it: alongside M26_C's world voice (~1.8/yr) and M30_E's drift notices (≤4/yr), the channel still lands inside 5–20/yr. The better fix, whenever someone has cause to touch it, is to make it name the rival and the contract — both are live entities in the simulation — at which point it becomes real world voice and can carry weight again. Until then it is capped as atmosphere. (Scenario-data change, for the implementing agent; frozen-seed assertions on michigan_1920s may need re-baselining.)

Measurement plan. FullEngine10YearHarness reports, per 10-year run: consequential decisions per year, the silent-year count, ambient reactions per year, and the totals against both ceilings. Compare before/after on every milestone that adds event content. Do not tune the cadence by adding events to a scenario whose decisions have no consequences — volume without stakes is the nag this budget exists to prevent.

Event Lifecycle¶

Every event passes through up to four phases:

Fire — the event is generated by the simulation when its trigger conditions are met. Triggers are scenario-scripted, condition-based, or driven by gameplay state.
Become known — the event reaches the player's awareness, subject to the information lag system. Local events become known immediately; distant events become known after the era's communication delay.
Resolve via choice — the player picks an option, and consequences apply.
Resolve via default — if the deadline passes after the player has become aware of the event without an explicit choice, the default option is automatically applied.

stateDiagram-v2
    [*] --> Fired: trigger conditions met
    Fired --> Known: player awareness (lag-gated)
    Known --> ResolvedByChoice: player picks an option
    Known --> ResolvedByDefault: deadline passes (default applied)
    ResolvedByChoice --> [*]
    ResolvedByDefault --> [*]

Critical principle: events never resolve via default before the player has become aware of them. If lag means a distant event takes weeks to reach the player, the event waits — but option availability changes with elapsed time (see Time Pressure below).

Event Structure¶

Each event carries:

Trigger conditions — what must be true in the simulation for the event to fire.
Severity — an authored level (trivial / routine / significant / major / critical) that the player's settings can use to determine blocking behavior.
Stakeholder(s) — which stakeholders are involved (drives where it appears, who it affects, and how prominent it is in the inbox per their Clout).
Description — the prose presented to the player.
Options — typically 2 to 4, each with:
A label and short description.
A lead-time requirement — defaults to one month; events override per-option in scenario data when needed (immediate-action options at zero, longer campaigns at three months, six months, etc.).
Consequences shown directly on the choice — explicit labels like "−10% revenue for the next 2 years" or "+15 with Industrialists, sticky." The player sees what each option does before picking; no surprises.
A goodwill consequence may name any of the three scopes: a global stakeholder; a county lever id plus a county (nine of the fifteen county levers are event-authored and have no engine hook by design); or a personal lever id moving the player's own name. Events are the only channel for the event-authored levers in the latter two — an unfired one is unwritten content, not unimplemented code.
Default option — the option that auto-applies if the player lets the deadline pass without an explicit choice. Authored as the least-negative outcome among the available choices.
Deadline — how long after firing the event remains open. Authored per event — no fallback-by-category; each event names its own deadline.

Default Choice (Victoria 3 Style)¶

Every event has a default option — the choice that auto-executes if the player lets the deadline pass without input. The authoring rubric is least-negative outcome: the option that does the least damage among the available choices. Some events may have only negative outcomes (a forced regulatory crackdown, a strike that demands a response, a debt obligation coming due); the default in those is the least-bad path — the Victoria 3 "safe, neutral fallback" idiom translated into a clear authoring rule.

The player who lets events expire without input is not punished by random catastrophic outcomes; they get the floor. The player who does engage may pick a more aggressive or rewarding option, accepting risk for upside.

The default option is cash-neutral (pinned 2026-08-08, M30_D)¶

"Least-negative" needs one narrowing, because the two things an option can spend are not symmetric. A default option never moves the treasury — it neither debits nor credits. Read precisely, the authoring rubric is: the default is the least-negative outcome among the event's cash-neutral options, measured on goodwill.

Why it may not debit.

A cash loss can end a run; a goodwill loss decays. Goodwill modifiers fade back toward the authored seed (Goodwill — Decay); a treasury drawn to zero reaches receivership. "Least-negative" across two currencies of that asymmetry is not a comparison the author can make on the player's behalf.
It is a tax on the player who sets their own depth. An auto-debit lands hardest on the player who advanced time, delegated, or was away — which is Pillar 6's no-penalty invariant inverted, and the same failure Economy — a tight economy raises stakes, it does not tax delegation refuses: stakes may rise, but never the gap between attending and delegating.
Lag can make it involuntary. Under information lag an event can reach the player with its deadline already passed. Spending their money at that moment is not a decision they declined to make; it is one they were never offered.

Why it may not credit either. A paying default would make neglect profitable and invert the same invariant from the other side — the absent player out-earning the engaged one, which quietly argues against opening the inbox at all. The no-penalty invariant is symmetric: flat, not favourable.

What this constrains — in authoring, not in play. Every event carrying a default must offer at least one cash-neutral option, and that option must be survivable: damaged, embarrassed, out of favour, but never terminal. An event whose only non-catastrophic branch costs money is mis-authored — restructure it so the free branch is the bad-but-alive one. This is a burden on the author, not an escape hatch for the player.

What this does not touch. An obligation the player already incurred — a bond coupon, a lease payment, a contract breach penalty, an operating cost — is debited by the system that owns it, on its own schedule, and is not an event default. The line: the simulation may take money for a decision the player made; it may not make a spending decision on the player's behalf.

Precedent, not novelty: the shipped michigan_1920s defaults already conform (cadillac_lumber_strike defaults to the no-cash option over "Settle ($800)"; treasury_crisis to "Tighten the belt"), and the M30_D recurring set was authored to it (M30_D §2.3).

Decisions are final. Once an event resolves — whether by explicit choice or by deadline expiry triggering the default — the simulation provides no rewind or undo mechanism. The player commits to their choices and lives with the consequences. (Save and reload is an OS-level concern outside the simulation's domain.)

Time Pressure and Option Decay¶

Events have a deadline in in-game time from the moment they fire. The deadline determines when the default would auto-apply (after the player has seen the event).

Each option also carries a lead-time requirement — how much in-game time it needs to be executed. Some options are immediate (paying a fine, conceding a point, ignoring a demand); others require lead time (running a counter-campaign, building public support, organizing a strike-breaking force).

When the player becomes aware of an event, available options are filtered to those whose lead time fits the remaining time before deadline:

Available options at the moment of awareness = options where lead_time ≤ deadline − awareness_time

Information lag has teeth: distant events that reach the player late offer a smaller decision space. The player must act immediately and may have to choose from a poorer set of options than someone closer to the source had.

Example: Union Demand Event¶

A union in a distant region issues a demand. The event has a 60-day deadline.

Options: - Ignore the demand. Lead time 0. Consequence: union goodwill drops; possible strike. - Concede to the demand. Lead time 0. Consequence: cash cost; goodwill rises. - Run a counter-campaign to persuade union members to vote it down. Lead time 30 days. Consequence: cheaper than conceding if successful, riskier if not.

Three scenarios:

Player location	Lag	Sees event on day	Time remaining	Options offered
Same region	0	1	60	All three
14-day postal lag	14	15	45	All three (counter-campaign needs 30, fits)
35-day postal lag	35	36	24	Ignore + Concede only (counter-campaign needs 30, doesn't fit)
75-day postal lag	75	76	−16	Ignore + Concede only — event has waited past its deadline; player must resolve immediately on awareness

In the last case, the event has been festering for weeks while the player was unaware. It does not auto-apply the default — it waits — but by the time the player sees it, every lead-time-positive option is gone, and the only remaining choices are the immediate ones. The simulation reflects the situation that has accumulated during the unwitnessed period.

Stop Settings¶

The player controls which events stop the running sim and which simply accumulate in the inbox. Because the sim only advances when the player drives it, this is the core signal-to-noise dial of the pacing model (the Football Manager / Out of the Park "what should interrupt me" preference).

To keep this from becoming the settings-bloat that drowns deep-simulation games, the control is per category, not per event. For each category the player picks one of:

Stop — when an event in this category becomes known (after any information lag), the running sim halts and the event demands attention before the clock moves on.
Log — the event accumulates quietly in the inbox; the player engages when they choose. Defaults auto-apply when deadlines pass (see Default Choice).

Categories are a curated, manageable set — by severity (trivial / routine / significant / major / critical) and by a few high-level kinds (a contract or financial deadline, a labor action, a project incident, a rival move, a government / regulatory matter). Sensible presets ship by default (e.g. "stop on major-and-up and on any hard financial deadline; log the rest"), so a player need never open the screen — but can tune it.

The design intent is that the player deals with events rather than filtering them away. Clout still shapes prominence (high-Clout stakeholders' events sort to the top of the inbox; their decisions feel weightier), and severity still informs the consequences of each choice. Whether an event stops the sim is the player's call, by category.

The Inbox¶

Pending events accumulate in the persistent inbox — every event that has fired and become known but is not yet resolved, alongside informational notices and offers. The inbox is the player's correspondence queue and the surface the sim stops them at (per UIArchitecture — the inbox).

Ordering: by deadline urgency, soonest first. The most pressing item is at the top, so the player's eye lands on what most needs attention. (High-Clout stakeholders' items weight upward within that ordering.)

Each inbox entry shows:

The event title and one-line description.
The deadline (date and remaining time).
The stakeholder(s) involved with their Clout indicators.
A summary of the available options and their consequences (per Event Structure) — with inline action buttons where the choice is simple, or a link to a modal / profile page for a fuller decision.

Opening an entry presents the full event — letting the player choose immediately, or close without committing (the event stays pending until its deadline, when the default auto-applies).

For categories the player has set to Stop, a new event halts the running sim and surfaces immediately; for categories set to Log, it lands in the inbox for the player to find when they next stop (see Stop Settings).

The event choice lives in the office (pinned 2026-07-16, M21)¶

The canonical event-decision surface is the inbox, not the map. The player lives in the office (UIArchitecture — pillars); the world speaks there. An unresolved event is an inbox entry; opening it presents the full event — title, prose body, and the labelled options with their consequences — as a focused-decision modal where the player picks an option. This is the Pillar-2 / Pillar-4 guarantee: consequences shown up front, the player chooses, decisions are final.

Two rules follow, and are M21's core:

The inbox row never silently applies the default. A row that resolves an event by auto-picking its default option without the player seeing the choices violates the guarantee. The inbox action opens the choice (the modal); the default applies only when the deadline expires unattended.
The map is not an event surface. An event choice must not require the on-demand map view to be open (the map is view + navigate, never act). The choice modal is a shell modal, reachable from the inbox regardless of which screen the player is on.

Interaction with Other Systems¶

Goodwill. Most goodwill modifiers come from event resolutions — both player choices and auto-applied defaults. Decision prompts label modifier consequences up-front.
Construction. Events fire on active projects (incidents, surveying surprises, labor disputes); some events offer the player project commissioning opportunities surfaced by scenario triggers.
Business Dealings. Bond, equity, and contract opportunities arrive as events. Procurement deals can also arrive as time-bounded offers.
Populations. Population shifts are driven partly by event resolutions; events about a region typically affect that region's interest groups.
Information lag. As described above, lag delays awareness and shrinks the option set on arrival.
Stakeholder Clout. Clout determines how prominently an event appears in the inbox and what tooltip detail it gets — but not whether it stops the sim. That's the player's stop setting.

All major Events design questions are currently resolved. Specific tunable values — deadline ranges per event category, default lead-time exceptions, exact log ordering tie-breakers — are scenario-tunable and will need playtesting.