CrowdControl/Assets/Feel/NiceVibrations/Scripts/Components/HapticController.cs

// Copyright (c) Meta Platforms, Inc. and affiliates. 

using UnityEngine;
using System;
using System.Timers;

#if (UNITY_ANDROID && !UNITY_EDITOR)
using System.Text;
#elif (UNITY_IOS && !UNITY_EDITOR)
using UnityEngine.iOS;
#endif

namespace Lofelt.NiceVibrations
{
    /// <summary>
    /// Provides haptic playback functionality.
    /// </summary>
    ///
    /// HapticController allows you to load and play <c>.haptic</c> clips, and
    /// provides various ways to control playback, such as seeking, looping and
    /// amplitude/frequency modulation.
    ///
    /// If you need a <c>MonoBehaviour</c> API, use HapticSource and
    /// HapticReceiver instead.
    ///
    /// On iOS and Android, the device is vibrated, using <c>LofeltHaptics</c>.
    /// On any platform, when a gamepad is connected, that gamepad is vibrated,
    /// using GamepadRumbler.
    ///
    /// Gamepads are vibrated automatically when HapticController detects that a
    /// gamepad is connected, no special code is needed to support gamepads.
    /// Gamepads only support Load(), Play(), Stop(), \ref clipLevel and \ref
    /// outputLevel. Other features like Seek(), Loop() and \ref clipFrequencyShift
    /// will have no effect on gamepads.
    ///
    /// None of the methods here are thread-safe and should only be called from
    /// the main (Unity) thread. Calling these methods from a secondary thread can
    /// cause undefined behaviour and memory leaks.
    public static class HapticController
    {
        static bool lofeltHapticsInitalized = false;

        // Timer used to call HandleFinishedPlayback() when playback is complete
        static Timer playbackFinishedTimer = new Timer();

        // Duration of the loaded haptic clip, in seconds
        static float clipLoadedDurationSecs = 0.0f;

        // Whether Load() has been called before
        static bool clipLoaded = false;

        // The value of the last call to seek()
        static float lastSeekTime = 0.0f;

        // Flag indicating if the device supports playing back .haptic clips
        static bool deviceMeetsAdvancedRequirements = false;

        // Flag indicating if the user enabled playback looping.
        // This does not necessarily mean that the currently active playback is looping, for
        // example gamepads don't support looping.
        static bool isLoopingEnabledByUser = false;

        // Flag indicating if the currently active playback is looping
        static bool isPlaybackLooping = false;

        static HapticPatterns.PresetType _fallbackPreset = HapticPatterns.PresetType.None;

        /// <summary>
        /// The haptic preset to be played when it's not possible to play a haptic clip
        /// </summary>
        public static HapticPatterns.PresetType fallbackPreset
        {
            get { return _fallbackPreset; }
            set { _fallbackPreset = value; }
        }

        internal static bool _hapticsEnabled = true;

        /// <summary>
        /// Property to enable and disable global haptic playback
        /// </summary>
        public static bool hapticsEnabled
        {
            get { return _hapticsEnabled; }
            set
            {
                if (_hapticsEnabled)
                {
                    Stop();
                }
                _hapticsEnabled = value;
            }
        }

        internal static float _outputLevel = 1.0f;

        /// <summary>
        /// The overall haptic output level
        /// </summary>
        ///
        /// It can be interpreted as the "volume control" for haptic playback.
        /// Output level is applied in combination with \ref clipLevel to the currently playing haptic clip.
        /// The combination of these two levels and the amplitude within the loaded haptic at a given moment
        /// in time determines the strength of the vibration felt on the device. \ref outputLevel is best used
        /// to increase or decrease the overall haptic level in a game.
        ///
        /// As output level pertains to all clips, unlike \ref clipLevel, it persists when a new clip is loaded.
        ///
        /// \ref outputLevel is a multiplication factor, it is <i>not</i> a dB value. The factor needs to be
        /// 0 or greater.
        ///
        /// The combination of \ref outputLevel and \ref clipLevel can result in a gain (for factors
        /// greater than 1.0) or an attenuation (for factors less than 1.0) to the clip. If the
        /// combination of \ref outputLevel, \ref clipLevel and the amplitude within the loaded haptic
        /// is greater than 1.0, it is clipped to 1.0. Hard clipping is performed, no limiter is used.
        ///
        /// On Android, an adjustment to \ref outputLevel will take effect in the next call to Play().
        /// On iOS, it will take effect right away.
        [System.ComponentModel.DefaultValue(1.0f)]
        public static float outputLevel
        {
            get { return _outputLevel; }
            set
            {
                _outputLevel = value;

                ApplyLevelsToLofeltHaptics();
                ApplyLevelsToGamepadRumbler();
            }
        }

        internal static float _clipLevel = 1.0f;

        /// <summary>
        /// The level of the loaded clip
        /// </summary>
        ///
        /// Clip level is applied in combination with \ref outputLevel, to the
        /// currently playing haptic clip. The combination of these two levels and the amplitude within the loaded
        /// haptic at a given moment in time determines the strength of the vibration felt on the device.
        /// \ref clipLevel is best used to adjust the level of a single clip based on game state.
        ///
        /// As clip level is specific to an individual clip, unlike \ref outputLevel, it resets to
        /// 1.0 when a new clip is loaded.
        ///
        /// \ref clipLevel is a multiplication factor, it is <i>not</i> a dB value. The factor needs to be
        /// 0 or greater.
        ///
        /// The combination of \ref outputLevel and \ref clipLevel can result in a gain (for factors
        /// greater than 1.0) or an attenuation (for factors less than 1.0) to the clip.
        ///
        /// If the combination of \ref outputLevel, \ref clipLevel and the amplitude within the loaded
        /// haptic is greater than 1.0, it is clipped to 1.0. Hard clipping is performed, no limiter is used.
        ///
        /// The clip needs to be loaded with Load() before adjusting \ref clipLevel. Loading a clip
        /// resets \ref clipLevel back to the default of 1.0.
        ///
        /// On Android, an adjustment to \ref clipLevel will take effect in the next call to Play(). On iOS,
        /// it will take effect right away.
        ///
        /// On Android, setting the clip level should be done before calling \ref Seek(), since
        /// setting a clip level ignores the sought value.
        ///
        [System.ComponentModel.DefaultValue(1.0f)]
        public static float clipLevel
        {
            get { return _clipLevel; }
            set
            {
                _clipLevel = value;

                ApplyLevelsToLofeltHaptics();
                ApplyLevelsToGamepadRumbler();
            }
        }

        /// Action that is invoked when Load() is called
        public static Action LoadedClipChanged;

        /// Action that is invoked when Play() is called
        public static Action PlaybackStarted;

        /// <summary>
        /// Action that is invoked when the playback has finished
        /// </summary>
        ///
        /// This happens either when Stop() is explicitly called, or when a non-looping
        /// clip has finished playing.
        ///
        /// This can be invoked spuriously, even if no haptics are currently playing, for example
        /// if Stop() is called multiple times in a row.
        public static Action PlaybackStopped;

        // Applies the current clip level and output level as the amplitude multiplication to
        // LofeltHaptics
        private static void ApplyLevelsToLofeltHaptics()
        {
            if (Init())
            {
                LofeltHaptics.SetAmplitudeMultiplication(_outputLevel * _clipLevel);
            }
        }

        // Applies the current clip level and output level as the motor speed multiplication to
        // GamepadRumbler
        private static void ApplyLevelsToGamepadRumbler()
        {
            #if ((!UNITY_ANDROID && !UNITY_IOS) || UNITY_EDITOR) && NICE_VIBRATIONS_INPUTSYSTEM_INSTALLED && ENABLE_INPUT_SYSTEM && !NICE_VIBRATIONS_DISABLE_GAMEPAD_SUPPORT
                            GamepadRumbler.lowFrequencyMotorSpeedMultiplication = _outputLevel * _clipLevel;
                            GamepadRumbler.highFrequencyMotorSpeedMultiplication = _outputLevel * _clipLevel;
            #endif
        }

        /// <summary>
        /// Initializes HapticController.
        /// </summary>
        ///
        /// Calling this method multiple times has no effect and is safe.
        ///
        /// You do not need to call this method, HapticController automatically calls this
        /// method before any operation that needs initialization, such as Play().
        /// However it can be beneficial to call this early during startup, so the initialization
        /// time is spent at startup instead of when the first haptic is triggered during gameplay.
        /// If you have a HapticReceiver in your scene, it takes care of calling
        /// Init() during startup for you.
        ///
        /// Do not call this method from a static constructor. Unity often invokes static
        /// constructors from a different thread, for example during deserialization. The
        /// initialization code is not thread-safe. This is the reason this method is not called
        /// from the static constructor of HapticController or HapticReceiver.
        ///
        /// <returns>Whether the device supports the minimum requirements to play haptics</returns>
        public static bool Init()
        {
            if (!lofeltHapticsInitalized)
            {
                lofeltHapticsInitalized = true;

                var syncContext = System.Threading.SynchronizationContext.Current;
                playbackFinishedTimer.Elapsed += (object obj, System.Timers.ElapsedEventArgs args) =>
                {
                    // Timer elapsed events are called from a separate thread, so use
                    // SynchronizationContext to handle it in the main thread.
                    syncContext.Post(_ =>
                    {
                        HandleFinishedPlayback();
                    }, null);
                };

                if (DeviceCapabilities.isVersionSupported)
                {
                    LofeltHaptics.Initialize();
                    DeviceCapabilities.Init();
                    deviceMeetsAdvancedRequirements = DeviceCapabilities.meetsAdvancedRequirements;
                }

                GamepadRumbler.Init();
            }
            return deviceMeetsAdvancedRequirements;
        }

        /// <summary>
        /// Loads a haptic clip given in JSON format for later playback.
        /// </summary>
        ///
        /// This overload of Load() is useful in cases there is only the JSON data of a haptic clip
        /// available. Due to only having the JSON data and no GamepadRumble, gamepad playback is
        /// not supported with this overload.
        ///
        /// <param name="data">The haptic clip, which is the content of the
        /// <c>.haptic</c> file, a UTF-8 encoded JSON string without a null
        /// terminator</param>
        public static void Load(byte[] data)
        {
            GamepadRumbler.Unload();
            lastSeekTime = 0.0f;
            clipLoaded = true;
            clipLoadedDurationSecs = 0.0f;
            if (Init())
            {
                LofeltHaptics.Load(data);
            }
            clipLevel = 1.0f;
            LoadedClipChanged?.Invoke();
        }

        /// <summary>
        /// Loads the given HapticClip for later playback.
        /// </summary>
        ///
        /// This is the standard way to load a haptic clip, while the other overloads of Load()
        /// are for more specialized cases.
        ///
        /// At the moment only one clip can be loaded at a time.
        ///
        /// <param name="clip">The HapticClip to be loaded</param>
        public static void Load(HapticClip clip)
        {
            Load(clip.json, clip.gamepadRumble);
        }

        /// <summary>
        /// Loads the haptic clip given as JSON and GamepadRumble for later playback.
        /// </summary>
        ///
        /// This is an overload of Load() that is useful when a HapticClip is not available, and
        /// both the JSON and GamepadRumble are. One such case is generating both dynamically at
        /// runtime.
        ///
        /// <param name="json">The haptic clip, which is the content of the <c>.haptic</c> file,
        /// a UTF-8 encoded JSON string without a null terminator</param>
        /// <param name="rumble">The GamepadRumble representation of the haptic clip</param>
        public static void Load(byte[] json, GamepadRumble rumble)
        {
            Load(json);

            GamepadRumbler.Load(rumble);
            // GamepadRumbler.Load() resets the motor speed multiplication to 1.0, so the levels
            // need to be applied here again
            ApplyLevelsToGamepadRumbler();

            // Load() only sets the correct clip duration on iOS and Android, and sets it to 0.0
            // on other platforms. For the other platforms, set a clip duration based on the
            // GamepadRumble here.
            if (clipLoadedDurationSecs == 0.0f && rumble.IsValid())
            {
                clipLoadedDurationSecs = rumble.totalDurationMs / 1000.0f;
            }
        }

        static void HandleFinishedPlayback()
        {
            lastSeekTime = 0.0f;
            isPlaybackLooping = false;
            playbackFinishedTimer.Enabled = false;
            PlaybackStopped?.Invoke();
        }

        /// <summary>
        /// Plays the haptic clip that was previously loaded with Load().
        /// </summary>
        ///
        /// If <c>Loop(true)</c> was called previously, the playback will be repeated
        /// until Stop() is called. Otherwise the haptic clip will only play once.
        ///
        /// In case the device does not meet the requirements to play <c>.haptic</c> clips, this
        /// function will call HapticPatterns.PlayPreset() with the \ref fallbackPreset set. In this
        /// case, functionality like seeking, looping and runtime modulation won't do anything as
        /// they aren't available for haptic presets.
        public static void Play()
        {
            if (!_hapticsEnabled)
            {
                return;
            }

            float remainingPlayDuration = 0.0f;
            bool canLoop = false;
            if (GamepadRumbler.CanPlay())
            {
                remainingPlayDuration = clipLoadedDurationSecs;
                GamepadRumbler.Play();
            }
            else if (Init())
            {
                remainingPlayDuration = Mathf.Max(clipLoadedDurationSecs - lastSeekTime, 0.0f);
                canLoop = DeviceCapabilities.canLoop;
                LofeltHaptics.Play();
            }
            else if (DeviceCapabilities.isVersionSupported)
            {
                remainingPlayDuration = HapticPatterns.GetPresetDuration(fallbackPreset);
                HapticPatterns.PlayPreset(fallbackPreset);
            }

            isPlaybackLooping = isLoopingEnabledByUser && canLoop;
            PlaybackStarted?.Invoke();

            //
            // Call HandleFinishedPlayback() after the playback finishes
            //
            if (remainingPlayDuration > 0.0f)
            {
                playbackFinishedTimer.Interval = remainingPlayDuration * 1000;
                playbackFinishedTimer.AutoReset = false;
                playbackFinishedTimer.Enabled = !isPlaybackLooping;
            }
            else
            {
                // Setting playbackFinishedTimer.Interval needs an interval > 0, otherwise it will
                // throw an exception.
                // Even if the remaining play duration is 0, we still want to trigger everything
                // that happens in HandleFinishedPlayback().
                // A playback duration of 0 happens in the Unity editor, when loading the clip
                // failed or when seeking to the end of a clip.
                HandleFinishedPlayback();
            }
        }


        /// <summary>
        /// Loads and plays the HapticClip given as an argument.
        /// </summary>
        ///
        /// <param name="clip">The HapticClip to be played</param>
        public static void Play(HapticClip clip)
        {
            Load(clip);
            Play();
        }

        /// <summary>
        /// Stops haptic playback
        ///
        /// </summary>
        public static void Stop()
        {

            if (Init())
            {
                LofeltHaptics.Stop();
            }
            else
            {
                LofeltHaptics.StopPattern();
            }
            GamepadRumbler.Stop();
            HandleFinishedPlayback();
        }

        /// <summary>
        /// Jumps to a time position in the haptic clip.
        /// </summary>
        ///
        /// The playback will always be stopped when this function is called.
        /// This is to match the behavior between iOS and Android, since Android needs to
        /// restart playback for seek to have effect.
        ///
        /// If seeking beyond the end of the clip, Play() will not reproduce any haptics.
        /// Seeking to a negative position will seek to the beginning of the clip.
        ///
        /// <param name="time">The new position within the clip, as seconds from the beginning
        /// of the clip</param>
        public static void Seek(float time)
        {
            if (Init())
            {
                LofeltHaptics.Stop();
                LofeltHaptics.Seek(time);
            }
            GamepadRumbler.Stop();
            lastSeekTime = time;
        }

        /// <summary>
        /// Adds the given shift to the frequency of every breakpoint in the clip, including the
        /// emphasis.
        /// </summary>
        ///
        /// In other words, this property shifts all frequencies of the clip. The frequency shift is
        /// added to each frequency value and needs to be between -1.0 and 1.0. If the resulting
        /// frequency of a breakpoint is smaller than 0.0 or greater than 1.0, it is clipped to that
        /// range. The frequency is clipped hard, no limiter is used.
        ///
        /// The clip needs to be loaded with Load() first. Loading a clip resets the shift back
        /// to the default of 0.0.
        ///
        /// Setting the frequency shift has no effect on Android; it only works on iOS.
        ///
        /// A call to this property will change the frequency shift of a currently playing clip
        /// right away. If no clip is playing, the shift is applied in the next call to
        /// Play().
        [System.ComponentModel.DefaultValue(0.0f)]
        public static float clipFrequencyShift
        {
            set
            {
                if (Init())
                {
                    LofeltHaptics.SetFrequencyShift(value);
                }
            }
        }

        /// <summary>
        /// Set the playback of a haptic clip to loop.
        /// </summary>
        ///
        /// On Android, calling this will always put the playback position at the start of the clip.
        /// Also, it will only have an effect when Play() is called again.
        ///
        /// On iOS, if a clip is already playing, calling this will leave the playback position as
        /// it is and repeat when it reaches the end. No need to call Play() again for
        /// changes to take effect.
        ///
        /// <param name="enabled">If the value is <c>true</c>, looping will be enabled which results
        /// in repeating the playback until Stop() is called; if <c>false</c>, the haptic
        /// clip will only be played once.</param>
        public static void Loop(bool enabled)
        {
            if (Init())
            {
                LofeltHaptics.Loop(enabled);
            }
            isLoopingEnabledByUser = enabled;
        }

        /// <summary>
        /// Checks if the loaded haptic clip is playing.
        /// </summary>
        ///
        /// <returns>Whether the loaded clip is playing</returns>
        public static bool IsPlaying()
        {
            if (playbackFinishedTimer.Enabled)
            {
                return true;
            }
            else
            {
                return isPlaybackLooping;
            }
        }

        /// <summary>
        /// Stops playback and resets the playback state.
        /// </summary>
        ///
        /// Seek position, clip level, clip frequency shift and loop are reset to the
        /// default values.
        /// The currently loaded clip stays loaded.
        /// \ref hapticsEnabled and \ref outputLevel are not reset.
        public static void Reset()
        {
            if (clipLoaded)
            {
                Seek(0.0f);
                Stop();
                clipLevel = 1.0f;
                clipFrequencyShift = 0.0f;
                Loop(false);
            }
            fallbackPreset = HapticPatterns.PresetType.None;
        }

        /// <summary>
        /// Processes an application focus change event.
        /// </summary>
        ///
        /// If you have a HapticReceiver in your scene, the HapticReceiver
        /// will take care of calling this method when needed. Otherwise it is your
        /// responsibility to do so.
        ///
        /// When the application loses the focus, playback is stopped.
        ///
        /// <param name="hasFocus">Whether the application now has focus</param>
        public static void ProcessApplicationFocus(bool hasFocus)
        {
            if (!hasFocus)
            {
                // While LofeltHaptics stops playback when the app loses focus,
                // calling Stop() here handles additional things such as invoking
                // the PlaybackStopped Action.
                Stop();
            }
        }
    }
}