# BP_PuzzleDeviceActor — Puzzle Device Actor

**Parent Class:** `Actor`
**Category:** Interaction
**Target UE Version:** 5.5–5.7
**Build Phase:** 2 — Interaction

---

## 1. Overview

`BP_PuzzleDeviceActor` is the base actor for all puzzle devices in the world — levers, pressure plates, valve wheels, keypads, combination locks, circuit boards, and custom logic puzzles. Each instance references a [`DA_PuzzleData`](../14-data-assets/DA_PuzzleData.md) that defines the puzzle rules, solution, and completion effects.

---

## 2. Enums

### `E_PuzzleType`

| Value | Description |
|-------|-------------|
| `Lever` | Single or multi-lever sequence |
| `PressurePlate` | Weight-activated plate |
| `ValveWheel` | Rotate-to-open valve |
| `Keypad` | Numeric code entry |
| `CombinationLock` | Multi-dial combination |
| `CircuitBoard` | Connect-the-pins puzzle |
| `Custom` | Script-driven puzzle |

### `E_PuzzleState`

| Value | Description |
|-------|-------------|
| `Unsolved` | Puzzle not yet completed |
| `InProgress` | Player interacting with puzzle |
| `Solved` | Puzzle completed successfully |
| `Failed` | Puzzle failed (if retryable) |
| `Locked` | Puzzle locked (requires item/flag) |

---

## 3. Variables

| Variable | Type | Description |
|----------|------|-------------|
| `PuzzleData` | `DA_PuzzleData*` | Data asset defining this puzzle |
| `CurrentState` | `E_PuzzleState` | Current puzzle state |
| `bIsInteractable` | `bool` | Can player interact with this puzzle |
| `InteractionPrompt` | `FText` | Prompt text for interaction |
| `LinkedActor` | `AActor*` | Actor to notify on solve (door, gate, etc.) |
| `bResetOnFail` | `bool` | Auto-reset after failure |
| `MaxAttempts` | `int32` | Max attempts before lockout (-1 = unlimited) |
| `CurrentAttempts` | `int32` | Attempts used so far |
| `CooldownSeconds` | `float` | Time before re-interaction allowed |

---

## 4. Functions

| Function | Description |
|----------|-------------|
| `BeginInteraction` | Player starts interacting with puzzle |
| `EndInteraction` | Player exits puzzle UI |
| `CheckSolution` | Validates player input against puzzle data |
| `OnPuzzleSolved` | Processes completion — notifies LinkedActor |
| `OnPuzzleFailed` | Processes failure — resets or locks |
| `ResetPuzzle` | Resets puzzle to default state |
| `GetPuzzleState` | Returns current `E_PuzzleState` |

---

## 5. Event Dispatchers

| Dispatcher | Payload | Description |
|------------|---------|-------------|
| `OnPuzzleStateChanged` | `E_PuzzleState NewState` | State transition occurred |
| `OnPuzzleSolved` | `AActor* Solver` | Puzzle completed |
| `OnPuzzleFailed` | `int32 AttemptNumber` | Attempt failed |
| `OnPuzzleLinkedActorTriggered` | `AActor* LinkedActor` | Linked actor notified |

---

## 6. Dependencies & Communication

| System | Relationship |
|--------|--------------|
| `DA_PuzzleData` | Defines puzzle rules and solution |
| `BPC_InteractionDetector` | Focus and interaction initiation |
| `BP_DoorActor` | Common linked actor (unlock on solve) |
| `BPC_NarrativeStateSystem` | Set narrative flags on solve |
| `SS_SaveManager` | Persist puzzle state |

---

## 7. Reuse Notes
- All puzzle logic is data-driven via `DA_PuzzleData`
- LinkedActor pattern decouples puzzle from effect