# 48 — DA_NarrativeDataAssets (Collection)

## Blueprint Spec — UE 5.5–5.7

---

### Purpose
This file defines all Data Asset types used by the Narrative systems. Each data asset subclass is a standalone asset that designers create in the Content Browser to author narrative content without blueprint modifications.

### Relationship to Systems

| Data Asset | Consumed By | Purpose |
|-----------|-------------|---------|
| `DA_DialogueSequence` | [`BPC_DialoguePlaybackSystem`](40_BPC_DialoguePlaybackSystem.md) | Dialogue lines, voiceover, subtitles |
| `DA_ConsequenceRule` | [`BPC_BranchingConsequenceSystem`](42_BPC_BranchingConsequenceSystem.md) | Flag → action mapping |
| `DA_EndingData` | [`BPC_EndingAccumulatorSystem`](45_BPC_EndingAccumulatorSystem.md) | Ending evaluation criteria |
| `DA_LoreEntryData` | [`BPC_LoreUnlockSystem`](46_BPC_LoreUnlockSystem.md) | Lore content and metadata |
| `DA_ScenarioData` | [`BPC_TrialScenarioSystem`](43_BPC_TrialScenarioSystem.md) | Trial scenario definition |
| `DA_CutsceneData` | [`BPC_CutsceneBridge`](44_BPC_CutsceneBridge.md) | Cutscene playback configuration |

---

### 48.1 — DA_DialogueSequence

**Parent Class:** `PrimaryDataAsset`

#### Variables

| Name | Type | Description |
|------|------|-------------|
| `DialogueTag` | GameplayTag | Unique identifier for this sequence |
| `SpeakerName` | FText | Display name for UI subtitle |
| `DialogueLines` | Array of FDialogueLine | Ordered lines in this sequence |
| `bLooping` | Bool | Repeat sequence until manually stopped |
| `bInterruptible` | Bool | Can be skipped / interrupted |
| `Priority` | Integer | Higher priority interrupts lower |
| `Category` | GameplayTag | e.g., "Dialogue.Major", "Dialogue.Ambient" |
| `PrerequisiteFlags` | Array of GameplayTag | Must all be set for this sequence to play |
| `ConsequenceFlagsOnComplete` | Array of GameplayTag | Flags set when sequence finishes |

#### Struct: FDialogueLine

| Field | Type | Description |
|-------|------|-------------|
| `LineText` | FText | Subtitle text |
| `VoiceoverSoftRef` | SoftObjectPath (USoundWave) | Audio file for this line |
| `Duration` | Float | Seconds (0 = auto-calculate from audio) |
| `EmotionOverride` | GameplayTag | e.g., "Emotion.Angry", "Emotion.Whisper" |
| `bWaitForInput` | Bool | Pause after line until player presses continue |
| `LineFlagsToSet` | Array of GameplayTag | Narrative flags set when this line plays |
| `CustomDelayAfter` | Float | Extra pause after this line before next |

---

### 48.2 — DA_ConsequenceRule

**Parent Class:** `PrimaryDataAsset`

#### Variables

| Name | Type | Description |
|------|------|-------------|
| `RuleTag` | GameplayTag | Unique identifier |
| `TriggerFlagTag` | GameplayTag | Which flag change triggers this rule |
| `bTriggerOnSet` | Bool | Fire when flag is set |
| `bTriggerOnClear` | Bool | Fire when flag is cleared |
| `RequiredContextFlags` | Array of GameplayTag | Additional flags that must be set for rule to fire |
| `ExclusiveContextFlags` | Array of GameplayTag | Flags that block this rule |
| `Actions` | Array of FConsequenceAction | Actions to execute |
| `bIsImmediate` | Bool | Always immediate (overrides per-action delay) |
| `Priority` | Integer | Execution order (higher first) |
| `bOnlyOnce` | Bool | Remove rule after first fire |
| `CooldownSeconds` | Float | Prevent re-fire within cooldown |

#### Struct: FConsequenceAction

| Field | Type | Description |
|-------|------|-------------|
| `ActionType` | EConsequenceActionType | PlayDialogue / UpdateObjective / SetFlag / ClearFlag / TriggerCutscene / UnlockLore / ModifyStat / SpawnActor / DestroyActor |
| `TargetTag` | GameplayTag | Target dialogue sequence, lore entry, etc. |
| `FloatValue` | Float | Numeric modifier for stat changes |
| `StringValue` | FString | Actor tag for spawn/destroy |
| `DelaySeconds` | Float | Delay before this action executes |
| `bBlocking` | Bool | Wait for completion before next action |

---

### 48.3 — DA_EndingData

**Parent Class:** `PrimaryDataAsset`

#### Variables

| Name | Type | Description |
|------|------|-------------|
| `EndingTag` | GameplayTag | Unique identifier |
| `EndingName` | FText | Display name for UI / debug |
| `EndingDescription` | FText | Brief description |
| `Priority` | Integer | Higher priority endings win over lower |
| `RequiredFlagTags` | Array of GameplayTag | All must be set to qualify |
| `ExclusiveFlagTags` | Array of GameplayTag | None must be set to qualify |
| `MinScore` | Float | Minimum accumulated score to qualify |
| `ScoreEntries` | Array of FEndingScoreEntry | Flags that contribute score |
| `CutsceneData` | TSoftObjectPtr<DA_CutsceneData> | Ending cutscene to play |
| `bIsFallbackEnding` | Bool | Always available if no other ending qualifies |
| `EndingRewards` | Array of GameplayTag | Bonuses, unlocks, achievements granted |

#### Struct: FEndingScoreEntry

| Field | Type | Description |
|-------|------|-------------|
| `FlagTag` | GameplayTag | Flag that grants score when set |
| `ScoreValue` | Float | Points awarded |
| `ScoreCategory` | FName | Group for UI display |

---

### 48.4 — DA_LoreEntryData

**Parent Class:** `PrimaryDataAsset`

#### Variables

| Name | Type | Description |
|------|------|-------------|
| `LoreTag` | GameplayTag | Unique identifier |
| `EntryType` | ELoreEntryType | Document, AudioLog, Note, EnvironmentalText, BestiaryEntry, Collectible |
| `CategoryTag` | GameplayTag | e.g., "Lore.Notes.DrWatson", "Lore.Bestiary.Creatures" |
| `Title` | FText | Entry title |
| `BodyText` | FText | Main content text |
| `FlavorText` | FText | Optional flavor/subtitle |
| `AudioSoftRef` | SoftObjectPath (USoundWave) | Audio narration (if audio log) |
| `AudioDuration` | Float | Length of audio in seconds |
| `ImageSoftRef` | SoftObjectPath (UTexture2D) | Optional image / photo |
| `UnlockMethod` | ELoreDiscoveryMethod | OnPickup / OnNarrativeFlag / OnLocationEnter / OnInteraction / OnConsequence |
| `UnlockFlagTag` | GameplayTag | If OnNarrativeFlag, which flag triggers unlock |
| `RequiredFlags` | Array of GameplayTag | Prerequisite flags |
| `SeriesTag` | GameplayTag | Part of a series (e.g., "Lore.Series.InvestigationNotes") |
| `SeriesIndex` | Integer | Order within series |
| `IsTimedEntry` | Bool | Entry expires after game time |
| `TimeToLiveSeconds` | Float | How long entry remains available |
| `bAutoReadOnUnlock` | Bool | Auto-mark as read when discovered |

---

### 48.5 — DA_ScenarioData

**Parent Class:** `PrimaryDataAsset`

#### Variables

| Name | Type | Description |
|------|------|-------------|
| `ScenarioTag` | GameplayTag | Unique identifier |
| `ScenarioName` | FText | Display name |
| `ScenarioType` | EScenarioType | CombatGauntlet, EscapeSequence, InvestigationTimed, SurvivalWave, Mixed |
| `TimeLimitSeconds` | Float | 0 = no time limit |
| `bFailOnPlayerDeath` | Bool | Player death = scenario failure |
| `SpawnTags` | Array of GameplayTag | Enemy / actor tags to spawn |
| `SpawnPointTags` | Array of GameplayTag | Where to spawn them |
| `Objectives` | Array of FScenarioObjectiveDef | Scenario objectives |
| `FailureConditions` | Array of FScenarioFailureCondition | What triggers failure |
| `LockedDoorTags` | Array of GameplayTag | Doors to lock during scenario |
| `UnlockOnSuccessDoorTags` | Array of GameplayTag | Doors to unlock on success |
| `SuccessFlags` | Array of GameplayTag | Flags set on success |
| `FailureFlags` | Array of GameplayTag | Flags set on failure |
| `CutsceneOnStart` | TSoftObjectPtr<DA_CutsceneData> | Cutscene before scenario |
| `CutsceneOnSuccess` | TSoftObjectPtr<DA_CutsceneData> | Cutscene on success |
| `CutsceneOnFailure` | TSoftObjectPtr<DA_CutsceneData> | Cutscene on failure |
| `bCreateCheckpointOnStart` | Bool | Auto-save before scenario |

#### Enums

| Enum | Values | Description |
|------|--------|-------------|
| `EScenarioType` | CombatGauntlet, EscapeSequence, InvestigationTimed, SurvivalWave, Mixed | Scenario gameplay type |

#### Struct: FScenarioObjectiveDef

| Field | Type | Description |
|-------|------|-------------|
| `ObjectiveTag` | GameplayTag | Reference to objective system |
| `Description` | FText | Objective description |
| `RequiredCount` | Integer | How many to complete |
| `bIsOptional` | Bool | Not required for success |

#### Struct: FScenarioFailureCondition

| Field | Type | Description |
|-------|------|-------------|
| `ConditionType` | EFailureConditionType | TimeExpired / PlayerDeath / TargetEscaped / ObjectiveFailed |
| `TargetTag` | GameplayTag | Specific target reference |
| `FloatParam` | Float | Threshold (e.g., max deaths) |

---

### 48.6 — DA_CutsceneData

**Parent Class:** `PrimaryDataAsset`

#### Variables

| Name | Type | Description |
|------|------|-------------|
| `CutsceneTag` | GameplayTag | Unique identifier |
| `CutsceneName` | FText | Editor display name |
| `SequenceSoftReference` | TSoftObjectPtr<ALevelSequenceActor> | The Level Sequence to play |
| `TransitionType` | ECutsceneTransitionType | FadeInOut, HardCut, LetterBox, BlackBars |
| `TransitionDuration` | Float | Fade duration in seconds |
| `bCanSkip` | Bool | Player can skip |
| `TimeBeforeSkipAvailable` | Float | Seconds before skip is enabled |
| `SkipHoldDuration` | Float | Hold seconds to skip |
| `Milestones` | Array of FCutsceneMilestone | Narrative flags at specific times |
| `bAutoSaveBefore` | Bool | Create checkpoint before cutscene |
| `bRestorePlayerState` | Bool | Save and restore player stats after |
| `DialogueSequences` | Array of TSoftObjectPtr<DA_DialogueSequence> | Subtitled dialogue during cutscene |
| `OnCompleteFlags` | Array of GameplayTag | Flags set when cutscene ends |
| `OnSkippedFlags` | Array of GameplayTag | Flags set if player skips |
| `bHideHUD` | Bool | Auto-hide HUD during cutscene |
| `bSuppressPlayerInput` | Bool | Disable player input during cutscene |

#### Struct: FCutsceneMilestone

| Field | Type | Description |
|-------|------|-------------|
| `TimeSeconds` | Float | Sequence timecode |
| `FlagTag` | GameplayTag | Flag to set |
| `bFireOnce` | Bool | Only fire if not already set |

---

### Asset Registration Pattern

All narrative data assets should be registered in the **Primary Asset Registry** (Project Settings > Asset Manager) with the appropriate scan paths:

| Data Asset | Directory Convention | Asset Prefix |
|-----------|---------------------|--------------|
| DA_DialogueSequence | `/Game/Dialogue/` | `SEQ_` |
| DA_ConsequenceRule | `/Game/Narrative/Consequences/` | `CON_` |
| DA_EndingData | `/Game/Narrative/Endings/` | `END_` |
| DA_LoreEntryData | `/Game/Narrative/Lore/` | `LORE_` |
| DA_ScenarioData | `/Game/Narrative/Scenarios/` | `SCEN_` |
| DA_CutsceneData | `/Game/Cinematics/CutsceneData/` | `CUT_` |

### Save System Integration

Each data asset is identified by its `Tag` field (GameplayTag). The narrative state system saves and loads only the tag references and flag states — the data assets themselves are loaded from content references and never serialized into save data. This means:
- Flags persisted as `Set<GameplayTag>` in save file
- Lore unlocked/read persisted as `Set<GameplayTag>`
- Data assets can be modified between saves without breaking save compatibility