Authors: Gabriel Brito, Steve Becker, Ben Mathwig
This document is a starting point for engaging the community and standards bodies in developing collaborative solutions fit for standardization. As the solutions to the problems described in this document progress along the standards-track, we will retain this document as an archive and use this section to keep the community up-to-date with the most current standards venue and content location of future work and discussions.
- This document status: Active
- Expected venue: W3C Web Applications Working Group
- Current version: This document
It is the haptic feedback effect generated by two Eccentric Rotating Mass (ERM) actuators, one in each grip of the gamepad.
It is the haptic feedback effect generated by two independent motors, with one motor located in each of the gamepad's triggers.
Currently, there are gamepads, like the Microsoft's Xbox and the Razer Wolverine Ultimate Controllers, which comes equipped with "impulse triggers" capable of providing trigger-rumble feedback to the user. While the GamepadHapticActuator, part of the Gamepad Haptics Extension proposal, already provides support for dual-rumble effect, it does not allow developers to have access to trigger-rumble yet.
This change will allow game developers to equip their web applications with a wider set of haptics feedback options, making it possible for their users to have a richer and more engaging experience on the web.
This explainer proposes an extension to the GamepadHapticActuator interface to expose the trigger-rumble capability in the Web for compatible gamepads.
A second type of gamepad haptic effect called "trigger-rumble" should be defined to represent the feedback generated by the two independent trigger motors. Therefore, we should add a "trigger-rumble" entry to the enum GamepadHapticEffectType.
enum GamepadHapticEffectType {
"dual-rumble",
"trigger-rumble"
};Moreover, it is necessary to add to the GamepadEffectParameters dictionary the double values "LeftTrigger" and "RightTrigger" to represent the trigger motors' rumble intensity normalized to the interval [0.0, 1.0].
dictionary GamepadEffectParameters {
double duration;
double startDelay;
double strongMagnitude;
double weakMagnitude;
double leftTrigger;
double rightTrigger;
};Since not every gamepad has the trigger-rumble feature, the developer must check the effects array to query the device's capabilities. This array should contain all the GamepadHapticEffectType strings that the gamepad device supports. We propose implementing an array like this, because it also allow applications to detect and discover new types of haptics effects - please refer to the Alternative Solutions section for more info on other options considered. It should be noted that devices with trigger-rumble support should also be capable to provide dual-rumble feedback.
interface GamepadHapticActuator {
[SameObject] readonly attribute FrozenArray<GamepadHapticEffectType> effects;
};The trigger-rumble effect could be activated for both triggers of a gamepad at index 0 using the code below (1 second, 50% intensity on left trigger and full on right), given that the device has support for it. Moreover, if the device is not able to play trigger rumble feedback, it should be capable to fallback to dual rumble.
let gamepads = navigator.getGamepads();
if (gamepads.length > 0) {
let gamepad = gamepads[0];
if (gamepad.vibrationActuator) {
if (gamepad.vibrationActuator.effects && gamepad.vibrationActuator.effects.includes("trigger-rumble")) {
gamepad.vibrationActuator.playEffect("trigger-rumble", {
duration: 1000,
leftTrigger: 0.5,
rightTrigger: 1.0,
});
} else {
gamepad.vibrationActuator.playEffect("dual-rumble", {
duration: 1000,
strongMagnitude: 0.5,
weakMagnitude: 1.0,
});
}
}
}Also, it is possible to activate the feedback only for one trigger by omitting the other one.
Allowing websites to query for Gamepads' haptic capabilities might raise fingerprinting concerns. However, navigator.getGamepads method returns an empty list before a gamepad user gesture has been detected (https://www.w3.org/TR/gamepad/#getgamepads-method), which will not allow queries to be done before the user has interacted with the gamepad in the website.
Adding a new entry entry, e.g. "trigger-rumble" to GamepadHapticActuatorType might be difficult to accomplish without breaking existing apps. For example, an app that always checks for "dual-rumble" may break if Xbox controllers suddenly begin to return "trigger rumble" as their GamepadHapticActuatorType. Therefore, it may be better to let the web applications do the required capability detection using a different route - e.g., by checking the effects array -; and always define GamepadHapticActuator.type to be "dual-rumble", so apps cannot rely on it, then deprecate, and eventually remove it.
A new canPlay method that takes a GamepadHapticEffectType string and returns a boolean could also be used to query a gamepad's haptics capabilities. However, this requires a new call to be made for every GamepadHapticEffectType we would like to check for support. Moreover, implementing a method like this could affect legacy engines, in case effect types need to be deprecated or renamed.
The extension to the GamepadHapticsActuator is a short-term solution to unblock developers from being limited to 2-motor rumble on current generation hardware. In the long-term, we plan to invest in the HapticsDevice API, which will supercede this API, the Vibration API, and will generalize haptics behaviors across many devices and applications. This new HapticsDevice API will be applied to Gamepad to support rumble and haptic effects in previous and next generation hardware.
Gamepad Haptics API proposal
Microsoft Xbox Controller
Razer Wolverine Ultimate Controller
W3C Gamepad Working Draft
W3C Gamepad Extensions draft
W3C Gamepad issue 138 - Xbox One impulse trigger effects