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.

13.7 KB
Raw Blame
#nullable enable
using System;
using UnityEngine;
using UnityEngine.Networking;
using UnityEngine.UIElements;

namespace Statecraft.Game.UI
{
    /// <summary>The start screen's "Play the recording" button: David Ben-Gurion reading the sentence of the Declaration of
    /// Independence that proclaims the state, from the archive's recording of the ceremony of 14 May 1948, Israel State
    /// Archives item ISA-Collections-Recordings-00113hj (docs/declaration-recording.md; docs/oss/DECISIONS.md D-R).
    /// The file is the archive's own Opus upload, cut by stream copy (no re-encode) and then decoded to 16-bit PCM WAV,
    /// which every browser and Unity's own reader play (the Web player could not load the Ogg Opus cut); it sits in StreamingAssets (its SHA-256 is pinned in a test), is fetched only when the player presses the button,
    /// and the browser decodes it. It plays only from that press, never by itself, never on Continue or New Game; it stops
    /// when the start screen closes or Report or Replay the opening covers it.
    /// While the file loads the button reads "Loading…" (pressing it again cancels); the
    /// captions and "Stop" show only once the audio is actually playing; a failed or slow load ends with a message.
    /// GameRoot builds it only when the start screen is shown, which automated runs skip (StartScreenPresenter.Skipped),
    /// and the button's row is hidden by the stylesheet until this class shows it.</summary>
    public sealed class DeclarationRecording : IDisposable
    {
        /// <summary>The recording's path under StreamingAssets, and the SHA-256 of the committed excerpt
        /// (DeclarationRecordingTests checks the shipped file against it).</summary>
        public const string File = "audio/declaration-1948-isa-00113hj.wav";
        public const string Sha256 = "24e7bc48f5d0134bbe28f0f81b3668235398e3a4bfd83d54aa8650aeae2da370";

        /// <summary>The limits before a press ends with "start.recording_failed". The fetch fails when no byte has arrived for
        /// StallTimeoutMs (a slow link that is still receiving is never cut off), or in any case after LoadCapMs (the 1.8 MB
        /// file takes about 60 s at 250 kbit/s). Decoding has its own budget, DecodeTimeoutMs from the moment the file has
        /// arrived; the audio then has StartTimeoutMs after Play to start.</summary>
        public const int StallTimeoutMs = 8000, LoadCapMs = 60000, DecodeTimeoutMs = 5000, StartTimeoutMs = 3000;
        const int WatchMs = 200;

        /// <summary>A fetch under way: the bytes received so far, and a call that aborts it (after which its done callback is
        /// not called).</summary>
        public interface IRequest
        {
            ulong Bytes { get; }
            void Abort();
        }

        /// <summary>Fetches <paramref name="url"/> as a clip and calls <paramref name="done"/> once, with the clip or with
        /// an error (never both).</summary>
        public delegate IRequest Fetch(string url, Action<AudioClip?, string?> done);

        /// <summary>Where the clip plays. The game's is an AudioSource on its own GameObject (SourceOutput).</summary>
        public interface IOutput : IDisposable
        {
            /// <summary>True when the clip's audio data is decoded and it can play (on the Web the browser decodes it after
            /// the fetch, asynchronously); asks for the data when it is not loaded yet. Null when it failed to load.</summary>
            bool? Ready(AudioClip clip);
            void Play(AudioClip clip);
            void Stop();
            bool IsPlaying { get; }
            /// <summary>The play position in seconds: it moves only when the audio really plays.</summary>
            float Position { get; }
        }

        public enum Phase { Idle, Loading, Playing }

        readonly Button button; readonly VisualElement caption, row; readonly UiText text;
        readonly Action onPress; readonly Action<string> say; readonly Action? retry; readonly Fetch fetch; readonly IOutput output;
        AudioClip? clip; IRequest? request; IVisualElementScheduledItem? timer;
        bool heard, started; int waitedMs, stalledMs, generation; ulong bytesSeen;

        /// <summary>Idle; Loading from the press until the audio is heard; Playing while it is heard.</summary>
        public Phase State { get; private set; }

        /// <summary>True from the press until the recording ends, fails or is stopped (including while it loads).</summary>
        public bool Playing => State != Phase.Idle;

        /// <param name="say">Shows a message (the toast) when the recording cannot be played.</param>
        /// <param name="retry">Called when a press starts a new load, so the toast can drop the last failure's line.</param>
        /// <param name="fetch">Test seam; null fetches with UnityWebRequestMultimedia.</param>
        /// <param name="output">Test seam; null plays through an AudioSource.</param>
        public DeclarationRecording(VisualElement root, UiText text, Action<string> say, Fetch? fetch = null, IOutput? output = null, Action? retry = null)
        {
            this.text = text; this.say = say; this.retry = retry;
            this.fetch = fetch ?? WebFetch;
            this.output = output ?? new SourceOutput();
            row = root.Q<VisualElement>("start-recording");
            button = root.Q<Button>("start-listen");
            caption = root.Q<VisualElement>("start-caption");
            button.text = text["start.listen"];
            row.Q<Label>("start-recording-credit").text = text["start.recording_credit"];
            onPress = Toggle;
            button.clicked += onPress;
            row.style.display = DisplayStyle.Flex;
            caption.style.display = DisplayStyle.None;
        }

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

        /// <summary>The button: play; or, while loading or playing, stop.</summary>
        public void Toggle()
        {
            if (Playing) { Stop(); return; }
            retry?.Invoke();
            State = Phase.Loading;
            button.text = text["start.loading"];
            waitedMs = 0; stalledMs = 0; bytesSeen = 0; heard = false; started = false;
            timer = button.schedule.Execute(Tick).Every(WatchMs).StartingIn(WatchMs);
            var mine = ++generation;
            request = fetch(Url(), (c, error) =>
            {
                if (mine != generation || State != Phase.Loading) { Release(c); return; }   // stopped, or pressed again, meanwhile
                request = null;
                if (c == null) { Fail("fetch: " + error); return; }
                clip = c;
                waitedMs = 0;   // the decode budget starts now
                Begin();
            });
            if (State != Phase.Loading || clip != null) request = null;   // the fetch answered at once
        }

        /// <summary>Plays the fetched clip once its data is ready (Tick tries again until then).</summary>
        void Begin()
        {
            var ready = output.Ready(clip!);
            if (ready == null) { Fail("the clip did not decode"); return; }
            if (ready == false) return;
            output.Play(clip!);
            started = true;
            waitedMs = 0;
        }

        void Heard()
        {
            heard = true;
            State = Phase.Playing;
            button.text = text["start.stop"];
            caption.style.display = DisplayStyle.Flex;
            Debug.Log(FormattableString.Invariant($"RECORDING playing {File} ({clip!.length:0.00} s, at {output.Position:0.00} s)"));
        }

        /// <summary>Every WatchMs while loading or playing: the load, decode and start timeouts; the play once the data is
        /// decoded; the first moment the audio is heard (playing, and its position has moved); and its end. The end is "was
        /// heard, now is not playing", so a slow first start never cancels itself.</summary>
        internal void Tick()
        {
            if (!Playing) return;
            waitedMs += WatchMs;
            if (clip == null)
            {
                var bytes = request?.Bytes ?? 0;
                if (bytes > bytesSeen) { bytesSeen = bytes; stalledMs = 0; } else stalledMs += WatchMs;
                if (stalledMs >= StallTimeoutMs) Fail($"no data for {StallTimeoutMs} ms");
                else if (waitedMs >= LoadCapMs) Fail($"not loaded after {LoadCapMs} ms");
                return;
            }
            if (!started)
            {
                Begin();
                if (Playing && !started && waitedMs >= DecodeTimeoutMs) Fail("timed out decoding");
                return;
            }
            if (!heard)
            {
                if (output.IsPlaying && output.Position > 0f) Heard();
                else if (waitedMs >= StartTimeoutMs) Fail("did not start");
                return;
            }
            if (!output.IsPlaying) Stop();
        }

        void Fail(string why)
        {
            Debug.LogWarning("RECORDING failed " + File + ": " + why);
            Stop();
            say(text["start.recording_failed"]);
        }

        /// <summary>Stops it (the start screen closing, Report or Replay the opening covering it, the button,
        /// the end of the clip) and releases the clip. Safe to call when it is not playing.</summary>
        public void Stop()
        {
            generation++;
            var r = request; request = null; r?.Abort();
            timer?.Pause(); timer = null;
            output.Stop();
            Release(clip); clip = null;
            heard = false; started = false;
            State = Phase.Idle;
            button.text = text["start.listen"];
            caption.style.display = DisplayStyle.None;
        }

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

        public void Dispose()
        {
            Stop();
            button.clicked -= onPress;
            output.Dispose();
        }

        /// <summary>The game's fetch: UnityWebRequestMultimedia from StreamingAssets, as WAV.</summary>
        internal static IRequest WebFetch(string url, Action<AudioClip?, string?> done) => new WebRequest(url, done, AudioType.WAV);

        /// <summary>The same fetch as Ogg Vorbis (the start menu's music, MenuMusic).</summary>
        internal static IRequest WebFetchOgg(string url, Action<AudioClip?, string?> done) => new WebRequest(url, done, AudioType.OGGVORBIS);

        sealed class WebRequest : IRequest
        {
            readonly UnityWebRequest request;
            bool aborted, finished;

            public WebRequest(string url, Action<AudioClip?, string?> done, AudioType type)
            {
                request = UnityWebRequestMultimedia.GetAudioClip(url, type);
                request.SendWebRequest().completed += _ => Done(done);
            }

            public ulong Bytes => finished ? 0 : request.downloadedBytes;

            public void Abort() { if (aborted || finished) return; aborted = true; request.Abort(); }

            void Done(Action<AudioClip?, string?> done)
            {
                finished = true;
                AudioClip? c = null; string? error = null;
                if (!aborted)
                {
                    if (request.result != UnityWebRequest.Result.Success) error = request.error;
                    else
                    {
                        try { c = DownloadHandlerAudioClip.GetContent(request); }
                        catch (Exception e) { error = e.Message; }
                        if (c == null && error == null) error = "no clip";
                    }
                }
                request.Dispose();
                if (!aborted) done(c, error);
            }
        }

        /// <summary>An AudioSource on its own GameObject, made at the first Play.</summary>
        public sealed class SourceOutput : IOutput
        {
            GameObject? go; AudioSource? source;

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

            /// <summary>IOutput.Ready's rule for any AudioSource output (MenuMusic's too).</summary>
            internal static bool? ReadyState(AudioClip clip)
            {
                switch (clip.loadState)
                {
                    case AudioDataLoadState.Loaded: return true;
                    case AudioDataLoadState.Failed: return null;
                    case AudioDataLoadState.Unloaded: clip.LoadAudioData(); return false;
                    default: return false;
                }
            }

            public void Play(AudioClip clip)
            {
                if (go == null)
                {
                    go = new GameObject("DeclarationRecording");
                    source = go.AddComponent<AudioSource>();
                    source.playOnAwake = false; source.loop = false; source.spatialBlend = 0f;
                }
                source!.clip = clip;
                source.Play();
            }

            public void Stop() { if (source != null) { source.Stop(); source.clip = null; } }

            public bool IsPlaying => source != null && source.isPlaying;

            public float Position => source != null ? source.time : 0f;

            public AudioSource? Source => source;

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