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

package/Runtime/Public/Core/HyperSDK.cs

@@ -226,6 +226,12 @@ namespace Hyper
         /// </summary>
         void ExitPracticeMenu();
 
+        /// <summary>
+        /// Notifies the SDK that game-owned custom restart cleanup is complete.
+        /// Replay Watch Again and seeking wait for this signal before restarting playback.
+        /// </summary>
+        void CompleteCustomRestart();
+
         // Lives Management (only available when ControlBarLayout is HeartsLeft)
         /// <summary>
         /// Initialize the lives system with a maximum and optional initial value.
@@ -480,10 +486,15 @@ namespace Hyper
         /// <summary>Fired when all replay activities have been dispatched.</summary>
         event Action OnEnded;
 
+        /// <summary>Fired at the recorded boundary where game-specific playable gameplay began.</summary>
+        event Action OnGameplayReady;
+
         bool IsPlaying { get; }
         double DurationSeconds { get; }
         double ElapsedSeconds { get; }
         float Progress01 { get; }
+        bool IsSeeking { get; }
+        bool HasGameplayReadyMarker { get; }
 
         /// <summary>
         /// Optional visual lead time. Gameplay actions still fire at their recorded time.
@@ -616,6 +627,8 @@ namespace Hyper
 
         public void ExitPracticeMenu() => Manager?.ExitPracticeMenu();
 
+        public void CompleteCustomRestart() => HyperRuntime.CompleteCustomRestart();
+
         public void InitializeLives(int maxLives, int initialLives = -1) => Manager?.InitializeLives(maxLives, initialLives);
         public void SetLives(int lives) => Manager?.SetLives(lives);
         public void AddLife() => Manager?.AddLife();
@@ -677,11 +690,14 @@ namespace Hyper
         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 event Action OnGameplayReady { add => _playback.OnGameplayReady += value; remove => _playback.OnGameplayReady -= value; }
 
         public bool IsPlaying => _playback.IsPlaying;
         public double DurationSeconds => _playback.DurationSeconds;
         public double ElapsedSeconds => _playback.ElapsedSeconds;
         public float Progress01 => _playback.Progress01;
+        public bool IsSeeking => ReplaySessionState.IsSeeking;
+        public bool HasGameplayReadyMarker => _playback.HasGameplayReadyMarker;
         public double ActionPreparationLeadSeconds
         {
             get => _playback.ActionPreparationLeadSeconds;

package/Runtime/Public/Replay/ReplayPlaybackEngine.cs

@@ -11,6 +11,7 @@ namespace Hyper
     internal sealed class ReplayPlaybackEngine : IReplayPlaybackEngine
     {
         private const string GameStarted = "GS";
+        private const string GameplayReady = "GPR";
         private const string GamePaused = "GP";
         private const string GameResumed = "GR";
         private const string GameEnded = "GE";
@@ -28,6 +29,13 @@ namespace Hyper
         private double _stoppedElapsed;
         private bool _isSuspended;
         private bool _completionPending;
+        private bool _gameplayClockStarted;
+        private double _gameplaySourceStartTime;
+        private double _gameplayElapsedSeconds;
+        private double _gameplayStepSeconds;
+        private double _gameplayPauseDurationAtStart;
+        private long _gameplayTick;
+        private double _currentTickDelta;
 
         public event Action<float, float> OnValues2;
         public event Action<float> OnValue;
@@ -45,6 +53,7 @@ namespace Hyper
         /// </summary>
         public event Action<string> OnActionPreparing;
         public event Action OnGameStarted;
+        public event Action OnGameplayReady;
         public event Action OnGameEnded;
 
         public bool IsPlaying { get; private set; }
@@ -55,6 +64,8 @@ namespace Hyper
         /// The action itself is still dispatched at its recorded timestamp.
         /// </summary>
         public double ActionPreparationLeadSeconds { get; set; }
+        public bool HasGameplayReadyMarker { get; private set; }
+        public float GameplayStartProgress01 { get; private set; }
         public float Progress01 => DurationSeconds <= 0d
             ? (IsPlaying ? 0f : 1f)
             : Mathf.Clamp01((float)(ElapsedSeconds / DurationSeconds));
@@ -72,7 +83,19 @@ namespace Hyper
             _endedRaised = false;
             _completionPending = false;
             _nextActionPrepared = false;
+            _gameplayClockStarted = false;
+            _gameplaySourceStartTime = 0d;
+            _gameplayElapsedSeconds = 0d;
+            _gameplayStepSeconds = 0d;
+            _gameplayPauseDurationAtStart = 0d;
+            _gameplayTick = 0L;
+            _currentTickDelta = 0d;
             DurationSeconds = CalculateDuration(_ndjson);
+            double gameplayStartSeconds = CalculateGameplayStart(_ndjson, out bool hasGameplayReadyMarker);
+            HasGameplayReadyMarker = hasGameplayReadyMarker;
+            GameplayStartProgress01 = hasGameplayReadyMarker && DurationSeconds > 0d
+                ? Mathf.Clamp01((float)(gameplayStartSeconds / DurationSeconds))
+                : 0f;
             _hasNext = TryReadNext(out _next);
 
             if (!_hasNext)
@@ -113,13 +136,19 @@ namespace Hyper
                            double.IsInfinity(fixedSimulationDeltaSeconds)
                 ? 0d
                 : Math.Max(0d, fixedSimulationDeltaSeconds);
+            _currentTickDelta = delta;
             _elapsedSeconds += delta;
+            if (_gameplayClockStarted && delta > 0d)
+            {
+                if (_gameplayStepSeconds <= 0d) _gameplayStepSeconds = delta;
+                _gameplayElapsedSeconds += delta;
+                _gameplayTick++;
+            }
 
             int processed = 0;
             while (IsPlaying && !_completionPending && _hasNext && processed++ < MaxActivitiesPerTick)
             {
-                double elapsed = GetElapsedSeconds();
-                double dueTime = _next.Time - _sourceStartTime - _removedPauseDuration;
+                GetSchedulingTime(_next, out double elapsed, out double dueTime);
                 PrepareNextActionIfDue(elapsed, dueTime);
                 if (elapsed + 0.000001d < dueTime) return;
 
@@ -145,6 +174,13 @@ namespace Hyper
             _isSuspended = false;
             _completionPending = false;
             _nextActionPrepared = false;
+            _gameplayClockStarted = false;
+            _gameplaySourceStartTime = 0d;
+            _gameplayElapsedSeconds = 0d;
+            _gameplayStepSeconds = 0d;
+            _gameplayPauseDurationAtStart = 0d;
+            _gameplayTick = 0L;
+            _currentTickDelta = 0d;
         }
 
         public void Suspend()
@@ -214,6 +250,10 @@ namespace Hyper
                 case GameStarted:
                     OnGameStarted?.Invoke();
                     break;
+                case GameplayReady:
+                    StartGameplayClock(activity.Time);
+                    OnGameplayReady?.Invoke();
+                    break;
                 case GamePaused:
                     SkipRecordedPause(activity.Time);
                     break;
@@ -243,10 +283,94 @@ namespace Hyper
             OnActionPreparing?.Invoke(_next.Action);
         }
 
+        private void StartGameplayClock(double sourceTime)
+        {
+            _gameplayClockStarted = true;
+            _gameplaySourceStartTime = sourceTime;
+            _gameplayElapsedSeconds = 0d;
+            _gameplayStepSeconds = _currentTickDelta;
+            _gameplayPauseDurationAtStart = _removedPauseDuration;
+            _gameplayTick = 0L;
+        }
+
+        private void GetSchedulingTime(ReplayActivity activity, out double elapsed, out double dueTime)
+        {
+            if (!_gameplayClockStarted)
+            {
+                elapsed = GetElapsedSeconds();
+                dueTime = activity.Time - _sourceStartTime - _removedPauseDuration;
+                return;
+            }
+
+            double removedGameplayPauses = Math.Max(0d,
+                _removedPauseDuration - _gameplayPauseDurationAtStart);
+            double rawDueTime = Math.Max(0d,
+                activity.Time - _gameplaySourceStartTime - removedGameplayPauses);
+
+            if (_gameplayStepSeconds <= 0d)
+            {
+                elapsed = _gameplayElapsedSeconds;
+                dueTime = rawDueTime;
+                return;
+            }
+
+            // Gameplay can only consume an activity on a fixed step. Mapping the
+            // timestamp to its nearest GPR-relative tick prevents sub-step JSON
+            // precision noise from moving an input to the following physics step.
+            long dueTick = Math.Max(0L, (long)Math.Round(
+                rawDueTime / _gameplayStepSeconds,
+                MidpointRounding.AwayFromZero));
+            elapsed = _gameplayTick * _gameplayStepSeconds;
+            dueTime = dueTick * _gameplayStepSeconds;
+        }
+
         private static bool IsLifecycleAction(string action)
         {
             return action == GameStarted || action == GamePaused ||
-                   action == GameResumed || action == GameEnded;
+                   action == GameResumed || action == GameEnded || action == GameplayReady;
+        }
+
+        private static double CalculateGameplayStart(string ndjson, out bool found)
+        {
+            found = false;
+            if (string.IsNullOrWhiteSpace(ndjson)) return 0d;
+
+            int cursor = 0;
+            bool hasFirst = false;
+            double firstTime = 0d;
+            double removedPauses = 0d;
+            double? pauseStartedAt = null;
+
+            while (TryReadLine(ndjson, ref cursor, out string line))
+            {
+                if (!TryParse(line, out ReplayActivity activity)) continue;
+                if (!hasFirst)
+                {
+                    hasFirst = true;
+                    firstTime = activity.Time;
+                }
+
+                if (activity.Kind != ReplayActivityKind.Action) continue;
+                if (activity.Action == GamePaused)
+                {
+                    pauseStartedAt ??= activity.Time;
+                    continue;
+                }
+
+                if (activity.Action == GameResumed && pauseStartedAt.HasValue)
+                {
+                    removedPauses += Math.Max(0d, activity.Time - pauseStartedAt.Value);
+                    pauseStartedAt = null;
+                    continue;
+                }
+
+                if (activity.Action != GameplayReady) continue;
+
+                found = true;
+                return Math.Max(0d, activity.Time - firstTime - removedPauses);
+            }
+
+            return 0d;
         }
 
         private void SkipRecordedPause(double pauseStartedAt)