Vibration/Haptics: Unity Plugin

PS: This is a fork of original Vibration package BenoitFreslon/Vibration to be published in openupm registry, while the changes aren't merged into it!

Native free plugin for Unity for Android, iOS and WebGL (with some limitations). Use custom vibrations/haptics on mobile.

If you like this free plugin, that's be cool if you can buy me a coffee 😀☕️ Send tips to https://paypal.me/UnityVibrationPlugin

Supported Platforms

• Android
• iOS
• WebGL (some limitations apply on Mobile)

Installation

OpenUPM

Install the OpenUPM CLI and add the com.benoitfreslon.vibration package

# Install node (e.g using NVM)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
# "node" is an alias for the latest version
nvm install node
# You can list available versions using "ls-remote"
nvm ls-remote
# or 16.3.0, 12.22.1, etc
nvm install 14.7.0

# Install openupm-cli
npm install -g openupm-cli

# Go to your Unity project directory
cd YOUR_UNITY_PROJECT_DIR

# Install package: com.benoitfreslon.vibration
openupm add com.benoitfreslon.vibration

OpenUPM package

Follow the installation guide from: openupm/com.benoitfreslon.vibration.

Alternatively, merge the snippet below to Packages/manifest.json manually

{
    // Verifiy which is the latest tag in this repository
    "dependencies": {
        "com.benoitfreslon.vibration": "<LATEST_VERSION>"
    },
    // If you already have the openupm registry,
    // only add this package to "scopes" array
    "scopedRegistries": [
        {
            "name": "package.openupm.com",
            "url": "https://package.openupm.com",
            "scopes": [
                "com.benoitfreslon.vibration"
            ]
        }
    ]
}

Github package

1. Generate an access token on your Github account, following the guide: Creating a personal access token (classic).

2. Add a $HOME/.upmconfig.toml file with the TOKEN to authenticate on registry

   [npmAuth."https://npm.pkg.github.com/@mfdeveloper"]
   # Generate the token from your github profile:
   # https://github.com/settings/tokens
   _authToken = "<TOKEN-VALUE>"
   email = "<YOUR_EMAIL>"
   alwaysAuth = true

   WARNING: GitHub/Gitlab Packages registry always requires authentication. For private and public packages. If you don't have a Github account, or won't create a TOKEN, try use the openupm package above.

   

3. Configure the scope registry and dependency in your Unity project Packages/manifest.json

   {
       "dependencies": {
           // Verifiy which is the latest tag in this repository
           "com.benoitfreslon.vibration": "<LATEST_VERSION>"
       },
       "scopedRegistries": [
           {
               "name": "Github Packages: mfdeveloper",
               "url": "https://npm.pkg.github.com/@mfdeveloper",
               "scopes": [
                   "com.benoitfreslon"
               ]
           }
       ]
   }

Git dependency

The minimal checked Unity Version is 2019.3.* LTS

Open Package Manager and "Add package from git url..." using next string:

• https://github.com/BenoitFreslon/Vibration.git#upm

Or use the latest git release/tag:

• https://github.com/BenoitFreslon/Vibration.git#<LATEST_VERSION>

You also can edit Packages/manifest.json manually, just add:

• "com.benoitfreslon.vibration": "https://github.com/BenoitFreslon/Vibration.git#<LATEST_VERSION>",

Or you can simply copy and paste the entire [upm] branch content from this repo, to your Unity3D Packages/<PACKAGE_NAME> folder.

Getting Started

There are 2 ways to use this plugin:

1. Use the Runtime/VibrationComponent.cs script attached to a gameObject (Recommended)

   

   On that script, you can:

   • Enable/Disable vibration from inspector or programatically

     TIP: Useful for enable/disable from a menu settings in your game!

   • Add a ScriptableObject asset with vibration settings (only enable/disable for now)
   • Configure the duration and/or select a pre-defined vibration effect type

   This MonoBehaviour component use Runtime/Vibration.cs static class as a "fallback" for some implemented native integrations (IOS and WebGL)

2. Use the Runtime/Vibration.cs static class

   See the scene and a sample MonoBehaviour script under folder: Samples/VibrationExample

Vibrations

Using Runtime/VibrationComponent

// That's the main method to pass a duration (milliseconds)
// and/or a pre-defined `VibrationType` effect
Vibrate(
    milliseconds: 20, 
    vibrationType: VibrationType.Click
);

Optionally, you can pass an array of values of pattern as well:

// That's the main method to pass a duration (milliseconds)
// and/or a pre-defined `VibrationType` effect
Vibrate(
    pattern: new[] { 200, 10, 50 }, 
    repeat: VibrationRepeat.Once
);

Also, it's possible define the timeunit of the duration value:

// That's the main method to pass a duration (milliseconds)
// and/or a pre-defined `VibrationType` effect
Vibrate(
    duration: 10, 
    timeUnit: MobileTimeUnit.Seconds
);

Check if the mobile device has vibration support:

// Fallback to "Vibration.HasVibrator()" on iOS and WebGL
HasVibrator();

Android (only)

Check if an Android VibrationEffect is supported:

// Where: "0" is `VibrationEffect.EFFECT_CLICK` value 
// from native Android Kotlin/Java
IsEffectSupported(0);

Check if an Android VibrationEffect.Composition is supported:

// Where: "1" is `VibrationEffect.Composition.PRIMITIVE_CLICK` value 
// from native Android Kotlin/Java
IsPrimitiveSupported(1);

iOS and Android

Using Runtime/Vibration.cs static class

Default vibration

Use Vibration.Vibrate(); for a classic default ~400ms vibration

Pop vibration

Pop vibration: weak boom (For iOS: only available with the haptic engine. iPhone 6s minimum or Android)

Vibration.VibratePop();

Peek Vibration

Peek vibration: strong boom (For iOS: only available on iOS with the haptic engine. iPhone 6s minimum or Android)

Vibration.VibratePeek();

Nope Vibration

Nope vibration: series of three weak booms (For iOS: only available with the haptic engine. iPhone 6s minimum or Android)

Vibration.VibrateNope();

---

Android Only

Custom duration in milliseconds

Vibration.Vibrate(500);

Pattern

long[] pattern = { 0, 1000, 1000, 1000, 1000 };
Vibration.Vibrate (pattern, -1);

Cancel

Using Runtime/VibrationComponent.cs

// Cancel for Android and WebGL
VibrationComponent.Cancel();

Using Runtime/Vibration.cs static class

Vibration.Cancel();

---

IOS only

vibration using haptic engine

Vibration.VibrateIOS(ImpactFeedbackStyle.Light);

Vibration.VibrateIOS(ImpactFeedbackStyle.Medium);

Vibration.VibrateIOS(ImpactFeedbackStyle.Heavy);

Vibration.VibrateIOS(ImpactFeedbackStyle.Rigid);

Vibration.VibrateIOS(ImpactFeedbackStyle.Soft);

Vibration.VibrateIOS(NotificationFeedbackStyle.Error);

Vibration.VibrateIOS(NotificationFeedbackStyle.Success);

Vibration.VibrateIOS(NotificationFeedbackStyle.Warning);

Vibration.VibrateIOS_SelectionChanged();

Development

Publish (Github Packages)

1. Install node (e.g using NVM)

2. Generate a Github access token (classic)

3. Authenticate using the generated TOKEN:

   Create a user $HOME/.npmrc file

   # Where: <GITHUB_TOKEN> is the access token (classic) generated in your profile
   @github:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=<GITHUB_TOKEN>

   Or, use the file Packages/<PACKAGE_NAME>/.npmrc that already exists in this repository:

   # Export the environment variable "$GITHUB_TOKEN"
   # the file ".npmrc" inside of this repo will use this variable
   export GITHUB_TOKEN=<GITHUB_TOKEN>

4. Publish the package with npm publish

   From [upm-package-embedded] git branch

   # Clone this repo and checkout to branch "[upm-package-embedded]"
   git clone https://github.com/mfdeveloper/Vibration.git
   git checkout upm-package-embedded
   
   # Run the npm scripts
   npm install
   npm run publish:package # Publish from repository ROOT path
   
   cd Packages/<PACKAGE_NAME>
   npm run pack:package # Pack in a .tgz for testing (optional)
   npm run package:publish-from-local # Publish from package path
   npm run publish:from-local # Or use this another script alias for publishing (optional)

   WARNING: Avoid use the common npm publish directly, because the hooks prepare, prepublish ... aren't triggered in this package. They have conflicts with OpenUPM Azure pipelines and fail when try run automation publishing tags to OpenUPM :(

NPM Scripts (optional)

Optionally, you can run specific npm scripts inside of Packages/<PACKAGE_NAME> or from [upm] branch:

# Go to the package dir
cd Packages/<PACKAGE_NAME>

# Pack a .tgz for testing (optional)
npm run package:pack

# Run the publish script (with $PUBLISH_FORCE environment variable)
npm run package:publish-from-local
# Alias script to "package:publish-from-local" above
npm run publish:from-local
# Or simply run the command line below from any unix-like bash terminal
# (e.g from Git bash on Windows)
PUBLISH_FORCE=1 && npm run package:prepare && npm publish

Publish (OpenUPM)

1. Bump the version with a new Github release or Git tag

   PS: Avoid change/rewrite a existent git tag. If you really need do that, create a new issue on Github repo => openupm: Unpublish a Package Version

2. The changes should be reflected in: https://openupm.com/packages/com.benoitfreslon.vibration

See: Modifying UPM Package

References

ANDROID

• Using Vibrate In Android
• Android 12: VibratorManager & New Vibration Primitives
• Developers Android: VibrationEffect
• Developers Android: VibrationEffect.Composition

OPENUPM

• Adding UPM Package
• Modifying UPM Package

GITHUB PACKAGES

• Custom Package with Git Dependencies
• Using GitHub Packages Registry with Unity Package Manager
• Package manager not displaying all packages in scoped registry

ICONS (Copyright)

Haptic icons created by Uniconlabs - Flaticon