UE5-Modular-Game-Framework/docs/game/haptics-example.md

Haptics Example — Project Void Controller Feedback

Version: 1.0 | Target UE: 5.5–5.7 | Framework System: BPC_HapticsController (148) + DA_HapticProfile (121)

---

Purpose

This document walks through setting up controller haptics/force feedback in the Project Void horror game prototype. It covers creating DA_HapticProfile Data Asset instances for every gameplay event, wiring BPC_HapticsController to all relevant systems, and platform-specific tuning for Xbox rumble and PS5 DualSense adaptive triggers.

Rule: All game haptic content lives in Content/Game/DataAssets/Haptics/. Never modify Content/Framework/Settings/BPC_HapticsController.

---

Game Haptics Directory Structure

Content/Game/DataAssets/
├── Haptics/                              ← ALL game haptic profiles
│   ├── DA_Haptic_Damage_Light.uasset
│   ├── DA_Haptic_Damage_Heavy.uasset
│   ├── DA_Haptic_Heartbeat_Normal.uasset
│   ├── DA_Haptic_Heartbeat_Fast.uasset
│   ├── DA_Haptic_Weapon_Pistol.uasset
│   ├── DA_Haptic_Weapon_Shotgun.uasset
│   ├── DA_Haptic_Weapon_Crowbar.uasset
│   ├── DA_Haptic_Reload.uasset
│   ├── DA_Haptic_Footstep_Tile.uasset
│   ├── DA_Haptic_Footstep_Wood.uasset
│   ├── DA_Haptic_Footstep_Concrete.uasset
│   ├── DA_Haptic_Explosion.uasset
│   ├── DA_Haptic_Pickup_Item.uasset
│   ├── DA_Haptic_Pickup_Weapon.uasset
│   ├── DA_Haptic_Grab_Object.uasset
│   ├── DA_Haptic_Release_Throw.uasset
│   ├── DA_Haptic_Scare_JumpScare.uasset
│   ├── DA_Haptic_Scare_TensionRise.uasset
│   ├── DA_Haptic_Ambient_Void.uasset
│   ├── DA_Haptic_LowHealth.uasset
│   ├── DA_Haptic_StaminaExhaust.uasset
│   ├── DA_Haptic_Death.uasset
│   ├── DA_Haptic_UI_Confirm.uasset
│   └── DA_Haptic_UI_Navigate.uasset

---

Step 1: Create DA_HapticProfile Data Asset Instances

For each event below, create a Data Asset instance in the Content Browser.

How to Create a Haptic Profile

1. Navigate to Content/Game/DataAssets/Haptics/
2. Right-click → Miscellaneous → Data Asset
3. Select class: DA_HapticProfile
4. Name: DA_Haptic_{Event} (see table below)
5. Open the asset → fill in the fields:
   • ProfileTag: The GameplayTag for this effect (e.g., Haptic.Damage.Light)
   • EventType: Select from EHapticEvent enum
   • ForceFeedbackEffect: Assign the UForceFeedbackEffect waveform curve asset
   • IntensityCurve: Optional UCurveFloat for intensity over time
   • Duration: Total effect seconds
   • MotorMask: Left, Right, or Both
   • Priority: 0 (lowest, like footsteps) to 100 (highest, like death)
   • bCanInterrupt: Whether lower-priority effects can interrupt this
   • PlatformMinIntensity: Minimum intensity before effect is felt

Complete Haptic Profile Data Table

Asset Name	GameplayTag	EventType	Duration	Motor	Priority	Trigger Condition
DA_Haptic_Damage_Light	Haptic.Damage.Light	Damage	0.15s	Both	60	Player takes ≤10 damage
DA_Haptic_Damage_Heavy	Haptic.Damage.Heavy	HeavyDamage	0.4s	Both	80	Player takes >30 damage
DA_Haptic_Damage_Critical	Haptic.Damage.Critical	HeavyDamage	0.6s	Both	90	Player HP <10% and hit
DA_Haptic_Heartbeat_Normal	Haptic.Heartbeat.Normal	Heartbeat	0.1s	Left	30	BPM 60–90 (calm/tense)
DA_Haptic_Heartbeat_Fast	Haptic.Heartbeat.Fast	Heartbeat	0.08s	Left	40	BPM 90–140 (scared)
DA_Haptic_Heartbeat_Panic	Haptic.Heartbeat.Panic	Heartbeat	0.05s	Both	50	BPM 140–180 (panic)
DA_Haptic_Weapon_Pistol	Haptic.WeaponFire.Pistol	WeaponFire	0.08s	Right	50	Pistol fired
DA_Haptic_Weapon_Shotgun	Haptic.WeaponFire.Shotgun	WeaponFire	0.25s	Both	70	Shotgun fired
DA_Haptic_Weapon_Crowbar	Haptic.MeleeImpact.Crowbar	MeleeImpact	0.15s	Both	55	Crowbar hits enemy
DA_Haptic_Reload	Haptic.WeaponReload	WeaponReload	0.1s	Right	40	Reload magazine click
DA_Haptic_Footstep_Tile	Haptic.Footstep.Tile	Footstep	0.02s	Left	10	Walking on tile floor
DA_Haptic_Footstep_Wood	Haptic.Footstep.Wood	Footstep	0.03s	Left	10	Walking on wood floor
DA_Haptic_Footstep_Concrete	Haptic.Footstep.Concrete	Footstep	0.04s	Both	10	Walking on concrete
DA_Haptic_Explosion	Haptic.Explosion	Explosion	0.6s	Both	85	Nearby explosion
DA_Haptic_Pickup_Item	Haptic.Pickup.Item	PickupItem	0.05s	Right	20	Item picked up
DA_Haptic_Pickup_Weapon	Haptic.Pickup.Weapon	PickupItem	0.1s	Both	25	Weapon equipped
DA_Haptic_Grab_Object	Haptic.Grab	GrabObject	0.08s	Both	35	Physics object grabbed
DA_Haptic_Release_Throw	Haptic.Release.Throw	ReleaseObject	0.12s	Both	35	Physics object thrown
DA_Haptic_Scare_JumpScare	Haptic.Scare.JumpScare	ScareEvent	0.5s	Both	95	Jump scare triggers
DA_Haptic_Scare_TensionRise	Haptic.Scare.TensionRise	ScareEvent	2.0s	Left	65	Ambient tension building
DA_Haptic_Ambient_Void	Haptic.Ambient.Void	AmbientPulse	3.0s	Left	15	Void Space ambient rumble
DA_Haptic_LowHealth	Haptic.LowHealth	LowHealth	0.2s	Both	75	HP drops below 25%
DA_Haptic_StaminaExhaust	Haptic.StaminaExhausted	StaminaExhausted	0.3s	Both	45	Stamina reaches zero
DA_Haptic_Death	Haptic.Death	Death	0.8s	Both	100	Player dies
DA_Haptic_UI_Confirm	Haptic.UI.Confirm	UI_Confirm	0.03s	Right	5	Menu option selected
DA_Haptic_UI_Navigate	Haptic.UI.Navigate	UI_Navigate	0.02s	Right	5	Menu cursor moved

Creating ForceFeedbackEffect Assets (Waveform Curves)

For each haptic profile that uses a UForceFeedbackEffect:

1. Navigate to Content/Game/DataAssets/Haptics/Curves/
2. Right-click → Miscellaneous → Force Feedback Effect
3. Name: FFE_{Event} (e.g., FFE_Damage_Light)
4. Open the asset:
   • Add a channel: Left Large (low frequency rumble motor)
   • Add a channel: Right Small (high frequency precision motor)
   • For the Damage Light curve: short spike at 0.5 intensity, 0.15s duration
   • For the Shotgun curve: heavy dual-motor spike, 0.25s duration
   • For the Heartbeat curve: single low-frequency pulse at 0.1s
5. Assign the FFE asset to the corresponding DA_HapticProfile

Platform-Specific Force Feedback Assets

For PS5 DualSense-only effects, create separate FFE assets in Curves/PS5/:

• FFE_Damage_Heavy_PS5 — higher fidelity trigger and haptic pattern
• FFE_Shotgun_PS5 — trigger kick + body rumble simultaneously
• FFE_Heartbeat_PS5 — pulse on both adaptive triggers

The BPC_HapticsController selects the right asset at runtime based on CurrentPlatform.

---

Step 2: Wiring BPC_HapticsController to Gameplay Systems

2.1 Player Damage → Haptic

In BP_HorrorPlayerCharacter (or wherever BPC_HealthSystem is attached):

[In BPC_HealthSystem: OnTakeDamage Event]
  → Get BPC_HapticsController from Owner (PlayerController)
  → Branch on damage amount:
    ≤10:    PlayHapticByTag(Haptic.Damage.Light, 1.0)
    10–30:  PlayHapticByTag(Haptic.Damage.Heavy, 1.0)
    >30:    PlayHapticByTag(Haptic.Damage.Critical, 1.0)
  → Branch on current health / max health:
    <0.25:  PlayHapticByTag(Haptic.LowHealth, 1.0)

2.2 Weapon Fire → Haptic

In BP_Pistol_Held and BP_Shotgun_Held (or the BPC_FirearmSystem):

[In BPC_FirearmSystem: OnFire Event]
  → Get Owner PlayerController → Get BPC_HapticsController
  → Switch on equipped weapon:
    Pistol:  PlayHapticByTag(Haptic.WeaponFire.Pistol, 1.0)
    Shotgun: PlayHapticByTag(Haptic.WeaponFire.Shotgun, 1.0)

For DualSense adaptive triggers (PS5 only — no-op on other platforms):

[AimDownSights pressed]
  → if IsDualSenseConnected:
    → SetDualSenseTriggerEffect("Right", "WeaponFire", 2, 5)  ← R2 stiffens at position 2

[AimDownSights released]
  → if IsDualSenseConnected:
    → SetDualSenseTriggerEffect("Right", "Resistance", 0, 0)  ← Remove trigger resistance

2.3 Reload → Haptic

[In BPC_ReloadSystem: ReloadComplete Event]
  → Get BPC_HapticsController
  → PlayHapticByTag(Haptic.WeaponReload, 1.0)

2.4 Melee → Haptic

[In BPC_MeleeSystem: OnMeleeHit Event]
  → Get BPC_HapticsController
  → PlayHapticByTag(Haptic.MeleeImpact.Crowbar, 1.0)

2.5 Heartbeat → Continuous Haptic

In PC_HorrorController (child of PlayerController with BPC_HapticsController attached):

[Event BeginPlay]
  → Get Pawn → Get BPC_StateManager
  → Bind Event OnHeartRateChanged → [Custom Event]
  
[Custom Event: OnHeartRateChanged(BPM)]
  → Get BPC_HapticsController (self)
  → PlayHeartbeatHaptic(BPM)    ← This starts/stops the looping heartbeat pulse

The heartbeat haptic automatically switches profiles based on BPM range:

In PlayHapticByTag (heartbeat):
  → Clamp BPM to 40–180
  → Select profile:
    BPM 40–90:  Haptic.Heartbeat.Normal  (slow pulse on left motor)
    BPM 90–140: Haptic.Heartbeat.Fast    (faster pulse, stronger)
    BPM 140–180: Haptic.Heartbeat.Panic  (both motors, double-pulse)

2.6 Footsteps → Surface-Dependent Haptic

In GASP animation notifies or BPC_MovementStateSystem:

[Animation Notify: Footstep]
  → Physical Surface Trace → Get Surface Type (Tile, Wood, Concrete, Carpet, Metal)
  → Get BPC_HapticsController
  → Switch on Surface:
    Tile:     PlayHapticByTag(Haptic.Footstep.Tile, surfaceDependentIntensity)
    Wood:     PlayHapticByTag(Haptic.Footstep.Wood, surfaceDependentIntensity)
    Concrete: PlayHapticByTag(Haptic.Footstep.Concrete, surfaceDependentIntensity)
    Metal:    PlayHapticByTag(Haptic.Footstep.Metal, surfaceDependentIntensity)
    Carpet:   Skip (no haptic on soft surfaces)
  → Scale intensity by movement speed:
    Sneak (0.3x), Walk (1.0x), Sprint (1.5x)

2.7 Scare Events → Haptic

[In BPC_ScareEventSystem: OnScareTriggered(ScareType)]
  → Get BPC_HapticsController
  → Switch on ScareType:
    JumpScare:  PlayHapticByTag(Haptic.Scare.JumpScare, 1.0)
    TensionRise: PlayHapticByTag(Haptic.Scare.TensionRise, 1.0)
                  → This plays a 2s ramp-up rumble on the left motor

2.8 Void Space Ambient → Continuous Tension Rumble

[In BP_AtmosphereController_WardA: EnterVoidSpace Event]
  → Get BPC_HapticsController
  → PlayHapticByTag(Haptic.Ambient.Void, 0.6)    ← Low-intensity ambient rumble

[ExitVoidSpace Event]
  → Get BPC_HapticsController
  → StopHaptic    ← Stop all ambient

2.9 Death → Final Rumble

[In BPC_DeathHandlingSystem: OnDeath Event]
  → Get BPC_HapticsController
  → PlayHapticByTag(Haptic.Death, 1.0)

2.10 Stamina Exhausted → Warning Pulse

[In BPC_StaminaSystem: Stamina = 0 Event]
  → Get BPC_HapticsController
  → PlayHapticByTag(Haptic.StaminaExhausted, 1.0)

2.11 UI Navigation → Subtle Clicks

[In WBP_MainMenu or WBP_PauseMenu: OnButtonHovered / OnSelectionChanged]
  → Get BPC_HapticsController (from owning PlayerController)
  → PlayHapticByTag(Haptic.UI.Navigate, 1.0)

[OnButtonPressed / Confirm]
  → PlayHapticByTag(Haptic.UI.Confirm, 1.0)

---

Step 3: Platform-Specific Configuration

3.1 Xbox Controller Settings

Xbox controllers use standard dual-motor rumble (Left = low frequency, Right = high frequency). No special setup required beyond creating UForceFeedbackEffect assets.

For Xbox-specific tuning:

• Left motor (low frequency): Use for heavy impacts, explosions, death
• Right motor (high frequency): Use for weapon fire, reload clicks, UI feedback
• Both motors: Use for damage, jump scares, melee impacts

3.2 PS5 DualSense Adaptive Triggers

The DualSense supports two trigger effect types via the PS5 Controller Plugin:

Effect Type	Description	Use Case
Resistance	Trigger stiffens at a certain press point	Aiming down sights (R2)
Vibration	Trigger motor vibrates	Weapon fire kick on R2
WeaponFire	Simulated trigger break	Pulling trigger on pistol/shotgun
BowDraw	Increasing resistance as trigger pulls	(future: bow weapon)
AutomaticRifle	Rapid trigger vibration	(future: automatic rifles)

Trigger Effect Parameters:

• StartPosition: Where on the trigger pull the effect begins (0 = fully released, 9 = fully pressed)
• Strength: Effect intensity (0 = off, 8 = maximum)
• EndPosition (Resistance only): Where the resistance wall ends

Example: Pistol trigger effect:

WeaponFire effect:
  StartPosition = 4    ← Effect starts midway through pull
  Strength = 6         ← Moderate break-point feel

Graceful fallback: On Xbox/PC, SetDualSenseTriggerEffect is a no-op. No crash, no error.

3.3 Controller Speaker Audio (PS5)

The DualSense has a small speaker. Use it sparingly for immersion:

Game Event	Speaker Audio
Radio crackle	When near a working radio or walkie-talkie
Heartbeat	Quiet heartbeat thump when stress is high
Key jingle	When picking up keys
Flashlight click	Mechanical click when toggling flashlight

Implementation:

1. Create USoundWave or UMetaSoundSource assets
2. Route through SS_AudioManager with Bus = Dialogue (or a dedicated Speaker sub-bus)
3. SS_AudioManager detects platform and routes to controller speaker on PS5, falls back to main output on other platforms

---

Step 4: Accessibility Integration

Settings Menu Integration

In WBP_SettingsMenu (or WBP_AccessibilityUI), add a Haptics section:

Haptics Settings:
├── [Toggle] Controller Vibration: ON/OFF
│   └─ Calls BPC_AccessibilitySettings.SetHapticsEnabled(bool)
│        └─ Dispatcher → BPC_HapticsController.SetHapticsEnabled()
├── [Slider] Vibration Intensity: 0% – 100%
│   └─ Sets BPC_HapticsController.HapticIntensityScale
├── [Toggle] Adaptive Triggers (PS5 Only): ON/OFF
│   └─ Sets BPC_HapticsController.bEnableDualSenseTriggers
└── [Toggle] Controller Speaker (PS5 Only): ON/OFF
    └─ Sets BPC_HapticsController.bEnableSpeakerAudio

Accessibility Presets

Provide preset profiles:

• Full Haptics (default): All effects on, full intensity
• Reduced Haptics: Half intensity, no ambient rumble, no trigger effects
• No Haptics: All vibration off (accessibility minimum)

---

Step 5: Testing Checklist

Basic Functionality

• Pick up an item → controller vibrates briefly
• Fire pistol → right motor kicks
• Fire shotgun → both motors heavy kick
• Take damage → vibration intensity scales with damage amount
• Heartbeat BPM increases when enemy nearby → pulse speeds up
• Walk on tile floor → light footstep ticks on left motor
• Sprint on concrete → heavier footstep pulses on both motors
• Jump scare triggers → intense 0.5s dual-motor rumble
• Enter Void Space → low continuous ambient rumble starts
• Leave Void Space → ambient rumble stops
• Death → final heavy 0.8s rumble plays

Platform

• Xbox controller: all effects work (standard rumble)
• PS5 DualSense: adaptive triggers stiffen when aiming
• PS5 DualSense: trigger kick on weapon fire
• PS4 DualShock: falls back to standard rumble
• PC keyboard/mouse: no vibration (expected — no controller connected)
• Controller hot-swap: new platform detected, correct profiles load

Accessibility

• Toggle vibration OFF in settings → no haptic effects play
• Toggle vibration ON again → haptics resume
• Reduce intensity to 50% → all effects half strength
• Disable adaptive triggers → trigger effects stop on PS5

Edge Cases

• Rapid weapon fire → respects MinTimeBetweenEffects, no rumble spam
• Damage + weapon fire simultaneously → higher priority damage wins
• Heartbeat continues during combat — doesn't overwhelm other effects
• Controller disconnected mid-gameplay → no crash, haptics gracefully stop
• Load save file → haptics settings restored from SS_SettingsSystem

---

Haptic GameplayTag Reference

All tags are in the Haptic. namespace, registered in DT_Tags_Player.csv:

Haptic.Damage.Light
Haptic.Damage.Heavy
Haptic.Damage.Critical
Haptic.Heartbeat.Normal
Haptic.Heartbeat.Fast
Haptic.Heartbeat.Panic
Haptic.WeaponFire.Pistol
Haptic.WeaponFire.Shotgun
Haptic.WeaponReload
Haptic.MeleeImpact.Crowbar
Haptic.MeleeImpact.Default
Haptic.Footstep.Tile
Haptic.Footstep.Wood
Haptic.Footstep.Concrete
Haptic.Footstep.Metal
Haptic.Footstep.Gravel
Haptic.Explosion
Haptic.Pickup.Item
Haptic.Pickup.Weapon
Haptic.Grab
Haptic.Release.Throw
Haptic.Scare.JumpScare
Haptic.Scare.TensionRise
Haptic.Ambient.Void
Haptic.Ambient.Default
Haptic.LowHealth
Haptic.StaminaExhausted
Haptic.Death
Haptic.UI.Confirm
Haptic.UI.Navigate

---

Haptics Example v1.0 — Part of the Project Void horror game prototype. Framework systems: BPC_HapticsController (148), DA_HapticProfile (121).