250 lines
11 KiB
Markdown
250 lines
11 KiB
Markdown
# 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 |