diff --git a/Interaction-%26-World-Manipulation-Systems.md b/Interaction-%26-World-Manipulation-Systems.md new file mode 100644 index 0000000..c58a953 --- /dev/null +++ b/Interaction-%26-World-Manipulation-Systems.md @@ -0,0 +1,244 @@ +# 03 — Interaction & World Manipulation Systems (Systems 16-23) + +**Category Purpose:** These 8 systems handle everything the player can do with the world — detecting interactable objects, opening doors, solving puzzles, traversing obstacles, dragging physics objects, using world devices (levers, buttons), viewing diegetic displays, and finding hiding spots. The `BPC_InteractionDetector` is the central hub; all other systems respond to its dispatchers or interface calls. + +--- + +## System Index + +| # | System | Asset Type | Role | +|---|--------|-----------|------| +| 16 | `BPC_InteractionDetector` | Component | Raycast interaction detection hub; holds/press/double-tap | +| 17 | `I_HidingSpot` | Interface | Interface for hideable world objects | +| 18 | `BPC_DiegeticDisplay` | Component | In-world screens (wristwatch, monitors, holograms) | +| 19 | `BP_DoorActor` | Actor | Physical door: 6-state machine, lock/barricade/key | +| 20 | `BP_PuzzleDeviceActor` | Actor | Puzzle device base: state machine, solution checking | +| 21 | `BPC_ContextualTraversalSystem` | Component | Vault/mantle/slide/squeeze via Motion Warping | +| 22 | `BPC_PhysicsDragSystem` | Component | Grab/drag/release physics objects | +| 23 | `BPC_UsableWorldObjectSystem` | Component | Generic world objects: levers, valves, buttons, panels | + +--- + +## Category Data Flow + +``` +┌────────────────────────────────────────────────────────────────────┐ +│ INTERACTION FLOW │ +│ │ +│ BPC_InteractionDetector (runs on player) │ +│ │ Timer-based sphere trace every 0.1s │ +│ │ Filters by: I_Interactable interface │ +│ │ Sorts by: Priority (Emergency > High > Normal > Low) │ +│ │ then Distance (closest wins) │ +│ ├─► OnTargetFound → WBP_InteractionPromptDisplay (show prompt) │ +│ │ │ +│ │ On player input: │ +│ ├─► Press: immediate interaction │ +│ ├─► Hold: radial progress fill → interaction on complete │ +│ └─► DoubleTap: two rapid presses │ +│ │ +│ Target types are routed: │ +│ ├─► BP_DoorActor.Interact_Implementation → door logic │ +│ ├─► BP_PuzzleDeviceActor.Interact_Implementation → puzzle │ +│ ├─► BP_ItemPickup.Interact_Implementation → inventory add │ +│ ├─► BP_ContainerInventory.Interact_Implementation → container │ +│ ├─► BP_UsableWorldObject.Interact_Implementation → lever/etc. │ +│ └─► I_HidingSpot → BPC_HidingSystem.EnterHideSpot() │ +│ │ +│ Independent systems (not through InteractionDetector): │ +│ ├─► BPC_ContextualTraversalSystem (movement-based, auto-detect) │ +│ └─► BPC_PhysicsDragSystem (grab input, physics constraint) │ +└────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 16 — BPC_InteractionDetector: The Interaction Hub + +**What It Does:** The player's "interaction eye" — performs continuous sphere traces forward from the camera, detects all `I_Interactable` actors within range, sorts them by priority and distance, selects the best target, and manages the interaction prompt UI. Every interactive object in the game funnels through this component. + +**How It Works Internally:** + +**Detection Loop:** +- Timer fires every `ScanInterval` (default 0.1s) +- Sphere trace forward: `InteractionRange` (default 250cm), `DetectionAngle` cone, `TraceRadius` sphere +- Each hit actor checked for `I_Interactable` implementation +- Duplicates removed, sorted by `Priority` descending then `Distance` ascending +- Clamped to `MaxTargetsInRange` (default 16) +- `DetectionState` tracks: NoTarget → TargetInRange → TargetConfirmed → Interacting + +**Input Modes:** +- `Press`: Single press to interact (standard) +- `Hold`: Hold button for `HoldDuration` seconds with progress bar +- `DoubleTap`: Two rapid presses within threshold +- `Auto`: Triggers on proximity without input + +**Interaction Protocol:** +1. Player presses interact → `OnInputInteractPressed` +2. If `DetectionState >= TargetConfirmed` and input mode matches: + - Press mode: calls `PerformInteraction(Press)` immediately + - Hold mode: starts hold timer, fires `OnHoldProgressUpdated` each tick (for radial UI fill) + - DoubleTap mode: waits for second press within window +3. `PerformInteraction` sets `bIsPerformingInteraction = true`, calls `CurrentTarget.InterfaceRef.ExecuteInteraction(Instigator)` +4. Waits for interaction completion or timeout +5. On completion/cancel: resumes scanning + +**Blocking Conditions:** +- During death (`bBlockDuringDeath`): interaction blocked +- While hidden (`bBlockDuringHiding`): blocked (player is inside a locker) +- During combat (`bBlockDuringCombat`): optionally blocked +- While already interacting (`bIsPerformingInteraction`): blocked (no double-interact) + +**Target Scoring:** +- `CalculateInteractionScore()`: `Score = Priority * 100 - Distance * 0.5` +- Facing bonus: if camera angle to target < 15°, add 50 +- Best target = highest score within range + +**Implementation Patterns:** +- Trace pauses while interacting, resumes after completion +- `ForceSetTarget(Actor)` for scripted interactions (cutscene buttons) +- Highlight effect applied to current target via `I_Interactable.SetHighlighted()` +- Enter/exit tracking: fires `OnTargetEntered`/`OnTargetExited` when actors enter/leave range + +**Integration Points:** +- **Broadcasts:** `OnTargetFound/Lost`, `OnInteractionStarted/Completed/Cancelled/Error`, `OnHoldProgressUpdated` +- **Calls:** `I_Interactable.ExecuteInteraction()` on target, `I_Interactable.SetHighlighted()` +- **Listens to:** `BPC_MovementStateSystem.OnPostureChanged`, `BPC_HealthSystem.OnDeathStateChanged` + +--- + +## 17 — I_HidingSpot: Hiding Spot Interface + +**What It Does:** Interface that all hideable world objects must implement. Provides slot management, entry/exit transforms, peek capability, and type classification. + +**Key Functions:** +- `GetHideSpotInfo()` → returns `S_HideSpotInfo` (type, slots, peek sockets, exit location, tags) +- `HasAvailableSlots()` → boolean for occupancy check +- `OnPlayerEntered(Player)` / `OnPlayerExited(Player)` → notify on occupancy change +- `GetEntryAnimation()` / `GetExitAnimation()` → animation montages for smooth transitions +- `IsDetectableFrom(EnemyLocation)` → LOS check helper + +**Implementation:** Actors like lockers, wardrobes, beds, tall grass volumes, and shadow volumes implement this interface. The `BPC_HidingSystem` calls these functions to manage hide state. + +--- + +## 18 — BPC_DiegeticDisplay: In-World Screens + +**What It Does:** Manages in-world display surfaces — the player's wristwatch UI, computer monitors, holographic projectors, and security camera feeds. These are diegetic (exist in the game world) rather than screen-space UI. + +**Key Features:** +- Renders widget blueprints onto world-space surfaces via `WidgetComponent` +- Supports multiple display types: wristwatch, monitor, hologram, projection +- Screen power states: on/off/damaged/static +- Distortion effects for damaged screens +- Interaction-based activation (press E on monitor to view) + +--- + +## 19 — BP_DoorActor: Physical Door System + +**What It Does:** Powers all door-like actors — hinged doors, sliding doors, double doors, roll-up doors, and trap doors. Manages a 6-state machine with lock/key mechanics, barricade health, one-way passage, auto-close, and puzzle-linked unlocking. + +**State Machine:** +``` +Closed → Opening → Open → Closing → Closed + ↑ ↓ +Locked ← (unlock transitions to Closed) + ↑ +Barricaded → (break) → Closed +``` + +**Lock Types:** Unlocked, KeyRequired (specific key item), ItemRequired (crowbar/code), PuzzleLinked (external puzzle), Breachable (force/weapon) + +**Animation System:** +- Uses Timeline to interpolate door rotation (hinged) or translation (sliding) from 0→OpenAngle +- `OpenSpeed` and `CloseSpeed` control animation rate +- `AutoCloseDelay` starts timer after open; resets on re-open +- `LinkedActors` array notified on open/close (lights, alarms, traps) + +**Implementation Patterns:** +- Implements `I_Interactable` — called by InteractionDetector +- `TryUnlockWithItem()` queries `BPC_InventorySystem` for required key +- `DamageBarricade()` reduces health, broadcasts `OnBarricadeBroken` at 0 +- `ForceSetState()` for save/load restoration — bypasses animation +- One-way doors track which side was opened from (`bIsOpenFromFront`) + +**Integration Points:** +- **Called by:** `BPC_InteractionDetector` (interact) +- **Queries:** `BPC_InventorySystem` (key check) +- **Notifies:** `LinkedActors`, AI perception (pathfinding update), AudioManager (door sounds), Save System + +--- + +## 20 — BP_PuzzleDeviceActor: Puzzle Device Base + +**What It Does:** Base class for puzzle devices — combination locks, pressure plate sequences, symbol matching, pipe routing, and any interactive puzzle. Manages a state machine, validates solutions, and provides hints and rewards. + +**Features:** +- State machine: Idle → Active → Solved → Failed +- Solution checking against `DA_PuzzleData` Data Asset +- Hint system with configurable hint count and cooldown +- Reward dispatching on solve (item grant, door unlock, narrative flag set) +- Linked actor notifications (unlock connected door, activate machine) +- Timer-based puzzles with configurable countdown + +--- + +## 21 — BPC_ContextualTraversalSystem: Vaulting & Climbing + +**What It Does:** Handles player traversal of environmental obstacles using UE5 Motion Warping. Detects traversable surfaces (low walls, ledges, gaps, barriers) and plays root motion traversal montages with precise target alignment. + +**Traversal Types:** Vault (low obstacles), Mantle (ledges), Slide (under barriers), Squeeze (narrow gaps), LedgeGrab (hang from ledges) + +**Detection:** +- Forward capsule trace at waist, chest, and head heights +- Classifies obstacles by height: Low (step up), Medium (vault), High (mantle) +- Cooldown between traversals prevents animation spam + +**Motion Warping:** +- Calculates exact target location for landing +- Warps root motion to hit target precisely +- `bIsTraversing` flag blocks input and other actions during animation + +--- + +## 22 — BPC_PhysicsDragSystem: Object Grabbing + +**What It Does:** Enables the player to grab, drag, and release physics-simulated objects. Uses physics constraints for smooth dragging and supports throw mechanics. + +**Features:** +- Grab detection via line trace from camera +- Physics constraint attaches object to player's "hold position" +- Rotation control while held (mouse wheel or gamepad) +- Throw with configurable force on release +- Weight limit: heavier objects require more time to lift +- Works with `I_Holdable` interface for puzzle-specific objects + +--- + +## 23 — BPC_UsableWorldObjectSystem: Generic World Devices + +**What It Does:** Provides a generic interaction system for world objects that don't fit into door/puzzle/pickup categories — levers, valves, buttons, switches, panels, dials, and crank handles. + +**Features:** +- Implements `I_Interactable`, `I_Toggleable`, and `I_Adjustable` interfaces +- Binary devices (levers, buttons): toggle on/off +- Analog devices (valves, dials): continuous adjustment via mouse wheel or hold-and-drag +- Linked actor notifications: pulling a lever opens a gate elsewhere +- Animation playback with configurable duration +- State persistence via `I_Persistable` + +--- + +## Common Implementation Patterns in This Category + +1. **Interface-Driven Detection:** `BPC_InteractionDetector` doesn't know about doors, pickups, or puzzles — it only checks for `I_Interactable`. Any new interactable just implements the interface. +2. **Priority Sorting:** Emergency targets (hide spots in combat) always selected over Low priority (ambient items). +3. **State Machines on Actors:** Doors, puzzles, and devices all use discrete state machines exposed via dispatchers — never polling. +4. **Linked Actor Pattern:** Doors/puzzles/devices can notify other actors (lights, traps, doors) on state change via `LinkedActors` array. +5. **Input Mode Variety:** Press for quick actions, Hold for deliberate actions (pick lock, solve puzzle), DoubleTap for rapid actions. +6. **Save-Aware:** All interactive objects implement `I_Persistable` for state restoration. + +--- + +*Developer Reference v1.0 — 03 Interaction Systems. Companion to docs/blueprints/03-interaction/ specs.*