UE5-Modular-Game-Framework/docs/blueprints/10-adaptive/100_BPC_RareEventSystem.md

BPC_RareEventSystem — Rare Event System

Blueprint Spec — UE 5.5–5.7

---

Parent Class

ActorComponent

Dependencies

• Requires: DA_RareEvent — Rare event definitions with probability and conditions
• Requires: BPC_NarrativeStateSystem — Reads narrative flags for eligibility conditions
• Required By: BPC_AdaptiveEnvironmentDirector — Requests rare event roll
• Engine/Plugin Requirements: GameplayTags, Timer system, Random stream

Purpose

Controls ultra-rare, randomised world events that can occur once per session or with very low probability: hidden messages, brief hallucinations, entity sightings, environmental easter eggs. Tracks which rare events have already fired to prevent repeats and evaluates complex eligibility conditions.

---

1. Enums

No new enums defined. Uses GameplayTags for event and condition identification.

---

2. Structs

S_RareEventCondition

Field	Type	Description
RequiredFlags	Array of GameplayTag	All must be true for eligibility
ForbiddenFlags	Array of GameplayTag	None must be true for eligibility
RequiredPlaystyleTag	GameplayTag	Player must currently have this playstyle
MinSessionTime	Float	Minimum session elapsed seconds
MinDeathCount	Integer	Minimum player deaths this session
RequiredChapterTag	GameplayTag	Current chapter must match

---

3. Variables

Configuration (Instance Editable, Expose On Spawn)

Variable	Type	Default	Category	Description
RareEventPool	Array of DA_RareEvent	Empty	RareEventConfig	All available rare events for this session

Internal (Private / Protected, No Expose)

Variable	Type	Default	Category	Description
FiredRareEvents	Set of GameplayTag	Empty	Internal	Already triggered rare events (prevent repeat)
EligibilityConditions	Map (GameplayTag → S_RareEventCondition)	Empty	Internal	Resolved eligibility conditions per event
RollTimer	TimerHandle	—	Internal	Periodic roll timer
RollInterval	Float	60.0	Internal	Seconds between rare event roll checks

---

4. Functions

Public Functions

RollForRareEvent → DA_RareEvent

• Description: Evaluates all eligible rare events, rolls probability, and returns a selected event (or None). Fires the event if one is selected.
• Parameters: None
• Blueprint Authority: Any
• Flow: Filter pool by eligibility → exclude fired events → for each eligible, roll probability → if roll passes, select and fire → add to FiredRareEvents → broadcast OnRareEventFired → return selected event

IsEventEligible → Bool

• Description: Checks if a specific rare event's conditions are currently met.
• Parameters:

  Param	Type	Description
  EventTag	GameplayTag	Rare event identifier

• Blueprint Authority: Any
• Flow: Read S_RareEventCondition from map → check RequiredFlags against narrative state → check ForbiddenFlags → check playstyle match → check session time → check death count → check chapter → return true if all pass

ForceRareEvent → void

• Description: Fires a specific rare event immediately, bypassing probability and eligibility checks.
• Parameters:

  Param	Type	Description
  EventTag	GameplayTag	Rare event to fire

• Blueprint Authority: Any

GetFiredEvents → Set of GameplayTag

• Description: Returns all rare events that have already fired this session.
• Parameters: None
• Blueprint Authority: Any

GetEligibleEvents → Array of DA_RareEvent

• Description: Returns all rare events that are currently eligible (conditions met, not yet fired).
• Parameters: None
• Blueprint Authority: Any

ResetSession → void

• Description: Clears fired events and resets eligibility. Called on new game.
• Parameters: None
• Blueprint Authority: Any

SetRollInterval → void

• Description: Adjusts the periodic roll check interval.
• Parameters:

  Param	Type	Description
  Interval	Float	New interval in seconds

• Blueprint Authority: Any

---

5. Event Dispatchers

Dispatcher	Parameters	Bind Access	Description
OnRareEventFired	EventTag: GameplayTag	Public	A rare event was triggered
OnRareEventFailed	EventTag: GameplayTag	Public	Probability roll failed for an eligible event
OnAllRareEventsFired	—	Public	All events in pool have been fired

---

6. Overridden Events / Custom Events

Event: BeginPlay

• Description: Initialises the rare event pool and starts the periodic roll timer.
• Flow:
  1. Build EligibilityConditions map from RareEventPool entries
  2. Start RollTimer with RollInterval
  3. Perform initial roll check

Event: TickRoll

• Description: Timer callback. Performs a rare event roll check.
• Flow:
  1. Call RollForRareEvent
  2. If event fired → broadcast OnRareEventFired
  3. If all events in pool are fired → stop timer and broadcast OnAllRareEventsFired

---

7. Blueprint Graph Logic Flow

flowchart TD
    A[BeginPlay] --> B[Build EligibilityConditions map]
    B --> C[Start RollTimer at RollInterval]
    C --> D[Timer fires]
    D --> E[GetEligibleEvents]
    E --> F{Any eligible events?}
    F -->|No| G[Wait for next tick]
    F -->|Yes| H[For each eligible event:]
    H --> I[Roll random against DA_RareEvent.Probability]
    I --> J{Roll <= Probability?}
    J -->|Yes| K[Fire the rare event]
    J -->|No| L[Broadcast OnRareEventFailed]
    K --> M[Add to FiredRareEvents]
    M --> N[Broadcast OnRareEventFired]
    N --> O{All events fired?}
    O -->|Yes| P[Stop RollTimer]
    O -->|No| G
    L --> H
    P --> Q[Broadcast OnAllRareEventsFired]

---

8. Communication Matrix

Who Talks	How	What Is Sent
BPC_AdaptiveEnvironmentDirector	Direct call	RollForRareEvent()
BPC_NarrativeStateSystem	Direct read	Narrative flags for eligibility condition checks
BPC_PlaystyleClassifier	Direct read	CurrentPlaystyleTag for playstyle-gated events
GS_CoreGameState	Direct read	ElapsedPlayTime, ActiveChapterTag
DA_RareEvent	Data asset read	Event def: tag, probability, conditions, actions

---

9. Validation / Testing Checklist

• S_RareEventCondition struct has all 6 fields
• RareEventPool is populated with DA_RareEvent assets
• IsEventEligible correctly checks all condition types
• RollForRareEvent respects probability values (0.0 = never, 1.0 = always)
• FiredRareEvents prevents repeat triggering
• ForceRareEvent bypasses all checks for scripted/debug use
• RollTimer stops when all events exhausted
• Edge case: RareEventPool empty → no errors, timer still runs harmlessly
• Edge case: all events fired → OnAllRareEventsFired broadcasts once
• Edge case: rapid probability rolls don't fire same event twice (FiredRareEvents set check)

---

10. Reuse Notes

• RareEventPool is population-defined — populate per project with unique events
• Probability values in DA_RareEvent are designer-tuned per event (0.001 for ultra-rare, 0.1 for uncommon)
• Eligibility conditions support complex gating (chapter, playstyle, time, death count)
• For non-horror games, fill pool with easter eggs and hidden secrets instead of scary events
• Extend S_RareEventCondition with project-specific gates (e.g., specific item held, specific ending achieved)

---

Specification based on Master Section 9.9, line 2922.