app.hypergames.hypersdk 1.10.0 → 1.11.0-beta.2

package/Runtime/Public/Core/HyperSDK.cs

@@ -17,6 +17,7 @@ namespace Hyper
         private static EventAPIAdapter _eventAdapter;
         private static LoaderAPIAdapter _loaderAdapter;
         private static ScreenAPIAdapter _screenAdapter;
+        private static ReplayAPIAdapter _replayAdapter;
 
         /// <summary>
         /// Returns true if the SDK runtime has been initialized.
@@ -91,6 +92,19 @@ namespace Hyper
             }
         }
 
+        /// <summary>
+        /// Access replayed gameplay activities. The SDK owns loading, timing,
+        /// progress, suspension and completion.
+        /// </summary>
+        public static IReplayAPI Replay
+        {
+            get
+            {
+                EnsureAdaptersReady();
+                return _replayAdapter;
+            }
+        }
+
         /// <summary>
         /// Access loader control for custom pre-loading workflows.
         /// Use when EnableCustomLoading is enabled in HyperGameContentConfig.
@@ -149,7 +163,13 @@ namespace Hyper
                 _eventAdapter = new EventAPIAdapter();
             }
 
+            if (_replayAdapter == null)
+            {
+                _replayAdapter = new ReplayAPIAdapter();
+            }
+
             _eventAdapter.RefreshBindings();
+            _replayAdapter.RefreshBindings();
         }
 
     }
@@ -159,29 +179,34 @@ namespace Hyper
     /// </summary>
     public interface IGameAPI
     {
-		/// <summary>
-		/// True when the current mode is Battle (PvP or timed battle).
-		/// </summary>
+        /// <summary>
+        /// True when using Battle gameplay. Replay mode also returns true so games
+        /// can load the same level and rules used by the original battle.
+        /// </summary>
         bool IsBattleMode { get; }
-		/// <summary>
-		/// True when the current mode is Practice.
-		/// </summary>
+        /// <summary>
+        /// True when the current mode is Practice.
+        /// </summary>
         bool IsPracticeMode { get; }
-		/// <summary>
-		/// True if the game is currently paused by the SDK.
-		/// </summary>
+        /// <summary>
+        /// True when the SDK is playing a recorded battle session.
+        /// </summary>
+        bool IsReplayMode { get; }
+        /// <summary>
+        /// True if the game is currently paused by the SDK.
+        /// </summary>
         bool IsPaused { get; }
-		/// <summary>
-		/// True once gameplay has begun (post countdown/start).
-		/// </summary>
+        /// <summary>
+        /// True once gameplay has begun (post countdown/start).
+        /// </summary>
         bool HasGameStarted { get; }
-		/// <summary>
-		/// True after the current game session has ended.
-		/// </summary>
+        /// <summary>
+        /// True after the current game session has ended.
+        /// </summary>
         bool HasGameEnded { get; }
 
         /// <summary>
-        /// Seconds remaining on the PvP match clock. Zero in practice mode or when not in a timed battle.
+        /// Seconds remaining on the timed Battle or Replay clock. Zero in Practice mode.
         /// </summary>
         int BattleTimeRemaining { get; }
 
@@ -196,105 +221,155 @@ namespace Hyper
         [Obsolete("Use EndGame() instead; it ends practice or battle based on the current mode.")]
         void EndPracticeGame();
 
-		/// <summary>
-		/// Closes the practice menu and enters gameplay (only relevant when practice scene is a menu).
-		/// </summary>
+        /// <summary>
+        /// Closes the practice menu and enters gameplay (only relevant when practice scene is a menu).
+        /// </summary>
         void ExitPracticeMenu();
 
         // Lives Management (only available when ControlBarLayout is HeartsLeft)
-		/// <summary>
-		/// Initialize the lives system with a maximum and optional initial value.
-		/// </summary>
+        /// <summary>
+        /// Initialize the lives system with a maximum and optional initial value.
+        /// </summary>
         void InitializeLives(int maxLives, int initialLives = -1);
-		/// <summary>
-		/// Set the current number of lives.
-		/// </summary>
+        /// <summary>
+        /// Set the current number of lives.
+        /// </summary>
         void SetLives(int lives);
-		/// <summary>
-		/// Increment lives by one.
-		/// </summary>
+        /// <summary>
+        /// Increment lives by one.
+        /// </summary>
         void AddLife();
-		/// <summary>
-		/// Decrement lives by one.
-		/// </summary>
+        /// <summary>
+        /// Decrement lives by one.
+        /// </summary>
         void RemoveLife();
-		/// <summary>
-		/// Get the current number of lives.
-		/// </summary>
+        /// <summary>
+        /// Get the current number of lives.
+        /// </summary>
         int GetCurrentLives();
-		/// <summary>
-		/// Get the configured maximum number of lives.
-		/// </summary>
+        /// <summary>
+        /// Get the configured maximum number of lives.
+        /// </summary>
         int GetMaxLives();
 
         // Health Management (only available when ControlBarLayout is HealthBarGreenLeft)
-		/// <summary>
-		/// Initialize the health system with a maximum and optional initial value.
-		/// </summary>
+        /// <summary>
+        /// Initialize the health system with a maximum and optional initial value.
+        /// </summary>
         void InitializeHealth(float maxHealth, float initialHealth = -1f, bool isNormalized = false);
-		/// <summary>
-		/// Set the current health (absolute units).
-		/// </summary>
+        /// <summary>
+        /// Set the current health (absolute units).
+        /// </summary>
         void SetHealth(float health);
-		/// <summary>
-		/// Set the current health as a normalized value in [0,1].
-		/// </summary>
+        /// <summary>
+        /// Set the current health as a normalized value in [0,1].
+        /// </summary>
         void SetHealthNormalized(float normalizedHealth);
-		/// <summary>
-		/// Add to the current health by an absolute amount.
-		/// </summary>
+        /// <summary>
+        /// Add to the current health by an absolute amount.
+        /// </summary>
         void AddHealth(float amount);
-		/// <summary>
-		/// Remove from the current health by an absolute amount.
-		/// </summary>
+        /// <summary>
+        /// Remove from the current health by an absolute amount.
+        /// </summary>
         void RemoveHealth(float amount);
-		/// <summary>
-		/// Get the current health (absolute units).
-		/// </summary>
+        /// <summary>
+        /// Get the current health (absolute units).
+        /// </summary>
         float GetCurrentHealth();
-		/// <summary>
-		/// Get the maximum health (absolute units).
-		/// </summary>
+        /// <summary>
+        /// Get the maximum health (absolute units).
+        /// </summary>
         float GetMaxHealth();
-		/// <summary>
-		/// Get the current health normalized to [0,1].
-		/// </summary>
+        /// <summary>
+        /// Get the current health normalized to [0,1].
+        /// </summary>
         float GetHealthNormalized();
     }
 
     /// <summary>
     /// Public API for score and gameplay data management.
     /// </summary>
+    /// <remarks>
+    /// For deterministic physics replay, queue raw input from Update and record it in the
+    /// same FixedUpdate where the input is applied to the simulation.
+    /// </remarks>
     public interface IDataAPI
     {
-		/// <summary>
-		/// Current in-session score value.
-		/// </summary>
+        /// <summary>
+        /// Current in-session score value.
+        /// </summary>
         int CurrentScore { get; }
 
-		/// <summary>
-		/// Overwrite the current score with a new value.
-		/// </summary>
+        /// <summary>
+        /// Overwrite the current score with a new value.
+        /// </summary>
         void UpdateScore(int score);
-		/// <summary>
-		/// Set the combo multiplier applied to scoring.
-		/// </summary>
+        /// <summary>Records one numeric replay value with a fixed-simulation-aligned session timestamp.</summary>
+        /// <param name="value">The value to record.</param>
+        /// <example><code>HyperSDK.Data.RecordActivity(0.39f); // [time, 0.39]</code></example>
+        void RecordActivity(float value);
+        /// <summary>Records two numeric replay values in the supplied order.</summary>
+        /// <param name="first">The first value.</param>
+        /// <param name="second">The second value.</param>
+        /// <example><code>HyperSDK.Data.RecordActivity(4f, 2f); // [time, 4, 2]</code></example>
+        void RecordActivity(float first, float second);
+        /// <summary>Records three numeric replay values in the supplied order.</summary>
+        /// <param name="first">The first value.</param>
+        /// <param name="second">The second value.</param>
+        /// <param name="third">The third value.</param>
+        /// <example><code>HyperSDK.Data.RecordActivity(1f, 5f, 3f); // [time, 1, 5, 3]</code></example>
+        void RecordActivity(float first, float second, float third);
+        /// <summary>Records one named replay action. GS, GP, GR, and GE are reserved by the SDK.</summary>
+        /// <param name="action">A non-empty game-defined action name.</param>
+        /// <example><code>HyperSDK.Data.RecordActivity("WoodenWand"); // [time, "WoodenWand"]</code></example>
+        void RecordActivity(string action);
+        /// <summary>Records two named replay actions in the supplied order.</summary>
+        /// <param name="firstAction">The first game-defined action.</param>
+        /// <param name="secondAction">The second game-defined action.</param>
+        /// <example><code>HyperSDK.Data.RecordActivity("D", "R"); // [time, "D", "R"]</code></example>
+        void RecordActivity(string firstAction, string secondAction);
+        /// <summary>Records a named action followed by one numeric value.</summary>
+        /// <param name="action">A non-empty game-defined action name.</param>
+        /// <param name="first">The numeric value associated with the action.</param>
+        /// <example><code>HyperSDK.Data.RecordActivity("B", 5f); // [time, "B", 5]</code></example>
+        void RecordActivity(string action, float first);
+        /// <summary>Records one numeric value followed by a named action.</summary>
+        /// <param name="first">The numeric value.</param>
+        /// <param name="action">A non-empty game-defined action name.</param>
+        /// <example><code>HyperSDK.Data.RecordActivity(5f, "B"); // [time, 5, "B"]</code></example>
+        void RecordActivity(float first, string action);
+        /// <summary>Records a named action followed by two numeric values.</summary>
+        /// <param name="action">A non-empty game-defined action name.</param>
+        /// <param name="first">The first numeric value.</param>
+        /// <param name="second">The second numeric value.</param>
+        /// <example><code>HyperSDK.Data.RecordActivity("B", 3f, 5f); // [time, "B", 3, 5]</code></example>
+        void RecordActivity(string action, float first, float second);
+        /// <summary>Records two numeric values followed by a named action.</summary>
+        /// <param name="first">The first numeric value.</param>
+        /// <param name="second">The second numeric value.</param>
+        /// <param name="action">A non-empty game-defined action name.</param>
+        /// <example><code>HyperSDK.Data.RecordActivity(4f, 2f, "R"); // [time, 4, 2, "R"]</code></example>
+        void RecordActivity(float first, float second, string action);
+        /// <summary>
+        /// Set the combo multiplier applied to scoring.
+        /// </summary>
         void SetComboMultiplier(float value);
-		/// <summary>
-		/// Set a global multiplier applied to scoring.
-		/// </summary>
+        /// <summary>
+        /// Set a global multiplier applied to scoring.
+        /// </summary>
         void SetGlobalMultiplier(float value);
-		/// <summary>
-		/// Register that a powerup is active by type identifier.
-		/// </summary>
+        /// <summary>
+        /// Register that a powerup is active by type identifier.
+        /// </summary>
         void AddPowerup(string powerupType);
-		/// <summary>
-		/// Remove an active powerup by type identifier.
-		/// </summary>
+        /// <summary>
+        /// Remove an active powerup by type identifier.
+        /// </summary>
         void RemovePowerup(string powerupType);
-		/// <summary>
-		/// Retrieve the best/high score recorded for the player.
-		/// </summary>
+        /// <summary>
+        /// Retrieve the best/high score recorded for the player.
+        /// </summary>
         int GetBestScore();
     }
 
@@ -334,44 +409,88 @@ namespace Hyper
     /// </summary>
     public interface IEventAPI
     {
-		/// <summary>
-		/// Fired when gameplay begins.
-		/// </summary>
+        /// <summary>
+        /// Fired when gameplay begins.
+        /// </summary>
         event Action OnGameStart;
-		/// <summary>
-		/// Fired when the match timer reaches zero (battle mode).
-		/// </summary>
+        /// <summary>
+        /// Fired when the match timer reaches zero (battle mode).
+        /// </summary>
         event Action OnTimeUp;
-		/// <summary>
-		/// Fired when the game is paused by the SDK.
-		/// </summary>
+        /// <summary>
+        /// Fired when the game is paused by the SDK.
+        /// </summary>
         event Action OnGamePaused;
-		/// <summary>
-		/// Fired when the game resumes from a paused state.
-		/// </summary>
+        /// <summary>
+        /// Fired when the game resumes from a paused state.
+        /// </summary>
         event Action OnGameResumed;
-		/// <summary>
-		/// Fired when the current game session ends.
-		/// </summary>
+        /// <summary>
+        /// Fired when gameplay is frozen by setting <see cref="Time.timeScale"/> to zero.
+        /// </summary>
+        event Action OnTimeScaleFrozen;
+        /// <summary>
+        /// Fired when gameplay resumes from a zero <see cref="Time.timeScale"/>.
+        /// </summary>
+        event Action OnTimeScaleResumed;
+        /// <summary>
+        /// Fired when the current game session ends.
+        /// </summary>
         event Action OnGameEnded;
-		/// <summary>
-		/// Fired when the SDK sound setting changes (true = enabled).
-		/// </summary>
+        /// <summary>
+        /// Fired when the SDK sound setting changes (true = enabled).
+        /// </summary>
         event Action<bool> OnSoundChanged;
-		/// <summary>
-		/// Fired when lives reach zero (when lives UI is in use).
-		/// </summary>
+        /// <summary>
+        /// Fired when lives reach zero (when lives UI is in use).
+        /// </summary>
         event Action OnLivesExhausted;
-		/// <summary>
-		/// Fired when health reaches zero (when health UI is in use).
-		/// </summary>
+        /// <summary>
+        /// Fired when health reaches zero (when health UI is in use).
+        /// </summary>
         event Action OnHealthExhausted;
-		/// <summary>
-		/// Fired when a custom restart flow is requested by the SDK.
-		/// </summary>
+        /// <summary>
+        /// Fired when a custom restart flow is requested by the SDK.
+        /// </summary>
         event Action OnCustomRestart;
     }
 
+    /// <summary>
+    /// Callbacks for activities dispatched from an active replay. Games map
+    /// these callbacks to their existing gameplay commands.
+    /// </summary>
+    public interface IReplayAPI
+    {
+        event Action<float, float> OnValues2;
+        event Action<float> OnValue;
+        event Action<float, float, float> OnValues;
+        event Action<string> OnAction;
+        event Action<string, string> OnActions;
+        event Action<string, float, float> OnActionValues;
+        event Action<float, float, string> OnValuesAction;
+        event Action<string, float> OnActionValue;
+        event Action<float, string> OnValueAction;
+
+        /// <summary>
+        /// Fired before a named action when <see cref="ActionPreparationLeadSeconds"/>
+        /// is configured. Use it only for presentation such as button-down feedback.
+        /// </summary>
+        event Action<string> OnActionPreparing;
+
+        /// <summary>Fired when all replay activities have been dispatched.</summary>
+        event Action OnEnded;
+
+        bool IsPlaying { get; }
+        double DurationSeconds { get; }
+        double ElapsedSeconds { get; }
+        float Progress01 { get; }
+
+        /// <summary>
+        /// Optional visual lead time. Gameplay actions still fire at their recorded time.
+        /// </summary>
+        double ActionPreparationLeadSeconds { get; set; }
+    }
+
     /// <summary>
     /// Safe-area-adjusted screen dimensions.
     /// Use these instead of Screen.width / Screen.height to match the playable area after notch and system inset adjustments.
@@ -479,6 +598,7 @@ namespace Hyper
 
         public bool IsBattleMode => Manager != null && Manager.IsBattleMode;
         public bool IsPracticeMode => Manager != null && Manager.IsPracticeMode;
+        public bool IsReplayMode => Manager != null && Manager.IsReplayMode;
         public bool IsPaused => Manager != null && Manager.IsPaused;
         public bool HasGameStarted => Manager != null && Manager.HasGameStarted;
         public bool HasGameEnded => Manager != null && Manager.HasGameEnded;
@@ -523,6 +643,15 @@ namespace Hyper
         public int CurrentScore => Manager?.CurrentScore ?? 0;
 
         public void UpdateScore(int score) => Manager?.UpdateScore(score);
+        public void RecordActivity(float value) => Manager?.RecordActivity(value);
+        public void RecordActivity(float first, float second) => Manager?.RecordActivity(first, second);
+        public void RecordActivity(float first, float second, float third) => Manager?.RecordActivity(first, second, third);
+        public void RecordActivity(string action) => Manager?.RecordActivity(action);
+        public void RecordActivity(string firstAction, string secondAction) => Manager?.RecordActivity(firstAction, secondAction);
+        public void RecordActivity(string action, float first) => Manager?.RecordActivity(action, first);
+        public void RecordActivity(float first, string action) => Manager?.RecordActivity(first, action);
+        public void RecordActivity(string action, float first, float second) => Manager?.RecordActivity(action, first, second);
+        public void RecordActivity(float first, float second, string action) => Manager?.RecordActivity(first, second, action);
         public void SetComboMultiplier(float value) => Manager?.SetComboMultiplier(value);
         public void SetGlobalMultiplier(float value) => Manager?.SetGlobalMultiplier(value);
         public void AddPowerup(string powerupType) => Manager?.AddPowerup(powerupType);
@@ -530,6 +659,41 @@ namespace Hyper
         public int GetBestScore() => Manager?.GetBestScore() ?? 0;
     }
 
+    /// <summary>
+    /// Bridges the SDK-owned scheduler to game-specific replay handlers.
+    /// </summary>
+    internal sealed class ReplayAPIAdapter : IReplayAPI
+    {
+        private readonly ReplayPlaybackEngine _playback = new ReplayPlaybackEngine();
+
+        public event Action<float, float> OnValues2 { add => _playback.OnValues2 += value; remove => _playback.OnValues2 -= value; }
+        public event Action<float> OnValue { add => _playback.OnValue += value; remove => _playback.OnValue -= value; }
+        public event Action<float, float, float> OnValues { add => _playback.OnValues += value; remove => _playback.OnValues -= value; }
+        public event Action<string> OnAction { add => _playback.OnAction += value; remove => _playback.OnAction -= value; }
+        public event Action<string, string> OnActions { add => _playback.OnActions += value; remove => _playback.OnActions -= value; }
+        public event Action<string, float, float> OnActionValues { add => _playback.OnActionValues += value; remove => _playback.OnActionValues -= value; }
+        public event Action<float, float, string> OnValuesAction { add => _playback.OnValuesAction += value; remove => _playback.OnValuesAction -= value; }
+        public event Action<string, float> OnActionValue { add => _playback.OnActionValue += value; remove => _playback.OnActionValue -= value; }
+        public event Action<float, string> OnValueAction { add => _playback.OnValueAction += value; remove => _playback.OnValueAction -= value; }
+        public event Action<string> OnActionPreparing { add => _playback.OnActionPreparing += value; remove => _playback.OnActionPreparing -= value; }
+        public event Action OnEnded { add => _playback.OnGameEnded += value; remove => _playback.OnGameEnded -= value; }
+
+        public bool IsPlaying => _playback.IsPlaying;
+        public double DurationSeconds => _playback.DurationSeconds;
+        public double ElapsedSeconds => _playback.ElapsedSeconds;
+        public float Progress01 => _playback.Progress01;
+        public double ActionPreparationLeadSeconds
+        {
+            get => _playback.ActionPreparationLeadSeconds;
+            set => _playback.ActionPreparationLeadSeconds = Math.Max(0d, value);
+        }
+
+        internal void RefreshBindings()
+        {
+            HyperRuntime.ReplayManager?.AttachPlayback(_playback);
+        }
+    }
+
     /// <summary>
     /// Bridges SDK events to consumers while allowing subscriptions before initialization.
     /// </summary>
@@ -541,6 +705,8 @@ namespace Hyper
         private Action _onTimeUp;
         private Action _onGamePaused;
         private Action _onGameResumed;
+        private Action _onTimeScaleFrozen;
+        private Action _onTimeScaleResumed;
         private Action _onGameEnded;
         private Action<bool> _onSoundChanged;
         private Action _onLivesExhausted;
@@ -551,6 +717,8 @@ namespace Hyper
         private Action _timeUpBridge;
         private Action _gamePausedBridge;
         private Action _gameResumedBridge;
+        private Action _timeScaleFrozenBridge;
+        private Action _timeScaleResumedBridge;
         private Action _gameEndedBridge;
         private Action<bool> _soundChangedBridge;
         private Action _livesExhaustedBridge;
@@ -597,6 +765,26 @@ namespace Hyper
             remove => _onGameResumed -= value;
         }
 
+        public event Action OnTimeScaleFrozen
+        {
+            add
+            {
+                _onTimeScaleFrozen += value;
+                RefreshBindings();
+            }
+            remove => _onTimeScaleFrozen -= value;
+        }
+
+        public event Action OnTimeScaleResumed
+        {
+            add
+            {
+                _onTimeScaleResumed += value;
+                RefreshBindings();
+            }
+            remove => _onTimeScaleResumed -= value;
+        }
+
         public event Action OnGameEnded
         {
             add
@@ -671,6 +859,8 @@ namespace Hyper
             _timeUpBridge = () => _onTimeUp?.Invoke();
             _gamePausedBridge = () => _onGamePaused?.Invoke();
             _gameResumedBridge = () => _onGameResumed?.Invoke();
+            _timeScaleFrozenBridge = () => _onTimeScaleFrozen?.Invoke();
+            _timeScaleResumedBridge = () => _onTimeScaleResumed?.Invoke();
             _gameEndedBridge = () => _onGameEnded?.Invoke();
             _soundChangedBridge = enabled => _onSoundChanged?.Invoke(enabled);
             _livesExhaustedBridge = () => _onLivesExhausted?.Invoke();
@@ -681,6 +871,8 @@ namespace Hyper
             manager.OnTimeUp += _timeUpBridge;
             manager.OnGamePaused += _gamePausedBridge;
             manager.OnGameResumed += _gameResumedBridge;
+            manager.OnTimeScaleFrozen += _timeScaleFrozenBridge;
+            manager.OnTimeScaleResumed += _timeScaleResumedBridge;
             manager.OnGameEnded += _gameEndedBridge;
             manager.OnSoundChanged += _soundChangedBridge;
             manager.OnLivesExhausted += _livesExhaustedBridge;
@@ -701,6 +893,8 @@ namespace Hyper
             if (_timeUpBridge != null) _attachedManager.OnTimeUp -= _timeUpBridge;
             if (_gamePausedBridge != null) _attachedManager.OnGamePaused -= _gamePausedBridge;
             if (_gameResumedBridge != null) _attachedManager.OnGameResumed -= _gameResumedBridge;
+            if (_timeScaleFrozenBridge != null) _attachedManager.OnTimeScaleFrozen -= _timeScaleFrozenBridge;
+            if (_timeScaleResumedBridge != null) _attachedManager.OnTimeScaleResumed -= _timeScaleResumedBridge;
             if (_gameEndedBridge != null) _attachedManager.OnGameEnded -= _gameEndedBridge;
             if (_soundChangedBridge != null) _attachedManager.OnSoundChanged -= _soundChangedBridge;
             if (_livesExhaustedBridge != null) _attachedManager.OnLivesExhausted -= _livesExhaustedBridge;
@@ -711,6 +905,8 @@ namespace Hyper
             _timeUpBridge = null;
             _gamePausedBridge = null;
             _gameResumedBridge = null;
+            _timeScaleFrozenBridge = null;
+            _timeScaleResumedBridge = null;
             _gameEndedBridge = null;
             _soundChangedBridge = null;
             _livesExhaustedBridge = null;

package/Runtime/Public/Hyper.asmdef

@@ -3,7 +3,8 @@
     "rootNamespace": "Hyper",
     "references": [
         "GUID:a05ed6f43b536684b893d8a6a28d33bc",
-        "GUID:a701715b74d53214c9a994c9a64f14b6"
+        "GUID:a701715b74d53214c9a994c9a64f14b6",
+        "GUID:6055be8ebefd69e48b49212b09b47b2f"
     ],
     "includePlatforms": [],
     "excludePlatforms": [],