UE5-Modular-Game-Framework/docs/blueprints/14-data-assets/125_DA_RareEvent.md

DA_RareEvent — Rare Event Data Asset

Blueprint Spec — UE 5.5–5.7

---

Parent Class

UPrimaryDataAsset

Dependencies

• Requires: GameplayTags — EventTag, EventConditions, EventActions
• Required By: BPC_RareEventSystem — Reads rare event pool at runtime, rolls probability, fires events
• Engine/Plugin Requirements: GameplayTags

Purpose

Defines a single rare world event that can occur with limited probability during gameplay. Each rare event asset specifies its unique tag, probability of occurrence, eligibility conditions, resulting actions, and whether it can fire only once per session.

---

1. Enums

Enum Name: E_RareEventActionType
(DisplayName = "Rare Event Action Type")

Values:
  PlayAudio              = 0    // Play a one-shot sound or stinger
  SpawnActor             = 1    // Spawn a visual/hallucination actor
  TriggerScreenEffect    = 2    // Trigger a screen effect (vignette, flash)
  SetNarrativeFlag       = 3    // Set a narrative flag
  TriggerDialogue        = 4    // Play a dialogue line or sequence
  ModifyAtmosphere       = 5    // Temporarily change atmosphere state
  SpawnCollectible       = 6    // Spawn a hidden collectible
  DisplayMessage         = 7    // Show a subtitle/message to player
  ModifyLighting         = 8    // Change room lighting temporarily
  TeleportEntity         = 9    // Teleport an entity near player briefly

---

2. Structs

S_RareEventAction

Field	Type	Description
ActionType	E_RareEventActionType	What kind of action to perform
ActionTag	GameplayTag	Action-specific identifier (audio cue, actor class, effect tag)
ActionValue	Float	Numeric parameter (duration, intensity, volume)
Delay	Float	Seconds to wait before executing this action

---

3. Variables

Data Asset Fields

Variable	Type	Default	Category	Description
EventTag	GameplayTag	—	Identity	Unique identifier for this rare event
DisplayName	FText	—	Editor	Human-readable name for designers
Probability	Float	0.01	Core	Chance of occurring on each roll (0.0–1.0)
EventConditions	Array of GameplayTag	Empty	Conditions	Narrative flags required for event to be eligible
ForbiddenConditions	Array of GameplayTag	Empty	Conditions	Narrative flags that block the event if set
EventActions	Array of S_RareEventAction	Empty	Actions	Sequence of actions executed when event fires
bOncePerSession	Bool	True	Core	If true, event fires at most once per game session
bOncePerSaveFile	Bool	False	Core	If true, event fires at most once per save file lifetime
bBlockOtherEvents	Bool	False	Core	No other rare events can fire during this event's action sequence
RequiredPlaystyleTag	GameplayTag	—	Conditions	Player must have this playstyle for eligibility
RequiredChapterTag	GameplayTag	—	Conditions	Current chapter must match for eligibility
MinSessionTime	Float	0.0	Conditions	Minimum session elapsed time before eligible
MinDeathCount	Integer	0	Conditions	Minimum player deaths before eligible
MaxOccurrences	Integer	1	Limits	Maximum times event can occur (overrides bOncePerSession)
CooldownAfterFire	Float	0.0	Limits	Cooldown in seconds before this event is eligible again
Priority	Integer	0	Core	Priority over other events when multiple are eligible (higher = first)

---

4. Functions

Data asset only. No runtime functions. Data is read by BPC_RareEventSystem at runtime.

---

5. Event Dispatchers

Data asset only. No event dispatchers.

---

6. Validation / Testing Checklist

• EventTag is unique and valid GameplayTag
• Probability is in range 0.0–1.0 (0.001 = 0.1%, 0.01 = 1%, 0.1 = 10%)
• EventConditions tags exist in DA_GameTagRegistry
• EventActions array has at least one action
• S_RareEventAction.ActionType matches the data needed (audio uses ActionTag for cue, spawn uses ActionTag for actor class)
• bOncePerSession and bOncePerSaveFile properly gated (don't set both unless intended)
• Priority values correctly order competing events
• Edge case: Probability of 0.0 = never fires randomly (scripted only)
• Edge case: Probability of 1.0 = always fires when eligible
• Edge case: empty EventConditions = always eligible
• Edge case: CooldownAfterFire of 0 = no cooldown (only gated by bOncePerSession/MaxOccurrences)

---

7. Example Data Row

Field	Value	Note
EventTag	RareEvent.Hallucination.CorridorGhost	Unique identifier
DisplayName	"Corridor Ghost Sighting"	Designer reference name
Probability	0.005	0.5% chance per roll
EventConditions	[Narrative.Phase.Ch2, Player.Stress.High]	Only in chapter 2 when stress is high
ForbiddenConditions	[Narrative.Flag.SeenGhost]	Doesn't repeat if already seen
EventActions	[SpawnActor(GhostMesh, 0.5, 0.0), TriggerScreenEffect(Flash, 0.3, 0.5), PlayAudio(GhostWhisper, 0.8, 1.0)]	Three sequential actions
bOncePerSession	True	Don't repeat
bOncePerSaveFile	False	Can appear in different save files
RequiredPlaystyleTag	Cautious	Prefer scaring cautious players
RequiredChapterTag	Narrative.Phase.Ch2	Only in chapter 2
MinSessionTime	600.0	At least 10 minutes played
MinDeathCount	2	Player must have died at least twice
Priority	5	Higher than ambient events, lower than story reveals

---

8. Reuse Notes

• One DA_RareEvent per rare world occurrence
• Probability values should be very low (0.001–0.05) for true "rare" feel
• EventActions array supports complex multi-step sequences with delays
• bBlockOtherEvents prevents simultaneous rare events from stacking
• For non-horror games, use rare events for easter eggs and hidden content instead of scares
• Extend E_RareEventActionType with new action types per project
• CooldownAfterFire allows events to repeat within a session without being once-only

---

Specification based on Master Section 13, line 3422.