Nice Vibrations

Nice Vibrations is an Asset Package designed to add advanced haptic feedback to mobile applications created with Unity. It provides haptic playback functionality through two primary interfaces:

1. C# Code-only API: For programmatic control via scripts.
2. MonoBehaviour API: For configuring haptics directly within the Unity Editor.

The package includes:

• Haptic Samples: A collection of free-to-use haptic clips and associated audio files for UX and game effects.
• Demo Project: A buildable project for iOS and Android showcasing package functionality.
• Legacy Support: Includes version 3.9 to assist with porting existing projects to the current API.

Nice Vibrations is a Unity Asset built on top of the Lofelt Studio SDK. It provides a universal interface to trigger HD haptic feedback across multiple platforms simultaneously, including:

• Android: Native haptic support.
• iOS: High-performance haptic APIs (including iOS Core Haptics).
• Gamepad: Standard rumble support.

Key capabilities include playing/stopping .haptic files, looping, seeking within a clip, modulating frequency or amplitude in real-time, and setting haptic priority to manage overlapping effects. It offers both a Code Only API for non-MonoBehaviour workflows and a MonoBehaviour API for easy Unity Editor usage.

The Nice Vibrations Unity asset provides haptic feedback capabilities within Unity. The asset structure includes:

• Plugin script code: Located in Assets/NiceVibrations/Scripts/.
• iOS and Android plugins: Native libraries used by the script code, located in Assets/NiceVibrations/Plugins.
• Haptic samples: Audio and haptic example files in Assets/NiceVibrations/HapticSamples/.
• Demo scene: An example scene located in Assets/NiceVibrations/Demo/.

The Lofelt Haptic Data Model describes vibrotactile content derived from an audio signal source in a parametric way. This approach decouples design intent from playback, allowing for device-independent haptics and backward compatibility.

The datamodel crate provides the schema for the Lofelt SDK Data model, including JSON serialization/deserialization, version upgrades, and conversion to platform-specific haptic data.

The Unity Editor Plugin is a tool used by the Nice Vibrations Unity asset to convert .haptic clips into a structure compatible with playback on gamepads via Unity's Gamepad API.

Key Characteristics:

• Editor-Only: This is a plugin for the Unity editor and is not used at runtime by the Unity engine. This limitation exists because the plugin cannot be built for all Unity-supported platforms (like consoles with closed SDKs).
• Platform Support: It is built for the platforms the Unity editor runs on: Windows, macOS, and Linux.
• Implementation: It is written in Rust to reuse the datamodel crate. It exports a C-compatible API using extern "C" so that Unity's C# scripting can interface with it.
• Format: It is distributed as a dynamic library: .dylib (macOS), .dll (Windows), or .so (Linux).

The Lofelt Haptic Data Model uses semantic versioning to manage compatibility:

• Major Version: Incremented for non-directly compatible changes, such as deleting fields or restructuring parameter groups. These require a transformation (upgrade) mapping.
• Minor Version: Incremented for backward-compatible changes, such as adding optional fields, adding enum types, or renaming fields.
• Patch Version: Incremented for backward-compatible bug fixes.

The Nice Vibrations core is composed of several specialized crates that provide different layers of access to the haptic engine:

• lib: The foundation containing the core library source code and the primary Rust API.
• api: Provides C bindings to the Rust API. This crate produces the C library and header files used for cross-language integration.
• datamodel: Manages the Lofelt Data model, including schema definitions and versioning logic.
• utils: Provides shared utility functions and classes, such as the Error type.

To play back pre-authored clips in this crate, you must use an implementation of the PreAuthoredClipPlayback trait. The specific implementation you use depends on your target platform and your playback requirements.

Available implementations:

• android::Player: Use this when compiling for Android to access native Android haptic playback.
• null::Player: A dummy player implementation that does nothing; it is available for all target operating systems (useful for testing or when haptics are disabled).
• streaming::Player: Use this implementation when you need to stream clip breakpoints to callbacks rather than playing a static clip.

// Conceptually, you will interact with an object implementing this trait:
// trait PreAuthoredClipPlayback { ... }

In the context of Nice Vibrations, an Interface is any mechanism used to call into or pass data into the core library. Interfaces serve as the bridge between the core haptic logic and external environments. Common examples include:

• Game Engine Integrations: Such as the Unity editor plugin.
• Application Plugins: Extensions for other software.
• Language Wrappers: Adapters that expose the core API to specific programming languages (e.g., C#, Rust, etc.).

A continuous signal is the primary way to represent haptic data. It consists of parameter modulation envelopes:

Amplitude Envelope

Defines amplitude values over time using multiple breakpoints. Each breakpoint requires:

• time: Float (seconds)
• amplitude: Float (0.0 to 1.0)
• emphasis (Optional): An Emphasis structure applied to the breakpoint.

Frequency Envelope

Modulates the frequency ratio over time. Each breakpoint requires:

• time: Float (seconds)
• frequency: Float (0.0 to 1.0). This is a normalized value corresponding to the scaled output of the centroid tracker.

Emphasis Structure

Applied to amplitude breakpoints to add detail:

• amplitude: Float (0.0 to 1.0)
• frequency: Float (0.0 to 1.0) (Normalized frequency value)

The VIJ (Vibration Intermediate JSON) data model is the structured format used to represent haptic content. A VIJ file is composed of three primary top-level sections: Metadata, Variations, and Voices.

Root Structure

• Metadata: Contextual data about the file (e.g., editor used, duration).
• Variations: Parameters that modify the haptic output, such as global gain.
• Voices: The core haptic data containing envelopes, bands, and transients.

Data Hierarchy

1. Metadata: Stores editor (string), format (string), and duration (float in seconds).
2. Variation: Stores total gain (float, 0.0–1.0) and partials (float).
3. Voices: Contains the actual haptic waveforms via envelopes and transients.

If you make changes to the iOS, Android, or Unity Editor plugin host platforms, you must run the build-platform.sh script. This ensures that the latest changes from those libraries are correctly copied into the appropriate Unity asset folders within the project.

./build-platform.sh