# 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.*