Lua API for Haptics (controller vibration)
The input API is already functional, but there is no way to trigger force feedback on controllers
I've considered the SDL haptic API, and also OpenXR's haptic API for eventual VR fork merge, and came up with the following concept:
local input = require('openmw.input')
local vector3 = require('openmw.util').vector3
-- all the samples are from 0 to 1, get rescaled to implementation values
local effect = input.hapticEffect{
duration = 0.5, -- total duration in seconds
samples = { -- each sample lasts (duration / #samples) seconds
vector3(1, 0, 0), -- maximum power to the right
vector3(-1, 0, 0), -- maximum power to the left
vector3(0, 0.2, 0.2) -- weak effect in front and "above"
},
-- most controllers served by SDL won't support the third (Z) axis
-- but OpenXR implementation will
}
effect:run()
This would be implemented for SDL through https://wiki.libsdl.org/SDL_HapticCustom
And eventually for OpenXR through chains of https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrHapticVibration
(@madsbuvi do you happen to know if this has noticeable performance costs? E. g. could we chain 100 XrHapticVibration structures without worry?)
In the SDL implementation, we use the channels (i. e. axis) set to 3. For older controllers the vertical axis, or even direction at all will be ignored (e. g. when there is only one basic vibration motor).
In the OpenXR implementation, we will apply the vibration to all haptic devices, scaling the magnitude based on close they are to the specified direction, relative to the player (i. e. the headset with some offset). The initial implementation will likely assume we just have the two controllers for each hand.
The choice of the device on which to play the effect is not exposed, so that it's easy for mods to cover all the possible cases:
- no controller at all, resulting in noop
- one or multiple controllers connected, one of them used for play (we should probably add a way to manually choose the preferred controller in settings)
- playing in VR while using two standard controllers, one for each hand
- eventually we should be able to handle full body or other complex VR setups, with arbitrary amounts of haptic devices as well