Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mfdeveloper/vibration

Use custom vibrations on mobile with this native Plugin for Unity (Android, iOS & WebGL)
https://github.com/mfdeveloper/vibration

unity unity-android unity-mobile unity-plugin

Last synced: 3 months ago
JSON representation

Use custom vibrations on mobile with this native Plugin for Unity (Android, iOS & WebGL)

Awesome Lists containing this project

README 

        
# Vibration/Haptics: Unity Plugin





    




[![openupm](https://img.shields.io/npm/v/com.benoitfreslon.vibration?label=openupm&registry_uri=https://package.openupm.com)](https://openupm.com/packages/com.benoitfreslon.vibration/)



>**PS:** This is a fork of original Vibration package **[BenoitFreslon/Vibration](https://github.com/BenoitFreslon/Vibration)** to be published in [openupm](https://openupm.com) registry, while the changes aren't merged into it!



Native **free** plugin for Unity for Android, iOS and [WebGL](https://caniuse.com/webgl2) (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 



## Supported Platforms



- Aimeos logo Android

- Aimeos logo iOS

- Aimeos logo [WebGL](https://caniuse.com/webgl2) (some limitations apply on Mobile)



## Installation



### OpenUPM



Install the [OpenUPM](https://openupm.com) CLI and add the [com.benoitfreslon.vibration](https://openupm.com/packages/com.benoitfreslon.vibration) package



```bash



# 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](https://openupm.com/packages/com.benoitfreslon.vibration).



Alternatively, merge the snippet below to [Packages/manifest.json](https://docs.unity3d.com/Manual/upm-manifestPrj.html) manually



```jsonc

{

    // Verifiy which is the latest tag in this repository

    "dependencies": {

        "com.benoitfreslon.vibration": ""

    },

    // 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)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic).



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



    ```toml

    [npmAuth."https://npm.pkg.github.com/@mfdeveloper"]

    # Generate the token from your github profile:

    # https://github.com/settings/tokens

    _authToken = ""

    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](#openupm-package) package above.



    ![Github package authentication](./Images/github-package-auth-require-token.jpg)



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



    ```jsonc

    {

        "dependencies": {

            // Verifiy which is the latest tag in this repository

            "com.benoitfreslon.vibration": ""

        },

        "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#`



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



- `"com.benoitfreslon.vibration": "https://github.com/BenoitFreslon/Vibration.git#",`



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



## Getting Started



There are 2 ways to use this plugin:



1. Use the `Runtime/VibrationComponent.cs` script attached to a _gameObject_ **(Recommended)**



    ![Vibration Component](./Images/Screenshots/vibration-component-inspector.png)



    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`



```csharp

// 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:



```csharp

// 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:



```csharp

// 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**:



```csharp

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

HasVibrator();

```



### Android (only)



Check if an Android [VibrationEffect](https://developer.android.com/reference/android/os/VibrationEffect) is supported:



```csharp

// Where: "0" is `VibrationEffect.EFFECT_CLICK` value 

// from native Android Kotlin/Java

IsEffectSupported(0);

```



Check if an Android [VibrationEffect.Composition](https://developer.android.com/reference/android/os/VibrationEffect.Composition) is supported:



```csharp

// 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



```csharp

long[] pattern = { 0, 1000, 1000, 1000, 1000 };

Vibration.Vibrate (pattern, -1);

```



#### Cancel



Using `Runtime/VibrationComponent.cs`



```csharp



// Cancel for Android and WebGL

VibrationComponent.Cancel();

```



Using `Runtime/Vibration.cs` static class



```csharp

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](https://github.com/nvm-sh/nvm))



2. Generate a [Github access token (classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)



3. Authenticate using the generated TOKEN:



   Create a user `$HOME/.npmrc` file



    ```ini

    # Where:  is the access token (classic) generated in your profile

    @github:registry=https://npm.pkg.github.com

    //npm.pkg.github.com/:_authToken=

    ```



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



    ```bash

    # Export the environment variable "$GITHUB_TOKEN"

    # the file ".npmrc" inside of this repo will use this variable

    export GITHUB_TOKEN=

    ```



4. Publish the package with [npm publish](https://docs.npmjs.com/cli/v9/commands/npm-publish)



    From [`[upm-package-embedded]`](https://github.com/mfdeveloper/Vibration/tree/upm-package-embedded) git branch



    ```bash

    # 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/

    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](https://dev.azure.com/openupm/openupm/_build?definitionId=1&_a=summary) and fail when try run automation publishing tags to OpenUPM :(



#### NPM Scripts (optional)



Optionally, you can run specific npm scripts inside of `Packages/` or from **`[upm]`** branch:



```bash

# Go to the package dir

cd Packages/



# 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](https://github.com/openupm/openupm/issues/new?title=Unpublish%20package%20version&template=unpublish_version.md)

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



> **See:** [Modifying UPM Package](https://openupm.com/docs/modifying-upm-package.html#modifying-upm-package)



## References



### ANDROID



- [Using Vibrate In Android](https://proandroiddev.com/using-vibrate-in-android-b0e3ef5d5e07)

- [Android 12: VibratorManager & New Vibration Primitives](https://yggr.medium.com/exploring-android-12-vibratormanager-new-vibration-primitives-e862c95fe938)

- [Developers Android: VibrationEffect](https://developer.android.com/reference/android/os/VibrationEffect)

- [Developers Android: VibrationEffect.Composition](https://developer.android.com/reference/android/os/VibrationEffect.Composition)



### OPENUPM



- [Adding UPM Package](https://openupm.com/docs/adding-upm-package.html)

- [Modifying UPM Package](https://openupm.com/docs/modifying-upm-package.html#modifying-upm-package)



### GITHUB PACKAGES



- [Custom Package with Git Dependencies](https://forum.unity.com/threads/custom-package-with-git-dependencies.628390/)

- [Using GitHub Packages Registry with Unity Package Manager](https://forum.unity.com/threads/using-github-packages-registry-with-unity-package-manager.861076)

- [Package manager not displaying all packages in scoped registry](https://forum.unity.com/threads/package-manager-not-displaying-all-packages-in-scoped-registry.791598/#post-5666161)



#### ICONS (Copyright)



Haptic icons created by Uniconlabs - Flaticon