KAPLAY Gamepad Haptics Plugin

Easily add haptic feedback for those who play your games made with KAPLAY.js.

Installation

pnpm add @r47onfire/kaplay-gamepad-haptics

Then in your kaplay options:

import kaplay from "kaplay";
import gamepadHaptics from "@r47onfire/kaplay-gamepad-haptics";
// ...other imports...

const K = kaplay({
    // ...other options...
    plugins: [
        // ...other plugins...
        gamepadHaptics
    ]
});

Usage

• Play a haptic effect by calling haptics() with some parameters.

  • The first argument is always a number, and controls the general scale of the effect intensity.
  • If 2 or 3 parameters are given, the second argument is a string, defining the named haptic effect (see below).
  • If 4 or 5 numbers are given, the 2nd, 3rd, and 4th arguments, in order, the "strong" actuator intensity (typically on the left), the "weak" actuator intensity (typically on the right), and the duration in milliseconds.
  • If 6 or 7 numbers are given, the 2nd and 3rd are as with 4 or 5 arguments, and the 4rd and 5th arguments are the left trigger and right trigger actuators' intensities respectively, and the 6th is the duration.
  • In all cases with an odd number of arguments, the last argument is the player number and will only play the effect on the Nth gamepad if provided. (This is useful for local-multiplayer games, such as if you're making a Super Smash Bros clone in KAPLAY.)

  For example:

  player.onHurt(damage => {
      play("hurt");
      haptics(mapc(damage, 0, 20, 0, 1), 1, 1, 500);
  });

• You can enable or disable haptics entirely by setting haptics.enabled to true or false. If it is false, the promise returned from haptics() will resolve instantly without anything happening.

• You can control whether the gamepad will still rumble if the player switches to keyboard/mouse by setting haptics.onlyWhenGamepadInUse to true or false.

"Named effects"

You can create a "named" haptic effect by calling addHapticEffects({ name: effect, name: effect, ... }).

A haptic effect definition is a list of time-slices containing power levels for the haptic actuators in the gamepad. These correspond to the 4- or 6-argument forms of haptics() above, but without the general intensity (first parameter). Each slice is played in sequence. For example:

addHapticEffects({
    teleport: [
        [0.5, 0, 200],
        [0, 0.5, 200],
        [0.5, 0, 200],
        [0, 0.5, 200],
    ],
});

Then you can use that named effect anywhere:

player.onCollide("portal", portal => {
    player.moveTo(portal.target);
    play("woosh");
    haptics(1, "teleport");
});

Audio linking

Haptic effects can optionally be linked to automatically play simultaneously with a sound using the function linkSoundToHaptics(). The first argument is the sound name, and the rest are the parameters to pass to haptics() when the sound is played.

linkSoundToHaptics("hurt", 1, 1, 1, 500);

player.onHurt(() => {
    play("hurt"); // also plays the haptics!
});

Note that doing it this way removes the ability to calculate the intensity based on the event data.

Caveats

Not every browser and not every gamepad will support all features. To check if the browser supports it you can open this KAPLAYGROUND link and connect a gamepad:

https://play.kaplayjs.com/?code=eJxNUMtuwjAQvOcrVhYHW0UW5yCIqh76ESkSG8cYN2FtxQ5tFfLvdUJa2NM%2BZmZ3tkHf4g8foELVmM71VOfAqjZVDEaxzTJH73jRHus3R6RV5FzAbg9DBimUoxDBwA4Ir9ZgdJ00Oi6MwEW5OWyfkKH33nVR14nBjTyjj1a9qthPzABFAeVByIRVGNP8aqsOo3X0B1kQd0msa17O2RRRf0f%2Bry9bTSaeYQ8bKIDdFwXATj%2FdkIsPYvDy6MgLes5xDXb2eFwNdsxhNaDUp1PyHgr56SxxtgYm4HYD1lND7ovYeBTLKEkKyB8ryT3bzjkT88mTiem%2Fv9ELeaQ%3D&version=master