Skip to content

A Civilization-style strategy game about governing Israel from 15 May 1948. Real ministers, real map, every fact sourced. Unity + deterministic C# sim.

12.9 KB
Raw Blame
#nullable enable
using System;
using System.Collections.Generic;
using System.Globalization;
using Statecraft.Game.Boot;
using UnityEngine;
using UnityEngine.Rendering.Universal;

namespace Statecraft.Game.Map
{
    /// <summary>The web tier's runtime quality fallback (issue #44; visual v1 Deferred row "Runtime quality fallback"):
    /// when the frame-time p95 stays over the 30 fps floor, lower the render scale, then turn the tilt-shift off, then draw the
    /// town building models' far-off copies at every zoom (<see cref="Steps"/>); when it
    /// stays comfortably under, step back up in reverse. Pure logic (frame times in, a step out), so tests drive it with
    /// synthetic frames; QualityFallbackDriver feeds it the player's frames and applies its step. Presentation only: it
    /// reads nothing from the sim and changes no sim state, so turns, hashes and saves are the same on every step.
    ///
    /// Why these numbers (docs/visual-v1.md "Runtime quality fallback"):
    /// - Window 3 s: the p95 of a 3 s window needs at least 5% of the frames slow (5 of 90 at 30 fps), so a one-off hitch
    ///   (an End Turn redraw, a GC, a first shader compile: 1-2 frames) never trips it, while a real shortfall (every frame
    ///   slow) does within 3 s. Windows are back to back; one decision per window.
    /// - Step down when a window's p95 is over the 30 fps floor (33 ms, research notes 2.3) by more than the WebGL clock's
    ///   resolution: p95 > OverMs = 34 ms. The WebGL frame clock is quantised to about 1 ms, so exactly 30 fps (a display
    ///   or a battery saver capping the page at 30 Hz, or vsync halving 60 Hz) reads as 33 and 34 ms frames: that meets
    ///   the floor, and lowering the quality could not raise a capped rate anyway.
    /// - Step up only after RecoverWindows windows in a row with p95 &lt; 20 ms. 20 ms is the hysteresis: one step up
    ///   (0.8 -> 0.9 or 0.9 -> 1.0) draws at most 1.27 times the pixels, so a fill-bound frame at 20 ms lands at about 25 ms,
    ///   under the floor; the tilt-shift costs under 1.5 ms. Between 20 and 34 ms nothing changes (the dead band).
    /// - Settle: frames in the first 0.5 s after a change are not measured (the change reallocates render targets), nor
    ///   the first 3 s after start (scene load and shader compiles).
    /// - A frame over 1 s is a pause (a stalled load, a tab coming back), not load: it drops the window.
    /// - A hidden page is not measured (issue #216, integration B18): a browser throttles a background tab or a minimised
    ///   window to a few frames a second (170-200 ms frames, each under the 1 s pause line), which says nothing about the
    ///   device. Chromium on Windows and macOS also marks a window covered by others hidden (B18 was one); Firefox and
    ///   Safari do not, and there only the 1 s pause line catches a stall. While Background is set
    ///   (QualityFallbackDriver reads document.hidden) frames are ignored and
    ///   the partial window is dropped; on coming back the first ResumeSettleSeconds are not measured either. The level and
    ///   the count of good windows towards a step up are kept, so a level that a real shortfall set recovers as usual
    ///   once the page is in front: RecoverNeeded windows in a row under RecoverMs.
    /// - A window needs MinWindowFrames = 3 frames. With every counted frame at most 1 s, a full 3 s window always has 3,
    ///   so every window counts down to 1 fps (review M2: a minimum of 10 left 1-3 fps devices, the ones that need the
    ///   fallback most, with no decision at all). Few frames make the p95 the slowest frame, but a window that holds under
    ///   10 frames averages over 300 ms a frame, far over the floor anyway.
    /// - Anti-oscillation: a step up that is undone within two windows doubles the windows the next step up needs
    ///   (3, 6, 12 ... at most 48, 2.4 minutes), so a device on the edge settles instead of flipping every 10 s.</summary>
    public sealed class QualityFallback
    {
        public readonly struct Step
        {
            public readonly float RenderScale; public readonly bool TiltShift;
            /// <summary>The town building models draw their far-off copies, without shadows, even below the close switch
            /// (TownModelLayer.LowTier).</summary>
            public readonly bool TownModelsFar;
            public Step(float renderScale, bool tiltShift, bool townModelsFar = false) { RenderScale = renderScale; TiltShift = tiltShift; TownModelsFar = townModelsFar; }
            public override string ToString() => string.Format(CultureInfo.InvariantCulture, "scale={0:0.00} tiltshift={1} towns={2}", RenderScale, TiltShift ? "on" : "off", TownModelsFar ? "far" : "close");
        }

        /// <summary>Level 0 is the tier's own look; each level down costs less. Render scale first, within the research's
        /// 0.8-1.0 dynamic range (notes 2.3), then the tilt-shift, then the town building models' far-off copies at every
        /// zoom: since v0.3.5 the 30 km opening (owner, 3 November 2026, "Open at ~30 km, like the promo") sits below
        /// TownModelLayer.CloseEnterM, so the full originals and their shadows draw from the first frame, and on a weak or
        /// software GPU the nightly's start-screen p95 went from 35-88 ms (v0.3.4) to 320-690 ms (v0.3.5, v0.3.6). A device
        /// that reaches this step still opens at 30 km, with the far copies; a capable one never reaches it.</summary>
        public static readonly IReadOnlyList<Step> Steps = new[]
        {
            new Step(1f, true), new Step(0.9f, true), new Step(0.8f, true), new Step(0.8f, false), new Step(0.8f, false, townModelsFar: true),
        };

        public const float FloorMs = 33f, OverMs = 34f, RecoverMs = 20f, WindowSeconds = 3f, SettleSeconds = 0.5f, StartupSeconds = 3f, PauseMs = 1000f, ResumeSettleSeconds = 1f;
        public const int MinWindowFrames = 3, RecoverWindows = 3, MaxRecoverWindows = 48, FailedRecoveryWindows = 2;

        public int Level { get; private set; }
        public Step Current => Steps[Level];
        /// <summary>The p95 of the last complete window (NaN before the first).</summary>
        public float LastP95 { get; private set; } = float.NaN;
        /// <summary>Windows measured so far (diagnostics and tests).</summary>
        public int Windows { get; private set; }
        /// <summary>Windows in a row under RecoverMs that the next step up needs (doubles after a failed step up).</summary>
        public int RecoverNeeded { get; private set; } = RecoverWindows;

        /// <summary>Whether the page is hidden (document.hidden: a background tab or a minimised window, and in Chromium a
        /// covered one): frames are not measured.</summary>
        public bool Background { get; private set; }

        /// <summary>Sets <see cref="Background"/>. Going hidden drops the partial window; coming back starts a
        /// ResumeSettleSeconds settle (the first frames back redraw and refill caches).</summary>
        public void SetBackground(bool hidden)
        {
            if (hidden == Background) return;
            Background = hidden;
            window.Clear(); windowMs = 0f;
            if (!hidden) settleMs = Math.Max(settleMs, ResumeSettleSeconds * 1000f);
        }

        readonly List<float> window = new List<float>();
        float windowMs, settleMs = StartupSeconds * 1000f;
        int goodWindows, windowsSinceStepUp = int.MaxValue;

        /// <summary>Feeds one frame's time in ms; true when it moved Level (the caller then applies Current).</summary>
        public bool Feed(float frameMs)
        {
            if (float.IsNaN(frameMs) || frameMs < 0f || Background) return false;
            if (frameMs > PauseMs) { window.Clear(); windowMs = 0f; return false; }
            if (settleMs > 0f) { settleMs -= frameMs; return false; }
            window.Add(frameMs); windowMs += frameMs;
            if (windowMs < WindowSeconds * 1000f) return false;
            bool enough = window.Count >= MinWindowFrames;
            var p95 = enough ? FrameStats.Summary(window).p95 : float.NaN;
            window.Clear(); windowMs = 0f;
            if (!enough) return false;
            LastP95 = p95; Windows++;
            if (windowsSinceStepUp < int.MaxValue) windowsSinceStepUp++;
            if (p95 > OverMs)
            {
                goodWindows = 0;
                if (Level == Steps.Count - 1) return false;
                if (windowsSinceStepUp <= FailedRecoveryWindows) RecoverNeeded = Math.Min(RecoverNeeded * 2, MaxRecoverWindows);
                windowsSinceStepUp = int.MaxValue;
                return Move(+1);
            }
            if (p95 >= RecoverMs || Level == 0) { goodWindows = 0; return false; }
            if (++goodWindows < RecoverNeeded) return false;
            goodWindows = 0; windowsSinceStepUp = 0;
            return Move(-1);
        }

        bool Move(int by) { Level += by; settleMs = SettleSeconds * 1000f; return true; }

        /// <summary>Whether the fallback runs: the WebGL tier only (the desktop tier is the development and capture target, and
        /// in the editor a render-scale change would write the URP asset), and never under an instrument that must see the
        /// tier's own look (?vprofile, ?profile, ?shot) or with ?nofallback.</summary>
        public static bool Wanted(string? url, bool webgl) =>
            webgl && !UrlFlags.Has(url, "vprofile") && !UrlFlags.Has(url, "profile") && !UrlFlags.Has(url, "shot") && !UrlFlags.Has(url, "nofallback");

        public static bool Wanted() => Wanted(Application.absoluteURL, Application.platform == RuntimePlatform.WebGLPlayer);

        public string Line() => string.Format(CultureInfo.InvariantCulture, "QUALITY level={0} {1} p95_ms={2:0.00}", Level, Current, LastP95);
    }

    /// <summary>Feeds QualityFallback the player's frame times (unscaled, so a paused game still counts) and whether the page
    /// is hidden (document.hidden through DocumentVisibility.jslib, read every frame; never hidden outside the WebGL player), and applies its step:
    /// the active URP asset's render scale (never above the tier's own), TiltShift.FallbackOff and TownModelLayer.LowTier. CameraRig.Init attaches it
    /// to the map camera through Attach, whose undo (run by the map's teardown) removes it and puts both back.</summary>
    public sealed class QualityFallbackDriver : MonoBehaviour
    {
        public QualityFallback Controller { get; private set; } = new QualityFallback();
        /// <summary>Whether the page is hidden now (tests replace it).</summary>
        public Func<bool> Hidden { get; set; } = DocumentHidden;
        float tierScale = 1f;
        Action<float> setScale = _ => { };

        /// <summary>Adds the driver to <paramref name="camera"/> when <paramref name="wanted"/> (QualityFallback.Wanted());
        /// returns the undo for the map's teardown (a no-op when not wanted).</summary>
        public static Action Attach(GameObject camera, bool wanted)
        {
            if (!wanted) return () => { };
            var asset = UniversalRenderPipeline.asset;
            var driver = camera.AddComponent<QualityFallbackDriver>();
            driver.tierScale = asset != null ? asset.renderScale : 1f;
            driver.setScale = s => { if (asset != null) asset.renderScale = s; };
            var tierScale = driver.tierScale;
            // Every quality switch (#40) put the tier's own look or a fixed one in place: the fallback starts again from the top.
            Action restart = () => driver.Controller = new QualityFallback();
            GraphicsQuality.Changed += restart;
            return () =>
            {
                GraphicsQuality.Changed -= restart;
                if (asset != null) asset.renderScale = tierScale;
                TiltShift.FallbackOff = false;
                Kits.TownModelLayer.LowTier = false;
                if (driver != null) { if (Application.isPlaying) Destroy(driver); else DestroyImmediate(driver); }
            };
        }

        /// <summary>Feeds one frame (tests call it; Update feeds the real frames).</summary>
        public void Feed(float frameMs)
        {
            // High or Low in Settings (#40) fixes the quality: GraphicsQuality.Apply set the scale and ended FallbackOff.
            if (GraphicsQuality.Current != GraphicsQuality.Choice.Auto) return;
            if (!Controller.Feed(frameMs)) return;
            var step = Controller.Current;
            setScale(Mathf.Min(tierScale, step.RenderScale));
            TiltShift.FallbackOff = !step.TiltShift;
            Kits.TownModelLayer.LowTier = step.TownModelsFar;
            Debug.Log(Controller.Line());
        }

        void Update() { Controller.SetBackground(Hidden()); Feed(Time.unscaledDeltaTime * 1000f); }

#if UNITY_WEBGL && !UNITY_EDITOR
        [System.Runtime.InteropServices.DllImport("__Internal")] static extern int StatecraftDocumentHidden();
        static bool DocumentHidden() => StatecraftDocumentHidden() != 0;
#else
        static bool DocumentHidden() => false;
#endif
    }
}