A Civilization-style strategy game about governing Israel from 15 May 1948. Real ministers, real map, every fact sourced. Unity + deterministic C# sim.
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
using YamlDotNet.Core;
using YamlDotNet.Serialization;
namespace Statecraft.Sim
{
/// <summary>One unit a Historical game starts with (R-UNIT-006): the units_1948.yaml row it comes from, the anchor it
/// stands at, its type, side and strength in population units, and the anchor's hex.</summary>
public sealed class StartingForce
{
public string Row { get; set; } = "";
/// <summary>Player-facing names from the same units_1948.yaml row, used when a sim report names a required brigade.</summary>
public string Name { get; set; } = "";
/// <summary>The anchor's place, as the row names it.</summary>
public string Anchor { get; set; } = "";
public string Type { get; set; } = "";
public string Side { get; set; } = "";
public int Strength { get; set; }
public int Q { get; set; }
public int R { get; set; }
/// <summary>The row's review status (draft, to_verify, fact-checked); the release gate reads it (Q-START-3).</summary>
public string Status { get; set; } = "";
/// <summary>A fact-checked row's `checked_on`, the day of its person check ('YYYY-MM-DD'); empty for any other row.
/// The release gate counts a field sourced after it as unchecked (#2722).</summary>
public string CheckedOn { get; set; } = "";
/// <summary>The latest `checked` day among the sources of the row's strength, each anchor and each order target, in
/// the file's order, with the field's name (#2722): "strength", "anchors[k] (place)", "order_targets[k] (place)".</summary>
public List<(string Field, string Checked)> SourcesChecked { get; } = new List<(string Field, string Checked)>();
/// <summary>R-UNIT-009 (#1241): the day a row dated after the start arrives (its strength's as_of), or null for a row
/// that starts the game. Its unit's id is reserved at the start and the resolver adds it on that day's turn.</summary>
public DateTime? Arrives { get; set; }
/// <summary>The enemy AI's script (R-ENEMY-002; Q-ENEMY-1; #1270): the hex and window end (`to`) of each of the row's
/// anchors from 11 June 1948 on two sources, in the file's order. Empty when the row has none.</summary>
public List<(int Q, int R, DateTime Until)> Script { get; } = new List<(int Q, int R, DateTime Until)>();
}
/// <summary>The sourced starting forces, both sides (GDD Phase 5 PR 4; docs/rules/mvp.md R-UNIT-006, R-UNIT-007).
/// The sim reads map/units_1948.yaml (Q-START-1, owner, 15 October 2026), so the file is in the content hash. Only the
/// keys the start needs are read, untyped, as for settlements_1948.yaml: the map's reader (Unity's UnitData) and
/// tools/tests/test_units_1948.py own the rest of the row.</summary>
public static class StartingForces
{
public const string FileName = "map/units_1948.yaml";
/// <summary>Each anchor's hex, written by tools/unit_anchor_hexes.py with the map's projection and rounding
/// (tools/hexgrid.py, Unity's HexPicker), so the sim needs no trigonometry (docs/determinism.md).</summary>
public const string HexesFileName = "map/unit_anchor_hexes.yaml";
/// <summary>Every IDF brigade starts as a veteran soldier (#743, owner, 20 October 2026).</summary>
public const string IsraeliBrigadeType = "veteran_soldier";
/// <summary>The starting forces in the file's order (R-UNIT-006): every row that is not hidden, is an army row (the
/// squadron and the ships stay tokens, Q-UNIT-5), has a strength for the start day and an anchor window
/// [from, to) covering it. The first such anchor places the unit on its hex in unit_anchor_hexes.yaml (the hex holding
/// its coordinates, precomputed by tools/unit_anchor_hexes.py). Strength is the row's people in population units,
/// the nearest unit with a half up and at least 1 (#743). A row it cannot place is a load error.</summary>
internal static List<StartingForce> Read(Func<string, string?> readFile, Content c)
{
var rows = Rows(readFile, FileName, "units");
var hexes = Hexes(readFile, rows, "anchors", "anchor");
c.UnitAnchorHexes = hexes; // R-ENEMY-005: the operation cards' orders name these
foreach (var row in rows) // and end with their windows; EventRules refuses an order to an anchor with no end
if (row != null && row.TryGetValue("anchors", out var ao) && ao is List<object> windows)
for (int k = 0; k < windows.Count; k++)
if (windows[k] is Dictionary<object, object> a && DateTime.TryParseExact(Text(a, "to"), "yyyy-MM-dd", CultureInfo.InvariantCulture, DateTimeStyles.None, out var to))
c.UnitAnchorEnds[(Text(row, "id"), k)] = to;
OrderTargets(c, rows, Hexes(readFile, rows, "order_targets", "target"));
var start = c.Rules.Start.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture);
var ppu = c.RulesAt(c.Rules.Start).Mvp!.PeoplePerUnit; // the start day's rules, as Cities.Init reads them
var list = new List<StartingForce>();
var arrivals = new List<StartingForce>(); // R-UNIT-009: after every starting row, so unit i is still row i
for (int i = 0; i < rows.Count; i++)
{
var row = rows[i] ?? throw new ContentException(FileName, $"units[{i}]", "empty row");
var id = Text(row, "id");
if (id == "") throw new ContentException(FileName, $"units[{i}].id", "required");
var at = $"units[{id}]";
// #2722: a fact-checked row records the day of its person check, so a field sourced later can be told apart.
if (Text(row, "status") == "fact-checked"
&& !DateTime.TryParseExact(Text(row, "checked_on"), "yyyy-MM-dd", CultureInfo.InvariantCulture, DateTimeStyles.None, out _))
throw new ContentException(FileName, $"{at}.checked_on", "required on a fact-checked row, the day of its person check 'YYYY-MM-DD'");
if (row.ContainsKey("hidden") || Text(row, "service") != "army") continue;
if (!(row.TryGetValue("strength", out var so) && so is Dictionary<object, object> strength)) continue;
// R-UNIT-009: a strength dated after the start is the row's arrival day; one dated before starts nothing.
var day = Text(strength, "as_of");
if (!DateTime.TryParseExact(day, "yyyy-MM-dd", CultureInfo.InvariantCulture, DateTimeStyles.None, out var asOf))
throw new ContentException(FileName, $"{at}.strength.as_of", "required, a date 'YYYY-MM-DD'");
if (asOf < c.Rules.Start) continue;
if (!(row.TryGetValue("anchors", out var ao) && ao is List<object> anchors)) continue;
int k = anchors.FindIndex(a => a is Dictionary<object, object> m
&& string.CompareOrdinal(Text(m, "from"), day) <= 0 && string.CompareOrdinal(day, Text(m, "to")) < 0);
if (k < 0) continue;
var anchor = (Dictionary<object, object>)anchors[k];
var side = Text(row, "side");
var people = Number(strength, "value", $"{at}.strength.value");
if (people < 1 || people != decimal.Truncate(people)) throw new ContentException(FileName, $"{at}.strength.value", "must be a whole number >= 1");
var units = Cities.StartUnits(people, ppu); // the nearest unit, a half up, at least 1 (people is >= 1 here)
if (asOf > c.Rules.Start && side != Movement.PlayerSide)
throw new ContentException(FileName, $"{at}.strength.as_of", "an enemy-side force may not arrive after the game starts (R-ENEMY-004)");
if (!hexes.TryGetValue((id, k), out var qr))
throw new ContentException(HexesFileName, "anchors", $"no hex for {at}.anchors[{k}] ({FileName}); rerun tools/unit_anchor_hexes.py");
var (q, r) = qr;
var hex = c.HexAt(q, r);
if (hex == null) throw new ContentException(FileName, $"{at}.anchors[{k}]", FormattableString.Invariant($"hex q={q} r={r} is not on the map ({ContentLoader.HexesFile})"));
if (!hex.Land) throw new ContentException(FileName, $"{at}.anchors[{k}]", FormattableString.Invariant($"hex q={q} r={r} is not a land hex in {ContentLoader.HexesFile}"));
var force = new StartingForce
{
Row = id, Name = Text(row, "name"), Anchor = Text(anchor, "place"), Type = TypeFor(c, side, at), Side = side,
Strength = units, Q = q, R = r, Status = Text(row, "status"), Arrives = day == start ? (DateTime?)null : asOf,
CheckedOn = Text(row, "checked_on"),
};
force.SourcesChecked.Add(("strength", LatestCheck(strength)));
for (int j = 0; j < anchors.Count; j++)
if (anchors[j] is Dictionary<object, object> a) force.SourcesChecked.Add((FormattableString.Invariant($"anchors[{j}] ({Text(a, "place")})"), LatestCheck(a)));
if (row.TryGetValue("order_targets", out var oo) && oo is List<object> targets)
for (int j = 0; j < targets.Count; j++)
if (targets[j] is Dictionary<object, object> t) force.SourcesChecked.Add((FormattableString.Invariant($"order_targets[{j}] ({Text(t, "place")})"), LatestCheck(t)));
if (side != Movement.PlayerSide) Script(c, force, anchors, id, at, hexes);
(day == start ? list : arrivals).Add(force);
}
list.AddRange(arrivals);
return list;
}
/// <summary>R-ENEMY-002 (Q-ENEMY-1: the 15 May and 11 June 1948 positions two sources agree on, arab-forces-1948.md
/// section 10; #1270 past 8 July 1948). The 15 May position is the start; the script is every anchor of the row from
/// 11 June that cites at least two sources other than Wikipedia and Wikidata (which the file uses for coordinates
/// only), on that anchor's hex, in the file's order. A row with none has no script and its unit follows the goals.</summary>
static void Script(Content c, StartingForce force, List<object> anchors, string id, string at,
Dictionary<(string id, int anchor), (int q, int r)> hexes)
{
for (int j = 0; j < anchors.Count; j++)
{
if (!(anchors[j] is Dictionary<object, object> a) || string.CompareOrdinal(Text(a, "from"), EnemyAI.ScriptDate) < 0) continue;
// Distinct URLs, so one source listed twice counts once; hosts are case-insensitive, so EN.WIKIPEDIA.ORG is Wikipedia.
var sourced = a.TryGetValue("sources", out var so) && so is List<object> sources ? sources
.Select(x => x is Dictionary<object, object> m ? Text(m, "url") : "")
.Where(url => url != "" && !url.Contains("wikipedia.org", StringComparison.OrdinalIgnoreCase)
&& !url.Contains("wikidata.org", StringComparison.OrdinalIgnoreCase))
.Distinct(StringComparer.Ordinal).Count() : 0;
if (sourced < 2) continue;
if (!hexes.TryGetValue((id, j), out var qr))
throw new ContentException(HexesFileName, "anchors", $"no hex for {at}.anchors[{j}] ({FileName}); rerun tools/unit_anchor_hexes.py");
if (!(c.HexAt(qr.q, qr.r) is MapHex hex) || !hex.Land)
throw new ContentException(FileName, $"{at}.anchors[{j}]", FormattableString.Invariant($"hex q={qr.q} r={qr.r} is not a land hex in {ContentLoader.HexesFile}"));
if (!DateTime.TryParseExact(Text(a, "to"), "yyyy-MM-dd", CultureInfo.InvariantCulture, DateTimeStyles.None, out var until))
throw new ContentException(FileName, $"{at}.anchors[{j}].to", "required, a date 'YYYY-MM-DD'");
force.Script.Add((qr.q, qr.r, until));
}
}
/// <summary>Adds the starting forces to a new game, in the content's order, taking the next ids: the unit with id i
/// of a new game is <c>c.StartingForces[i]</c>. An arriving row's id is taken too, so it is free when it arrives
/// (R-UNIT-009). With an initialized gdd-0.3 ledger (the dark start, #1725 PR 5), each own starting formation's
/// strength must be its active-soldier records serving in it (R-POP-004), or nothing is added. Any other initialized
/// ledger (synthetic or Open) is refused, with nothing added (R-POP-002).</summary>
public static void Init(Content c, GameState s)
{
if (s.PopulationLedger.IsInitialized) { PopulationLedger.RefuseUnlessHistorical(s); RequireLedgerSoldiers(c, s); }
foreach (var f in c.StartingForces)
{
var id = s.NextId++;
if (f.Arrives == null) s.Units.Add(id, new Unit(id, f.Type, f.Q, f.R, side: f.Side, strength: f.Strength));
}
}
/// <summary>R-POP-004: an own formation in the start inventory gives its strength as active soldiers whose service
/// target is its source key (HistoricalPopulation.FormationPrefix plus its row), so the formations the game places and
/// the ledger's soldiers are the same people.</summary>
static void RequireLedgerSoldiers(Content c, GameState s)
{
var serving = s.PopulationLedger.Units.Where(p => p.Status == PopulationStatus.ActiveSoldier && p.Assignment.Target != null)
.GroupBy(p => p.Assignment.Target!, StringComparer.Ordinal).ToDictionary(g => g.Key, g => g.Count(), StringComparer.Ordinal);
foreach (var f in HistoricalPopulation.OpeningFormations(c))
{
var key = HistoricalPopulation.FormationPrefix + f.Row;
if ((serving.TryGetValue(key, out var n) ? n : 0) != f.Strength)
throw new InvalidOperationException($"Starting formation '{f.Row}' has strength {f.Strength} but the population ledger serves it with {n} (R-POP-004).");
}
}
/// <summary>R-UNIT-009 (#1241, owner, 21 October 2026, answer 1(a)): resolver step 9b. A row dated after the start
/// arrives in the resolution of the turn from s.Date to <paramref name="next"/> that reaches its day, once, as unit
/// <c>c.StartingForces[i]</c>'s id i, on its anchor's hex with its strength. Like a starting force it ignores the stack
/// limit and what else stands on the hex.
/// With an initialized Historical ledger (#1725 PR 7, producer 08) the brigade also brings its strength as new
/// active-soldier records serving in it (<see cref="HistoricalPopulation.ArrivalRows"/>; owner, 8 November 2026:
/// "Soldiers of brigade (Recommended)", "New people (Recommended)"), registered all or nothing before its unit is added.
/// A brigade whose records are already registered adds nothing, so a replay of the turn adds nobody twice (coordinator
/// call, 8 November 2026, Q7 (a)); its records are registered together, so its first ordinal marks the arrival. A
/// synthetic or Open ledger is still refused (R-POP-002).</summary>
public static void Arrive(Content c, GameState s, DateTime next)
{
PopulationLedger.RefuseUnlessHistorical(s); // #1725 PR 7: a Historical ledger's records are then the soldiers
bool Due(StartingForce f) => f.Arrives is DateTime day && s.Date < day && day <= next;
// Every due force is checked before any is added, so a refusal leaves the state unchanged.
foreach (var f in c.StartingForces)
if (Due(f) && f.Side != Movement.PlayerSide)
throw new InvalidOperationException($"Enemy-side starting force '{f.Row}' may not arrive after the game starts (R-ENEMY-004)");
var ledger = s.PopulationLedger.IsInitialized ? s.PopulationLedger : null;
var arriving = new List<int>();
var rows = new List<PopulationInventoryRow>();
for (int i = 0; i < c.StartingForces.Count; i++)
{
var f = c.StartingForces[i];
if (!Due(f)) continue;
if (ledger != null)
{
if (ledger.HasArrived(HistoricalPopulation.FormationPrefix + f.Row, 0)) continue;
rows.AddRange(HistoricalPopulation.ArrivalRows(c, f));
}
arriving.Add(i);
}
// All or nothing: an id already taken would refuse at Add, so it is refused before the records are registered.
foreach (var i in arriving)
if (s.Units.ContainsKey(i))
throw new InvalidOperationException($"Unit {i} of starting force '{c.StartingForces[i].Row}' is already in the game (R-UNIT-009)");
if (ledger != null && rows.Count > 0) ledger.RegisterArrivals(rows);
foreach (var i in arriving)
{
var f = c.StartingForces[i];
s.Units.Add(i, new Unit(i, f.Type, f.Q, f.R, side: f.Side, strength: f.Strength));
}
}
/// <summary>A starting row's unit type: Israel's brigade type, or the one military type of the row's side (one
/// labelled design-value infantry type per Arab side with a row; #743, owner, 20 October 2026).</summary>
static string TypeFor(Content c, string side, string at)
{
var types = side == "israel"
? c.UnitTypes.Where(t => t.Id == IsraeliBrigadeType && t.Side == side).ToList()
: c.UnitTypes.Where(t => t.Side == side && side != "").ToList();
if (types.Count != 1)
throw new ContentException(FileName, at + ".side", types.Count == 0
? $"no military type of side '{side}' in unit_types.yaml" + (side == "israel" ? $" (the brigades start as {IsraeliBrigadeType})" : "")
: $"side '{side}' has several military types in unit_types.yaml ({string.Join(", ", types.Select(t => t.Id))}); a starting row needs one");
return types[0].Id;
}
/// <summary>R-ENEMY-005 (owner, 2 November 2026, #2087, option 1): each row's `order_targets`, where an operation card may
/// send its unit, with the hex tools/unit_anchor_hexes.py gives it and the `to` that ends the card's order. Never a
/// start and never drawn, but sourced and dated as an anchor: one with no sources or no from/to date is a load error.</summary>
static void OrderTargets(Content c, List<Dictionary<object, object>> rows, Dictionary<(string id, int anchor), (int q, int r)> hexes)
{
foreach (var row in rows)
{
if (row == null || !(row.TryGetValue("order_targets", out var to) && to is List<object> targets)) continue;
var id = Text(row, "id");
for (int k = 0; k < targets.Count; k++)
{
var at = FormattableString.Invariant($"units[{id}].order_targets[{k}]");
if (!(targets[k] is Dictionary<object, object> t)) throw new ContentException(FileName, at, "empty order target");
if (!(t.TryGetValue("sources", out var so) && so is List<object> sources && sources.Count > 0))
throw new ContentException(FileName, at + ".sources", "required, at least one source");
if (!DateTime.TryParseExact(Text(t, "from"), "yyyy-MM-dd", CultureInfo.InvariantCulture, DateTimeStyles.None, out _))
throw new ContentException(FileName, at + ".from", "required, a date 'YYYY-MM-DD'");
if (!DateTime.TryParseExact(Text(t, "to"), "yyyy-MM-dd", CultureInfo.InvariantCulture, DateTimeStyles.None, out var until))
throw new ContentException(FileName, at + ".to", "required, a date 'YYYY-MM-DD'");
if (!hexes.TryGetValue((id, k), out var qr))
throw new ContentException(HexesFileName, "order_targets", $"no hex for {at} ({FileName}); rerun tools/unit_anchor_hexes.py");
c.UnitOrderTargets[(id, k)] = (qr.q, qr.r, until);
}
}
}
/// <summary>A file's list under <paramref name="key"/>, read untyped (only the keys the start needs are read). An
/// <paramref name="optional"/> key that is absent reads as an empty list.</summary>
static List<Dictionary<object, object>> Rows(Func<string, string?> readFile, string fileName, string key, bool optional = false)
{
string? text;
try { text = readFile(fileName); }
catch (System.IO.IOException e) { throw new ContentException(fileName, "(file)", e.Message); }
catch (UnauthorizedAccessException e) { throw new ContentException(fileName, "(file)", e.Message); }
if (text == null) throw new ContentException(fileName, "(file)", "missing file");
Dictionary<string, List<Dictionary<object, object>>>? file;
try { file = new DeserializerBuilder().Build().Deserialize<Dictionary<string, List<Dictionary<object, object>>>>(text); }
catch (YamlException e) { throw new ContentException(fileName, $"line {e.Start.Line}", e.InnerException?.Message ?? e.Message); }
if (file != null && file.TryGetValue(key, out var rows) && rows != null) return rows;
if (optional && (file == null || !file.ContainsKey(key))) return new List<Dictionary<object, object>>();
throw new ContentException(fileName, key, "required");
}
/// <summary>unit_anchor_hexes.yaml's <paramref name="key"/> list (anchors, or order_targets, R-ENEMY-005) by (row id,
/// index). Every row must name one entry of <paramref name="units"/>' list under the same key, once: a row that does
/// not means the file is stale (the tool was not rerun after units_1948.yaml changed).</summary>
static Dictionary<(string id, int anchor), (int q, int r)> Hexes(Func<string, string?> readFile, List<Dictionary<object, object>> units, string key, string index)
{
var anchors = new Dictionary<string, int>(StringComparer.Ordinal);
foreach (var u in units)
if (u != null) anchors[Text(u, "id")] = u.TryGetValue(key, out var ao) && ao is List<object> list ? list.Count : 0;
var hexes = new Dictionary<(string, int), (int, int)>();
var rows = Rows(readFile, HexesFileName, key, optional: key != "anchors");
for (int i = 0; i < rows.Count; i++)
{
var row = rows[i] ?? throw new ContentException(HexesFileName, $"{key}[{i}]", "empty row");
var id = Text(row, "id");
var at = id == "" ? $"{key}[{i}]" : $"{key}[{id}]";
int k = Int(row, index, at), q = Int(row, "q", at), r = Int(row, "r", at);
if (!anchors.TryGetValue(id, out var n) || k < 0 || k >= n)
throw new ContentException(HexesFileName, at, FormattableString.Invariant($"no {index} {k} of a row '{id}' in {FileName}; rerun tools/unit_anchor_hexes.py"));
if (!hexes.TryAdd((id, k), (q, r)))
throw new ContentException(HexesFileName, at, FormattableString.Invariant($"{index} {k} is listed twice"));
}
return hexes;
}
static int Int(Dictionary<object, object> m, string key, string at) =>
int.TryParse(Text(m, key), NumberStyles.AllowLeadingSign, CultureInfo.InvariantCulture, out var n)
? n : throw new ContentException(HexesFileName, $"{at}.{key}", "required, a whole number");
/// <summary>The latest `checked` day among an entry's `sources` ('YYYY-MM-DD' compares as text), or "" with none.</summary>
static string LatestCheck(Dictionary<object, object> m) =>
m.TryGetValue("sources", out var so) && so is List<object> sources
? sources.OfType<Dictionary<object, object>>().Select(x => Text(x, "checked")).OrderBy(x => x, StringComparer.Ordinal).LastOrDefault() ?? ""
: "";
static string Text(Dictionary<object, object> m, string key) => m.TryGetValue(key, out var v) && v is string s ? s : "";
static decimal Number(Dictionary<object, object> m, string key, string field) =>
decimal.TryParse(Text(m, key), NumberStyles.Float, CultureInfo.InvariantCulture, out var d)
? d : throw new ContentException(FileName, field, "required, a number");
}
}