add blueprints

docs/blueprints/03-interaction/20_BP_PuzzleDeviceActor.md

@@ -0,0 +1,97 @@
+# 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