This section describes everything you need to know to integrate Nice Vibrations to an existing project, or to a new one.

How do I add this to my game?

All you need to add and use Nice Vibrations in your game is to import the package, and have the NiceVibrations/Common folder in your project (ideally keep the rest as well). That’s all. No need to add anything to your scene(s), no need to add components anywhere. You’ll now be able to call the vibration methods from anywhere in your scripts.

Note that you’ll probably need to add this at the top of your scripts that call vibrations, but most IDE add that for you these days anyway :

using MoreMountains.NiceVibrations;

How do I trigger a vibration?

Nice Vibrations comes with many methods to trigger all sorts of vibrations. The most simple is Vibrate(). It’ll trigger a default vibration on both iOS and Android devices, and you can call it from anywhere like this :

MMVibrationManager.Vibrate();

This is all well and good, but Nice Vibrations offers much more. There’s another universal method (as opposed to gamepad, iOS or Android specific ones) that you can use. It’s called Haptic, takes an HapticType as a parameter, and will allow to trigger predetermined patterns. These patterns are native on iOS 10+, and they’ve been prebuilt into Nice Vibrations for you to simulate the same feedback for Android too.

Here’s how you use this method :

MMVibrationManager.Haptic (HapticTypes.Success);

The line above will cause your device to vibrate in a “success” pattern, which is a light vibration followed by a heavy one. There are 9 different HapticTypes to choose from, and you can learn more about them in Apple’s human interface guidelines.

If you want to also trigger gamepad rumble, here’s how it’s done :

MMVibrationManager.Haptic (HapticTypes.Success, true, this);

The types you can use are the following :

  • Selection : a light vibration on Android, and a light impact on iOS
  • Success : a light then heavy vibration on Android, and a success impact on iOS
  • Warning : a heavy then medium vibration on Android, and a warning impact on iOS
  • Failure : a medium / heavy / heavy / light vibration pattern on Android, and a failure impact on iOS
  • Light : a light impact on iOS and a short and light vibration on Android.
  • Medium : a medium impact on iOS and a medium and regular vibration on Android
  • Heavy : a heavy impact on iOS and a long and heavy vibration on Android
  • Rigid : a short and hard impact
  • Soft : a slightly longer and softer impact

And for reference, here’s how you call them all :

MMVibrationManager.Haptic (HapticTypes.Selection);
MMVibrationManager.Haptic (HapticTypes.Success);
MMVibrationManager.Haptic (HapticTypes.Warning);
MMVibrationManager.Haptic (HapticTypes.Failure);
MMVibrationManager.Haptic (HapticTypes.LightImpact);
MMVibrationManager.Haptic (HapticTypes.MediumImpact);
MMVibrationManager.Haptic (HapticTypes.HeavyImpact);
MMVibrationManager.Haptic (HapticTypes.Rigid);
MMVibrationManager.Haptic (HapticTypes.Soft);

Can I do more with Nice Vibrations?

Oh yes you can. You can trigger transient haptics, which are short and customizable vibrations, you can have continuous haptics, vibrations that live over time and for which you can control both intensity and sharpness at will, you can create and use custom haptic patterns to mimic sounds or feelings, and you can also trigger Android or iOS specific methods. Check out the respective sections of the documentation to learn more about all these.

Android users

For Android to support vibrations you’ll need to have the following line in your Android manifest :

<uses-permission android:name="android.permission.VIBRATE" />

To do so, you can either add a Handheld.Vibrate() somewhere in your code (it doesn’t have to be triggered for Unity to change the manifest), or you can copy the one provided with the asset (it’s in the Common/Plugins/Android/ folder) to Assets/Plugins/Android/AndroidManifest.xml.

You can learn more about Unity and Android manifest over here.

Helpers

Support Detection

Not all devices support haptic feedback, and not all devices support haptics equally. To help knowing what you’re dealing with, Nice Vibrations gives you access to a number of helpful methods :

// returns true if the device supports haptics, whether on Android, "old" iOS or iOS 13+
bool testUniversal = MMVibrationManager.HapticsSupported();

You’ll find more platform specific methods in the API documentation if you need them.

Global control

Haptics are amazing, but sometimes you just want to turn them off. To do so, you can simply call the following method :

// turns all haptics off
MMVibrationManager.SetHapticsActive(false);

// turns all haptics on
MMVibrationManager.SetHapticsActive(true);

Callbacks

Nice Vibrations comes with completion callbacks. Unfortunately, these are only really supported by iOS 13. Older iOS and most Android devices simply can’t use these. But if you’re in a context where you want to provide more functionality to iOS users, you can register to 3 types of callbacks : haptics stopped, haptics error, and haptics reset :

protected virtual void OnHapticsStopped()
{
  // do something when haptics stop - usually because they have finished playing
}

protected virtual void OnHapticsError()
{
  // do something when haptics encounter an error
}

protected virtual void OnHapticsReset()
{
  // do something when the haptic engine resets (relatively rare)
}

protected virtual void OnEnable()
{
    MMNViOSCoreHaptics.OnHapticPatternStopped += OnHapticsStopped;
    MMNViOSCoreHaptics.OnHapticPatternError += OnHapticsError;
    MMNViOSCoreHaptics.OnHapticPatternReset += OnHapticsReset;
}

protected virtual void OnDisable()
{
    MMNViOSCoreHaptics.OnHapticPatternStopped -= OnHapticsStopped;
    MMNViOSCoreHaptics.OnHapticPatternError -= OnHapticsError;
    MMNViOSCoreHaptics.OnHapticPatternReset -= OnHapticsReset;
}