162 lines
6.5 KiB
Markdown
162 lines
6.5 KiB
Markdown
# DA_PuzzleData — Puzzle Data Asset
|
||
|
||
## Blueprint Spec — UE 5.5–5.7
|
||
|
||
---
|
||
|
||
### Parent Class
|
||
`UPrimaryDataAsset`
|
||
|
||
### Dependencies
|
||
- **Requires:** GameplayTags — PuzzleTag, OnSolveFlag, OnFailFlag
|
||
- **Required By:** [`BP_PuzzleDeviceActor`](../03-interaction/BP_PuzzleDeviceActor.md) — Reads puzzle solution data at runtime
|
||
- **Required By:** [`BPC_NarrativeStateSystem`](../07-narrative/38_BPC_NarrativeStateSystem.md) — OnSolveFlag/OnFailFlag set as narrative flags
|
||
- **Engine/Plugin Requirements:** GameplayTags
|
||
|
||
### Purpose
|
||
Defines a puzzle's solution, constraints, and outcome flags. Each puzzle in the game has a corresponding DA_PuzzleData asset that the [`BP_PuzzleDeviceActor`](../03-interaction/BP_PuzzleDeviceActor.md) reads at runtime. The solution, attempt limits, time limits, and narrative flag consequences are all data-driven — no puzzle logic is hardcoded.
|
||
|
||
---
|
||
|
||
## 1. Enums
|
||
|
||
*No enums defined. Uses GameplayTags for all outcome and condition flags.*
|
||
|
||
---
|
||
|
||
## 2. Structs
|
||
|
||
### `S_PuzzleSolution`
|
||
| Field | Type | Description |
|
||
|-------|------|-------------|
|
||
| `SolutionType` | E_PuzzleInputType | How the solution is structured (Sequence, Combination, Timing, Pattern, ToggleSet) |
|
||
| `SequenceEntries` | Array of Integer | For sequence-type puzzles: the correct order of inputs |
|
||
| `CombinationValues` | Array of Name | For combination-type puzzles: correct values per input |
|
||
| `PatternTimings` | Array of Float | For timing/pattern puzzles: expected input timings |
|
||
| `ToggleTargets` | Array of GameplayTag | For toggle puzzles: which toggles must be ON |
|
||
| `Tolerance` | Float | Acceptable deviation (for timing puzzles) |
|
||
|
||
### `S_PuzzleConfig`
|
||
| Field | Type | Description |
|
||
|-------|------|-------------|
|
||
| `PuzzleTag` | GameplayTag | Unique identifier for this puzzle |
|
||
| `PuzzleType` | E_PuzzleType | Logical puzzle category |
|
||
| `Solution` | S_PuzzleSolution | The correct solution definition |
|
||
| `MaxAttempts` | Integer | Maximum allowed attempts (0 = unlimited) |
|
||
| `TimeLimit` | Float | Time limit in seconds (0 = unlimited) |
|
||
| `OnSolveFlag` | GameplayTag | Narrative flag set when puzzle is solved |
|
||
| `OnFailFlag` | GameplayTag | Narrative flag set when puzzle fails permanently |
|
||
| `bResettable` | Bool | Whether the puzzle can be retried after failure |
|
||
| `ResetDelay` | Float | Seconds before puzzle resets after failure |
|
||
| `RequiredFlag` | GameplayTag | Narrative flag required to interact with puzzle |
|
||
| `FailPenalty` | E_PuzzleFailPenalty | What happens on failure (None, Damage, Stress, Trapped, SpawnEnemy) |
|
||
| `FailPenaltyValue` | Float | Magnitude of fail penalty (damage amount, stress amount) |
|
||
|
||
---
|
||
|
||
## 3. Variables
|
||
|
||
### Data Asset Fields
|
||
|
||
| Variable | Type | Default | Category | Description |
|
||
|----------|------|---------|----------|-------------|
|
||
| `PuzzleTag` | GameplayTag | — | Identity | Unique puzzle identifier |
|
||
| `PuzzleType` | E_PuzzleType | Sequence | Solution | Logical puzzle category |
|
||
| `DisplayName` | FText | — | Presentation | Puzzle name shown to player |
|
||
| `PromptText` | FText | — | Presentation | Interaction prompt text |
|
||
| `SolutionSequence` | Array of Integer | Empty | Solution | Correct input sequence |
|
||
| `CombinationValues` | Array of Name | Empty | Solution | Correct combination values |
|
||
| `MaxAttempts` | Integer | 3 | Constraints | Max wrong attempts before permanent fail |
|
||
| `TimeLimit` | Float | 0.0 | Constraints | Time limit in seconds (0=unlimited) |
|
||
| `OnSolveFlag` | GameplayTag | — | Consequences | Narrative flag set on solve |
|
||
| `OnFailFlag` | GameplayTag | — | Consequences | Narrative flag set on permanent fail |
|
||
| `bResettable` | Bool | True | Config | Can retry after failure |
|
||
| `ResetDelay` | Float | 2.0 | Config | Seconds before reset |
|
||
| `RequiredFlag` | GameplayTag | — | Conditions | Flag required to interact |
|
||
| `FailPenalty` | E_PuzzleFailPenalty | None | Consequences | Effect on failure |
|
||
| `FailPenaltyValue` | Float | 0.0 | Consequences | Magnitude of penalty effect |
|
||
| `AvailableInputs` | Array of Integer | Empty | UI | Valid input values shown to player |
|
||
| `bShowSolutionProgress` | Bool | True | UI | Show partial progress during attempt |
|
||
|
||
---
|
||
|
||
## 4. Enums (Puzzle System)
|
||
|
||
```text
|
||
Enum Name: E_PuzzleType
|
||
(DisplayName = "Puzzle Type")
|
||
|
||
Values:
|
||
Sequence = 0 // Input a specific sequence of buttons/actions
|
||
Combination = 1 // Enter a correct combination/code
|
||
Timing = 2 // Match a rhythm or timing pattern
|
||
ToggleSet = 3 // Set a group of toggles to correct positions
|
||
PatternMatch = 4 // Match a displayed pattern
|
||
```
|
||
|
||
```text
|
||
Enum Name: E_PuzzleInputType
|
||
(DisplayName = "Puzzle Input Type")
|
||
|
||
Values:
|
||
Sequence = 0 // Ordered inputs
|
||
Combination = 1 // Named value inputs
|
||
Timing = 2 // Time-based inputs
|
||
Pattern = 3 // Position/pattern inputs
|
||
ToggleSet = 4 // Boolean toggle inputs
|
||
```
|
||
|
||
```text
|
||
Enum Name: E_PuzzleFailPenalty
|
||
(DisplayName = "Puzzle Fail Penalty")
|
||
|
||
Values:
|
||
None = 0 // No penalty
|
||
Damage = 1 // Deal damage to player
|
||
Stress = 2 // Increase stress
|
||
Trapped = 3 // Trigger environmental trap
|
||
SpawnEnemy = 4 // Spawn enemy encounter
|
||
LockPermanent = 5 // Permanently lock puzzle
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Functions
|
||
|
||
*Data asset only. No runtime functions. Data is read by [`BP_PuzzleDeviceActor`](../03-interaction/BP_PuzzleDeviceActor.md) at runtime.*
|
||
|
||
---
|
||
|
||
## 6. Event Dispatchers
|
||
|
||
*Data asset only. No event dispatchers.*
|
||
|
||
---
|
||
|
||
## 7. Validation / Testing Checklist
|
||
|
||
- [ ] PuzzleTag is unique and valid GameplayTag
|
||
- [ ] SolutionSequence/CombinationValues matches PuzzleType
|
||
- [ ] OnSolveFlag and OnFailFlag are valid GameplayTags
|
||
- [ ] MaxAttempts of 0 = unlimited attempts
|
||
- [ ] TimeLimit of 0 = no time pressure
|
||
- [ ] FailPenalty matches game systems (Damage targets BPC_HealthSystem, Stress targets BPC_StressSystem)
|
||
- [ ] RequiredFlag correctly gates puzzle interaction
|
||
- [ ] Edge case: all puzzles solved → narrative state reflects all OnSolveFlags
|
||
- [ ] Edge case: permanent fail with no fail flag → puzzle locks silently
|
||
- [ ] Edge case: resettable with ResetDelay of 0 → immediate reset
|
||
|
||
---
|
||
|
||
## 8. Reuse Notes
|
||
|
||
- One DA_PuzzleData per puzzle in the game
|
||
- PuzzleType determines how BP_PuzzleDeviceActor processes input
|
||
- E_PuzzleInputType tells the puzzle device what input mechanism to use (buttons, text, timing, toggles)
|
||
- FailPenalty allows puzzles to have real stakes without scripting per puzzle
|
||
- Extend S_PuzzleSolution with new solution types per project
|
||
- For non-puzzle games, leave this data asset unused
|
||
|
||
---
|
||
|
||
*Specification based on Master Section 13, line 3420.* |