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.

19.0 KB
Raw Blame
#nullable enable
using System;
using System.Collections.Generic;
using Statecraft.Sim;

namespace Statecraft.Game.Map.Units
{
    /// <summary>Where an anchor's token stands: its hex, its centre on the ground plane (metres), whether it is drawn
    /// compact (a smaller ring and a tighter trio, to fit beside a town) and whether it stands in a town (the kits then
    /// keep a clearing for it).</summary>
    public readonly struct AnchorSpot : IEquatable<AnchorSpot>
    {
        public readonly int Q, R; public readonly double X, Z; public readonly bool Compact, InTown;
        public AnchorSpot(int q, int r, double x, double z, bool compact, bool inTown = false) { Q = q; R = r; X = x; Z = z; Compact = compact; InTown = inTown; }
        public bool Equals(AnchorSpot o) => Q == o.Q && R == o.R && X == o.X && Z == o.Z && Compact == o.Compact && InTown == o.InTown;
        public override bool Equals(object? o) => o is AnchorSpot s && Equals(s);
        public override int GetHashCode() => HashCode.Combine(Q, R, X, Z, Compact, InTown);
        public override string ToString() => $"({Q},{R}){(Compact ? " compact" : "")}{(InTown ? " in town" : "")}";
    }

    /// <summary>A token with its spot.</summary>
    public readonly struct PlacedToken : IEquatable<PlacedToken>
    {
        public readonly UnitToken Token; public readonly AnchorSpot Spot;
        public PlacedToken(UnitToken token, AnchorSpot spot) { Token = token; Spot = spot; }
        public int Q => Spot.Q;
        public int R => Spot.R;
        public bool Equals(PlacedToken o) => Token.Equals(o.Token) && Spot.Equals(o.Spot);
        public override bool Equals(object? o) => o is PlacedToken p && Equals(p);
        public override int GetHashCode() => HashCode.Combine(Token, Spot);
        public override string ToString() => $"{Token} {Spot}";
    }

    /// <summary>Puts every anchor of the unit data on one spot, once, from the data alone (review M9: a token never moves
    /// because another unit appears). The spot lies within one hex step of the anchor point (review I2: about 7.6 km
    /// between hex centres on 4.4 km hexes) and is the nearest to it, or, when the anchor has a sourced `toward` point on
    /// the unit's own side (review MF1), the nearest to that, among the following; an anchor with a sourced `place_hex`
    /// considers only that hex:
    /// 1. the centres of the anchor's own hex and its six neighbours, drawn full size;
    /// 2. then, when none is clear, those centres and eighteen points inside each hex (six on each of
    ///    <see cref="InsideOffsets"/> of the hex circumradius), and rings round a `toward` point, drawn compact;
    /// 3. then, when the anchor's whole neighbourhood is town (Tel Aviv), the same compact points with the ring allowed
    ///    into the town: the one that reaches least deep into it (then the nearest; with a `toward` point, simply the nearest
    ///    to it) is taken, and the kits keep a clearing for it (MapScene), so the token never stands in a building;
    /// 4. then, when none of those is clear, the anchor's point and rings round it every <see cref="MeshStepM"/> out to the
    ///    one-hex limit, about <see cref="MeshStepM"/> apart on each ring, drawn compact and off the towns as in round 2: on
    ///    4.4 km hexes (#1183) the points above lie 1.1 to 2.9 km apart and can all miss the clear ground between villages
    ///    (Majdal, the Egyptian rear base, whose nearest clear ground lies 3.5 km south-west of its point, west of Ni'ilya). It
    ///    runs last, so an anchor that found a spot in rounds 1-3 keeps it; a spot it finds holds its hex like any other.
    ///    Ranked as above (by distance to a `toward` point when the anchor has one).
    /// A ship tries rounds 1 and 2 only, and its spot is never compact (it is drawn at its one size; issue #3038).
    /// A spot must be land (sea for a ship), on a hex no other anchor with an overlapping window holds, and clear (the
    /// caller's test: the ring off the settlement footprints except in round 3, the figures on land and off the railways
    /// and roads). An anchor with no such spot is left out and reported. The map holds no 1948 front line yet: where the
    /// nearest spot would be the other side's ground, the anchor's sourced `toward` point keeps the token on its own side
    /// (docs/units.md). Where the caller passes the control layer (<paramref name="otherSide"/> of PlaceAll), an Arab force's
    /// spot also keeps off the hexes Israel held on the anchor's first day (#226, ruling 9): on 4.4 km hexes (#1183) the
    /// nearest clear centre to Isdud, the Egyptian forward base, was the Israeli-held hex east of it. Anchors are placed in
    /// the data's order.</summary>
    public static class UnitPlacer
    {
        /// <summary>Hexes from the anchor's own hex (axial distance).</summary>
        public const int MaxShift = 1;
        /// <summary>The inside points' distances from a hex centre, as fractions of the circumradius (all inside the
        /// inradius, 0.87): six points on each ring.</summary>
        public static readonly double[] InsideOffsets = { 0.25, 0.45, 0.65 };

        /// <param name="toXZ">lon, lat to the map's ground plane (metres).</param>
        /// <param name="clear">(service, x, z, compact, inTown, anchor x, anchor z): true when a token of that service may
        /// stand there.</param>
        /// <param name="townOverlap">(x, z): how deep (m) a compact token there reaches into a town (round 3's ranking).</param>
        /// <param name="taken">Hexes other tokens already hold for good (a moved unit's spot keeps off the drawn tokens'
        /// hexes, UnitLayer); null: none.</param>
        /// <param name="otherSide">(unit, anchor, hex): true when the hex is the other side's ground for that unit on the
        /// anchor's first day, so no spot is taken there; null: no control layer.</param>
        public static Dictionary<UnitAnchor, AnchorSpot> PlaceAll(IReadOnlyList<UnitEntry> units, IReadOnlyList<MapHex> hexes, double hexSizeM,
            Func<double, double, (double x, double z)> toXZ, Func<string, double, double, bool, bool, double, double, bool> clear,
            Func<double, double, double> townOverlap, Action<string>? skipped = null, IEnumerable<(int q, int r)>? taken = null,
            Func<UnitEntry, UnitAnchor, MapHex, bool>? otherSide = null)
        {
            if (units == null) throw new ArgumentNullException(nameof(units));
            if (hexes == null || hexes.Count == 0) throw new ArgumentException("no hexes", nameof(hexes));
            var centres = new (double x, double z)[hexes.Count];
            for (int i = 0; i < hexes.Count; i++) centres[i] = toXZ(hexes[i].Lon, hexes[i].Lat);
            double maxOffset = Math.Sqrt(3.0) * hexSizeM + 1.0;   // one hex step (plus a metre of rounding)
            var held = new List<(int q, int r, DateTime from, DateTime to)>();
            if (taken != null) foreach (var (q, r) in taken) held.Add((q, r, DateTime.MinValue, DateTime.MaxValue));
            var result = new Dictionary<UnitAnchor, AnchorSpot>();
            foreach (var u in units)
            {
                if (!UnitRoster.OnMap(u)) continue;
                bool sea = u.Service == UnitData.Navy;
                foreach (var a in u.Anchors)
                {
                    var p = toXZ(a.Lon, a.Lat);
                    // A sourced point on the unit's own side, when the anchor has one: spots are ranked by distance to it.
                    var target = a.Toward != null ? toXZ(a.Toward.Lon, a.Toward.Lat) : p;
                    DateTime from = UnitData.Day(a.From), to = UnitData.Day(a.To);
                    int home = Nearest(centres, p);
                    var (hq, hr) = (hexes[home].Q, hexes[home].R);
                    // The hexes within the one-hex limit, in list order: the only ones whose points can pass the test below,
                    // so the others' candidate points are never made (issue #321: boot time; UnitPlacerSpeedTests).
                    var near = new List<int>();
                    for (int i = 0; i < hexes.Count; i++) if (MapActions.Distance(hexes[i].Q, hexes[i].R, hq, hr) <= MaxShift) near.Add(i);
                    AnchorSpot? best = null;
                    foreach (var round in new[] { 1, 2, 3, 4 })
                    {
                        // A ship tries its sea hexes' centres, then the points inside them (issue #3038: a centre can stand
                        // on a headland, and the hull must lie wholly in the water); never a town or the mesh.
                        if (sea && round > 2) break;
                        bool compact = round > 1, inTown = round == 3;
                        double bestD = double.MaxValue, bestDepth = double.MaxValue;
                        var points = round == 4 ? Mesh(centres, p, maxOffset)
                            : Candidates(near, centres, hexSizeM, compact, a.Toward != null ? target : ((double, double)?)null);
                        foreach (var (i, x, z) in points)
                        {
                            var h = hexes[i];
                            if (h.Land == sea || MapActions.Distance(h.Q, h.R, hq, hr) > MaxShift) continue;
                            if (a.PlaceHex != null && (h.Q != a.PlaceHex[0] || h.R != a.PlaceHex[1])) continue;
                            if (otherSide != null && otherSide(u, a, h)) continue;
                            if (held.Exists(c => c.q == h.Q && c.r == h.R && c.from < to && from < c.to)) continue;
                            if (Math.Sqrt((x - p.x) * (x - p.x) + (z - p.z) * (z - p.z)) > maxOffset) continue;
                            double d = Math.Sqrt((x - target.x) * (x - target.x) + (z - target.z) * (z - target.z));
                            // Round 3 ranks by depth into the town first (rounded to a metre), then by distance; with a
                            // sourced own-side point it ranks by distance to that alone (the town edge may be the other side's).
                            double overlap = inTown ? Math.Max(0.0, townOverlap(x, z)) : 0.0;
                            double depth = a.Toward == null ? Math.Round(overlap) : 0.0;
                            if (depth > bestDepth || (depth == bestDepth && d > bestD)) continue;
                            // Ties go to the lower (q, r): the result never depends on the hex list's order.
                            if (depth == bestDepth && d == bestD && best != null && (h.Q, h.R).CompareTo((best.Value.Q, best.Value.R)) > 0) continue;
                            if (!clear(u.Service, x, z, compact, inTown, p.x, p.z)) continue;
                            // A ship is drawn at its one size wherever it stands, so its spot is never compact.
                            best = new AnchorSpot(h.Q, h.R, x, z, compact && !sea, inTown && overlap > 0); bestD = d; bestDepth = depth;
                        }
                        if (best != null) break;
                    }
                    if (best == null) { skipped?.Invoke(SkipMessage(u, a)); continue; }
                    held.Add((best.Value.Q, best.Value.R, from, to));
                    result[a] = best.Value;
                }
            }
            return result;
        }

        /// <summary>The message for an anchor PlaceAll found no clear spot for.</summary>
        public static string SkipMessage(UnitEntry u, UnitAnchor a) => $"UNITS no clear spot within one hex of {a.Place} for {u.Id}";

        /// <summary>PlaceAll's skip messages for a placement it made of <paramref name="units"/>: one for every anchor of a
        /// drawn unit with no spot, in its order (issue #321: the units layer reports the map's skips when it takes its spots).</summary>
        public static List<string> SkipMessages(IReadOnlyList<UnitEntry> units, IReadOnlyDictionary<UnitAnchor, AnchorSpot> spots)
        {
            var list = new List<string>();
            foreach (var u in units)
            {
                if (!UnitRoster.OnMap(u)) continue;
                foreach (var a in u.Anchors) if (!spots.ContainsKey(a)) list.Add(SkipMessage(u, a));
            }
            return list;
        }

        /// <summary>Within the one-hex limit around a `toward` point (every round): rings every
        /// <see cref="TowardStepM"/> out to <see cref="TowardReachM"/>, twelve points each, so a spot can sit between a
        /// town's roads near the sourced place, not only on the hex grid's points.</summary>
        public const double TowardStepM = 500.0, TowardReachM = 2500.0;

        /// <summary>The round's candidate spots, each with the index of the hex it lies in: the centre of every hex in
        /// <paramref name="hexIndices"/> (in that order), and for a compact round the points inside each; and in every round
        /// the rings round the `toward` point (each with its nearest hex, whichever it is).</summary>
        static IEnumerable<(int i, double x, double z)> Candidates(IReadOnlyList<int> hexIndices, (double x, double z)[] centres, double hexSizeM,
            bool compact, (double x, double z)? toward)
        {
            foreach (var i in hexIndices)
            {
                yield return (i, centres[i].x, centres[i].z);
                if (!compact) continue;
                for (int k = 0; k < 6 * InsideOffsets.Length; k++) { var (x, z) = Inside(centres[i], k, hexSizeM); yield return (i, x, z); }
            }
            if (toward == null) yield break;   // the rings round a `toward` point are tried in every round
            var t = toward.Value;
            for (double rad = 0; rad <= TowardReachM; rad += TowardStepM)
                for (int k = 0; k < (rad == 0 ? 1 : 12); k++)
                {
                    double x = t.x + Math.Cos(Math.PI / 6.0 * k) * rad, z = t.z + Math.Sin(Math.PI / 6.0 * k) * rad;
                    yield return (Nearest(centres, (x, z)), x, z);
                }
        }

        /// <summary>Round 4's spacing (m): between its rings, and at most between two points on a ring. Its own constant, not
        /// <see cref="TowardStepM"/>: the `toward` rings keep twelve points a ring, this mesh keeps the spacing.</summary>
        public const double MeshStepM = 500.0;

        /// <summary>Round 4's candidate spots, each with its nearest hex: the anchor's point <paramref name="p"/>, then rings
        /// round it every <see cref="MeshStepM"/> out to <paramref name="reach"/>, each with as many points as keep them at
        /// most <see cref="MeshStepM"/> apart.</summary>
        static IEnumerable<(int i, double x, double z)> Mesh((double x, double z)[] centres, (double x, double z) p, double reach)
        {
            yield return (Nearest(centres, p), p.x, p.z);
            for (double rad = MeshStepM; rad <= reach; rad += MeshStepM)
            {
                int n = (int)Math.Ceiling(2.0 * Math.PI * rad / MeshStepM);
                for (int k = 0; k < n; k++)
                {
                    double x = p.x + Math.Cos(2.0 * Math.PI * k / n) * rad, z = p.z + Math.Sin(2.0 * Math.PI * k / n) * rad;
                    yield return (Nearest(centres, (x, z)), x, z);
                }
            }
        }

        /// <summary>The spot for a sim unit's anchor that <see cref="PlaceAll"/> found no clear spot for. Every unit the sim has
        /// must be drawn: End turn selects the units that need orders, and a unit with no token could be neither seen nor
        /// selected, so the turn could not end (owner, v0.3.0 RC, 25 October 2026: "the game is saying "a unit needs orders"
        /// but clicking on it does nothing and i cant find any unit that needs orders"). The spot is compact, on the unit's own
        /// sim hex (q, r): of the hex's centre and the points inside it (the outer ring first, so a crowded hex spreads out),
        /// the first whose distance to every spot in <paramref name="used"/> is at least <paramref name="gapM"/> and that is
        /// <paramref name="clear"/>; else the first at least <paramref name="gapM"/> from them; else the one farthest from
        /// them. Deterministic: the same inputs give the same spot.</summary>
        /// <param name="centre">The hex centre on the ground plane (metres).</param>
        /// <param name="used">The centres of the spots drawn tokens stand on now.</param>
        /// <param name="gapM">The least distance between two tokens' centres (UnitLayer: one and a half compact ring radii, so
        /// the rings may touch but the trios and badges stand apart; the hex's centre and its outer ring hold seven).</param>
        /// <param name="clear">(x, z): true when a compact token may stand there (off towns, roads and water).</param>
        public static AnchorSpot OnOwnHex(int q, int r, (double x, double z) centre, double hexSizeM, IReadOnlyCollection<(double x, double z)> used,
            double gapM, Func<double, double, bool> clear)
        {
            if (used == null) throw new ArgumentNullException(nameof(used));
            if (clear == null) throw new ArgumentNullException(nameof(clear));
            var points = new List<(double x, double z)> { centre };
            for (int ring = InsideOffsets.Length - 1; ring >= 0; ring--)
                for (int k = 0; k < 6; k++) points.Add(Inside(centre, ring * 6 + k, hexSizeM));
            double Room((double x, double z) p)
            {
                double d = double.MaxValue;
                foreach (var u in used) d = Math.Min(d, Math.Sqrt((u.x - p.x) * (u.x - p.x) + (u.z - p.z) * (u.z - p.z)));
                return d;
            }
            (double x, double z)? apart = null, roomiest = null; double most = -1;
            foreach (var p in points)
            {
                double room = Room(p);
                if (room >= gapM)
                {
                    if (clear(p.x, p.z)) return new AnchorSpot(q, r, p.x, p.z, compact: true);
                    if (apart == null) apart = p;
                }
                if (room > most) { most = room; roomiest = p; }
            }
            var best = apart ?? roomiest!.Value;
            return new AnchorSpot(q, r, best.x, best.z, compact: true);
        }

        /// <summary>The tokens on their anchors' spots; a token whose anchor has no spot is left out.</summary>
        public static List<PlacedToken> Place(IReadOnlyList<UnitToken> tokens, IReadOnlyDictionary<UnitAnchor, AnchorSpot> spots)
        {
            var list = new List<PlacedToken>(tokens.Count);
            foreach (var t in tokens) if (spots.TryGetValue(t.Anchor, out var s)) list.Add(new PlacedToken(t, s));
            return list;
        }

        static (double x, double z) Inside((double x, double z) c, int k, double hexSizeM)
        {
            double ang = Math.PI / 3.0 * (k % 6), off = InsideOffsets[k / 6] * hexSizeM;
            return (c.x + Math.Cos(ang) * off, c.z + Math.Sin(ang) * off);
        }

        static int Nearest((double x, double z)[] centres, (double x, double z) p)
        {
            int best = 0; double bestD = double.MaxValue;
            for (int i = 0; i < centres.Length; i++)
            {
                double d = (centres[i].x - p.x) * (centres[i].x - p.x) + (centres[i].z - p.z) * (centres[i].z - p.z);
                if (d < bestD) { bestD = d; best = i; }
            }
            return best;
        }
    }
}