Gamepad trigger-rumble and associated updates

files/en-us/web/api/gamepadhapticactuator/effects/index.md

@@ -0,0 +1,43 @@
+---
+title: "GamepadHapticActuator: effects property"
+short-title: effects
+slug: Web/API/GamepadHapticActuator/effects
+page-type: web-api-instance-property
+browser-compat: api.GamepadHapticActuator.effects
+---
+
+{{APIRef("Gamepad API")}}
+
+The **`effects`** read-only property of the {{domxref("GamepadHapticActuator")}} interface returns an array of enumerated values representing the different haptic effects that the actuator supports.
+
+## Value
+
+An array representing the supported haptic effects. Possible included values are:
+
+- `"dual-rumble"`
+  - : A positional rumbling effect created by dual vibration motors in each handle of a controller, which can be vibrated independently.
+- `"trigger-rumble"`
+  - : Localized rumbling effects on the surface of a controller's trigger buttons created by vibrational motors located in each button. These buttons most commonly take the form of spring-loaded triggers.
+
+> **Note:** If an effect is not listed that is known to be supported by the hardware, it may be that the browser does not support playing effects of that type.
+
+## Examples
+
+```js
+const gamepad = navigator.getGamepads()[0];
+
+// Logs "dual-rumble" or "trigger-rumble"
+console.log(gamepad.hapticActuators[0].effects[0]);
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Gamepad API](/en-US/docs/Web/API/Gamepad_API)

files/en-us/web/api/gamepadhapticactuator/index.md

@@ -13,17 +13,19 @@ This interface is accessible through the {{domxref("Gamepad.hapticActuators")}}
 
 ## Instance properties
 
-- {{domxref("GamepadHapticActuator.type")}} {{ReadOnlyInline}} {{deprecated_inline}}
-  - : Returns an enum representing the type of the haptic hardware.
+- {{domxref("GamepadHapticActuator.effects")}} {{ReadOnlyInline}}
+  - : Returns an array of enumerated values representing the different haptic effects that the actuator supports.
+- {{domxref("GamepadHapticActuator.type")}} {{deprecated_inline}} {{ReadOnlyInline}}
+  - : Returns an enumerated value representing the type of the haptic hardware. This property is deprecated: use `GamepadHapticActuator.effects` to detect effect support.
 
 ## Instance methods
 
+- {{domxref("GamepadHapticActuator.playEffect()")}} {{ReadOnlyInline}}
+  - : Causes the hardware to play a specific vibration effect.
 - {{domxref("GamepadHapticActuator.pulse()")}} {{ReadOnlyInline}}
-
   - : Makes the hardware pulse at a certain intensity for a specified duration.
-
-- {{domxref("GamepadHapticActuator.playEffect()")}} {{ReadOnlyInline}}
-  - : Makes the hardware play a specific vibration pattern.
+- {{domxref("GamepadHapticActuator.reset()")}} {{ReadOnlyInline}}
+  - : Stops the hardware from playing an active vibration effect.
 
 ## Examples
 

files/en-us/web/api/gamepadhapticactuator/playeffect/index.md

@@ -6,9 +6,9 @@ page-type: web-api-instance-method
 browser-compat: api.GamepadHapticActuator.playEffect
 ---
 
-{{APIRef("Gamepad")}}
+{{APIRef("Gamepad API")}}
 
-The **`playEffect()`** method of the {{domxref("GamepadHapticActuator")}} interface makes the hardware play a specific vibration pattern.
+The **`playEffect()`** method of the {{domxref("GamepadHapticActuator")}} interface causes the hardware to play a specific vibration effect.
 
 ## Syntax
 
@@ -20,40 +20,62 @@ playEffect(type, params)
 
 - `type`
 
-  - : A string representing the desired effect. This can vary depending on the hardware type. Possible values are "dual-rumble" or "vibration".
+  - : A string representing the desired effect. Possible values are `"dual-rumble"` and `"trigger-rumble"`, and their effects can vary depending on the hardware type. See {{domxref("GamepadHapticActuator.effects")}} for further details of the effect types.
 
 - `params`
 
   - : An object to describe a desired haptic effect.
 
     Expected values are:
 
-    - `duration`
+    - `duration` {{optional_inline}}
       - : The duration of the effect in milliseconds.
-    - `startDelay`
+        Defaults to `0`.
+    - `startDelay` {{optional_inline}}
       - : The delay in milliseconds before the effect is started.
-    - `strongMagnitude`
-      - : Rumble intensity of the low-frequency (strong) rumble motors, normalized to the range between 0.0 and 1.0.
-    - `weakMagnitude`
-      - : Rumble intensity of the high-frequency (weak) rumble motors, normalized to the range between 0.0 and 1.0.
+        Defaults to `0`.
+    - `strongMagnitude` {{optional_inline}}
+      - : The rumble intensity of the low-frequency (strong) rumble motors, normalized to the range between `0.0` and `1.0`.
+        Defaults to `0.0`.
+    - `weakMagnitude` {{optional_inline}}
+      - : The rumble intensity of the high-frequency (weak) rumble motors, normalized to the range between `0.0` and `1.0`.
+        Defaults to `0.0`.
+    - `leftTrigger` (relevant to `"trigger-rumble"` effects only) {{optional_inline}}
+      - : The rumble intensity of the bottom-left front trigger, normalized to the range between `0.0` and `1.0`.
+        Defaults to `0.0`.
+    - `rightTrigger` (relevant to `"trigger-rumble"` effects only) {{optional_inline}}
+      - : The rumble intensity of the bottom-right front trigger, normalized to the range between `0.0` and `1.0`.
+        Defaults to `0.0`.
 
 > **Note:** A new call to `playEffect()` overrides a previous ongoing call.
 
 ### Return value
 
-A promise that resolves with `true` when the playEffect successfully completes.
+A promise that resolves with `"complete"` when the effect successfully completes, or `"preempted"` if the current effect is stopped or replaced by another effect.
+
+The promise may reject with the following exception types:
+
+- `InvalidStateError` {{domxref("DOMException")}}
+  - : The current document is not active or hidden.
+- `NotSupportedError` {{domxref("DOMException")}}
+  - : The requested `type` is not supported by the current gamepad's actuator.
+- `TypeError` {{domxref("DOMException")}}
+  - : The requested `type` is not a valid effect type.
 
 ## Examples
 
 ```js
 const gamepad = navigator.getGamepads()[0];
 
-gamepad.vibrationActuator.playEffect("dual-rumble", {
-  startDelay: 0,
-  duration: 200,
-  weakMagnitude: 1.0,
-  strongMagnitude: 1.0,
-});
+gamepad.vibrationActuator
+  .playEffect("dual-rumble", {
+    startDelay: 0,
+    duration: 200,
+    weakMagnitude: 1.0,
+    strongMagnitude: 1.0,
+  })
+  .then((result) => console.log(result));
+// Should log "complete" if effect successfully runs
 ```
 
 ## Specifications

files/en-us/web/api/gamepadhapticactuator/pulse/index.md

@@ -6,7 +6,7 @@ page-type: web-api-instance-method
 browser-compat: api.GamepadHapticActuator.pulse
 ---
 
-{{APIRef("Gamepad")}}
+{{APIRef("Gamepad API")}}
 
 The **`pulse()`** method of the {{domxref("GamepadHapticActuator")}} interface makes the hardware pulse at a certain intensity for a specified duration.
 

files/en-us/web/api/gamepadhapticactuator/reset/index.md

@@ -0,0 +1,62 @@
+---
+title: "GamepadHapticActuator: reset() method"
+short-title: reset()
+slug: Web/API/GamepadHapticActuator/reset
+page-type: web-api-instance-method
+browser-compat: api.GamepadHapticActuator.reset
+---
+
+{{APIRef("Gamepad API")}}
+
+The **`reset()`** method of the {{domxref("GamepadHapticActuator")}} interface stops the hardware from playing an active vibration effect.
+
+## Syntax
+
+```js-nolint
+reset()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+A promise that resolves with `"complete"` if the effect is successfully reset, or `"preempted"` if the effect was stopped or replaced by another effect.
+
+The promise may reject with the following exception types:
+
+- `InvalidStateError` {{domxref("DOMException")}}
+  - : Promise rejects with `InvalidStateError` if the current document is not active or hidden.
+
+## Examples
+
+```js
+const gamepad = navigator.getGamepads()[0];
+
+setTimeout(() => {
+  gamepad.vibrationActuator.reset();
+}, 150);
+
+gamepad.vibrationActuator
+  .playEffect("dual-rumble", {
+    startDelay: 0,
+    duration: 200,
+    weakMagnitude: 1.0,
+    strongMagnitude: 1.0,
+  })
+  .then((result) => console.log(result));
+// Should log "preempted" because reset() will run before the effect ends
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Gamepad API](/en-US/docs/Web/API/Gamepad_API)

files/en-us/web/api/gamepadhapticactuator/type/index.md

@@ -8,19 +8,29 @@ status:
 browser-compat: api.GamepadHapticActuator.type
 ---
 
-{{APIRef("Gamepad")}}{{deprecated_header}}
+{{APIRef("Gamepad API")}}{{deprecated_header}}
 
-The **`type`** read-only property of the {{domxref("GamepadHapticActuator")}} interface returns an enum representing the type of the haptic hardware.
+The **`type`** read-only property of the {{domxref("GamepadHapticActuator")}} interface returns an enumerated value representing the type of the haptic hardware.
+
+This property is deprecated: use {{domxref("GamepadHapticActuator.effects")}} to detect effect support.
 
 ## Value
 
-An enum of type [`GamepadHapticActuatorType`](https://w3c.github.io/gamepad/extensions.html#gamepadhapticactuatortype-enum); currently available types are:
+An enumerated value representing the haptic hardware type. Currently available types are:
 
-- `vibration` — vibration hardware, which creates a rumbling effect.
+- `"vibration"`
+  - : Simple vibration hardware, which creates a rumbling effect.
+- `"dual-rumble"`
+  - : A controller with a vibration motor in each handle. Each motor can be vibrated independently to create positional rumbling effects.
 
 ## Examples
 
-TBC
+```js
+const gamepad = navigator.getGamepads()[0];
+
+// Logs "vibration" or "dual-rumble"
+console.log(gamepad.hapticActuators[0].type);
+```
 
 ## Specifications
 

files/jsondata/GroupData.json

@@ -619,7 +619,12 @@
         "/docs/Web/API/Gamepad_API/Using_the_Gamepad_API",
         "/docs/Games/Techniques/Controls_Gamepad_API"
       ],
-      "interfaces": ["Gamepad", "GamepadButton", "GamepadEvent"],
+      "interfaces": [
+        "Gamepad",
+        "GamepadButton",
+        "GamepadEvent",
+        "GamepadHapticActuator"
+      ],
       "methods": ["Navigator.getGamepads()"],
       "properties": [],
       "events": ["Window: gamepadconnected", "Window: gamepaddisconnected"]