tweak(notifications): blur and pause notifications when game is paused.

Author: TomGrobbe

assets/enhanced/ui/notifications.css

@@ -16,6 +16,13 @@
     flex-direction: column;
     gap: var(--toast-gap);
     pointer-events: none;
+    transition: filter 0.25s ease, opacity 0.25s ease;
+}
+
+/* The game blurs the world behind the pause menu, and the stack sits in that world, so it blurs with it. */
+#toasts.paused {
+    filter: blur(2px);
+    opacity: 0.75;
 }
 
 .toast {

assets/enhanced/ui/notifications.js

@@ -8,6 +8,9 @@
     /* Long enough for `.leaving` to finish; the row is only removed once it has faded out. */
     const EXIT_MS = 200;
 
+    /* Handed back to a row the pause menu froze, so there is time to read it once the game returns. */
+    const PAUSE_GRACE_MS = 2000;
+
     const ICONS = {
         info: '<circle cx="12" cy="12" r="9"/><path d="M12 11.2v5"/><path d="M12 7.6h.01"/>',
         success: '<circle cx="12" cy="12" r="9"/><path d="M7.9 12.3l2.8 2.8 5.4-5.6"/>',
@@ -36,6 +39,7 @@
     const queued = [];
 
     let shown = 0;
+    let paused = false;
 
     /*
        Written per message rather than per frame: the client only recalculates where the map ends
@@ -142,13 +146,68 @@
         replay(entry.badge);
     }
 
-    /* Puts the row back on a full timer, so a repeat keeps the message on screen instead of ending it sooner. */
-    function restart(entry) {
+    /*
+       Starts, or restarts, a row's countdown with `remaining` of its duration left to run. The bar's
+       keyframe always spans the whole duration and is wound forward with a negative delay, so a row
+       coming back from a pause picks up at the width its remaining time deserves rather than
+       snapping back to full.
+    */
+    function run(entry, remaining) {
         clearTimeout(entry.timer);
-        entry.timer = setTimeout(() => dismiss(entry), entry.duration);
+
+        entry.remaining = remaining;
 
         replay(entry.progress);
         entry.progress.style.animationDuration = `${entry.duration}ms`;
+        entry.progress.style.animationDelay = `-${entry.duration - remaining}ms`;
+
+        if (paused) {
+            entry.progress.style.animationPlayState = "paused";
+            entry.timer = 0;
+
+            return;
+        }
+
+        entry.endsAt = performance.now() + remaining;
+        entry.timer = setTimeout(() => dismiss(entry), remaining);
+    }
+
+    /* Keeps what is left of a row's time instead of spending it behind the pause menu. */
+    function freeze(entry) {
+        clearTimeout(entry.timer);
+
+        entry.timer = 0;
+        entry.remaining = Math.max(0, entry.endsAt - performance.now());
+        entry.progress.style.animationPlayState = "paused";
+    }
+
+    /* Never past the time the row was given, so pausing over and over cannot keep it on screen. */
+    function thaw(entry) {
+        run(entry, Math.min(entry.remaining + PAUSE_GRACE_MS, entry.duration));
+    }
+
+    function setPaused(next) {
+        if (next === paused) {
+            return;
+        }
+
+        paused = next;
+
+        // Blurred along with the world the pause menu draws over.
+        listEl.classList.toggle("paused", paused);
+
+        for (const entry of tracked.values()) {
+            // A row still waiting its turn has no time to hold; it is started when it reaches the screen.
+            if (!entry.toast) {
+                continue;
+            }
+
+            if (paused) {
+                freeze(entry);
+            } else {
+                thaw(entry);
+            }
+        }
     }
 
     function dismiss(entry) {
@@ -197,7 +256,6 @@
 
         const progress = document.createElement("span");
         progress.className = "progress";
-        progress.style.animationDuration = `${entry.duration}ms`;
 
         toast.append(bar, body);
 
@@ -215,7 +273,8 @@
         entry.toast = toast;
         entry.badge = badge;
         entry.progress = progress;
-        entry.timer = setTimeout(() => dismiss(entry), entry.duration);
+
+        run(entry, entry.duration);
 
         // Carried over from the wait, where a row can pick up repeats before it ever reaches the screen.
         if (entry.repeats > 1) {
@@ -246,7 +305,9 @@
             // Nothing to redraw while it is still waiting; it is built with the count it has by then.
             if (repeat.toast) {
                 count(repeat);
-                restart(repeat);
+
+                // Back on a full timer, so a repeat keeps the message on screen instead of ending it sooner.
+                run(repeat, repeat.duration);
             }
 
             return;
@@ -263,6 +324,8 @@
             badge: null,
             progress: null,
             timer: 0,
+            remaining: duration,
+            endsAt: 0,
         };
 
         tracked.set(key, entry);
@@ -287,7 +350,20 @@
             }
         }
 
-        if (data && typeof data === "object" && data.type === "notify") {
+        if (!data || typeof data !== "object") {
+            return;
+        }
+
+        if (data.type === "notify_pause") {
+            setPaused(data.paused === true);
+
+            return;
+        }
+
+        if (data.type === "notify") {
+            // Carried on the message itself, so one arriving during a pause is frozen from the start.
+            setPaused(data.paused === true);
+
             notify(data);
         }
     });

src/Client/vMenu.Enhanced.MenuFramework/Notifications.cs

@@ -1,7 +1,9 @@
 using CitizenFX.FiveM.Client;
 
+using vMenu.Enhanced.Data.Ticks;
 using vMenu.Enhanced.MenuFramework.Localization;
 using vMenu.Enhanced.Serialization;
+using vMenu.Enhanced.Ticks;
 
 namespace vMenu.Enhanced.MenuFramework;
 
@@ -26,6 +28,27 @@ public static class Notifications
     /// <summary>Thirty seconds of waiting for a spawn, after which the message is shown regardless.</summary>
     private const int MaxVisibilityChecks = 60;
 
+    /// <summary>What the page hands a frozen message back when the pause menu closes, mirrored here.</summary>
+    private const int PauseGraceMs = 2000;
+
+    /// <summary>Covers the fade the page plays after a message's time is up.</summary>
+    private const int ExitGraceMs = 500;
+
+    private const long PauseCheckIntervalMs = 100;
+
+    private const string PausedMessage = """{"type":"notify_pause","paused":true}""";
+
+    private const string ResumedMessage = """{"type":"notify_pause","paused":false}""";
+
+    private static TickHandle? _pauseTick;
+
+    private static bool _paused;
+
+    /// <summary>Game time by which every message sent so far has had its say.</summary>
+    private static long _liveUntil;
+
+    private static long _polledAt;
+
     public static void Info(MenuText text, int durationMs = DefaultDurationMs) =>
         Show(NotificationStyle.Info, text, durationMs);
 
@@ -73,7 +96,75 @@ public static void Show(
             return;
         }
 
-        Native.SendNuiMessage(BuildMessage(Name(style), message, durationMs, source));
+        // Read once and sent with the message, so a notification raised during a pause is drawn the
+        // way the ones already on screen are instead of waiting for the next poll to catch up.
+        var paused = Native.IsPauseMenuActive();
+
+        Native.SendNuiMessage(BuildMessage(Name(style), message, durationMs, source, paused));
+
+        Watch(durationMs, paused);
+    }
+
+    /// <summary>Keeps the pause menu watch alive for as long as this message can still be on screen.</summary>
+    // An estimate, never the truth: the page owns the timers, and this side only needs to know when
+    // watching is pointless. It rounds up on a repeat, which restarts the row and this window with
+    // it, and falls short only when messages arrive faster than the page shows them, where the ones
+    // still queued go without their blur and their extra time.
+    private static void Watch(int durationMs, bool paused)
+    {
+        var until = Native.GetGameTimer() + durationMs + ExitGraceMs;
+
+        if (until > _liveUntil)
+        {
+            _liveUntil = until;
+        }
+
+        // Registered on the first message rather than from an Initialize, so a client that never
+        // notifies never lists a loop, and nothing has to be ordered in front of this.
+        _pauseTick ??= TickRegistry.Register(
+            "Notifications.Pause",
+            PollPause,
+            TickRate.Every(PauseCheckIntervalMs),
+            () => _liveUntil > Native.GetGameTimer(),
+            () => _polledAt = Native.GetGameTimer());
+
+        // The page is told the state on every message, so the poll has nothing left to announce.
+        _paused = paused;
+
+        _pauseTick.Reevaluate();
+    }
+
+    private static void PollPause()
+    {
+        var now = Native.GetGameTimer();
+        var paused = Native.IsPauseMenuActive();
+
+        // The page holds its messages for as long as the pause menu is up, so this window holds with them.
+        if (paused)
+        {
+            _liveUntil += now - _polledAt;
+        }
+
+        _polledAt = now;
+
+        if (paused != _paused)
+        {
+            _paused = paused;
+
+            // Mirrors the grace the page hands back, so watching does not end while a message is still living on it.
+            if (!paused)
+            {
+                _liveUntil += PauseGraceMs;
+            }
+
+            Native.SendNuiMessage(paused ? PausedMessage : ResumedMessage);
+        }
+
+        // Conditions are only re-run on demand, so the loop has to be the one to notice it is done.
+        if (now >= _liveUntil)
+        {
+            _pauseTick?.Reevaluate();
+        }
     }
 
     /// <summary>The box the stack grows out of, as fractions of the screen, lined up with the minimap.</summary>
@@ -99,7 +190,7 @@ private static float MinimapWidth()
         return aspect > 0f ? 1f / (4f * aspect) : 1f / 4f;
     }
 
-    private static string BuildMessage(string style, string text, int durationMs, string? source)
+    private static string BuildMessage(string style, string text, int durationMs, string? source, bool paused)
     {
         var (left, bottom, width) = Anchor();
 
@@ -109,6 +200,7 @@ private static string BuildMessage(string style, string text, int durationMs, st
             Text = text,
             Duration = durationMs,
             Footer = string.IsNullOrWhiteSpace(source) ? null : source,
+            Paused = paused,
             Anchor = new AnchorBox
             {
                 Left = Fraction(left),
@@ -133,6 +225,9 @@ private sealed class NotifyMessage
 
         public string? Footer { get; init; }
 
+        /// <summary>Whether the pause menu is up, which is also the state the page as a whole goes into.</summary>
+        public required bool Paused { get; init; }
+
         public required AnchorBox Anchor { get; init; }
     }
 

src/Client/vMenu.Enhanced.MenuFramework/vMenu.Enhanced.MenuFramework.csproj

@@ -11,6 +11,9 @@
     <ProjectReference Include="..\vMenu.Enhanced.Configuration\vMenu.Enhanced.Configuration.csproj" />
     <ProjectReference Include="..\vMenu.Enhanced.Permissions\vMenu.Enhanced.Permissions.csproj" />
     <ProjectReference Include="..\vMenu.Enhanced.Serialization\vMenu.Enhanced.Serialization.csproj" />
+
+    <!-- Notifications watch the pause menu from a registered tick while a message is on screen. -->
+    <ProjectReference Include="..\vMenu.Enhanced.Ticks\vMenu.Enhanced.Ticks.csproj" />
   </ItemGroup>
 
 </Project>