app.hypergames.hypersdk 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.7.0](https://github.com/mvmhyper/hyper-sdk/compare/v1.6.0...v1.7.0) (2026-04-02)
+
+
+### Features
+
+* add loader API, device classification, and landscape canvas scaling fixes ([780ac39](https://github.com/mvmhyper/hyper-sdk/commit/780ac39b2d4f4c73286614a8e6b960fa947276f2))
+
 # [1.6.0](https://github.com/mvmhyper/hyper-sdk/compare/v1.5.10...v1.6.0) (2026-03-28)
 
 

package/Editor/Scripts/Windows/HyperGameContentWindow.cs

@@ -126,6 +126,16 @@ namespace Hyper.Editor
                 "• TRANSITION → optional loading/transition scene.",
                 MessageType.Info);
 
+            if (_contentConfig.EnableCustomLoading)
+            {
+                EditorGUILayout.Space(4);
+                EditorGUILayout.HelpBox(
+                    "Custom Pre-Loading is enabled. The HyperLoader bootstrap will pause after SDK " +
+                    "initialization and wait for HyperSDK.Loader.CompleteCustomLoading() to be called " +
+                    "before loading the game scene.",
+                    MessageType.Info);
+            }
+
             EditorGUILayout.Space(10);
 
             _scrollPosition = EditorGUILayout.BeginScrollView(_scrollPosition);

package/Editor/Scripts/Windows/HyperSettingsWindow.cs

@@ -253,6 +253,16 @@ namespace Hyper.Editor
                 "• TRANSITION → optional loading/transition scene.",
                 MessageType.Info);
 
+            if (_contentConfig.EnableCustomLoading)
+            {
+                EditorGUILayout.Space(4);
+                EditorGUILayout.HelpBox(
+                    "Custom Pre-Loading is enabled. The HyperLoader bootstrap will pause after SDK " +
+                    "initialization and wait for HyperSDK.Loader.CompleteCustomLoading() to be called " +
+                    "before loading the game scene.",
+                    MessageType.Info);
+            }
+
             EditorGUILayout.Space(8);
 
             _scrollPosition = EditorGUILayout.BeginScrollView(_scrollPosition);

package/HyperLoader.unity

@@ -304,7 +304,7 @@ RectTransform:
   m_LocalEulerAnglesHint: {x: 0, y: 0, z: 0}
   m_AnchorMin: {x: 0, y: 1}
   m_AnchorMax: {x: 0, y: 1}
-  m_AnchoredPosition: {x: 489.20746, y: -280.1698}
+  m_AnchoredPosition: {x: 489.45853, y: -280.1698}
   m_SizeDelta: {x: 1044.9, y: 239.347}
   m_Pivot: {x: 0.5, y: 0.5}
 --- !u!114 &751153944
@@ -840,7 +840,7 @@ GameObject:
   m_Component:
   - component: {fileID: 1064166296}
   m_Layer: 0
-  m_Name: __HyperSDK_BuildMarker_639075716235347695
+  m_Name: __HyperSDK_BuildMarker_639104165398939431
   m_TagString: Untagged
   m_Icon: {fileID: 0}
   m_NavMeshLayer: 0
@@ -1092,7 +1092,7 @@ RectTransform:
   m_LocalEulerAnglesHint: {x: 0, y: 0, z: 0}
   m_AnchorMin: {x: 0, y: 1}
   m_AnchorMax: {x: 0, y: 1}
-  m_AnchoredPosition: {x: 489.20746, y: -133.2274}
+  m_AnchoredPosition: {x: 489.45853, y: -133.2274}
   m_SizeDelta: {x: 875, y: 54.5378}
   m_Pivot: {x: 0.5, y: 0.5}
 --- !u!1 &2874543288936963705

package/Runtime/Internal/Bootstrap/HyperLoader.cs

@@ -42,6 +42,10 @@ namespace Hyper.Internal
         private GameManager _gameManager;
         private BackendManager _backendManager;
 
+        // Progress budget milestones (adjusted based on custom pre-loading)
+        private float _progressAfterInit = 0.20f;
+        private float _progressAfterBackend = 0.50f;
+        private float _progressAfterCustomLoad = 0.50f;
 
         #endregion
 
@@ -231,6 +235,12 @@ namespace Hyper.Internal
             _bootstrapProgress = 0f;
             _loadingBarSlider.value = _bootstrapProgress;
 
+            // Configure progress budget based on whether custom pre-loading is enabled
+            bool hasCustomPreLoading = _gameContentConfig != null && _gameContentConfig.EnableCustomLoading;
+            _progressAfterInit = 0.20f;
+            _progressAfterBackend = hasCustomPreLoading ? 0.45f : 0.50f;
+            _progressAfterCustomLoad = hasCustomPreLoading ? 0.75f : _progressAfterBackend;
+
             // Step 1: Initialize HyperSDK
             bool sdkInitialized = false;
             HyperRuntime.Initialize(() =>
@@ -245,12 +255,12 @@ namespace Hyper.Internal
 
             while (!sdkInitialized)
             {
-                _bootstrapProgress = Mathf.MoveTowards(_bootstrapProgress, 0.20f, Time.deltaTime * 2f);
+                _bootstrapProgress = Mathf.MoveTowards(_bootstrapProgress, _progressAfterInit, Time.deltaTime * 2f);
                 _loadingBarSlider.value = _bootstrapProgress;
                 yield return null;
             }
 
-            _bootstrapProgress = 0.20f;
+            _bootstrapProgress = _progressAfterInit;
             _loadingBarSlider.value = _bootstrapProgress;
 
             // Step 2: Handle Backend/PVP or Practice mode initialization
@@ -267,6 +277,12 @@ namespace Hyper.Internal
                 InitializePracticeMode();
             }
 
+            // Step 2.5: Custom Pre-Loading (if enabled)
+            if (hasCustomPreLoading)
+            {
+                yield return WaitForCustomPreLoading();
+            }
+
             // Step 3: Load target scene asynchronously
             yield return LoadTargetScene();
         }
@@ -275,17 +291,20 @@ namespace Hyper.Internal
         {
             _targetSceneName = _gameContentConfig.GameScene?.SceneName;
 
+            // WebSocket milestone is midpoint between init and backend completion
+            float webSocketMilestone = Mathf.Lerp(_progressAfterInit, _progressAfterBackend, 0.5f);
+
             // Initialize WebSocket
             HyperRuntime.BackendManager.InitializeWebSocket();
 
             while (!HyperRuntime.BackendManager.isSocketConnected)
             {
-                _bootstrapProgress = Mathf.MoveTowards(_bootstrapProgress, 0.35f, Time.deltaTime * 0.5f);
+                _bootstrapProgress = Mathf.MoveTowards(_bootstrapProgress, webSocketMilestone, Time.deltaTime * 0.5f);
                 _loadingBarSlider.value = _bootstrapProgress;
                 yield return null;
             }
 
-            _bootstrapProgress = 0.35f;
+            _bootstrapProgress = webSocketMilestone;
             _loadingBarSlider.value = _bootstrapProgress;
 
             // Create session
@@ -297,12 +316,12 @@ namespace Hyper.Internal
 
             while (!sessionCreated)
             {
-                _bootstrapProgress = Mathf.MoveTowards(_bootstrapProgress, 0.50f, Time.deltaTime * 0.5f);
+                _bootstrapProgress = Mathf.MoveTowards(_bootstrapProgress, _progressAfterBackend, Time.deltaTime * 0.5f);
                 _loadingBarSlider.value = _bootstrapProgress;
                 yield return null;
             }
 
-            _bootstrapProgress = 0.50f;
+            _bootstrapProgress = _progressAfterBackend;
             _loadingBarSlider.value = _bootstrapProgress;
         }
 
@@ -322,6 +341,38 @@ namespace Hyper.Internal
                 : _gameContentConfig.GameScene?.SceneName;
         }
 
+        private IEnumerator WaitForCustomPreLoading()
+        {
+            HyperRuntime.CustomLoadingComplete = false;
+            HyperRuntime.CustomLoadingProgress = 0f;
+
+            float simulatedProgress = 0f;
+            const float simulatedSpeed = 0.15f;
+            const float simulatedCap = 0.70f;
+
+            HyperDebug.Log("Custom pre-loading enabled. Waiting for HyperSDK.Loader.CompleteCustomLoading()");
+
+            while (!HyperRuntime.CustomLoadingComplete)
+            {
+                float devProgress = HyperRuntime.CustomLoadingProgress;
+
+                // Simulate progress if dev isn't reporting (auto-animate so bar doesn't look stuck)
+                simulatedProgress = Mathf.MoveTowards(simulatedProgress, simulatedCap, Time.unscaledDeltaTime * simulatedSpeed);
+
+                // Use whichever is higher: dev-reported or simulated
+                float effectiveProgress = Mathf.Max(devProgress, simulatedProgress);
+
+                _bootstrapProgress = Mathf.Lerp(_progressAfterBackend, _progressAfterCustomLoad, effectiveProgress);
+                _loadingBarSlider.value = _bootstrapProgress;
+
+                yield return null;
+            }
+
+            // Snap to end of custom loading range
+            _bootstrapProgress = _progressAfterCustomLoad;
+            _loadingBarSlider.value = _bootstrapProgress;
+        }
+
         private long GetRandomSeed()
         {
 #if UNITY_EDITOR
@@ -424,9 +475,5 @@ namespace Hyper.Internal
         }
 
         #endregion
-
-        #region Utility Methods
-
-        #endregion
     }
 }

package/Runtime/Internal/Core/HyperRuntime.cs

@@ -19,6 +19,8 @@ namespace Hyper.Internal
 
         private static bool _isInitialized;
         private static bool _isSoftRestarting;
+        private static bool _customLoadingComplete;
+        private static float _customLoadingProgress;
         private static HyperSDKSettings _settings;
         private static HyperGameContentConfig _gameContent;
         private static GameManager _gameManager;
@@ -33,6 +35,16 @@ namespace Hyper.Internal
             get => _isSoftRestarting;
             set => _isSoftRestarting = value;
         }
+        internal static bool CustomLoadingComplete
+        {
+            get => _customLoadingComplete;
+            set => _customLoadingComplete = value;
+        }
+        internal static float CustomLoadingProgress
+        {
+            get => _customLoadingProgress;
+            set => _customLoadingProgress = value;
+        }
         internal static HyperSDKSettings Settings => _settings;
         internal static HyperGameContentConfig GameContent => _gameContent;
         internal static GameManager GameManager => _gameManager;
@@ -287,6 +299,8 @@ namespace Hyper.Internal
 
             HyperRandom.Clear();
             _gameContent = null;
+            _customLoadingComplete = false;
+            _customLoadingProgress = 0f;
 
             if (_singletonObject != null)
             {
@@ -335,6 +349,8 @@ namespace Hyper.Internal
             _dataManager = null;
             _gameContent = null;
             _isInitialized = false;
+            _customLoadingComplete = false;
+            _customLoadingProgress = 0f;
         }
     }
 }

package/Runtime/Internal/Managers/BackendManager.cs

@@ -498,7 +498,11 @@ namespace Hyper.Internal.Managers
             if (_gameManager.HasGameStarted)
             {
                 _gameManager?.ShowConnectionRestored();
-                SendGameResumed();
+
+                if (!_gameManager.IsPaused)
+                {
+                    SendGameResumed();
+                }
             }
             else
             {
@@ -723,10 +727,6 @@ namespace Hyper.Internal.Managers
             LastSubmissionError = SubmissionErrorType.None;
 
             // Keep connection alive during game end sequence
-            // WebSocket connections can be closed by proxies/firewalls if idle for too long (typically 30-60 seconds)
-            // During gameplay, scores are sent every second, keeping the connection active
-            // But at game end, we stop sending scores, so the connection might go idle
-            // We ensure the connection is active right before submission by checking and reconnecting if needed
             if (!isSocketConnected)
             {
                 HyperDebug.LogWarning("WebSocket disconnected at game end - attempting to reconnect before submission");
@@ -748,8 +748,7 @@ namespace Hyper.Internal.Managers
             }
             else
             {
-                // Connection is active - ensure it stays active by verifying it's still connected
-                // The act of checking and the upcoming gameResumed call will keep it active
+
                 HyperDebug.Log("Connection active - maintaining during game end sequence");
             }
 
@@ -777,7 +776,10 @@ namespace Hyper.Internal.Managers
                 var finalScoreData = _dataManager?.CurrentScoreData;
                 finalScoreData.isFinal = true;
 
-                string rawScoreJson = JsonConvert.SerializeObject(finalScoreData);
+                // For consistency with per-second and backlog submissions, always send
+                // the final score as an array of ScoreData.
+                var finalScoreList = new List<ScoreData>(1) { finalScoreData };
+                string rawScoreJson = JsonConvert.SerializeObject(finalScoreList);
                 var compressedScoreData = JsonCompressor.CompressJson(rawScoreJson);
                 string scoreJson = compressedScoreData.MinifiedJson;
                 string encryptedScoreData = EncryptScore(scoreJson);
@@ -835,6 +837,18 @@ namespace Hyper.Internal.Managers
                     continue;
                 }
 
+                // Flush any offline backlog that accumulated while disconnected.
+                if (_dataManager?.PendingScores != null && _dataManager.PendingScores.Count > 0)
+                {
+                    var backlog = new List<ScoreData>(_dataManager.PendingScores);
+                    _dataManager.PendingScores.Clear();
+                    int backlogCount = backlog.Count;
+                    HyperDebug.Log($"[Score] Flushing {backlogCount} offline backlog score(s) before final submission.");
+                    SendScoresOverWebSocket(backlog);
+
+                    yield return new WaitForSecondsRealtime(1f);
+                }
+
                 // Sending final score via WebSocket
                 _finalScoreSubmitted = false;
                 _isWaitingForFinalScoreResponse = true;
@@ -986,15 +1000,30 @@ namespace Hyper.Internal.Managers
         {
             while (true)
             {
+                // Don't drain PendingScores while offline - let them accumulate as an offline batch.
+                // Scores will be flushed when the connection is restored.
+                if (!isSocketConnected)
+                {
+                    int pendingCount = _dataManager?.PendingScores?.Count ?? 0;
+                    HyperDebug.Log($"[Score] Socket disconnected - accumulating scores for offline batch. PendingCount={pendingCount}");
+                    yield return _scoreSendInterval;
+                    continue;
+                }
+
                 var scoresToSend = _scoreSendBuffer;
                 scoresToSend.Clear();
 
                 if (_dataManager?.PendingScores.Count > 0)
                 {
-                    // Copy pending scores into our reusable buffer, then clear the source list
+                    // Copy pending scores into our reusable buffer, then clear the source list.
+                    // This may be 1 score (normal) or many (offline backlog after reconnection).
                     scoresToSend.AddRange(_dataManager?.PendingScores);
                     _dataManager?.PendingScores.Clear();
-                    HyperDebug.Log($"[Score] Preparing to send {scoresToSend.Count} score sample(s) over WebSocket. LastPendingCumulativeScore={scoresToSend[scoresToSend.Count - 1].cumulativeScore}");
+                    int count = scoresToSend.Count;
+                    HyperDebug.Log($"[Score] Preparing to send {count} score sample(s) over WebSocket. LastPendingCumulativeScore={scoresToSend[count - 1].cumulativeScore}");
+
+                    // Send the entire batch as an array payload.
+                    // Normal ticks send [1 score], reconnection flushes send [N scores].
                     SendScoresOverWebSocket(scoresToSend);
                 }
                 else
@@ -1021,77 +1050,36 @@ namespace Hyper.Internal.Managers
 
             try
             {
-                // Clone the last batch into standalone ScoreData instances
+                // Clone the batch into standalone ScoreData instances
                 // so that pooling/reset in DataManager does not zero out the values we log/use here.
                 _lastSentBatch.Clear();
 
-                ScoreData scoreData = null;
-                if (scores.Count > 0)
+                for (int i = 0; i < scores.Count; i++)
                 {
-                    // We only need the last score point for submission, but we keep the whole batch
-                    // for events so listeners can inspect the last acknowledged score accurately.
-                    for (int i = 0; i < scores.Count; i++)
-                    {
-                        var source = scores[i];
-                        if (source == null) continue;
-
-                        var cloned = new ScoreData
-                        {
-                            cumulativeScore = source.cumulativeScore,
-                            isFinal = source.isFinal,
-                            timestampUtc = source.timestampUtc
-                        };
-
-                        if (source.scoreSnapshot != null)
-                        {
-                            var snapshot = source.scoreSnapshot;
-                            var clonedSnapshot = new ScoreSnapshot
-                            {
-                                scoreTime = snapshot.scoreTime,
-                                scoreDelta = snapshot.scoreDelta
-                            };
-
-                            if (snapshot.gameplayModifiers != null)
-                            {
-                                var mods = snapshot.gameplayModifiers;
-                                var clonedMods = new GameplayModifiers
-                                {
-                                    comboModifiers = mods.comboModifiers,
-                                    globalModifiers = mods.globalModifiers,
-                                    activePowerUps = mods.activePowerUps != null
-                                        ? new List<string>(mods.activePowerUps)
-                                        : null
-                                };
-
-                                clonedSnapshot.gameplayModifiers = clonedMods;
-                            }
-
-                            cloned.scoreSnapshot = clonedSnapshot;
-                        }
-
-                        _lastSentBatch.Add(cloned);
-                    }
-
-                    scoreData = scores[scores.Count - 1];
+                    var source = scores[i];
+                    if (source == null) continue;
+                    _lastSentBatch.Add(CloneScoreData(source));
                 }
 
-                string rawScoreJson = JsonConvert.SerializeObject(scoreData);
+                // Serialize the full array of scores.
+                // Normal ticks: array of 1.  Offline backlog flush: array of N.
+                string rawScoreJson = JsonConvert.SerializeObject(scores);
                 var compressedScoreData = JsonCompressor.CompressJson(rawScoreJson);
                 string scoreJson = compressedScoreData.MinifiedJson;
                 string encryptedData = EncryptScore(scoreJson);
 
                 if (string.IsNullOrEmpty(encryptedData))
                 {
-                    int lastScore = scoreData != null ? scoreData.cumulativeScore : -1;
-                    HyperDebug.LogError($"[Score] Encryption failed for per-second submission. CumulativeScore={lastScore} [ErrorType=EncryptionError]");
+                    int lastScore = scores[scores.Count - 1].cumulativeScore;
+                    HyperDebug.LogError($"[Score] Encryption failed for score submission. LastCumulativeScore={lastScore} [ErrorType=EncryptionError]");
                     return;
                 }
 
                 var message = new WebSocketScoreMessage(_cachedSessionId, _csrfToken, encryptedData);
                 string json = JsonConvert.SerializeObject(message);
                 int csrfLength = string.IsNullOrEmpty(_csrfToken) ? 0 : _csrfToken.Length;
-                int cumulativeScore = scoreData != null ? scoreData.cumulativeScore : -1;
-                HyperDebug.Log($"[Score] Sending per-second score. CumulativeScore={cumulativeScore}, BatchSize={scores.Count}, SessionId={_cachedSessionId}, CsrfLength={csrfLength}");
+                int lastCumulativeScore = scores[scores.Count - 1].cumulativeScore;
+                HyperDebug.Log($"[Score] Sending score batch. LastCumulativeScore={lastCumulativeScore}, BatchSize={scores.Count}, SessionId={_cachedSessionId}, CsrfLength={csrfLength}");
                 SendWebSocketMessage(json);
             }
             catch (Exception ex)
@@ -1107,6 +1095,51 @@ namespace Hyper.Internal.Managers
             }
         }
 
+        /// <summary>
+        /// Creates a deep clone of a ScoreData instance.
+        /// Used to create standalone copies that are not affected by the DataManager's object pooling.
+        /// </summary>
+        private static ScoreData CloneScoreData(ScoreData source)
+        {
+            if (source == null) return null;
+
+            var cloned = new ScoreData
+            {
+                cumulativeScore = source.cumulativeScore,
+                isFinal = source.isFinal,
+                timestampUtc = source.timestampUtc
+            };
+
+            if (source.scoreSnapshot != null)
+            {
+                var snapshot = source.scoreSnapshot;
+                var clonedSnapshot = new ScoreSnapshot
+                {
+                    scoreTime = snapshot.scoreTime,
+                    scoreDelta = snapshot.scoreDelta
+                };
+
+                if (snapshot.gameplayModifiers != null)
+                {
+                    var mods = snapshot.gameplayModifiers;
+                    var clonedMods = new GameplayModifiers
+                    {
+                        comboModifiers = mods.comboModifiers,
+                        globalModifiers = mods.globalModifiers,
+                        activePowerUps = mods.activePowerUps != null
+                            ? new List<string>(mods.activePowerUps)
+                            : null
+                    };
+
+                    clonedSnapshot.gameplayModifiers = clonedMods;
+                }
+
+                cloned.scoreSnapshot = clonedSnapshot;
+            }
+
+            return cloned;
+        }
+
         [Serializable]
         private class WebSocketScoreMessage
         {
@@ -1244,7 +1277,7 @@ namespace Hyper.Internal.Managers
 
             string eventName = eventType switch
             {
-                ConsoleEventType.GameStart => "GameStart",
+                ConsoleEventType.GameStarted => "GameStarted",
                 ConsoleEventType.GameResumed => "GameResumed",
                 ConsoleEventType.GamePaused => "GamePaused",
                 ConsoleEventType.GameEnd => "GameEnd",
@@ -1255,27 +1288,22 @@ namespace Hyper.Internal.Managers
                 _ => string.Empty
             };
 
-            bool includeScoreData = eventType == ConsoleEventType.GameEnd ||
-                                   eventType == ConsoleEventType.PracticeGameEnd;
-
-            ConsoleEvent logEntry;
+            bool stopGameOnLog = true;
 
-            if (includeScoreData)
+            switch (eventType)
             {
-                ConsoleData consoleData = new ConsoleData
-                {
-                    score = _dataManager.CurrentScore,
-                    time = HyperRuntime.Timer.CurrentTime,
-                    gameId = _gameManager?.Config.GameId
-                };
-
-                logEntry = new ConsoleEvent { name = eventName, data = consoleData };
-            }
-            else
-            {
-                logEntry = new ConsoleEvent { name = eventName };
+                case ConsoleEventType.GameStarted:
+                    stopGameOnLog = false;
+                    break;
+                case ConsoleEventType.GameResumed:
+                    stopGameOnLog = false;
+                    break;
+                case ConsoleEventType.GamePaused:
+                    stopGameOnLog = false;
+                    break;
             }
 
+            ConsoleEvent logEntry = new ConsoleEvent { name = eventName };
             string jsonLog = JsonUtility.ToJson(logEntry);
 
 #if UNITY_WEBGL && !UNITY_EDITOR
@@ -1283,7 +1311,7 @@ namespace Hyper.Internal.Managers
 #endif
 
 #if UNITY_EDITOR
-            UnityEditor.EditorApplication.isPlaying = false;
+            if (stopGameOnLog) UnityEditor.EditorApplication.isPlaying = false;
 #endif
         }
 

package/Runtime/Internal/Managers/DataManager.cs

@@ -429,21 +429,10 @@ namespace Hyper
 {
     #region Public Data Structures
 
-    [Serializable]
-    public class ConsoleData
-    {
-        public int score;
-        public double time;
-        public string gameId;
-        public string currentPlatform;
-        public string recommendedPlatform;
-    }
-
     [Serializable]
     public class ConsoleEvent
     {
         public string name;
-        public ConsoleData data;
     }
 
     #endregion

package/Runtime/Internal/Managers/EventManager.cs

@@ -67,7 +67,7 @@ namespace Hyper.Internal.Managers
         internal void InvokeGameStartEvent()
         {
             OnGameStart?.Invoke();
-            HyperRuntime.BackendManager.LogEvent(ConsoleEventType.GameStart);
+            HyperRuntime.BackendManager.LogEvent(ConsoleEventType.GameStarted);
         }
 
         internal void InvokeSoundChangedEvent(bool sound) => OnSoundChanged?.Invoke(sound);

package/Runtime/Internal/Managers/GameManager.cs

@@ -59,32 +59,14 @@ namespace Hyper.Internal.Managers
         {
             if (!IsInGameScene || _hasGameEnded || !_hasGameStarted) return;
 
-            // Automatically end the game when lives are exhausted
-            // Use appropriate method based on game mode
-            if (IsBattleMode)
-            {
-                EndBattleGame();
-            }
-            else
-            {
-                EndPracticeGame();
-            }
+            EndGame();
         }
 
         private void HandleHealthExhausted()
         {
             if (!IsInGameScene || _hasGameEnded || !_hasGameStarted) return;
 
-            // Automatically end the game when health is exhausted
-            // Use appropriate method based on game mode
-            if (IsBattleMode)
-            {
-                EndBattleGame();
-            }
-            else
-            {
-                EndPracticeGame();
-            }
+            EndGame();
         }
 
         internal void Cleanup()
@@ -107,6 +89,22 @@ namespace Hyper.Internal.Managers
         public bool HasGameStarted => _hasGameStarted;
         public bool HasGameEnded => _hasGameEnded;
 
+        internal int BattleTimeRemaining =>
+            IsBattleMode && HyperRuntime.Timer != null
+                ? HyperRuntime.Timer.BattleTimeRemaining
+                : 0;
+
+        /// <summary>
+        /// Ends the current session for whichever mode is active (practice or battle).
+        /// </summary>
+        public void EndGame()
+        {
+            if (IsBattleMode)
+                EndBattleGame();
+            else
+                EndPracticeGame();
+        }
+
         public void EndBattleGame()
         {
             if (!IsBattleMode) return;
@@ -222,6 +220,14 @@ namespace Hyper.Internal.Managers
                     _eventManager.InvokeTimeScaleResumedEvent();
                     HyperDebug.Log("Time scale resumed event invoked");
 
+                    // Always restart capturing when game resumes, even if offline,
+                    // so scores accumulate for the offline batch and are flushed on reconnect.
+                    if (!_hasGameEnded && _hasGameStarted)
+                    {
+                        _dataManager.StartCapturingScores();
+                    }
+
+                    // Only resume server session if connected
                     if (_backendManager.isSocketConnected && !_hasGameEnded && _hasGameStarted)
                     {
                         _backendManager.SendGameResumed();
@@ -993,7 +999,7 @@ namespace Hyper.Internal.Managers
             _canvasScaler = _canvas.GetComponent<CanvasScaler>();
             _canvasScaler.uiScaleMode = CanvasScaler.ScaleMode.ScaleWithScreenSize;
             _canvasScaler.referenceResolution = new Vector2(1080, 1920);
-            _canvasScaler.matchWidthOrHeight = 0.5f;
+            _canvasScaler.matchWidthOrHeight = IsPortrait() ? 0.43f : 0.73f;
 
             CreateSafeArea();
             CreateBlockerUI();

package/Runtime/Internal/Managers/TimeManager.cs

@@ -68,6 +68,11 @@ namespace Hyper.Internal.Managers
             ? (int)_battleTimer
             : (int)_practiceTimer;
 
+        /// <summary>
+        /// Match countdown seconds (floored, clamped at zero). Same source as battle branch of <see cref="CurrentTime"/>.
+        /// </summary>
+        internal int BattleTimeRemaining => Mathf.Max(0, (int)_battleTimer);
+
         public int SessionTimeRemaining => (int)_sessionTimer;
 
         private GameManager _gameManager;

package/Runtime/Internal/ScriptableObjects/HyperGameContentConfig.cs

@@ -49,6 +49,14 @@ namespace Hyper.Internal
 
         #endregion
 
+        #region Custom Pre-Loading
+
+        [Header("Custom Pre-Loading")]
+        [Tooltip("Enable if your game needs to perform custom work (e.g. downloading assets, fetching remote config) after SDK initialization but before the game scene loads. When enabled, the bootstrap will pause and wait for HyperSDK.Loader.CompleteCustomLoading() to be called.")]
+        public bool EnableCustomLoading = false;
+
+        #endregion
+
         #region Game Posters & Hints
 
         [Space]

package/Runtime/Internal/UI/Modals/GamePausedModal.cs

@@ -96,16 +96,9 @@ namespace Hyper.Internal
 
         public void ForfeitGame()
         {   
+            HyperRuntime.GameManager.EndGame();
             if (!IsPVPMode)
-            {
-                HyperRuntime.GameManager.EndPracticeGame();
                 _gameManager.LoadPracticeMenuScene();
-            }
-
-            else
-            {
-                HyperRuntime.GameManager.EndBattleGame();
-            }
         }
 
         public void ToggleSound()

package/Runtime/Plugins/WebGL/HyperCorePlugin.jslib

@@ -56,6 +56,32 @@ mergeInto(LibraryManager.library, {
         window.location.reload();
     },
 
+    HyperIsMobileUserAgent: function () {
+        var ua = navigator.userAgent || '';
+        if (/Android|iPhone|iPad|iPod|Opera Mini|IEMobile|WPDesktop|Mobile/i.test(ua)) {
+            return 1;
+        }
+        return 0;
+    },
+
+    // Large screen.* vs small inner viewport: typical of desktop Chrome DevTools device toolbar (not a guarantee).
+    HyperIsLikelyDesktopDevtoolsMobileViewport: function () {
+        try {
+            var sw = window.screen.width;
+            var sh = window.screen.height;
+            var screenLong = Math.max(sw, sh);
+            var iw = window.innerWidth;
+            var ih = window.innerHeight;
+            var innerLong = Math.max(iw, ih);
+            if (screenLong >= 1280 && innerLong <= 900 && screenLong > innerLong * 1.35) {
+                return 1;
+            }
+            return 0;
+        } catch (e) {
+            return 0;
+        }
+    },
+
     getDeviceScreenResolution: function () {
         // Get the device screen width and height
         const width = window.screen.width;

package/Runtime/Public/Core/HyperSDK.cs

@@ -15,6 +15,7 @@ namespace Hyper
         private static GameAPIAdapter _gameAdapter;
         private static DataAPIAdapter _dataAdapter;
         private static EventAPIAdapter _eventAdapter;
+        private static LoaderAPIAdapter _loaderAdapter;
 
         /// <summary>
         /// Returns true if the SDK runtime has been initialized.
@@ -89,11 +90,33 @@ namespace Hyper
             }
         }
 
+        /// <summary>
+        /// Access loader control for custom pre-loading workflows.
+        /// Use when EnableCustomLoading is enabled in HyperGameContentConfig.
+        /// </summary>
+        public static ILoaderAPI Loader
+        {
+            get
+            {
+                if (_loaderAdapter == null)
+                {
+                    _loaderAdapter = new LoaderAPIAdapter();
+                }
+                return _loaderAdapter;
+            }
+        }
+
         /// <summary>
         /// Current Hyper SDK version string.
         /// </summary>
         public static string Version => HyperSDKVersion.Version;
 
+        /// <summary>True if the player is treated as mobile (heuristic). In the Unity Editor, follows the Device Simulator when active.</summary>
+        public static bool PlayerDeviceIsMobile => PlayerDeviceClassification.PlayerDeviceIsMobile;
+
+        /// <summary>True if the player is treated as PC/desktop (opposite of <see cref="PlayerDeviceIsMobile"/>).</summary>
+        public static bool PlayerDeviceIsPC => PlayerDeviceClassification.PlayerDeviceIsPC;
+
         private static void EnsureAdaptersReady()
         {
             if (_gameAdapter == null)
@@ -121,32 +144,106 @@ namespace Hyper
     /// </summary>
     public interface IGameAPI
     {
+		/// <summary>
+		/// True when the current mode is Battle (PvP or timed battle).
+		/// </summary>
         bool IsBattleMode { get; }
+		/// <summary>
+		/// True when the current mode is Practice.
+		/// </summary>
         bool IsPracticeMode { 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>
         bool HasGameStarted { get; }
+		/// <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.
+        /// </summary>
+        int BattleTimeRemaining { get; }
+
+        /// <summary>
+        /// Ends the current session for whichever mode is active (practice or battle).
+        /// </summary>
+        void EndGame();
+
+        [Obsolete("Use EndGame() instead; it ends practice or battle based on the current mode.")]
         void EndBattleGame();
+
+        [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>
         void ExitPracticeMenu();
 
         // Lives Management (only available when ControlBarLayout is HeartsLeft)
+		/// <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>
         void SetLives(int lives);
+		/// <summary>
+		/// Increment lives by one.
+		/// </summary>
         void AddLife();
+		/// <summary>
+		/// Decrement lives by one.
+		/// </summary>
         void RemoveLife();
+		/// <summary>
+		/// Get the current number of lives.
+		/// </summary>
         int GetCurrentLives();
+		/// <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>
         void InitializeHealth(float maxHealth, float initialHealth = -1f, bool isNormalized = false);
+		/// <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>
         void SetHealthNormalized(float normalizedHealth);
+		/// <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>
         void RemoveHealth(float amount);
+		/// <summary>
+		/// Get the current health (absolute units).
+		/// </summary>
         float GetCurrentHealth();
+		/// <summary>
+		/// Get the maximum health (absolute units).
+		/// </summary>
         float GetMaxHealth();
+		/// <summary>
+		/// Get the current health normalized to [0,1].
+		/// </summary>
         float GetHealthNormalized();
     }
 
@@ -155,34 +252,119 @@ namespace Hyper
     /// </summary>
     public interface IDataAPI
     {
+		/// <summary>
+		/// Current in-session score value.
+		/// </summary>
         int CurrentScore { get; }
 
+		/// <summary>
+		/// Overwrite the current score with a new value.
+		/// </summary>
         void UpdateScore(int score);
+		/// <summary>
+		/// Set the combo multiplier applied to scoring.
+		/// </summary>
         void SetComboMultiplier(float value);
+		/// <summary>
+		/// Set a global multiplier applied to scoring.
+		/// </summary>
         void SetGlobalMultiplier(float value);
+		/// <summary>
+		/// Register that a powerup is active by type identifier.
+		/// </summary>
         void AddPowerup(string powerupType);
+		/// <summary>
+		/// Remove an active powerup by type identifier.
+		/// </summary>
         void RemovePowerup(string powerupType);
+		/// <summary>
+		/// Retrieve the best/high score recorded for the player.
+		/// </summary>
         int GetBestScore();
     }
 
+    /// <summary>
+    /// Public API for custom pre-loading control during the HyperLoader bootstrap.
+    /// </summary>
+    public interface ILoaderAPI
+    {
+        /// <summary>
+        /// Report progress of your custom loading (0.0 to 1.0).
+        /// This feeds into the loading bar so players see smooth progress during your custom work.
+        /// Optional — if not called, the loader will simulate progress automatically.
+        /// </summary>
+        void ReportCustomLoadingProgress(float progress);
+
+        /// <summary>
+        /// Signal that your custom pre-loading is complete.
+        /// The HyperLoader bootstrap will resume and load the game scene.
+        /// Must be called when EnableCustomLoading is true in HyperGameContentConfig.
+        /// </summary>
+        void CompleteCustomLoading();
+    }
+
     /// <summary>
     /// Public API for SDK events.
     /// </summary>
     public interface IEventAPI
     {
+		/// <summary>
+		/// Fired when gameplay begins.
+		/// </summary>
         event Action OnGameStart;
+		/// <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>
         event Action OnGamePaused;
+		/// <summary>
+		/// Fired when the game resumes from a paused state.
+		/// </summary>
         event Action OnGameResumed;
+		/// <summary>
+		/// Fired when the current game session ends.
+		/// </summary>
         event Action OnGameEnded;
+		/// <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>
         event Action OnLivesExhausted;
+		/// <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>
         event Action OnCustomRestart;
     }
 
     #region Adapter Implementations
 
+    /// <summary>
+    /// Bridges the public loader API to the internal HyperRuntime custom loading state.
+    /// </summary>
+    internal sealed class LoaderAPIAdapter : ILoaderAPI
+    {
+        public void ReportCustomLoadingProgress(float progress)
+        {
+            HyperRuntime.CustomLoadingProgress = Mathf.Clamp01(progress);
+        }
+
+        public void CompleteCustomLoading()
+        {
+            HyperRuntime.CustomLoadingComplete = true;
+            HyperDebug.Log("Custom pre-loading complete. Bootstrap resuming");
+        }
+    }
+
     /// <summary>
     /// Bridges the public game API to the internal GameManager without exposing it to consumers.
     /// </summary>
@@ -196,8 +378,17 @@ namespace Hyper
         public bool HasGameStarted => Manager != null && Manager.HasGameStarted;
         public bool HasGameEnded => Manager != null && Manager.HasGameEnded;
 
+        public int BattleTimeRemaining => Manager?.BattleTimeRemaining ?? 0;
+
+        /// <inheritdoc/>
+        public void EndGame() => Manager?.EndGame();
+
+        [Obsolete("Use EndGame() instead; it ends practice or battle based on the current mode.")]
         public void EndBattleGame() => Manager?.EndBattleGame();
+
+        [Obsolete("Use EndGame() instead; it ends practice or battle based on the current mode.")]
         public void EndPracticeGame() => Manager?.EndPracticeGame();
+
         public void ExitPracticeMenu() => Manager?.ExitPracticeMenu();
 
         public void InitializeLives(int maxLives, int initialLives = -1) => Manager?.InitializeLives(maxLives, initialLives);

package/Runtime/Public/PlayerDeviceClassification.cs

@@ -0,0 +1,41 @@
+using System.Runtime.InteropServices;
+using Hyper.Shared;
+using UnityEngine;
+
+namespace Hyper
+{
+    internal static class PlayerDeviceClassification
+    {
+        internal static bool PlayerDeviceIsMobile => Resolve() == DevicePlatform.Mobile;
+
+        internal static bool PlayerDeviceIsPC => !PlayerDeviceIsMobile;
+
+        private static DevicePlatform Resolve()
+        {
+#if UNITY_EDITOR
+            // Unity Device Simulator: Device.Application matches the simulated device; Application does not.
+            return UnityEngine.Device.Application.isMobilePlatform ? DevicePlatform.Mobile : DevicePlatform.PC;
+#elif UNITY_WEBGL && !UNITY_EDITOR
+            if (HyperIsLikelyDesktopDevtoolsMobileViewport() != 0)
+                return DevicePlatform.PC;
+            if (Application.isMobilePlatform || HyperIsMobileUserAgent() != 0)
+                return DevicePlatform.Mobile;
+            return DevicePlatform.PC;
+#else
+            return Application.isMobilePlatform ? DevicePlatform.Mobile : DevicePlatform.PC;
+#endif
+        }
+
+#if UNITY_WEBGL && !UNITY_EDITOR
+        [DllImport("__Internal")]
+        private static extern int HyperIsMobileUserAgent();
+
+        [DllImport("__Internal")]
+        private static extern int HyperIsLikelyDesktopDevtoolsMobileViewport();
+#else
+        private static int HyperIsMobileUserAgent() => 0;
+
+        private static int HyperIsLikelyDesktopDevtoolsMobileViewport() => 0;
+#endif
+    }
+}

package/Runtime/Public/PlayerDeviceClassification.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: 6462d3b83a3aab741899fa52596c2263

package/Runtime/Resources/HyperGameContentConfig.asset

@@ -25,4 +25,5 @@ MonoBehaviour:
     sceneGUID: 
     scenePath: 
     sceneName: 
+  EnableCustomLoading: 0
   gamePosterSprite: {fileID: 0}

package/Runtime/Shared/DTOs/Enums.cs

@@ -53,7 +53,7 @@ namespace Hyper.Shared
         /// <summary>
         /// Fired when the game starts.
         /// </summary>
-        GameStart,
+        GameStarted,
 
         /// <summary>
         /// Fired when the game is resumed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "app.hypergames.hypersdk",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "displayName": "HyperSDK",
   "description": "Official Unity SDK for Hyper: multiplayer battles, leaderboards, deterministic RNG, session management, tutorials, and WebGL optimizations for production-ready games.",
   "unity": "6000.0",
@@ -24,9 +24,9 @@
     "email": "info@mvm.gg",
     "url": "https://mvm.gg/"
   },
-  "licensesUrl": "https://mvm.gg/",
-  "changelogUrl": "https://mvm.gg/",
-  "documentationUrl": "https://mvm.gg/",
+  "licensesUrl": "https://github.com/mvmhyper/hyper-sdk/blob/releaseTests/LICENSE.md",
+  "changelogUrl": "https://github.com/mvmhyper/hyper-sdk/blob/releaseTests/CHANGELOG.md",
+  "documentationUrl": "https://docs-getting-started-updates.hyper-sdk-documentation.pages.dev/",
   "repository": {
     "type": "git",
     "url": "https://github.com/mvmhyper/hyper-sdk.git",