Player Random Events

The Player Random Events (PREE) system is an optional gameplay layer that offers event-driven choices to players each turn. The system is gated behind a single feature flag — when disabled, no new events are offered, but pending instances still sweep (expire and resolve).

Feature Flag

The master gate is isPlayerRandomEventsEnabled() in src/lib/events/featureFlag.ts. It reads gameState.playerRandomEventsEnabled from the database and returns a boolean.

Because the flag is a single boolean on the gameState document, admins can flip the system on or off at any time. When off, no new events are offered, but any already-pending events continue to exist until they expire or are resolved.

Per-Turn Driver

The PREE driver (src/lib/events/pree/driver.ts) runs each turn and orchestrates the full event-offer lifecycle:

1. Sweep expired instances — resolve any pending event whose expiresAtRealtimeMs has passed, notifying the owning player
2. Check the feature flag — if isPlayerRandomEventsEnabled() is false, return early with offered: 0
3. Process election debates (if RPG stats are enabled) — roll debate challenges and resolve overdue debates before offering normal events. Debate participants are excluded from the standard event offer loop (the "supersede" rule).
4. Load approved definitions — fetch all EventDefinition documents with status: "approved" from the database
5. Walk every player character in chunks of 200 — for each character:
   • Skip if the character has a pending event already
   • Skip if the character is on cooldown (per-kind and global cooldowns tracked in the event cooldown ledger)
   • Filter definitions by eligibility tags
   • Roll a weighted pick among eligible templates
   • Offer the event: create a pending EventInstance and notify the player

The driver returns a PlayerRandomEventsTurnResult with counts of swept, offered, and skipped events.

Eligibility Checks

Not every character receives every event. The system uses a two-layer eligibility model:

Character Event Context

Each character is classified into a context at offer time:

Eligibility Tags

Each event definition declares an eligibility array of tags. A character matches if:

• The tag "all" is present (matches everyone), OR
• Any of these tags match the character's context:
  • "politician" — matches if isPolitician is true
  • "ceo" — matches if isCeo is true
  • "inElection" — matches if isInElection is true

This means an event tagged ["ceo"] only goes to characters running a corporation. An event tagged ["politician"] only goes to officeholders and active candidates. An event tagged ["all"] goes to everyone.

Cooldowns

Each character has an event cooldown ledger that tracks when they are next eligible for an offer, both globally and per-kind:

The cooldown ledger is checked before eligibility filtering — a character on global cooldown receives no offers regardless of how many eligible templates exist.

Event Definitions and Handlers

Each event kind has two components:

1. EventDefinition (database document) — display copy, eligibility tags, default option, version. Definitions are seeded and admin-approved before they can be offered.
2. EventHandler (registered in code) — outcome tables (positive/negative ranges per option), payload builder, default option ID.

The seed definitions live in src/lib/events/pree/countryDefinitions.ts and the handlers in src/lib/events/pree/handlers/. A barrel file (index.ts) side-effect-imports all handlers to register them at startup. A test verifies that every seed definition matches its registered handler and that option IDs haven't drifted.

Example Event Kinds

Each event presents the player with a choice (typically 2–4 options) and resolves with an outcome drawn from the handler's outcome tables, modified by a seeded RNG roll.

Active Event Tracking

A character can have at most one pending event at a time. The driver checks hasPendingEvent(db, "character", character._id) before offering — if a pending event exists, the character is skipped.

This prevents event spam: a character who hasn't resolved their current event won't receive another until they do. If the event expires before the player responds, it auto-resolves (typically with a default or negative outcome) and the character becomes eligible again on the next cooldown cycle.

Integration with RPG Stats

The PREE driver integrates with the RPG Stats system. When both flags are enabled:

1. The driver calls isRpgStatsEnabled() at the start of the turn
2. If true, it processes election debates before offering normal events
3. Characters locked into a debate this pass are excluded from the standard event offer loop — a debate supersedes a standard event
4. If RPG stats are off, the debate step is skipped and all eligible characters receive normal event offers

This coupling means debates and random events share the same "one event per character per turn" slot.

Strategic Implications

The flag is a game-admin decision, not a per-player choice. Once on, it applies to all player characters in the game.

Related Systems

• RPG Stats & Debates — Debates supersede normal PREE events when both flags are on
• Crisis Interaction — Separate feature flag, independent of PREE
• Core Systems — Turn structure, action economy