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.

24.8 KB
Raw Blame
#nullable enable
using System;
using UnityEngine;
using UnityEngine.UIElements;
using YamlDotNet.Serialization;
using YamlDotNet.Serialization.NamingConventions;

namespace Statecraft.Game.UI
{
    /// <summary>The start menu's music (#39): the main theme by Afik (afikomposer, PR #2240; CC BY-NC-ND 4.0, owner 2 Nov 2026),
    /// an OGG in StreamingAssets/audio/music/ (docs/audio.md). It loops while the start screen shows and fades out over
    /// FadeMs of real time when a game starts; it never plays in the game. The whole file is downloaded when it is about to
    /// play (UnityWebRequestMultimedia, DeclarationRecording's fetch; not streamed) and decoded (by the browser on the web);
    /// the clip is released when the fade ends. Browsers block audio until the page's first activation (a click, a tap or a
    /// key other than Escape), so on the web nothing is fetched before one (GestureSeen; the desktop has no such rule). The
    /// Settings screen's Music row sets Volume (SettingsPresenter; MenuMusic's own default is the row's Low, so a missed
    /// wiring can't play loud); at 0 it is not even fetched. It drops to DipLevel while Ben-Gurion's recording plays on the
    /// same screen (Duck). No theme (main before #2240, a 404 or any failed fetch) is silence for the rest of the page
    /// (Absent): one fetch at most, one plain log line, no warning and no error. GameRoot keeps one for the page, across the
    /// rebuild a language switch makes, and builds it only in a player that shows the start screen, never in the automated
    /// runs (StartScreenPresenter.Skipped) or in EditMode. Presentation only: the sim and the golden hashes never see it.</summary>
    public sealed class MenuMusic : IDisposable
    {
        /// <summary>The theme's path under StreamingAssets. A renamed file is renamed here too (MenuMusicTests checks a
        /// committed file against it).</summary>
        public const string File = "audio/music/Main_1.3.ogg";

        /// <summary>The theme's loop points (#2338), Afik's proposed 00:10 to 04:03 (ASSETS.yaml), as data:
        /// Assets/Resources/Music/menu-music.yaml (`file`, `loop_start_s`, `loop_end_s`). In Resources, not next to the OGG:
        /// the music folder holds OGG files only, and Resources needs no second fetch on the web.</summary>
        public const string LoopResource = "Music/menu-music";

        /// <summary>The fade when a game starts (and the dip under the recording), in real time, and the watch's period while
        /// it loads or plays.</summary>
        public const int FadeMs = 1000, WatchMs = 50;

        /// <summary>The theme's level under Ben-Gurion's recording, as a share of the Music volume. The owner's ruling on #2297
        /// (2 Nov 2026), "Dip under the recording (Recommended)": "The theme drops low while the recording plays, then comes
        /// back". Low, not silence.</summary>
        public const float DipLevel = 0.2f;

        /// <summary>The volume until Settings sets one: the Music row's default, Low (owner, #2297, 2 Nov 2026: "Low by default
        /// (Recommended)"; SettingsPresenter.SoundLevels' "low").</summary>
        public const float DefaultVolume = 0.35f;

        /// <summary>Where the theme plays. The game's is two AudioSources on their own GameObject (SourceOutput).</summary>
        public interface IOutput : IDisposable
        {
            /// <summary>As DeclarationRecording.IOutput.Ready: true once decoded, false while not yet, null when it failed.</summary>
            bool? Ready(AudioClip clip);
            /// <summary>Plays the clip from sample 0 to the loop's End once, then its Start to End again and again
            /// (LoopRegion.SampleAt), the next part scheduled on the same audio-clock time the last one ends.</summary>
            void Play(AudioClip clip, LoopRegion loop);
            /// <summary>Every WatchMs while it plays: time to schedule the next seam.</summary>
            void Watch();
            void Stop();
            float Volume { set; }
        }

        /// <summary>The part of the clip that loops, in samples at Frequency: playback runs from sample 0 to End once, then
        /// from Start to End again and again. The whole clip is (0, samples).</summary>
        public readonly struct LoopRegion : IEquatable<LoopRegion>
        {
            public readonly int Start, End, Frequency;
            public LoopRegion(int start, int end, int frequency) { Start = start; End = end; Frequency = frequency; }

            /// <summary>The clip's sample heard after <paramref name="played"/> samples of playback.</summary>
            public long SampleAt(long played) => played < End ? played : Start + (played - End) % (End - Start);

            /// <summary>How many samples of playback come before seam <paramref name="n"/> (from 0), where End hands over to Start.
            /// Counted in samples, not by adding seconds up, so no rounding drifts over an hour on the menu.</summary>
            public long SeamAt(long n) => End + n * (End - Start);

            public bool Equals(LoopRegion o) => Start == o.Start && End == o.End && Frequency == o.Frequency;
            public override bool Equals(object? o) => o is LoopRegion r && Equals(r);
            public override int GetHashCode() => (Start * 31 + End) * 31 + Frequency;
            public override string ToString() => Start + ".." + End + " @ " + Frequency + " Hz";
        }

        sealed class LoopFile
        {
            public string File { get; set; } = "";
            public double LoopStartS { get; set; } = -1;
            public double LoopEndS { get; set; } = -1;
        }

        /// <summary>The loop region the file gives for a clip of <paramref name="samples"/> at <paramref name="frequency"/>;
        /// no file, a broken one, one for another file, or a region that is empty, reversed or outside the clip is the whole
        /// clip, with <paramref name="why"/> saying which (null when the file's region holds).</summary>
        internal static LoopRegion Loop(string? yaml, int samples, int frequency, out string? why)
        {
            why = null;
            LoopFile? f = null;
            if (string.IsNullOrWhiteSpace(yaml)) why = "no Resources/" + LoopResource + ".yaml";
            else
            {
                try
                {
                    f = new DeserializerBuilder().WithNamingConvention(UnderscoredNamingConvention.Instance)
                        .WithDuplicateKeyChecking().Build().Deserialize<LoopFile>(yaml);
                }
                catch (YamlDotNet.Core.YamlException e) { why = e.Message; }
            }
            if (why == null && f == null) why = "an empty loop file";
            if (why == null && f!.File != File) why = "the loop file is for '" + f.File + "'";
            if (why != null) return new LoopRegion(0, samples, frequency);
            long start = (long)Math.Round(f!.LoopStartS * frequency), end = (long)Math.Round(f.LoopEndS * frequency);
            if (start < 0 || end <= start || end > samples)
            {
                why = "loop " + f.LoopStartS + " s to " + f.LoopEndS + " s does not fit a clip of " + samples + " samples at " + frequency + " Hz";
                return new LoopRegion(0, samples, frequency);
            }
            return new LoopRegion((int)start, (int)end, frequency);
        }

        /// <summary>Idle (not wanted, or waiting for the screen, the first gesture or a volume above 0); Loading (fetching or
        /// decoding); Playing; Fading (the game has started); Absent (no theme: silent for the rest of the page).</summary>
        public enum Phase { Idle, Loading, Playing, Fading, Absent }

        /// <summary>True once the page has had an activation (a click, a tap or a key other than Escape): the browser's rule is
        /// per page, so it holds for every instance.</summary>
        public static bool GestureSeen { get; internal set; }

        /// <summary>True once a fetch failed or the file is missing: no theme for the rest of the page, whatever instance asks
        /// again (no second fetch, no second log line). A failed fetch for any reason counts: a reload tries again.</summary>
        public static bool ThemeAbsent { get; internal set; }

        static readonly TrickleDown[] Phases = { TrickleDown.TrickleDown, TrickleDown.NoTrickleDown };

        readonly VisualElement root, listener; readonly bool web; readonly string url;
        readonly DeclarationRecording.Fetch fetch; readonly IOutput output; readonly Func<double> now; readonly string? loopYaml;
        readonly EventCallback<PointerDownEvent> onPointerDown; readonly EventCallback<PointerUpEvent> onPointerUp;
        readonly EventCallback<KeyDownEvent> onKey;
        readonly IVisualElementScheduledItem timer;
        DeclarationRecording.IRequest? request; AudioClip? clip; VisualElement? hooked;
        bool wanted, playing, fadingOut; int generation; double lastTick;
        float volume = DefaultVolume, dip = 1f, fade = 1f;

        /// <summary>Absent for the page once ThemeAbsent is set; otherwise the instance's own phase.</summary>
        public Phase State => ThemeAbsent ? Phase.Absent : clip == null ? (request != null ? Phase.Loading : Phase.Idle)
            : !playing ? Phase.Loading : fadingOut ? Phase.Fading : Phase.Playing;

        /// <summary>Whether the start screen wants it (Show).</summary>
        internal bool Wanted => wanted;

        /// <summary>True while the theme must drop to DipLevel (GameRoot: while Ben-Gurion's recording plays).</summary>
        public Func<bool>? Duck { get; set; }

        /// <summary>0 (off) to 1 (the theme as mastered); SettingsPresenter sets it from the player's choice. Applies at once;
        /// raised from 0, it starts the theme if the start screen is up.</summary>
        public float Volume
        {
            get => volume;
            set { volume = Mathf.Clamp01(value); Apply(); TryStart(); }
        }

        /// <param name="web">The browser's rule: nothing before the page's first activation.</param>
        /// <param name="url">Test seam; null is Url().</param>
        /// <param name="fetch">Test seam; null fetches with UnityWebRequestMultimedia as Ogg Vorbis.</param>
        /// <param name="output">Test seam; null plays through an AudioSource.</param>
        /// <param name="now">Test seam: the clock, in seconds; null is Time.realtimeSinceStartupAsDouble.</param>
        /// <param name="loop">Test seam: the loop file's text; null reads Resources/Music/menu-music.yaml (LoopResource).</param>
        public MenuMusic(VisualElement root, bool web, string? url = null, DeclarationRecording.Fetch? fetch = null, IOutput? output = null,
            Func<double>? now = null, string? loop = null)
        {
            loopYaml = loop ?? Resources.Load<TextAsset>(LoopResource)?.text;
            this.root = root; this.web = web;
            this.url = url ?? Url();
            this.fetch = fetch ?? DeclarationRecording.WebFetchOgg;
            this.output = output ?? new SourceOutput();
            this.now = now ?? (() => Time.realtimeSinceStartupAsDouble);
            // On the panel's own root: a key with nothing focused goes there, never through the document's root below it.
            listener = root.panel?.visualTree ?? root;
            onPointerDown = e => PointerDown(e);
            onPointerUp = e => { if (e.pointerType != UnityEngine.UIElements.PointerType.mouse) Gesture(); };     // a touch's release activates
            onKey = e => { if (e.keyCode != KeyCode.Escape && e.character != '\u001b') Gesture(); };   // Escape never activates
            // Both phases: trickle-down sees an event before any element can stop it; bubble-up sees one aimed at the panel's
            // root itself. Gesture is idempotent, so an event seen twice counts once.
            foreach (var phase in Phases)
            {
                listener.RegisterCallback(onPointerDown, phase);
                listener.RegisterCallback(onPointerUp, phase);
                listener.RegisterCallback(onKey, phase);
            }
            timer = root.schedule.Execute(Tick).Every(WatchMs);
            timer.Pause();
        }

        /// <summary>The theme's URL, with the build's id on the web (issue #437), as DeclarationRecording.Url.</summary>
        public static string Url()
        {
            var u = Application.streamingAssetsPath + "/" + File;
            return u.Contains("://") ? Boot.GameInputs.WithBuildId(u, Application.buildGUID) : "file://" + u;
        }

        /// <summary>The start screen shows (true: play, once allowed; a fade under way turns back up) or closes (false: a game
        /// starts, so fade out; a load under way is cancelled).</summary>
        public void Show(bool shown)
        {
            wanted = shown;
            if (shown)
            {
                if (playing) fadingOut = false;   // shown again before the fade ended: it comes back up from where it is
                TryStart();
                return;
            }
            if (playing) fadingOut = true;
            else if (clip != null || request != null) Stop();
        }

        /// <summary>A mouse press activates. A touch or pen press does not (iOS); its release does. The element pressed (a
        /// button) captures the pointer, and a captured release goes to it alone, never through the panel's root, so the
        /// release is also heard on the element pressed.</summary>
        void PointerDown(PointerDownEvent e)
        {
            if (e.pointerType == UnityEngine.UIElements.PointerType.mouse) { Gesture(); return; }
            if (GestureSeen || !(e.target is VisualElement pressed) || pressed == listener) return;
            Unhook();
            hooked = pressed;
            hooked.RegisterCallback(onPointerUp, TrickleDown.TrickleDown);
        }

        void Unhook()
        {
            hooked?.UnregisterCallback(onPointerUp, TrickleDown.TrickleDown);
            hooked = null;
        }

        void Gesture()
        {
            if (GestureSeen) return;
            GestureSeen = true;
            Unhook();
            TryStart();
        }

        void TryStart()
        {
            if (!wanted || ThemeAbsent || clip != null || request != null || volume <= 0f || (web && !GestureSeen)) return;
            if (url.StartsWith("file://", StringComparison.Ordinal) && !System.IO.File.Exists(url.Substring("file://".Length)))
            {
                Absent(null);
                return;
            }
            var mine = ++generation;
            var r = fetch(url, (c, error) =>
            {
                if (mine != generation) { Release(c); return; }   // stopped meanwhile
                request = null;
                if (c == null) { Absent(error); return; }
                clip = c;
                Begin();
            });
            if (mine == generation && clip == null && !ThemeAbsent) { request = r; timer.Resume(); }   // still on its way
        }

        /// <summary>No theme: silent for the rest of the page, with one line in the log (never a warning: main ships no
        /// theme until #2240 lands).</summary>
        void Absent(string? why)
        {
            Stop();
            ThemeAbsent = true;
            Debug.Log("MUSIC no theme at " + File + ": the start menu is silent" + (why == null ? "" : " (" + why + ")"));
        }

        /// <summary>Plays the clip once it is decoded; until then the watch asks again.</summary>
        void Begin()
        {
            var ready = output.Ready(clip!);
            if (ready == null) { Absent("the clip did not decode"); return; }
            if (ready == false) { timer.Resume(); return; }
            playing = true; fadingOut = false; fade = 1f;
            dip = Duck?.Invoke() == true ? DipLevel : 1f;   // the recording may have started since the fetch did (N1)
            lastTick = now();
            Apply();
            var loop = Loop(loopYaml, clip!.samples, clip.frequency, out var why);
            if (why != null) Debug.Log("MUSIC no loop region for " + File + ": the whole clip loops (" + why + ")");
            output.Play(clip, loop);
            timer.Resume();
        }

        /// <summary>Every WatchMs while loading or playing: the play once decoded, and the dip and the fade, by the real time
        /// since the last tick (a slow or hitching frame rate does not stretch them). Allocates nothing.</summary>
        internal void Tick()
        {
            if (clip == null) return;
            if (!playing) { Begin(); return; }
            var t = now();
            float step = (float)((t - lastTick) * 1000.0 / FadeMs);
            lastTick = t;
            output.Watch();
            dip = Duck?.Invoke() == true ? Mathf.Max(DipLevel, dip - step) : Mathf.Min(1f, dip + step);
            fade = fadingOut ? Mathf.Max(0f, fade - step) : Mathf.Min(1f, fade + step);
            if (fadingOut && fade <= 1e-4f) { Stop(); return; }   // float steps: 20 x 0.05 may leave a hair above 0
            // (Shown again before this point, the fade had already turned back up: Show(true) clears fadingOut.)
            Apply();
        }

        void Apply()
        {
            if (playing) output.Volume = volume * dip * fade;
        }

        /// <summary>Stops it, cancels a fetch and releases the clip. Safe to call at any time.</summary>
        void Stop()
        {
            generation++;
            var r = request; request = null; r?.Abort();
            timer.Pause();
            output.Stop();
            Release(clip); clip = null;
            playing = false; fadingOut = false;
        }

        static void Release(AudioClip? c)
        {
            if (c == null) return;
            if (Application.isPlaying) UnityEngine.Object.Destroy(c); else UnityEngine.Object.DestroyImmediate(c);
        }

        public void Dispose()
        {
            wanted = false;
            Stop();
            Unhook();
            foreach (var phase in Phases)
            {
                listener.UnregisterCallback(onPointerDown, phase);
                listener.UnregisterCallback(onPointerUp, phase);
                listener.UnregisterCallback(onKey, phase);
            }
            output.Dispose();
        }

        /// <summary>Two AudioSources on their own GameObject, made at the first Play. The whole clip loops on one
        /// (AudioSource.loop). A loop region hands over between the two at each seam on the audio clock: the playing one's
        /// scheduled end and the other's scheduled start (at Start) are the same dspTime (the design; nobody has listened to the
        /// seam in a web build yet, #2338). On the web, Unity's Audio.js turns these into AudioBufferSourceNode start(when,
        /// offset) and stop(when) (Chromium decodes every clip to a buffer). AudioSource.loop cannot do it: it always loops the
        /// whole clip.</summary>
        internal sealed class SourceOutput : IOutput
        {
            /// <summary>The first play's lead on the audio clock, so both of the first seam's halves can be scheduled.</summary>
            const double Lead = 0.1;
            readonly Func<double> dsp; readonly Func<ISource> make;
            /// <summary>The sources are AudioSources on our own GameObject: something else may destroy it (Unity's null), and
            /// the next Play then makes both again.</summary>
            readonly bool own;
            GameObject? go; ISource? playing, next; float volume = DefaultVolume;
            LoopRegion loop; bool region; double startDsp, seamDsp; long seam;

            /// <param name="dsp">Test seam: the audio clock, in seconds; null is AudioSettings.dspTime.</param>
            /// <param name="make">Test seam: makes one of the two sources; null adds an AudioSource to the MenuMusic
            /// GameObject. EditMode has no running audio clock, so a test records the scheduling calls instead.</param>
            internal SourceOutput(Func<double>? dsp = null, Func<ISource>? make = null)
            {
                this.dsp = dsp ?? (() => AudioSettings.dspTime);
                this.make = make ?? MakeSource;
                own = make == null;
            }

            public bool? Ready(AudioClip clip) => DeclarationRecording.SourceOutput.ReadyState(clip);

            public void Play(AudioClip clip, LoopRegion loop)
            {
                if (playing == null || (own && go == null)) { playing = make(); next = make(); }
                Stop();
                this.loop = loop;
                region = loop.Start != 0 || loop.End != clip.samples;
                playing!.Clip = next!.Clip = clip;
                playing.Volume = next.Volume = volume;
                playing.Loop = !region;
                playing.TimeSamples = (int)loop.SampleAt(0);
                if (!region) { playing.Play(); return; }
                startDsp = dsp() + Lead;
                playing.PlayScheduled(startDsp);
                seam = 0;
                Schedule();
            }

            ISource MakeSource()
            {
                if (go == null) go = new GameObject("MenuMusic");
                var s = go.AddComponent<AudioSource>();
                s.playOnAwake = false; s.loop = false; s.spatialBlend = 0f;
                return new UnitySource(s);
            }

            /// <summary>Seam number `seam`: the playing source ends and the other starts where the loop goes on, at one time.</summary>
            void Schedule()
            {
                seamDsp = startDsp + (double)loop.SeamAt(seam) / loop.Frequency;
                playing!.SetScheduledEndTime(seamDsp);
                next!.TimeSamples = (int)loop.SampleAt(loop.SeamAt(seam));
                next.PlayScheduled(seamDsp);
            }

            /// <summary>Once a seam has passed, the source that took over plays on and the next seam is scheduled, a whole
            /// region (3:53 for the theme) ahead.</summary>
            public void Watch()
            {
                var now = dsp();
                if (!region || now < seamDsp) return;
                (playing, next) = (next, playing);
                seam++;
                if (startDsp + (double)loop.SeamAt(seam) / loop.Frequency <= now + Lead)
                {
                    // More than a region late: a hidden tab stalls this watch but not the audio clock, so the source that took
                    // over ran past the loop end and stopped. Scheduling the missed seams would restart once per region in a
                    // row; instead the loop starts again at its start, as if seam 0 fell just now.
                    var at = now + Lead;
                    startDsp = at - (double)loop.End / loop.Frequency;
                    playing!.TimeSamples = loop.Start;
                    playing.PlayScheduled(at);
                    seam = 1;
                }
                Schedule();
            }

            public void Stop()
            {
                region = false;
                if (playing != null) { playing.Stop(); playing.Clip = null; }
                if (next != null) { next.Stop(); next.Clip = null; }
            }

            public float Volume
            {
                set
                {
                    volume = value;
                    if (playing != null) playing.Volume = value;
                    if (next != null) next.Volume = value;
                }
            }

            public void Dispose()
            {
                if (go != null) { if (Application.isPlaying) UnityEngine.Object.Destroy(go); else UnityEngine.Object.DestroyImmediate(go); }
                go = null; playing = null; next = null;
            }
        }

        /// <summary>The calls SourceOutput makes on one of its two sources: an AudioSource in the game (UnitySource), a
        /// recorder in MenuMusicTests, so the handover at each seam can be checked without an audio clock.</summary>
        internal interface ISource
        {
            AudioClip? Clip { set; }
            float Volume { set; }
            bool Loop { set; }
            int TimeSamples { set; }
            void Play();
            void PlayScheduled(double at);
            void SetScheduledEndTime(double at);
            void Stop();
        }

        /// <summary>Every call skips a destroyed AudioSource (Unity's null): a scene teardown can destroy the MenuMusic
        /// GameObject before GameRoot.OnDisable disposes the music.</summary>
        sealed class UnitySource : ISource
        {
            readonly AudioSource s;
            public UnitySource(AudioSource s) { this.s = s; }
            public AudioClip? Clip { set { if (s != null) s.clip = value; } }
            public float Volume { set { if (s != null) s.volume = value; } }
            public bool Loop { set { if (s != null) s.loop = value; } }
            public int TimeSamples { set { if (s != null) s.timeSamples = value; } }
            public void Play() { if (s != null) s.Play(); }
            public void PlayScheduled(double at) { if (s != null) s.PlayScheduled(at); }
            public void SetScheduledEndTime(double at) { if (s != null) s.SetScheduledEndTime(at); }
            public void Stop() { if (s != null) s.Stop(); }
        }
    }
}