Table of Contents

03 — Interaction & World Manipulation Systems (Systems 16-23)

System Index
Category Data Flow
16 — BPC_InteractionDetector: The Interaction Hub
17 — I_HidingSpot: Hiding Spot Interface
18 — BPC_DiegeticDisplay: In-World Screens
19 — BP_DoorActor: Physical Door System
20 — BP_PuzzleDeviceActor: Puzzle Device Base
21 — BPC_ContextualTraversalSystem: Vaulting & Climbing
22 — BPC_PhysicsDragSystem: Object Grabbing
23 — BPC_UsableWorldObjectSystem: Generic World Devices
Common Implementation Patterns in This Category

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:

Player presses interact → OnInputInteractPressed
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
PerformInteraction sets bIsPerformingInteraction = true, calls CurrentTarget.InterfaceRef.ExecuteInteraction(Instigator)
Waits for interaction completion or timeout
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

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.
Priority Sorting: Emergency targets (hide spots in combat) always selected over Low priority (ambient items).
State Machines on Actors: Doors, puzzles, and devices all use discrete state machines exposed via dispatchers — never polling.
Linked Actor Pattern: Doors/puzzles/devices can notify other actors (lights, traps, doors) on state change via LinkedActors array.
Input Mode Variety: Press for quick actions, Hold for deliberate actions (pick lock, solve puzzle), DoubleTap for rapid actions.
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.