14441c000c
- 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.
179 lines
6.9 KiB
Markdown
179 lines
6.9 KiB
Markdown
# DA_HapticProfile — Data Asset
|
||
|
||
**Parent Class:** `UPrimaryDataAsset`
|
||
**Dependencies:** [`BPC_HapticsController`](../12-settings/148_BPC_HapticsController.md)
|
||
**Purpose:** Defines haptic feedback profiles for controller vibration and force feedback effects tied to gameplay events. Each profile maps a GameplayTag to a platform-specific `UForceFeedbackEffect` waveform asset with configurable intensity, duration, motor mask, and priority.
|
||
|
||
---
|
||
|
||
## Enums Used
|
||
|
||
| Enum | Defined In | Values |
|
||
|------|-----------|--------|
|
||
| `EHapticEvent` | `BPC_HapticsController` (148) | Damage, HeavyDamage, Heartbeat, WeaponFire, WeaponReload, MeleeImpact, Footstep, Explosion, PickupItem, DropItem, GrabObject, ReleaseObject, ScareEvent, AmbientPulse, UI_Confirm, UI_Navigate, LowHealth, StaminaExhausted, Death |
|
||
| `EHapticMotor` | `BPC_HapticsController` (148) | Left, Right, Both |
|
||
|
||
---
|
||
|
||
## Variables / Structure
|
||
|
||
### Core Fields
|
||
|
||
| Field | Type | Description |
|
||
|-------|------|-------------|
|
||
| `ProfileTag` | `FGameplayTag` | Unique haptic profile identifier (e.g., `Haptic.Damage.Heavy`) |
|
||
| `EventType` | `EHapticEvent` | Event category this profile handles |
|
||
| `ForceFeedbackEffect_Generic` | `UForceFeedbackEffect*` | Waveform curve asset for PC/Xbox generic controllers |
|
||
| `ForceFeedbackEffect_PS5` | `UForceFeedbackEffect*` | Waveform curve asset for PS5 DualSense (higher fidelity) |
|
||
| `ForceFeedbackEffect_Xbox` | `UForceFeedbackEffect*` | Waveform curve asset for Xbox controllers (optional override) |
|
||
| `IntensityCurve` | `UCurveFloat*` | Optional: vibration intensity over time (0.0–1.0) |
|
||
| `Duration` | `float` | Total haptic effect duration in seconds |
|
||
| `MotorMask` | `EHapticMotor` | Left motor, Right motor, or Both |
|
||
| `Priority` | `int32` | Higher priority overrides lower during conflicts (0 = lowest, 100 = highest) |
|
||
| `bCanInterrupt` | `bool` | Can this effect be interrupted by a higher-priority effect? |
|
||
| `bIgnoreTimeDilation` | `bool` | Should this play at real-time regardless of game speed? |
|
||
|
||
### Platform-Specific Fields
|
||
|
||
| Field | Type | Description |
|
||
|-------|------|-------------|
|
||
| `PlatformMinIntensity` | `float` | Minimum intensity threshold before effect is felt (0.0–1.0) |
|
||
| `DualSense_TriggerSide` | `FName` | PS5 adaptive trigger side ("Left", "Right", "None") |
|
||
| `DualSense_TriggerEffect` | `FName` | PS5 trigger effect type ("Resistance", "Vibration", "WeaponFire", "BowDraw", "None") |
|
||
| `DualSense_TriggerStartPosition` | `int32` | PS5 trigger position where effect begins (0–9) |
|
||
| `DualSense_TriggerStrength` | `int32` | PS5 trigger effect strength (0–8) |
|
||
|
||
### Heartbeat-Specific Fields
|
||
|
||
| Field | Type | Description |
|
||
|-------|------|-------------|
|
||
| `bIsHeartbeatProfile` | `bool` | Whether this profile is used for heartbeat pulse effects |
|
||
| `TargetBPMRange_Min` | `float` | Minimum BPM this profile handles |
|
||
| `TargetBPMRange_Max` | `float` | Maximum BPM this profile handles |
|
||
|
||
---
|
||
|
||
## Gameplay Tags
|
||
|
||
- Namespace: `Haptic.<Category>.<Subcategory>`
|
||
- Examples: `Haptic.Damage.Heavy`, `Haptic.Heartbeat.Normal`, `Haptic.WeaponFire.Pistol`
|
||
- All tags must be registered in `DT_Tags_Player.csv` for validation at startup
|
||
|
||
### Full Tag Hierarchy
|
||
|
||
```
|
||
Haptic.
|
||
├── Damage.Light
|
||
├── Damage.Heavy
|
||
├── Damage.Critical
|
||
├── Heartbeat.Normal
|
||
├── Heartbeat.Fast
|
||
├── Heartbeat.Panic
|
||
├── WeaponFire.Pistol
|
||
├── WeaponFire.Shotgun
|
||
├── WeaponReload
|
||
├── MeleeImpact.Crowbar
|
||
├── MeleeImpact.Default
|
||
├── Footstep.Tile
|
||
├── Footstep.Wood
|
||
├── Footstep.Concrete
|
||
├── Footstep.Metal
|
||
├── Footstep.Gravel
|
||
├── Explosion
|
||
├── Pickup.Item
|
||
├── Pickup.Weapon
|
||
├── Grab
|
||
├── Release.Throw
|
||
├── Scare.JumpScare
|
||
├── Scare.TensionRise
|
||
├── Ambient.Void
|
||
├── Ambient.Default
|
||
├── LowHealth
|
||
├── StaminaExhausted
|
||
├── Death
|
||
├── UI.Confirm
|
||
└── UI.Navigate
|
||
```
|
||
|
||
---
|
||
|
||
## Validation Rules
|
||
|
||
- `ProfileTag` must be unique across all profiles
|
||
- `Duration` must be > 0.0
|
||
- At least one `ForceFeedbackEffect_*` must be assigned (Generic falls back for all platforms)
|
||
- `Priority` must be 0–100
|
||
- If `bIsHeartbeatProfile` is true, `TargetBPMRange_Min` and `TargetBPMRange_Max` must be set
|
||
- If `DualSense_TriggerSide != "None"`, trigger effect fields must be valid
|
||
|
||
---
|
||
|
||
## Example Data
|
||
|
||
### Damage Profile — Heavy Hit
|
||
| Field | Value |
|
||
|-------|-------|
|
||
| `ProfileTag` | `Haptic.Damage.Heavy` |
|
||
| `EventType` | `HeavyDamage` |
|
||
| `Duration` | `0.4` |
|
||
| `MotorMask` | `Both` |
|
||
| `Priority` | `80` |
|
||
| `bCanInterrupt` | `true` |
|
||
| `bIgnoreTimeDilation` | `true` |
|
||
| `ForceFeedbackEffect_Generic` | `FFE_Damage_Heavy` |
|
||
| `ForceFeedbackEffect_PS5` | `FFE_Damage_Heavy_PS5` |
|
||
|
||
### Heartbeat Profile — Normal
|
||
| Field | Value |
|
||
|-------|-------|
|
||
| `ProfileTag` | `Haptic.Heartbeat.Normal` |
|
||
| `EventType` | `Heartbeat` |
|
||
| `Duration` | `0.1` |
|
||
| `MotorMask` | `Left` |
|
||
| `Priority` | `30` |
|
||
| `bCanInterrupt` | `true` |
|
||
| `bIsHeartbeatProfile` | `true` |
|
||
| `TargetBPMRange_Min` | `60.0` |
|
||
| `TargetBPMRange_Max` | `90.0` |
|
||
| `ForceFeedbackEffect_Generic` | `FFE_Heartbeat` |
|
||
|
||
### Weapon Fire — Pistol
|
||
| Field | Value |
|
||
|-------|-------|
|
||
| `ProfileTag` | `Haptic.WeaponFire.Pistol` |
|
||
| `EventType` | `WeaponFire` |
|
||
| `Duration` | `0.08` |
|
||
| `MotorMask` | `Right` |
|
||
| `Priority` | `50` |
|
||
| `DualSense_TriggerSide` | `Right` |
|
||
| `DualSense_TriggerEffect` | `WeaponFire` |
|
||
| `DualSense_TriggerStartPosition` | `4` |
|
||
| `DualSense_TriggerStrength` | `6` |
|
||
|
||
---
|
||
|
||
## Consumed By
|
||
- [`BPC_HapticsController`](../12-settings/148_BPC_HapticsController.md) — loads all profiles into `HapticProfileMap` at initialization
|
||
|
||
## Referenced By
|
||
- `BPC_HealthSystem` (08) — damage haptics
|
||
- `BPC_FirearmSystem` (74) — weapon fire haptics
|
||
- `BPC_MeleeSystem` (76) — melee impact haptics
|
||
- `BPC_ScareEventSystem` (101) — scare event haptics
|
||
- `BPC_MovementStateSystem` (11) — footstep haptics
|
||
- `BPC_ReloadSystem` (78) — reload haptics
|
||
- `BPC_PhysicsDragSystem` (22) — grab/release haptics
|
||
- `BP_ItemPickup` (25) — pickup haptics
|
||
- `BPC_DeathHandlingSystem` (39) — death haptics
|
||
- `BPC_StaminaSystem` (09) — stamina exhausted haptics
|
||
|
||
---
|
||
|
||
## Reuse Notes
|
||
- Haptic profiles are platform-agnostic in design; `BPC_HapticsController` selects the correct `UForceFeedbackEffect` asset at runtime based on `CurrentPlatform`.
|
||
- Designers create FFE waveform curves in the Content Browser — no Blueprint changes needed for tuning.
|
||
- For heartbeat profiles: create 3 instances (Normal 60-90 BPM, Fast 90-140 BPM, Panic 140-180 BPM). `BPC_HapticsController` auto-selects based on current BPM.
|
||
- For footstep profiles: create one per surface type. `BPC_MovementStateSystem` selects based on physical surface trace result.
|
||
- Priority guidelines: 0–20 (ambient/footsteps), 30–50 (weapons/reload/pickups), 60–80 (damage), 90–100 (scares/death).
|
||
- The `Haptic.` namespace should be registered in `DT_Tags_Player.csv` so `DA_GameTagRegistry` validates them at startup.
|