Add haptics example documentation for Project Void controller feedback

- Introduced comprehensive guide for setting up controller haptics and force feedback. - Detailed directory structure for haptic profiles and creation steps for DA_HapticProfile instances. - Included platform-specific configurations for Xbox and PS5 DualSense adaptive triggers. - Outlined wiring of BPC_HapticsController to various gameplay systems and events. - Provided accessibility integration options and testing checklist for haptic functionality.
2026-05-22 17:16:34 +03:00
parent 7c2e8df6b1
commit 14441c000c
16 changed files with 1213 additions and 46 deletions
--- a/docs/blueprints/12-settings/148_BPC_HapticsController.md
+++ b/docs/blueprints/12-settings/148_BPC_HapticsController.md
@@ -0,0 +1,577 @@
+# 148 — Haptics Controller (`BPC_HapticsController`)
+
+> **Blueprint-Only Implementation** — UE 5.5–5.7 fully supports controller haptics/force feedback from Blueprints. No C++ required. This component wraps UE5's `Play Force Feedback`, `Set Haptics By Value`, and DualSense adaptive trigger APIs behind a GameplayTag-driven event system.
+
+---
+
+## Purpose
+Abstraction layer for all controller haptic feedback and force feedback effects. Gameplay systems trigger haptics by GameplayTag (e.g., `Haptic.Damage.Heavy`) rather than calling raw UE5 haptic APIs. This component handles platform detection (Xbox rumble vs PS5 DualSense adaptive triggers vs generic PC gamepad), respects accessibility settings (`BPC_AccessibilitySettings.bHapticsEnabled`), and manages effect priority/conflict resolution.
+
+## Dependencies
+- **Requires:** [`DA_HapticProfile`](docs/blueprints/14-data-assets/121_DA_HapticProfile.md) (effect definitions), [`BPC_AccessibilitySettings`](docs/blueprints/12-settings/104_BPC_AccessibilitySettings.md) (master toggle), [`BPC_StateManager`](docs/blueprints/16-state/130_BPC_StateManager.md) (heart rate for heartbeat haptic)
+- **Required By:** `BPC_HealthSystem` (damage haptics), `BPC_FirearmSystem` (weapon fire kick), `BPC_MeleeSystem` (melee impact), `BPC_PhysicsDragSystem` (grab/release), `BPC_ScareEventSystem` (tension rumble), `BP_ItemPickup` (pickup pulse), `BPC_MovementStateSystem` (footstep rumble via GASP notifies)
+- **Engine/Plugin Requirements:** Enhanced Input Plugin (controller detection), PlayStation 5 Controller Plugin (DualSense adaptive triggers — optional, graceful fallback)
+
+## Class Info
+| Property | Value |
+|----------|-------|
+| **Parent Class** | `ActorComponent` |
+| **Class Type** | Blueprint Component |
+| **Asset Path** | `Content/Framework/Settings/BPC_HapticsController` |
+| **Implements Interfaces** | None |
+| **Attachment** | Player Controller (`PC_CoreController`) |
+
+---
+
+## 1. Enums
+
+### `EHapticEvent`
+| Value | Description |
+|-------|-------------|
+| `None = 0` | No haptic effect |
+| `Damage = 1` | Player takes damage (intensity scales with amount) |
+| `HeavyDamage = 2` | Critical/major damage hit |
+| `Heartbeat = 3` | Heartbeat pulse (tempo from BPC_StateManager heart rate) |
+| `WeaponFire = 4` | Weapon fire kick |
+| `WeaponReload = 5` | Reload action feedback |
+| `MeleeImpact = 6` | Melee weapon hit/kill |
+| `Footstep = 7` | Footstep surface-dependent rumble |
+| `Explosion = 8` | Nearby explosion or environmental blast |
+| `PickupItem = 9` | Item picked up |
+| `DropItem = 10` | Item dropped/discarded |
+| `GrabObject = 11` | Physics object grabbed |
+| `ReleaseObject = 12` | Physics object released/thrown |
+| `ScareEvent = 13` | Jump scare / tension event |
+| `AmbientPulse = 14` | Low-level ambient tension rumble |
+| `UI_Confirm = 15` | Menu confirm/select haptic click |
+| `UI_Navigate = 16` | Menu navigation tick |
+| `LowHealth = 17` | Health-critical warning pulse |
+| `StaminaExhausted = 18` | Stamina depleted heavy pulse |
+| `Death = 19` | Player death rumble |
+
+### `EHapticMotor`
+| Value | Description |
+|-------|-------------|
+| `Left = 0` | Left (low-frequency) motor only |
+| `Right = 1` | Right (high-frequency) motor only |
+| `Both = 2` | Both motors simultaneously |
+
+### `EControllerPlatform`
+| Value | Description |
+|-------|-------------|
+| `Unknown = 0` | Platform not yet detected |
+| `PC_Generic = 1` | PC with generic gamepad (XInput) |
+| `Xbox = 2` | Xbox Series X\|S / Xbox One controller |
+| `PS5_DualSense = 3` | PlayStation 5 DualSense controller |
+| `PS4_DualShock = 4` | PlayStation 4 DualShock 4 controller |
+
+---
+
+## 2. Structs
+
+### `S_HapticRequest`
+| Field | Type | Description |
+|-------|------|-------------|
+| `ProfileTag` | `FGameplayTag` | Which DA_HapticProfile to use |
+| `EventType` | `EHapticEvent` | Event category |
+| `IntensityMultiplier` | `Float` | Scale intensity (0.0–2.0, 1.0 = default) |
+| `DurationOverride` | `Float` | Override duration (-1 = use profile default) |
+| `Priority` | `Int32` | Higher interrupts lower (0–100) |
+| `RequestTime` | `Float` | Game time when requested (for cooldown) |
+
+---
+
+## 3. Variables
+
+### Configuration (Instance Editable)
+| Variable | Type | Default | Category | Description |
+|----------|------|---------|----------|-------------|
+| `HapticProfileMap` | `TMap<FGameplayTag, DA_HapticProfile>` | `Empty` | `Config` | All haptic profiles loaded at startup |
+| `bHapticsEnabled` | `Bool` | `true` | `Config` | Master toggle (synced from BPC_AccessibilitySettings) |
+| `bEnableDualSenseTriggers` | `Bool` | `true` | `Config` | Enable adaptive trigger effects on PS5 |
+| `bEnableSpeakerAudio` | `Bool` | `true` | `Config` | Enable controller speaker audio on PS5 |
+| `MinTimeBetweenEffects` | `Float` | `0.05` | `Config` | Minimum seconds between any two effects (prevents rumble spam) |
+| `HapticIntensityScale` | `Float` | `1.0` | `Config` | Global intensity multiplier (0.0 = off, 1.0 = full) |
+| `HeartbeatMinBPM` | `Float` | `40.0` | `Config` | Minimum BPM for heartbeat haptic |
+| `HeartbeatMaxBPM` | `Float` | `180.0` | `Config` | Maximum BPM for heartbeat haptic |
+
+### Internal (Private)
+| Variable | Type | Default | Category | Description |
+|----------|------|---------|----------|-------------|
+| `CurrentPlatform` | `EControllerPlatform` | `Unknown` | `State` | Detected controller platform |
+| `bIsInitialized` | `Bool` | `false` | `State` | Whether Initialize has completed |
+| `CachedPlayerController` | `APlayerController` | `None` | `Cache` | Cached owner PlayerController reference |
+| `ActiveHapticEffect` | `UForceFeedbackEffect` | `None` | `State` | Currently playing effect asset |
+| `LastPlayTime` | `Float` | `0.0` | `State` | Game time of last played effect |
+| `PendingRequest` | `S_HapticRequest` | `Empty` | `State` | Currently queued request |
+| `bHeartbeatActive` | `Bool` | `false` | `State` | Whether heartbeat loop is active |
+
+---
+
+## 4. Functions
+
+### Public Functions
+
+#### `Initialize` → `void`
+- **Description:** Detects controller platform, loads all `DA_HapticProfile` instances into `HapticProfileMap`, caches PlayerController.
+- **Parameters:** None
+- **Blueprint Authority:** Local Client Only
+- **Flow:**
+  1. Get Owner → Cast to `APlayerController` → Store as `CachedPlayerController`
+  2. Detect platform: Check `UGameplayStatics::GetPlatformName()` + connected input devices
+  3. Set `CurrentPlatform` (Xbox, PS5_DualSense, PS4_DualShock, or PC_Generic)
+  4. Load all `DA_HapticProfile` assets from `Content/Framework/DataAssets/Haptics/` into `HapticProfileMap`
+  5. If `BPC_AccessibilitySettings` exists on owner → bind to `OnHapticsToggleChanged`
+  6. Bind to `BPC_StateManager.OnHeartRateChanged` for heartbeat haptic
+  7. Set `bIsInitialized = true`
+  8. Broadcast `OnHapticsControllerInitialized`
+
+#### `PlayHapticByTag` → `void`
+- **Description:** Play a haptic effect by its GameplayTag. Main entry point for all gameplay systems.
+- **Parameters:**
+  | Param | Type | Description |
+  |-------|------|-------------|
+  | `ProfileTag` | `FGameplayTag` | Tag matching a DA_HapticProfile |
+  | `IntensityMultiplier` | `Float` | Scale intensity (default 1.0) |
+- **Blueprint Authority:** Local Client Only
+- **Flow:**
+  1. Validate `bHapticsEnabled` and `bIsInitialized` — if disabled, return
+  2. Check `MinTimeBetweenEffects` cooldown — if too soon, queue or skip
+  3. Look up `DA_HapticProfile` from `HapticProfileMap` by `ProfileTag`
+  4. If not found: log warning, return
+  5. Build `S_HapticRequest` with profile data
+  6. Call `PlayHapticInternal()` with the request
+  7. Broadcast `OnHapticPlayed` with tag
+
+#### `PlayHapticByEvent` → `void`
+- **Description:** Play a haptic effect by event type. Convenience wrapper for systems that don't know the exact tag.
+- **Parameters:**
+  | Param | Type | Description |
+  |-------|------|-------------|
+  | `EventType` | `EHapticEvent` | Which event to trigger |
+  | `IntensityMultiplier` | `Float` | Scale intensity (default 1.0) |
+- **Flow:** Converts `EHapticEvent` to default tag (e.g., `Damage` → `Haptic.Damage.Default`) and calls `PlayHapticByTag`.
+
+#### `StopHaptic` → `void`
+- **Description:** Stop all currently playing haptic effects.
+- **Flow:**
+  1. If `CachedPlayerController` valid: call `Stop Force Feedback` node
+  2. Set `ActiveHapticEffect = None`
+  3. If `bHeartbeatActive`: call `StopHeartbeatHaptic()`
+  4. Broadcast `OnHapticStopped`
+
+#### `PlayHeartbeatHaptic` → `void`
+- **Description:** Start or update the continuous heartbeat pulse haptic at the given BPM.
+- **Parameters:**
+  | Param | Type | Description |
+  |-------|------|-------------|
+  | `BeatsPerMinute` | `Float` | Heart rate in BPM (from BPC_StateManager) |
+- **Flow:**
+  1. Clamp BPM to `HeartbeatMinBPM` — `HeartbeatMaxBPM`
+  2. Calculate pulse interval: `Interval = 60.0 / BPM`
+  3. Set `bHeartbeatActive = true`
+  4. Start a looping timer at `Interval` seconds
+  5. Each tick: call `PlayHapticByTag(Haptic.Heartbeat)` with intensity from BPM
+  6. If BPM changes: update timer interval
+
+#### `StopHeartbeatHaptic` → `void`
+- **Description:** Stop the continuous heartbeat haptic loop.
+- **Flow:** Clear heartbeat timer, set `bHeartbeatActive = false`.
+
+#### `SetHapticsEnabled` → `void`
+- **Description:** Enable or disable all haptic output. Called by accessibility toggle.
+- **Parameters:**
+  | Param | Type | Description |
+  |-------|------|-------------|
+  | `bEnabled` | `Bool` | New state |
+- **Flow:**
+  1. Set `bHapticsEnabled = bEnabled`
+  2. If disabled: call `StopHaptic()`
+  3. Broadcast `OnHapticsEnabledChanged`
+
+#### `SetControllerPlatform` → `void`
+- **Description:** Force a specific controller platform (for testing or hot-swap).
+- **Parameters:**
+  | Param | Type | Description |
+  |-------|------|-------------|
+  | `Platform` | `EControllerPlatform` | Target platform |
+
+#### `GetControllerPlatform` → `EControllerPlatform`
+- **Description:** Returns the detected controller platform. Read-only.
+
+#### `IsDualSenseConnected` → `Bool`
+- **Description:** Returns true if a PS5 DualSense controller is detected.
+- **Flow:** Returns `CurrentPlatform == PS5_DualSense`
+
+#### `SetDualSenseTriggerEffect` → `void`
+- **Description:** Set adaptive trigger resistance on a specific DualSense trigger. No-op on non-DualSense platforms.
+- **Parameters:**
+  | Param | Type | Description |
+  |-------|------|-------------|
+  | `TriggerSide` | `Name` | "Left" or "Right" |
+  | `EffectType` | `Name` | "Resistance", "Vibration", "WeaponFire", "BowDraw", etc. |
+  | `StartPosition` | `Int32` | Trigger position where effect begins (0–9) |
+  | `Strength` | `Int32` | Effect strength (0–8) |
+- **Blueprint Authority:** Local Client Only
+- **Flow:**
+  1. If `CurrentPlatform != PS5_DualSense`: return (graceful no-op)
+  2. If `bEnableDualSenseTriggers == false`: return
+  3. Call platform-specific DualSense trigger API via `PlayerController`
+  4. Log effect for debugging
+
+### Protected / Private Functions
+
+#### `PlayHapticInternal` → `void`
+- **Description:** Core haptic playback logic. Resolves platform, selects the right effect asset, handles priority conflicts.
+- **Parameters:**
+  | Param | Type | Description |
+  |-------|------|-------------|
+  | `Request` | `S_HapticRequest` | Full haptic request |
+- **Flow:**
+  1. Check priority: if `Request.Priority < PendingRequest.Priority` and `PendingRequest` is active → skip
+  2. If `Request.Priority >= PendingRequest.Priority`: interrupt current effect
+  3. Resolve platform: select `UForceFeedbackEffect` from `DA_HapticProfile` for `CurrentPlatform`
+  4. If no platform-specific asset: fall back to generic PC effect
+  5. Apply `IntensityMultiplier` to `HapticIntensityScale`
+  6. Call `Play Force Feedback` node on `CachedPlayerController`:
+     - Input: `ForceFeedbackEffect`, `IntensityMultiplier`, `bLooping=false`, `bIgnoreTimeDilation=true`
+  7. Store as `ActiveHapticEffect`
+  8. Set `LastPlayTime = GameTimeInSeconds`
+  9. Broadcast `OnHapticPlayed`
+
+#### `DetectControllerPlatform` → `void`
+- **Description:** Queries the input system to determine which controller is connected.
+- **Flow:**
+  1. Check `UGameplayStatics::GetPlatformName()`
+  2. If platform contains "PS5" → `PS5_DualSense`
+  3. If platform contains "PS4" → `PS4_DualShock`
+  4. If platform contains "Xbox" or "XboxOne" or "XSX" → `Xbox`
+  5. Otherwise: check connected devices → if gamepad found → `PC_Generic`, else → `Unknown`
+
+---
+
+## 5. Event Dispatchers
+
+| Dispatcher | Parameters | Bind Access | Description |
+|------------|-----------|-------------|-------------|
+| `OnHapticsControllerInitialized` | — | `Public` | Fired after Initialize completes |
+| `OnHapticPlayed` | `FGameplayTag ProfileTag`, `EHapticEvent EventType`, `Float Intensity` | `Public` | Fired when any haptic effect starts |
+| `OnHapticStopped` | — | `Public` | Fired when haptics stop (manual or effect ends) |
+| `OnHapticsEnabledChanged` | `Bool bEnabled` | `Public` | Fired when master toggle changes |
+| `OnControllerPlatformChanged` | `EControllerPlatform NewPlatform` | `Public` | Fired on controller hot-swap |
+| `OnDualSenseTriggerActivated` | `Name TriggerSide`, `Name EffectType` | `Public` | Fired when adaptive trigger effect applied (PS5 only) |
+
+---
+
+## 6. Overridden Events / Custom Events
+
+### Event: `BeginPlay`
+- **Description:** Startup. Calls `Initialize()`.
+- **Flow:**
+  1. Call `Initialize()`
+  2. If `CachedPlayerController` is null: log error, return
+  3. Register for controller connection/disconnection events
+
+### Event: `EndPlay`
+- **Description:** Cleanup on component destruction.
+- **Flow:**
+  1. Call `StopHaptic()` (stop all effects)
+  2. Call `StopHeartbeatHaptic()`
+  3. Unbind from all dispatchers
+  4. Clear cached references
+
+---
+
+## 7. Blueprint Graph Logic Flow
+
+```mermaid
+flowchart TD
+    A[BeginPlay] --> B[Initialize]
+    B --> C{Detect Controller Platform}
+    C --> D[Set CurrentPlatform]
+    D --> E[Load DA_HapticProfile Map]
+    E --> F[Bind to AccessibilitySettings.OnHapticsToggleChanged]
+    F --> G[Bind to StateManager.OnHeartRateChanged]
+    G --> H[Broadcast OnInitialized]
+
+    I[PlayHapticByTag] --> J{bHapticsEnabled?}
+    J -->|No| K[Return]
+    J -->|Yes| L{Cooldown check}
+    L -->|TooSoon| M[Queue or skip]
+    L -->|OK| N[Lookup DA_HapticProfile]
+    N --> O{Found?}
+    O -->|No| P[Log Warning]
+    O -->|Yes| Q[Build S_HapticRequest]
+    Q --> R[PlayHapticInternal]
+    R --> S{Platform == PS5?}
+    S -->|Yes| T[Play Force Feedback PS5 Profile]
+    S -->|No| U[Play Force Feedback Generic]
+    T --> V[Broadcast OnHapticPlayed]
+    U --> V
+
+    W[PlayHeartbeatHaptic] --> X[Clamp BPM]
+    X --> Y[Calculate Interval = 60/BPM]
+    Y --> Z[Start Looping Timer]
+    Z --> AA[Each Tick: PlayHapticByTag Haptic.Heartbeat]
+```
+
+---
+
+## 8. Communication Matrix
+
+| Who Talks | How | What Is Sent |
+|-----------|-----|-------------|
+| `BPC_HealthSystem` | `Function Call` | `BPC_HapticsController::PlayHapticByTag(Haptic.Damage.Heavy, Intensity)` on damage taken |
+| `BPC_FirearmSystem` | `Function Call` | `BPC_HapticsController::PlayHapticByTag(Haptic.WeaponFire.Pistol)` on fire |
+| `BPC_MeleeSystem` | `Function Call` | `BPC_HapticsController::PlayHapticByTag(Haptic.MeleeImpact)` on hit |
+| `BPC_PhysicsDragSystem` | `Function Call` | `BPC_HapticsController::PlayHapticByTag(Haptic.Grab)` / `Haptic.Release` |
+| `BPC_ScareEventSystem` | `Function Call` | `BPC_HapticsController::PlayHapticByTag(Haptic.ScareEvent)` on scare trigger |
+| `BPC_ReloadSystem` | `Function Call` | `BPC_HapticsController::PlayHapticByTag(Haptic.WeaponReload)` on reload complete |
+| `BP_ItemPickup` | `Function Call` | `BPC_HapticsController::PlayHapticByTag(Haptic.PickupItem)` on collect |
+| `BPC_MovementStateSystem` | `Function Call` | `BPC_HapticsController::PlayHapticByTag(Haptic.Footstep. + SurfaceTag)` via GASP notify |
+| `BPC_StateManager` | `Dispatcher` | `OnHeartRateChanged(BPM)` → `BPC_HapticsController::PlayHeartbeatHaptic(BPM)` |
+| `BPC_AccessibilitySettings` | `Dispatcher` | `OnHapticsToggleChanged(bEnabled)` → `BPC_HapticsController::SetHapticsEnabled()` |
+| `BPC_DeathHandlingSystem` | `Function Call` | `BPC_HapticsController::PlayHapticByTag(Haptic.Death)` on death |
+| `BPC_DamageReceptionSystem` | `Function Call` | `BPC_HapticsController::PlayHapticByTag(Haptic.Explosion)` on area damage |
+| `BPC_StaminaSystem` | `Function Call` | `BPC_HapticsController::PlayHapticByTag(Haptic.StaminaExhausted)` on empty |
+| `BPC_HealthSystem` (low) | `Function Call` | `BPC_HapticsController::PlayHapticByTag(Haptic.LowHealth)` when <25% HP |
+
+---
+
+## 9. Validation / Testing Checklist
+
+- [ ] `Initialize` correctly detects Xbox controller: `CurrentPlatform = Xbox`
+- [ ] `Initialize` correctly detects PS5 DualSense: `CurrentPlatform = PS5_DualSense`
+- [ ] `PlayHapticByTag` with valid tag plays force feedback on controller
+- [ ] `PlayHapticByTag` with invalid tag logs warning but does not crash
+- [ ] `StopHaptic` immediately stops all controller vibration
+- [ ] `bHapticsEnabled = false` causes all `PlayHapticByTag` calls to be skipped
+- [ ] Heartbeat haptic loops at correct interval (60 BPM → 1 pulse/second)
+- [ ] Heartbeat BPM changes dynamically when `PlayHeartbeatHaptic(120)` called
+- [ ] DualSense trigger resistance activates on PS5 (R2 stiffens when aiming)
+- [ ] Non-DualSense platforms gracefully skip trigger effects (no crash, no log spam)
+- [ ] Priority conflict: higher priority effect interrupts lower (damage overrides footstep)
+- [ ] `MinTimeBetweenEffects` prevents rapid-fire rumble spam
+- [ ] Edge case: `PlayHapticByTag` before `Initialize` logs warning and returns
+- [ ] Edge case: Controller disconnected mid-effect — `StopHaptic` called safely
+- [ ] Edge case: Multiple rapid `PlayHapticByTag` calls — only highest priority plays
+- [ ] Edge case: Platform hot-swap (Xbox → PS5) fires `OnControllerPlatformChanged`
+
+---
+
+## 10. Reuse Notes
+
+- Attach this component to the **Player Controller** (not the Pawn). Haptics are per-controller, per-player.
+- All gameplay systems trigger haptics via GameplayTag — never hardcode `Play Force Feedback` nodes.
+- The `DA_HapticProfile` Data Asset stores platform-specific `UForceFeedbackEffect` curves. Designers author these in the Content Browser without touching Blueprints.
+- For multiplayer: haptics are **local client only** — never replicated. The server doesn't need to know about controller vibration.
+- Heartbeat haptic is the only continuous/looping effect. All others are one-shot.
+- DualSense adaptive triggers require the **PS5 Controller Plugin** enabled. Framework gracefully degrades on other platforms.
+- The `Haptic.` GameplayTag namespace is documented in `DT_Tags_Player.csv` and `DA_GameTagRegistry`.
+- Accessibility: `bHapticsEnabled` syncs with `BPC_AccessibilitySettings` so players can disable all vibration from settings.
+- For platform profiles: create one `DA_HapticProfile` instance per event per platform, then reference all three in the profile map. `BPC_HapticsController` selects the right one at runtime.
+
+---
+
+## 11. Manual Implementation Guide
+
+> **This section is for a human implementer building the Blueprint manually in UE5.**
+> Follow these steps in order. Each function is broken down into specific UE5 Blueprint nodes.
+
+### 11.1 Class Setup
+
+1. Create a new Blueprint Class:
+   - Parent Class: `ActorComponent`
+   - Name: `BPC_HapticsController`
+   - Path: `Content/Framework/Settings/`
+2. Add all variables from Section 3 to the Class Defaults.
+   - Configuration variables: set `Instance Editable` ✓
+   - Internal variables: set to `Private` (no expose)
+3. Add the Event Dispatchers from Section 5.
+
+### 11.2 Variable Initialization (BeginPlay)
+
+```
+Event BeginPlay
+  ├─ Get Owner → Cast to PlayerController → Store as CachedPlayerController
+  │    └─ If NOT valid: Print String "BPC_HapticsController: Owner is not a PlayerController!" → Return
+  ├─ Call DetectControllerPlatform → Set CurrentPlatform
+  ├─ Load Asset Registry → Get All Assets of Class (DA_HapticProfile)
+  │    └─ ForEach: Add to HapticProfileMap [ProfileTag → Asset]
+  ├─ Get Owner → Get Component by Class (BPC_AccessibilitySettings)
+  │    └─ If valid: Bind Event OnHapticsToggleChanged → SetHapticsEnabled
+  │    └─ If valid: Read initial bHapticsEnabled value
+  ├─ Get Owner Pawn → Get Component by Class (BPC_StateManager)
+  │    └─ If valid: Bind Event OnHeartRateChanged → PlayHeartbeatHaptic
+  ├─ Set bIsInitialized = true
+  └─ Call OnHapticsControllerInitialized
+```
+
+### 11.3 Function Implementations
+
+#### `PlayHapticByTag`
+
+**Input Pins:** `ProfileTag` (GameplayTag), `IntensityMultiplier` (Float)
+**Output Pins:** None
+
+**Node-by-Node Logic:**
+```
+[Function: PlayHapticByTag]
+  Step 1: Branch on bHapticsEnabled → False: Return
+  Step 2: Get Game Time in Seconds → Subtract LastPlayTime → Compare to MinTimeBetweenEffects
+           Branch → Too soon: Return (or queue if needed)
+  Step 3: HapticProfileMap → Find (ProfileTag) → Store as FoundProfile
+  Step 4: Branch on FoundProfile valid?
+    True →
+      Step 4a: Make S_HapticRequest:
+         - ProfileTag = ProfileTag
+         - EventType = FoundProfile.EventType
+         - IntensityMultiplier = IntensityMultiplier
+         - DurationOverride = -1 (use profile default)
+         - Priority = FoundProfile.Priority
+      Step 4b: Call PlayHapticInternal(S_HapticRequest)
+      Step 4c: Call OnHapticPlayed(ProfileTag, FoundProfile.EventType, IntensityMultiplier)
+    False →
+      Step 4d: Print String Warning: "No haptic profile found for tag: {ProfileTag}"
+```
+
+**Nodes Used:** `Branch`, `FindGameplayTag`, `Map Find`, `Make Struct (S_HapticRequest)`, `Call Function`, `Print String`
+
+#### `PlayHapticInternal`
+
+**Input Pins:** `Request` (S_HapticRequest)
+**Output Pins:** None
+
+**Node-by-Node Logic:**
+```
+[Function: PlayHapticInternal]
+  Step 1: If ActiveHapticEffect is valid → Call StopHaptic (interrupt current)
+  Step 2: Break S_HapticRequest → get ProfileTag
+  Step 3: Look up DA_HapticProfile from HapticProfileMap
+  Step 4: Switch on CurrentPlatform:
+    Case PS5_DualSense: Get PS5_ForceFeedbackCurve from profile
+    Case Xbox: Get Xbox_ForceFeedbackCurve from profile
+    Default: Get Generic_ForceFeedbackCurve from profile
+  Step 5: Branch on selected curve valid?
+    True →
+      Step 5a: CachedPlayerController → Play Force Feedback
+         - Force Feedback Effect: selected curve asset
+         - Intensity Multiplier: Request.IntensityMultiplier * HapticIntensityScale
+         - bLooping: false
+         - bIgnore Time Dilation: true
+      Step 5b: Set ActiveHapticEffect = selected curve
+    False →
+      Step 5c: Print String Warning: "No ForceFeedbackEffect for platform {CurrentPlatform}"
+  Step 6: Set LastPlayTime = Get Game Time in Seconds
+```
+
+**Nodes Used:** `Switch on EControllerPlatform`, `Break S_HapticRequest`, `Map Find`, `Play Force Feedback (PlayerController)`, `Branch`
+
+#### `PlayHeartbeatHaptic`
+
+**Input Pins:** `BeatsPerMinute` (Float)
+**Output Pins:** None
+
+**Node-by-Node Logic:**
+```
+[Function: PlayHeartbeatHaptic]
+  Step 1: Clamp (BeatsPerMinute, HeartbeatMinBPM, HeartbeatMaxBPM) → Store as ClampedBPM
+  Step 2: Divide 60.0 / ClampedBPM → Store as PulseInterval
+  Step 3: If bHeartbeatActive:
+           True → Clear Timer by Handle (HeartbeatTimerHandle)
+  Step 4: Set bHeartbeatActive = true
+  Step 5: Set Timer by Event:
+    - Event: Custom Event (HeartbeatPulse)
+    - Time: PulseInterval
+    - Looping: true
+    - Store handle as HeartbeatTimerHandle
+  [Custom Event: HeartbeatPulse]
+    → Call PlayHapticByTag(Haptic.Heartbeat, 1.0)
+```
+
+**Nodes Used:** `Clamp (float)`, `Divide`, `Set Timer by Event`, `Clear Timer by Handle`
+
+#### `SetHapticsEnabled`
+
+**Input Pins:** `bEnabled` (Bool)
+**Output Pins:** None
+
+```
+[Function: SetHapticsEnabled]
+  Step 1: Set bHapticsEnabled = bEnabled
+  Step 2: Branch:
+    False → Call StopHaptic
+  Step 3: Call OnHapticsEnabledChanged(bEnabled)
+```
+
+#### `DetectControllerPlatform`
+
+```
+[Function: DetectControllerPlatform]
+  Step 1: Get Platform Name → Store as PlatformStr
+  Step 2: String Contains (PlatformStr, "PS5") → True: Set CurrentPlatform = PS5_DualSense → Return
+  Step 3: String Contains (PlatformStr, "PS4") → True: Set CurrentPlatform = PS4_DualShock → Return
+  Step 4: String Contains (PlatformStr, "Xbox") → True: Set CurrentPlatform = Xbox → Return
+  Step 5: Get Input Device Type → Switch on Type:
+    Gamepad → Set CurrentPlatform = PC_Generic
+    Default → Set CurrentPlatform = Unknown
+```
+
+**Nodes Used:** `Get Platform Name`, `Contains (string)`, `Switch on String`, `Get Input Device Type`
+
+### 11.4 Event Dispatcher Bindings (Inbound Listeners)
+
+| Bind to Dispatcher | Custom Event to Create | What it Does |
+|--------------------------------------|------------------------|--------------|
+| `BPC_StateManager.OnHeartRateChanged` | `OnHeartRateChanged_Handler` | `PlayHeartbeatHaptic(CurrentHeartRate)` |
+| `BPC_AccessibilitySettings.OnHapticsToggleChanged` | `OnHapticsToggle_Handler` | `SetHapticsEnabled(bEnabled)` |
+
+### 11.5 Multiplayer Networking
+
+- This component is **local client only**. No replication needed.
+- Haptics play only on the local player's controller.
+- No `HasAuthority()` gates needed — haptics are cosmetic.
+- For listen server hosts: `IsLocalPlayerController()` check before playing effects.
+
+### 11.6 Quick Node Reference
+
+| Node | Where to Find | Used For |
+|------|---------------|----------|
+| `Play Force Feedback` | Right-click → "Play Force Feedback" | Playing rumble effect on controller |
+| `Stop Force Feedback` | Right-click → "Stop Force Feedback" | Stopping all active vibration |
+| `Set Timer by Event` | Right-click → "Set Timer by Event" | Looping heartbeat pulse |
+| `Get Platform Name` | Right-click → "Get Platform Name" | Detecting Xbox/PS5/PC |
+| `Clamp (float)` | Right-click → "Clamp" | Clamping BPM range |
+| `Make Struct` | Right-click → "Make S_HapticRequest" | Building haptic request |
+| `Map Find` | Right-click → "Find" | Looking up profile by tag |
+| `Get Game Time in Seconds` | Right-click → "Get Game Time" | Cooldown tracking |
+
+---
+
+## 12. Blueprint Build Checklist
+
+- [ ] Create Blueprint class: `BPC_HapticsController` (parent: `ActorComponent`)
+- [ ] Add all variables from Section 3 with correct types and defaults
+- [ ] Create `EHapticEvent`, `EHapticMotor`, `EControllerPlatform` enums (in Content Browser)
+- [ ] Create `S_HapticRequest` struct (in Content Browser)
+- [ ] Build `BeginPlay` event → `Initialize` chain
+- [ ] Implement `DetectControllerPlatform` function
+- [ ] Implement `PlayHapticInternal` with Platform Switch
+- [ ] Implement `PlayHapticByTag` (public entry point)
+- [ ] Implement `PlayHapticByEvent` (convenience wrapper)
+- [ ] Implement `StopHaptic` / `StopHeartbeatHaptic`
+- [ ] Implement `PlayHeartbeatHaptic` with looping timer
+- [ ] Implement `SetHapticsEnabled` / `SetDualSenseTriggerEffect`
+- [ ] Create all 6 event dispatchers
+- [ ] Bind to `BPC_StateManager.OnHeartRateChanged`
+- [ ] Bind to `BPC_AccessibilitySettings.OnHapticsToggleChanged`
+- [ ] Create at least one `DA_HapticProfile` instance for `Haptic.Damage.Default`
+- [ ] Test: PlayHapticByTag triggers vibration on Xbox controller
+- [ ] Test: PlayHapticByTag triggers vibration on PS5 DualSense
+- [ ] Test: bHapticsEnabled=false blocks all effects
+- [ ] Test: Heartbeat BPM changes pitch/speed of pulse
+- [ ] Test: Rapid-fire calls respect MinTimeBetweenEffects
+
+---
+
+*Blueprint Spec: Haptics Controller. Conforms to TEMPLATE.md v2.0 — part of the UE5 Modular Game Framework, SETTINGS layer.*