World Events

> ⚠️ EXPERIMENTAL — Disabled by default. API may change.

World Events — server-wide events that affect gameplay. The system has been expanded into a Living World Pipeline — a cascading event system where events trigger other events, players can prevent catastrophes, and the world changes permanently.

Key Concepts

Configuration

{
  "WorldEvents": {
    "Enabled": false,
    "MinCooldownBetweenEventsMinutes": 60,
    "EventChancePerCheck": 0.02,
    "CascadesEnabled": true,
    "ConsequencesEnabled": true,
    "MaxCascadeDepth": 5,
    "MaxTimelineRecords": 200,
    "PreventionThreshold": 3
  }
}

Built-in Events

Custom Events

Place JSON files in assets/yourmod/config/worldevents/:

{
  "eventId": "drought",
  "nameKey": "worldevent-drought",
  "descKey": "worldevent-drought-desc",
  "durationMinutes": 30,
  "cooldownMinutes": 360,
  "weight": 0.6,
  "severity": "minor",
  "tags": ["weather", "natural"],
  "cascadeOnly": false,
  "effects": ["weather:clear", "temperature:+10"],
  "conditions": [
    { "type": "season", "key": "season", "op": "eq", "value": "summer" }
  ],
  "preventableByQuests": ["quest_rain_ritual"],
  "cascades": [
    {
      "targetEventId": "monster_migration",
      "delayHours": 6.0,
      "chance": 0.8,
      "requiresUnprevented": true,
      "minPlayersOnline": 0,
      "emergencyQuest": {
        "questId": "quest_build_barriers",
        "deadlineHours": 5.0,
        "requiredCompletions": 2,
        "failureEventId": null,
        "successEventId": "celebration_feast"
      }
    }
  ],
  "consequences": [
    {
      "type": "set_flag",
      "target": "world_drought_active",
      "parameters": { "value": "true" },
      "descriptionKey": "consequence-drought-crops",
      "reversible": true
    }
  ]
}

Event Definition Fields

Cascade System

Cascades are chains where one event's completion can trigger the next.

Cascade Link

{
  "targetEventId": "monster_migration",
  "delayHours": 6.0,
  "chance": 0.8,
  "requiresUnprevented": true,
  "minPlayersOnline": 2,
  "emergencyQuest": {
    "questId": "quest_fortify_village",
    "deadlineHours": 5.0,
    "requiredCompletions": 2
  }
}

Example Cascade Chain

Drought (minor, 30 min)
  ↓ [6h delay, 80% chance]
Monster Migration (moderate, 25 min) ← preventable!
  ↓ [4h delay, 60% chance, 2+ players]
Village Siege (major, 20 min) ← preventable!
  ↓ [2h delay, 40% chance, 3+ players]
Village Destruction (catastrophic, 10 min) ← last chance!

Each link gives players time to react. The further down the chain, the more severe the consequences.

Emergency Quests

When a cascade is queued, the system can automatically assign a quest to ALL online players with a deadline.

How It Works

• Event A ends → cascade to B is queued
• Emergency quest is auto-assigned to all online players
• New players joining also receive the quest automatically
• Progress is announced to everyone: *"Progress: 1/2 — 1 more needed!"*
• Enough completions → cascade prevented + optional success event
• Deadline expires → cascade proceeds + optional failure event

Emergency Quest Config

{
  "questId": "quest_fortify_village",
  "deadlineHours": 3.5,
  "requiredCompletions": 2,
  "failureEventId": "punishment_raid",
  "successEventId": "celebration_feast",
  "exclusive": false
}

Prevention System

Two ways to prevent cascades:

• Manual — Players find and complete quests from preventableByQuests
• Emergency Quests — System auto-assigns quests with deadline

When PreventionThreshold players complete a preventive quest, the cascade is blocked.

Consequences

Permanent world changes applied when an event ends unprevented.

Consequence Types

Reversible vs Permanent

{ "type": "kill_npc", "target": "village_elder", "reversible": false }

{ "type": "corrupt_zone", "target": "eastern_plains", "reversible": true }

Reversible consequences can be undone via restoration quests.

Conditions

Events only fire when all conditions are met.

Operators: eq, neq, gt, lt, gte, lte, contains, not_contains

Commands

Timeline

Full history of all server events. Records:

• Event ID, start/end time
• Whether it was prevented (and by which quest)
• Consequences applied
• Cascade source (if part of a chain)

Architecture

• Check every 30s (only when enabled + players online)
• Cascades have priority over random events
• Max cascade depth prevents infinite loops
• State (timeline, cascades, consequences) persists across restarts
• World flags accessible by other systems (quests, NPCs, merchants)
• Zero load when disabled or no active event