# 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`](../10-adaptive/BPC_RareEventSystem.md) — 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

```text
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`](../10-adaptive/BPC_RareEventSystem.md) 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 GI_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.*