131 lines
6.2 KiB
Markdown
131 lines
6.2 KiB
Markdown
# 43 — BPC_TrialScenarioSystem
|
||
|
||
## Blueprint Spec — UE 5.5–5.7
|
||
|
||
---
|
||
|
||
### Parent Class
|
||
`ActorComponent`
|
||
|
||
### Dependencies
|
||
- [`BPC_NarrativeStateSystem`](58_BPC_NarrativeStateSystem.md)
|
||
- [`BPC_ObjectiveSystem`](39_BPC_ObjectiveSystem.md)
|
||
- [`DA_ScenarioData`](../12-content/48_DA_NarrativeDataAssets.md)
|
||
- [`BPC_CheckpointSystem`](../04-save/34_BPC_CheckpointSystem.md)
|
||
- [`BPC_DeathHandlingSystem`](../04-save/35_BPC_DeathHandlingSystem.md)
|
||
|
||
### Purpose
|
||
Manages trial-based gameplay scenarios: combat gauntlets, escape sequences, investigation time-limits, survival waves. Tracks trial state (setup / active / success / fail), enforces rules, and reports outcome to the narrative system.
|
||
|
||
### Responsibilities
|
||
- Load scenario definition from `DA_ScenarioData`
|
||
- Initialize world state for the trial (spawn enemies, lock doors, set lighting)
|
||
- Track trial objectives and completion conditions
|
||
- Monitor failure conditions (player death, time expiry, target escape)
|
||
- Broadcast success/failure to narrative state
|
||
- Clean up trial elements on completion
|
||
|
||
### Does NOT Handle
|
||
- Individual enemy AI (that is Phase 8 AI system)
|
||
- Lighting or atmosphere changes (that is Phase 9 AtmosphereController)
|
||
- Checkpoint creation (that is BPC_CheckpointSystem)
|
||
|
||
### Variables
|
||
|
||
| Name | Type | Description |
|
||
|------|------|-------------|
|
||
| `ActiveScenario` | DA_ScenarioData | Currently running scenario (null if none) |
|
||
| `ScenarioState` | EScenarioState | Current phase of scenario |
|
||
| `ScenarioStartTime` | Float | World time when scenario began |
|
||
| `SuccessTags` | Array of GameplayTag | Tags to set on success (fired to NarrativeState) |
|
||
| `FailureTags` | Array of GameplayTag | Tags to set on failure |
|
||
| `bHasCheckedFailure` | Bool | Already evaluated fail conditions this tick |
|
||
|
||
### Enums
|
||
|
||
| Enum | Values | Description |
|
||
|------|--------|-------------|
|
||
| `EScenarioState` | Inactive, SetupRunning, ActiveRunning, Success, Failure, Cleanup | Lifecycle of a trial scenario |
|
||
|
||
### Structs
|
||
|
||
| Struct | Fields | Description |
|
||
|--------|--------|-------------|
|
||
| `FScenarioObjective` | TargetTag: GameplayTag, RequiredCount: Integer, CurrentCount: Integer, bIsComplete: Bool | A tracked objective within the scenario |
|
||
| `FScenarioCompletionReport` | bSuccess: Bool, ElapsedTime: Float, ObjectivesCompleted: Integer, ObjectivesTotal: Integer, FlagsSet: Array of GameplayTag | Outcome report for narrative |
|
||
|
||
### Functions / Events
|
||
|
||
| Name | Inputs | Outputs | Description |
|
||
|------|--------|---------|-------------|
|
||
| `BeginScenario` | Scenario: DA_ScenarioData | — | Start a new trial scenario |
|
||
| `EndScenario` | bIsSuccess: Bool | — | End current scenario with outcome |
|
||
| `UpdateObjectiveProgress` | ObjectiveTag: GameplayTag, Delta: Integer | — | Increment/update objective tracker |
|
||
| `CheckAllObjectives` | — | Bool | Have all objectives been met? |
|
||
| `CheckFailureConditions` | — | Bool | Has any failure condition triggered? |
|
||
| `GetTimeRemaining` | — | Float | Time left if scenario has time limit |
|
||
| `GetElapsedTime` | — | Float | Seconds since scenario started |
|
||
| `GetScenarioCompletionReport` | — | FScenarioCompletionReport | |
|
||
| `AbortScenario` | — | — | Force-end with failure, clean up |
|
||
| `IsScenarioActive` | — | Bool | |
|
||
|
||
### Event Dispatchers
|
||
|
||
| Name | Parameters | Fired When |
|
||
|------|-----------|-----------|
|
||
| `OnScenarioStarted` | Scenario: DA_ScenarioData | Scenario begins setup |
|
||
| `OnScenarioActive` | Scenario: DA_ScenarioData | Setup complete, trial is live |
|
||
| `OnObjectiveProgressed` | ObjectiveTag: GameplayTag, Progress: Integer, Required: Integer | Any objective count changed |
|
||
| `OnScenarioSuccess` | Report: FScenarioCompletionReport | All objectives complete |
|
||
| `OnScenarioFailure` | Report: FScenarioCompletionReport | Failure condition met |
|
||
| `OnScenarioAborted` | Scenario: DA_ScenarioData | Force-aborted |
|
||
| `OnScenarioCleanup` | Scenario: DA_ScenarioData | Cleanup complete |
|
||
|
||
### Blueprint Flow
|
||
|
||
```
|
||
[BeginScenario: DA_ScenarioData]
|
||
└─► Set ScenarioState = SetupRunning
|
||
└─► Broadcast OnScenarioStarted
|
||
└─► Trigger checkpoint auto-save (if configured)
|
||
└─► Execute scenario setup actions from DA_ScenarioData:
|
||
└─► Spawn enemies on spawn points
|
||
└─► Lock / unlock doors by tag
|
||
└─► Set initial objective state from scenario definition
|
||
└─► Apply lighting overrides (via AtmosphereController if present)
|
||
└─► Set ScenarioState = ActiveRunning
|
||
└─► Broadcast OnScenarioActive
|
||
└─► Record ScenarioStartTime + start tick monitors
|
||
|
||
[Tick / UpdateObjectiveProgress]
|
||
└─► CheckAllObjectives → if true → EndScenario(success = true)
|
||
└─► If not bHasCheckedFailure → CheckFailureConditions
|
||
└─► If failure condition true → EndScenario(success = false)
|
||
|
||
[EndScenario: bIsSuccess]
|
||
└─► ScenarioState = Success or Failure
|
||
└─► Build FScenarioCompletionReport
|
||
└─► Broadcast appropriate dispatcher
|
||
└─► Set narrative success/failure tags via BPC_NarrativeStateSystem
|
||
└─► ScenarioState = Cleanup
|
||
└─► Execute cleanup actions:
|
||
└─► Despawn trial-specific actors
|
||
└─► Reset doors, lights, etc.
|
||
└─► Unlock doors that were locked for trial
|
||
└─► Broadcast OnScenarioCleanup
|
||
└─► ScenarioState = Inactive
|
||
└─► ActiveScenario = null
|
||
```
|
||
|
||
### Communications With
|
||
|
||
| Target System | Method | Why |
|
||
|---------------|--------|-----|
|
||
| [`BPC_NarrativeStateSystem`](58_BPC_NarrativeStateSystem.md) | Direct | Set success/failure flags upon completion |
|
||
| [`BPC_ObjectiveSystem`](39_BPC_ObjectiveSystem.md) | Direct | Sync scenario objectives with objective UI |
|
||
| [`BPC_CheckpointSystem`](../04-save/34_BPC_CheckpointSystem.md) | Direct | Create checkpoint on scenario start |
|
||
| [`BPC_DeathHandlingSystem`](../04-save/35_BPC_DeathHandlingSystem.md) | Dispatcher | Player death triggers scenario failure |
|
||
| Phase 8 AI | Indirect | Spawn/despawn enemy actors by tag |
|
||
|
||
### Reuse Notes
|
||
Scenarios are fully data-driven via `DA_ScenarioData`. Designers configure spawn tags, objective tags, time limits, and cleanup actions without blueprint modifications. Supports mixed scenarios: combat + investigation, timed + untimed, survival + objective. |