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.

15.9 KB
Raw Blame
#nullable enable
using System;
using UnityEngine;

namespace Statecraft.Game.Map.Collection
{
    /// <summary>Flies Tal Heuberger's Egyptian Spitfire round its loop (SeaAirCollection.LoopOffset, owner, 2 November 2026:
    /// "Fly a slow loop"), nose along the path, banked into the turns (SeaAirCollection.LoopBankDegrees), its propeller
    /// turning, its shadow on the ground and its side's flag over its tail (owner's report, 2 November 2026: "the gyptian plane's
    /// propelor isn't moving and it doesnt look fliying, also it doesnt show its an egyptian unit"). Presentation only: it
    /// reads the map's animation clock (Time.time, as the steam train and the showcase flight do), sets a few transforms per
    /// frame and allocates nothing. It lives on the aircraft's own object, so it stops when the layer drops the aircraft (its
    /// dates end, or the map is torn down) and does not run while the layer is inactive.
    /// The model is one fused mesh, so the turning propeller is a separate translucent disc at its nose (<see cref="Attach"/>,
    /// SeaAirCollection.Fly). Editor renders and screenshots (`?shot` / `-shot`) hold the loop's start, propeller included, so
    /// they repeat exactly, as the train does (RouteLayer.ModeFor).</summary>
    public sealed class SpitfireLoop : MonoBehaviour
    {
        /// <summary>DESIGN VALUE: the propeller's turn (degrees a second), as ShowcaseFlight turns the unit tokens' propellers:
        /// about 4 turns a second, so its three blurred blades move a sixth of a turn or less between two frames at 30 fps
        /// and never seem to turn backwards.</summary>
        public const float PropDegreesPerSecond = 1500f;

        /// <summary>DESIGN VALUE: the shadow's lift (m) over the highest of the five ground points sampled under it, so the flat
        /// disc lies over the dunes rather than in them.</summary>
        public const float ShadowLiftM = 30f;

        /// <summary>The direction the map's sun shines (MapLighting.Apply), pointing down: the shadow's ray when the scene has
        /// no directional sun, or one under 10 degrees.</summary>
        public static readonly Vector3 SunRay = Quaternion.Euler(MapLighting.SunElevation, MapLighting.SunAzimuth - 180f, 0f) * Vector3.forward;

        /// <summary>The ray the scene's sun casts now (RenderSettings.sun: MapLighting's, or the opt-in hex map's dusk or night
        /// light, HexTimeOfDay), so the shadow lies with the real ones; <see cref="SunRay"/> without one, or with one under
        /// 10 degrees, whose shadow would run off the board.</summary>
        static Vector3 SunNow()
        {
            var sun = RenderSettings.sun;
            if (sun != null && sun.type == LightType.Directional)
            {
                var ray = sun.transform.forward;
                if (ray.y < -0.17f) return ray;
            }
            return SunRay;
        }

        Vector3 centre, offset; Quaternion level; bool still;
        Transform? prop, shadow, flag; Terrain? ground; Vector2 shadowHalf; Vector3 half; float flagHalf, seaY;

        /// <summary>DESIGN VALUE: the gap (m) between the top of the aircraft's tail and the flag's lower edge. 150 m left it
        /// floating detached above the tail in the end turns (e21's captures of #2728, v2, 5 November 2026).</summary>
        public const float FlagClearM = 60f;

        /// <summary>MEASURED from Tal's model (its FBX's vertices, 5 November 2026), for how high the banked tail reaches
        /// (<see cref="TailTopOver"/>). The model sits in its ground attitude, tail down, so its box's top is the propeller's tip
        /// and its bottom the tail wheel. The fin's top stands only 0.19 of the box's half height over the box's centre (0.20,
        /// with a margin). The tailplane reaches 0.273 of the half span out (0.28), its tips 0.414 of the half height under the
        /// centre (0.41). With these the estimate meets the measured tail top within 0.003 of the half height at every bank to
        /// 35 degrees. Taking the whole half height for the fin (as before) put the flag about 600 m too high.</summary>
        public const float TailFinShare = 0.20f, TailplaneReachShare = 0.28f, TailplaneDropShare = 0.41f;

        /// <summary>DESIGN VALUE (agent-chosen, coordinator-agreed, 5 November 2026; checked in captures): the shadow is cast as
        /// if the aircraft flew at this share of its drawn height over the ground under it. The aircraft is drawn 420 times life
        /// size (UnitShowcase.AircraftScale) at UnitShowcase.AltitudeM, so the true ray lays its shadow about 7 km away at
        /// MapLighting's 30 degree sun, too far to read as its shadow; at a quarter it lies about 1.8 km away (half an airframe's length), on
        /// the same sun's line. The Spitfires use it; the Dakotas' shadows keep the full height (1, the default).</summary>
        public const float ShadowHeightShare = 0.25f;

        /// <summary>How far the top of the aircraft's box stands over its centre at <paramref name="bankDegrees"/>: its half box
        /// <paramref name="half"/> (half its length, height and span) rolled about its length.</summary>
        public static float TopOver(Vector3 half, float bankDegrees)
        {
            float b = bankDegrees * Mathf.Deg2Rad;
            return half.z * Mathf.Abs(Mathf.Sin(b)) + half.y * Mathf.Cos(b);
        }

        /// <summary>How far the top of the aircraft's tail stands over its centre at <paramref name="bankDegrees"/>, rolled about
        /// its length: the higher of the fin's top (<see cref="TailFinShare"/> of the half height) and the raised tailplane tip
        /// (<see cref="TailplaneReachShare"/> of the half span out, <see cref="TailplaneDropShare"/> of the half height under the
        /// centre). Far lower than <see cref="TopOver"/>, whose raised wingtip is nowhere near the tail.</summary>
        public static float TailTopOver(Vector3 half, float bankDegrees)
        {
            float b = bankDegrees * Mathf.Deg2Rad, cos = Mathf.Cos(b), sin = Mathf.Abs(Mathf.Sin(b));
            return Mathf.Max(TailFinShare * half.y * cos, TailplaneReachShare * half.z * sin - TailplaneDropShare * half.y * cos);
        }

        /// <summary>The animation clock, Time.time. Test seam (internal; the tests see it through InternalsVisibleTo): an
        /// EditMode test has no frame clock.</summary>
        internal static Func<float> Clock = () => Time.time;

        /// <summary>True when the aircraft holds the loop's start (edit mode, screenshots).</summary>
        public bool Still => still;

        /// <summary>The turning propeller disc (a child of the aircraft's mesh), the shadow and the flag (each in world space,
        /// beside the aircraft), the terrain the shadow lies on, the shadow's half size across and along the heading (m), and
        /// the aircraft's half box at level (half its length, height and span, m), and the sea's surface (world y: the shadow
        /// never lies under it). Before <see cref="Configure"/>, which places them all.</summary>
        internal void Attach(Transform? prop, Transform? shadow, Transform? flag, Terrain? ground, Vector2 shadowHalf, Vector3 airframeHalf = default,
            float seaY = float.NegativeInfinity)
        {
            this.prop = prop; this.shadow = shadow; this.flag = flag; this.ground = ground; this.shadowHalf = shadowHalf; half = airframeHalf; this.seaY = seaY;
            flagHalf = flag != null ? flag.GetComponent<MeshFilter>().sharedMesh.bounds.extents.y : 0f;
        }

        /// <summary><paramref name="centre"/>: the loop's centre in the air. <paramref name="level"/>: the model's rotation
        /// with its nose east. <paramref name="offset"/>: its drawn centre from its pivot at that rotation.</summary>
        internal void Configure(Vector3 centre, Quaternion level, Vector3 offset, bool still)
        {
            this.centre = centre; this.level = level; this.offset = offset; this.still = still;
            // Where the clock puts it now: a component added mid-frame gets no Update that frame (review k2 C1).
            Place(still ? 0f : Clock());
        }

        void Update()
        {
            if (!still) Place(Clock());
        }

        /// <summary>Puts the aircraft where it is <paramref name="seconds"/> into its loop: its drawn centre on the path, its
        /// nose along the path's tangent, rolled into the turn about that tangent; the propeller at its angle then; the flag
        /// over its tail; the shadow where the sun's ray through the drawn centre meets the ground.</summary>
        public void Place(float seconds)
        {
            var at = SeaAirCollection.LoopOffset(seconds); var heading = SeaAirCollection.LoopHeading(seconds);
            var forward = new Vector3(heading.x, 0f, heading.y);
            // A turn about the vertical from east (+x) to the heading; Unity's yaw turns +x toward -z.
            var yaw = Quaternion.Euler(0f, -Mathf.Atan2(heading.y, heading.x) * Mathf.Rad2Deg, 0f);
            // The loop turns left (anticlockwise seen from above): a positive turn about the heading lowers the left wing.
            float bank = SeaAirCollection.LoopBankDegrees(seconds);
            var turn = Quaternion.AngleAxis(bank, forward) * yaw;
            transform.localRotation = turn * level;
            var drawn = centre + new Vector3(at.x, 0f, at.y);
            transform.position = drawn - turn * offset;
            // The angle in double: a float product with the clock loses whole degrees after hours (review of #2260).
            if (prop != null) prop.localRotation = Quaternion.AngleAxis(-(float)((double)seconds * PropDegreesPerSecond % 360.0), Vector3.up);
            // The flag over the tail, its lower edge FlagClearM over the top of the tail at this bank: clear of it at every bank
            // and heading. Not over the box's top: in a bank that is the raised wingtip, and a flag that high was drawn over the
            // cockpit from the map's camera (e21's captures, 5 November 2026).
            if (flag != null) flag.position = drawn - forward * half.x + Vector3.up * (TailTopOver(half, bank) + FlagClearM + flagHalf * flag.lossyScale.y);
            if (shadow != null && ground != null) LayShadow(shadow, ground, seaY, shadowHalf, drawn, forward, bank, heightShare: ShadowHeightShare);
        }

        /// <summary>Lays <paramref name="shadow"/> (half <paramref name="shadowHalf"/> across and along the heading) for an
        /// aircraft drawn at <paramref name="drawn"/>, heading <paramref name="forward"/>, banked <paramref name="bank"/> degrees,
        /// on <paramref name="ground"/> or the sea's surface <paramref name="seaY"/>: the scene sun's ray from the aircraft to the
        /// ground (by default in two steps, the ground's height where the ray lands setting how far it travels); the disc flat, turned
        /// with the heading, narrowed across by the bank, lifted over the highest ground under its middle and its four ends. The
        /// Spitfire's, and the Dakotas' (DakotaLoop, #2482).
        ///
        /// The two steps are a fixed-point guess: each takes the ground's height where the last ray landed. Their miss is the
        /// height left between the last two guesses times the ray's run per metre of fall (cot of the sun's elevation, 1.73 at
        /// MapLighting's 30 degrees), and the guess only closes in where the ground under the ray rises more slowly than the ray
        /// falls (slope x cot(elevation) under 1). That holds on the flat coast by el-Arish where the Spitfire flies, so its
        /// shadow keeps the two steps (the default). The Dakotas over Tel Aviv cast theirs about 8 km east-south-east, up the
        /// rising ground toward the hills, where two steps left it about 200 m off the ray (gate H4 on #2490). With
        /// <paramref name="converge"/> the ray is cut instead by halving: between the aircraft (above the ground) and the point
        /// where the ray falls to the lowest surface there can be (the sea's, or the terrain's base), so the ground is crossed
        /// between them whatever its slope or the sun's height; a march in <see cref="ShadowMarchM"/> steps finds the first
        /// crossing, and each halving halves that step, to under
        /// <see cref="ShadowConvergeM"/> along the ray, at most <see cref="ShadowConvergeSteps"/> halvings. With
        /// <paramref name="heightShare"/> under 1 the ray starts lower, at that share of the aircraft's height over the surface
        /// under it (<see cref="ShadowHeightShare"/>), so the shadow lies nearer on the same line.</summary>
        internal static void LayShadow(Transform shadow, Terrain ground, float seaY, Vector2 shadowHalf, Vector3 drawn, Vector3 forward, float bank,
            bool converge = false, float heightShare = 1f)
        {
            if (heightShare < 1f)
            {
                float under = Surface(ground, seaY, drawn);
                drawn.y = under + heightShare * (drawn.y - under);
            }
            var ray = SunNow();
            var hit = drawn;
            float floor;
            if (converge)
            {
                // At s = 0 the ray is at the aircraft, over the ground; at hi it is at the lowest surface there can be, at or
                // under the ground (Surface is never below the sea's surface or the terrain's base).
                float lo = 0f, hi = (drawn.y - Mathf.Max(seaY, ground.transform.position.y)) / -ray.y;
                // The first crossing, not any: march out in ShadowMarchM steps until the ray is at or under the ground, so a
                // ridge the ray clips puts the shadow on the ridge, not in the valley beyond it (review of #2490).
                for (float s = ShadowMarchM; s < hi; s += ShadowMarchM)
                {
                    var q = drawn + ray * s;
                    if (q.y > Surface(ground, seaY, q)) lo = s; else { hi = s; break; }
                }
                for (int i = 0; i < ShadowConvergeSteps && hi - lo > ShadowConvergeM; i++)
                {
                    float mid = 0.5f * (lo + hi);
                    var q = drawn + ray * mid;
                    if (q.y > Surface(ground, seaY, q)) lo = mid; else hi = mid;
                }
                hit = drawn + ray * hi;
                floor = Surface(ground, seaY, hit);
            }
            else
            {
                floor = Surface(ground, seaY, drawn);
                for (int i = 0; i < 2; i++)
                {
                    hit = drawn + ray * ((drawn.y - floor) / -ray.y);
                    floor = Surface(ground, seaY, hit);
                }
            }
            var across = new Vector3(forward.z, 0f, -forward.x);
            float half = shadowHalf.x * Mathf.Cos(bank * Mathf.Deg2Rad);
            float top = floor;
            top = Mathf.Max(top, Surface(ground, seaY, hit + across * half));
            top = Mathf.Max(top, Surface(ground, seaY, hit - across * half));
            top = Mathf.Max(top, Surface(ground, seaY, hit + forward * shadowHalf.y));
            top = Mathf.Max(top, Surface(ground, seaY, hit - forward * shadowHalf.y));
            shadow.SetPositionAndRotation(new Vector3(hit.x, top + ShadowLiftM, hit.z), Quaternion.LookRotation(forward, Vector3.up));
            shadow.localScale = new Vector3(half, 1f, shadowHalf.y);
        }

        /// <summary>The converging shadow's halvings (<see cref="LayShadow"/>): stop once the bracket along the ray is under
        /// <see cref="ShadowConvergeM"/> (m), and after <see cref="ShadowConvergeSteps"/> at most. From 4,200 m at a 30 degree
        /// sun the bracket starts under 10 km; the march (<see cref="ShadowMarchM"/>) leaves one step of it, so about 8 halvings.</summary>
        internal const float ShadowConvergeM = 1f, ShadowMarchM = 200f;
        internal const int ShadowConvergeSteps = 24;

        /// <summary>The ground's height under <paramref name="p"/>, or the sea's surface over the sea.</summary>
        static float Surface(Terrain ground, float seaY, Vector3 p) => Mathf.Max(ground.SampleHeight(p) + ground.transform.position.y, seaY);
    }
}