A Civilization-style strategy game about governing Israel from 15 May 1948. Real ministers, real map, every fact sourced. Unity + deterministic C# sim.
#nullable enable
using System;
using System.Collections.Generic;
using System.Linq;
using Statecraft.Sim;
using UnityEngine;
namespace Statecraft.Game.Map.Routes
{
/// <summary>The 1948 railways and roads on the map (issue #35): one ribbon mesh per look (rail; roads and the Burma
/// Road's track), draped on the terrain along the traced lines of route_paths_1948.yaml, drawn with the editor-made
/// Statecraft/Route materials in Resources (no runtime Shader.Find, no new serialized field on MapScene). Each route
/// shows only while the game date is inside its window (RoutePath.From/To; review C1: the Burma Road from 14 June
/// 1948): routes are grouped by window, one ribbon pair per group, and <see cref="ShowAt"/> switches the groups. A
/// steam train runs on the Jaffa–Jerusalem line: in normal play only from the sourced date regular service resumed
/// (<see cref="ServiceTrain"/>, issue #668), and as the promo's showcase in screenshots and `?train` (<see cref="ModeFor"/>). Widths are symbolic, measured on the
/// promo's gameplay frame like the settlements and units (docs/routes.md): a road's pale core about 8 px and the railway
/// about 16 px wide at 1920 px (the soft edges take about a sixth of the railway's width, so its bed is drawn 680 m), so they read at the gameplay zoom as the promo draws them. Registers the "routes" (ribbons)
/// and "train" visual toggles, so the frame profile prices each. Pure geometry from the data: the same file gives the
/// same meshes, vertex for vertex.</summary>
public static class RouteLayer
{
public const string RootName = "Routes", RibbonsName = "RouteRibbons", RoutesToggle = "routes", TrainToggle = "train";
public const string RailMaterialResource = "Routes/Rail", RoadMaterialResource = "Routes/Road";
public const string Folder = "Assets/Resources/Routes";
/// <summary>Full ribbon widths (m), soft edges included (the shader fades the outer 16-30%). A road is 420 m: its pale
/// core, inside the verges, is about 280 m, about 8 px at the gameplay zoom, as promo 03's dirt tracks (at 300 m the
/// core was about 4 px, a thin line between dark verges); still well under the railway's bed.</summary>
public const float RailWidthM = 680f, RoadWidthM = 420f, TrackWidthM = 200f;
/// <summary>Spacing (m) of the ribbon's cross-sections along its line: under the heightmap's 211 m N-S spacing, so
/// every terrain row gets a section; about 3 px at the gameplay zoom.</summary>
public const float StepM = 120f;
/// <summary>Vertices across a ribbon: its edges, its centre and the quarter lines, each on its own ground, so a
/// ribbon on a slope follows the slope instead of standing out flat.</summary>
public const int Across = 5;
/// <summary>Height above the highest ground sampled around each vertex; the shader's depth offset does the rest.</summary>
public const float ClearanceM = 20f;
/// <summary>The train's route: the Jaffa–Jerusalem railway. The showcase runs from its Jaffa end to Lydda junction
/// (<see cref="TrainTurnAt"/>), the stretch the promo's train runs (promo/final/03): ambience for the promo frames, not
/// a timetable. No regular trains ran on the line from the British withdrawal in May 1948 until 2 March 1950, after
/// Lydda was taken in July 1948 and the 1949 armistice (Israel Railways; routes_1948.yaml), so normal play runs its
/// train only from then, on the stretches of the route's service that run (Lod to Jerusalem, the 1950 service's
/// stretch of this line; Tel Aviv South to Lod once a person signs it off): <see cref="ServiceTrain"/>, maintainer
/// decision on #35, 16 October 2026.</summary>
public const string TrainRoute = "jaffa_jerusalem_railway";
public static readonly (double lon, double lat) TrainTurnAt = (34.87556, 31.94583); // Lod railway station
/// <summary>The date the map shows before the game tells it one (editor renders, screenshots before GAME OK): the
/// game's start, 15 May 1948.</summary>
public static readonly DateTime DefaultDate = new DateTime(1948, 5, 15);
/// <summary>None: no train. Still and Moving: the promo's showcase train. Service: normal play's (issue #668), from
/// the route's sourced service date only.</summary>
public enum TrainMode { None, Still, Moving, Service }
/// <summary>Which train (review I1; issue #668): editor renders and screenshots (`?shot` / `-shot`) show the promo's
/// still train; `?train` or `?units` (desktop `-train` / `-units`) asks for the moving showcase; normal play runs the
/// service train, from the date regular service resumed (<see cref="ServiceTrain"/>).</summary>
public static TrainMode ModeFor(bool playing, bool shot, bool requested) =>
!playing || shot ? TrainMode.Still : requested ? TrainMode.Moving : TrainMode.Service;
public static bool TrainRequested(string? url, string[] args, bool webgl) =>
webgl ? Boot.UrlFlags.Has(url, "train") || Boot.UrlFlags.Has(url, "units") : Array.IndexOf(args, "-train") >= 0 || Array.IndexOf(args, "-units") >= 0;
public static TrainMode ModeForThisRun() => ModeFor(Application.isPlaying, VisualShots.Requested(),
TrainRequested(Application.absoluteURL, Environment.GetCommandLineArgs(), Application.platform == RuntimePlatform.WebGLPlayer));
/// <summary>Shows the route groups whose window covers <paramref name="date"/> and hides the rest (the game calls it
/// on every state change; cheap: a few SetActive calls), and remembers the date on the map, so a rebuild of the map
/// (MapScene.Build) draws the routes as at the game's date at once. A map without routes is left alone.
/// In the GDD loop (<paramref name="built"/> given: route id to each segment built, <see cref="BuiltSegments"/>), a
/// route a corridor follows is drawn by its built segments instead, whatever the date (spec §2.6, "Routes"; #792):
/// its dated ribbon is hidden and each built segment's own ribbon shown. Every other route keeps its dates.</summary>
public static void ShowAt(MapScene map, DateTime date, IReadOnlyDictionary<string, IReadOnlyList<bool>>? built = null)
{
if (map == null) return;
map.RouteDate = date; // a later rebuild of this map starts at the game's date (re-review nit 2)
map.RouteSegmentsBuilt = built; // and with the corridors as built
if (map.Terrain == null) return;
var service = map.Terrain.transform.Find($"{RootName}/{ServiceTrain.Name}");
if (service != null) service.GetComponent<ServiceTrain>().ShowAt(date); // from the service date on (issue #668)
var vehicles = map.Terrain.transform.Find($"{RootName}/{RoadVehicles.Name}");
if (vehicles != null) vehicles.GetComponent<RoadVehicles>().ShowAt(date, built);
var ribbons = map.Terrain.transform.Find($"{RootName}/{RibbonsName}");
if (ribbons == null) return;
foreach (var g in ribbons.GetComponentsInChildren<RouteGroup>(true)) g.gameObject.SetActive(g.Window.Covers(date));
ShowSegments(ribbons, built);
}
/// <summary>Outside the GDD loop (<paramref name="built"/> null), each corridor route's dated ribbon and none of its
/// segments; in it, only the built segments.</summary>
static void ShowSegments(Transform ribbons, IReadOnlyDictionary<string, IReadOnlyList<bool>>? built)
{
foreach (var s in ribbons.GetComponentsInChildren<RouteSegment>(true))
s.gameObject.SetActive(built == null ? s.Index < 0
: s.Index >= 0 && built.TryGetValue(s.Route, out var b) && s.Index < b.Count && b[s.Index]);
}
/// <summary>For <see cref="ShowAt"/> in the GDD loop: each corridor's route (corridors.yaml route) and, per segment,
/// whether the sim has built it (State.Corridors, R-COR-002). The sim decides what is built; this only reads it.</summary>
public static Dictionary<string, IReadOnlyList<bool>> BuiltSegments(Content content, GameState state) =>
content.Corridors.ToDictionary(d => d.Route, d => (IReadOnlyList<bool>)Enumerable.Range(0, d.Segments.Count)
.Select(i => state.Corridors.TryGetValue(d.Id, out var w) && i < w.Segments.Count && w.Segments[i]?.BuiltOn != null).ToArray());
/// <summary>Clearance (m) beyond a ribbon's drawn half-width that kit buildings and trees keep from it, so a lot's or
/// crown's edge never touches the soft edge of the road or the ballast.</summary>
public const float CorridorMarginM = 100f;
/// <summary>The roads' clearance (m) beyond their drawn half-width: 40 m, so their corridor stays the 250 m half-width
/// it had when roads were 300 m wide. A wider corridor pushed town kits off the roads that run through the towns
/// (Jerusalem's Haram al-Sharif, Beersheba's houses: TownCensusTests). The road's outer 22% is its soft edge, so a
/// lot or crown still keeps about 130 m from the visible dirt.</summary>
public const float RoadCorridorMarginM = 40f;
/// <summary>Each route's traced line (world x, z; <see cref="World"/>, not cut as <see cref="Drawn"/> is) with the half-width kits must keep clear of: half the drawn width plus
/// <see cref="CorridorMarginM"/> (<see cref="RoadCorridorMarginM"/> for roads). The units keep off every route's; the
/// kits only off those of <see cref="KitRoutes"/>.</summary>
public static List<(List<Vector2> line, float halfWidth)> Corridors(GeoFrame frame, IEnumerable<RoutePath> routes) =>
routes.Select(r => (World(frame, r), WidthOf(r.Kind) / 2f + (r.Kind == RoutePaths.Road ? RoadCorridorMarginM : CorridorMarginM))).ToList();
/// <summary>The routes whose corridors the kits keep clear: those drawn on the game's first day, <see cref="DefaultDate"/>.
/// The kits are built once, not per date, so a later route (the Burma Road, the 1949 rail link, the 1950 Tel Aviv–Netanya
/// road) clears no town's houses or trees from the start and draws over them when it appears (owner, 18 October 2026,
/// #786: the kit floors are kept, not lowered).</summary>
public static IEnumerable<RoutePath> KitRoutes(IEnumerable<RoutePath> routes) =>
routes.Where(r => RoutePaths.WindowOf(r).Covers(DefaultDate));
/// <summary>The routes whose corridors the unit tokens keep clear: those drawn on some day before <paramref name="until"/>,
/// the end of the last token's window. A route opened after every token has left the map (the 1949 rail link, the 1950
/// Tel Aviv–Netanya road) never stands beside one, so it takes no token's spot (#786: the straight 1950 road crossed
/// Tel Aviv and left Kiryati no spot there).</summary>
public static IEnumerable<RoutePath> UnitRoutes(IEnumerable<RoutePath> routes, DateTime until) =>
routes.Where(r => RoutePaths.WindowOf(r).From < until);
public static float WidthOf(string kind) => kind switch
{
RoutePaths.Rail => RailWidthM,
RoutePaths.Road => RoadWidthM,
RoutePaths.Track => TrackWidthM,
_ => throw new ArgumentException($"unknown route kind '{kind}'", nameof(kind)),
};
/// <summary>One ribbon mesh Build draws: the routes of one display window in one look ("Rail", or "Roads" for the
/// roads and tracks), in the file's order.</summary>
public sealed class RibbonPlan
{
public RouteWindow Window;
public string Look = "";
public List<RoutePath> Routes = new List<RoutePath>();
public bool RailGrade => Look == "Rail";
public string MeshName => $"Route{Look} {Window}";
}
/// <summary>The ribbons Build draws, in its order: the windows in the order they open, and in each the rail, then the
/// roads, where the window has any. The bake (RouteRibbonFile) stores its meshes in this order. A change to it, to
/// Derive or to what Derive calls needs a re-bake (RouteRibbonBake.Bake) and a bump of RouteRibbonFile.Version
/// (tools/tests/test_route_ribbon_bake.py fails until then, issue #535).</summary>
public static List<RibbonPlan> Plan(IReadOnlyList<RoutePath> routes)
{
var plans = new List<RibbonPlan>();
foreach (var group in routes.GroupBy(RoutePaths.WindowOf).OrderBy(g => g.Key.From).ThenBy(g => g.Key.To ?? DateTime.MaxValue))
foreach (var (kinds, look) in new[] { (new[] { RoutePaths.Rail }, "Rail"), (new[] { RoutePaths.Road, RoutePaths.Track }, "Roads") })
{
var members = group.Where(r => kinds.Contains(r.Kind)).ToList();
if (members.Count > 0) plans.Add(new RibbonPlan { Window = group.Key, Look = look, Routes = members });
}
return plans;
}
/// <summary>A plan's ribbon, derived from the terrain (what the bake stores). A change to it or to what it calls
/// (World, Geometry and their helpers) needs a re-bake and a bump of RouteRibbonFile.Version (see Plan).</summary>
public static RibbonGeometry Derive(RibbonPlan plan, GeoFrame frame, TerrainData data, Vector3 origin)
{
var g = Geometry(plan.Routes.Select(r => (r.Id, Drawn(frame, r), WidthOf(r.Kind))), data, origin, plan.RailGrade);
for (int k = 0; k < plan.Routes.Count; k++)
if (plan.Routes[k].SegmentEnds is { } ends)
{
var s = g.Routes[k];
var at = ends.ConvertAll(p => { var v = frame.ToWorld(p[0], p[1], 0); return new Vector2(v.x, v.z); });
g.Routes[k] = new RouteSpan(s.Id, s.FirstVertex, s.VertexCount, s.FirstIndex, s.IndexCount,
SegmentStarts(Drawn(frame, plan.Routes[k]), at, s.FirstIndex, s.IndexCount));
}
return g;
}
/// <summary>The route index's segment cuts (RouteSpan.Segments, #792) for a ribbon drawn along <paramref name="line"/>
/// (Geometry's cross-sections, <see cref="Resample"/>), starting at index <paramref name="firstIndex"/>: the first
/// segment starts at the ribbon's start and the last ends at its end, so the segments tile the route; between, each
/// segment ends at the cross-section nearest the point of the line nearest its end waypoint (<paramref name="ends"/>,
/// the route's first waypoint and each segment's end, world x, z), searched from the cut before it on, as
/// tools/corridor_hexes.py splits the hexes.</summary>
public static int[] SegmentStarts(List<Vector2> line, List<Vector2> ends, int firstIndex, int indexCount)
{
var cuts = new int[ends.Count];
cuts[0] = firstIndex; cuts[ends.Count - 1] = firstIndex + indexCount;
if (line.Count < 2) { for (int i = 1; i < ends.Count - 1; i++) cuts[i] = firstIndex; return cuts; }
var (_, along) = Resample(line, StepM);
const int perSection = (Across - 1) * 6; // Geometry's triangles between two cross-sections
float at = Project(line, ends[0], 0f);
int section = 0;
for (int i = 1; i < ends.Count - 1; i++)
{
at = Project(line, ends[i], at);
int best = section;
for (int k = section; k < along.Count; k++)
if (Mathf.Abs(along[k] - at) < Mathf.Abs(along[best] - at)) best = k;
section = best;
cuts[i] = firstIndex + section * perSection;
}
return cuts;
}
/// <summary>The distance along <paramref name="line"/> of its point nearest <paramref name="p"/>, among the points at
/// or past <paramref name="start"/>, so a route that passes near one waypoint twice is cut in order.</summary>
static float Project(List<Vector2> line, Vector2 p, float start)
{
float best = start, bestD = float.PositiveInfinity, s = 0f;
for (int i = 1; i < line.Count; i++)
{
var a = line[i - 1]; var d = line[i] - a; float len = d.magnitude;
if (len == 0f) continue;
float t = Mathf.Clamp01(Vector2.Dot(p - a, d) / (len * len)), here = s + t * len;
float dist = (a + d * t - p).magnitude;
if (here >= start && dist < bestD) { best = here; bestD = dist; }
s += len;
}
return best;
}
/// <summary>Builds the routes under <paramref name="terrain"/> (so a map rebuild destroys them): one group per display
/// window (its rail and road ribbons), shown as at <paramref name="date"/>, and, when <paramref name="train"/> is not
/// None and the train's route is in <paramref name="routes"/>, the train (still: it stands at its still position, so
/// screenshots and editor renders repeat exactly). Meshes, the train's palette and its material copy are owned by
/// the root's own MapRuntimeAssets, which also unregisters the toggles. Returns the root.
/// With <paramref name="baked"/> (the inputs the map read), the ribbons are placed from the bake
/// (RouteRibbonFile.Resource, Editor RouteRibbonBake) when it was made from the same inputs; a missing or stale bake
/// is refused with a warning and the ribbons derived at load, the same meshes, only slower (issue #321). Without it
/// they are derived.</summary>
public static GameObject Build(Terrain terrain, GeoFrame frame, IReadOnlyList<RoutePath> routes, TrainMode train, DateTime date,
RouteRibbonFile.Source? baked = null, MapScene? map = null)
{
if (terrain == null) throw new ArgumentNullException(nameof(terrain));
if (routes == null) throw new ArgumentNullException(nameof(routes));
var rail = Resources.Load<Material>(RailMaterialResource)
?? throw new InvalidOperationException($"Resources/{RailMaterialResource}.mat is missing (run RouteMaterialAssets.Create)");
var road = Resources.Load<Material>(RoadMaterialResource)
?? throw new InvalidOperationException($"Resources/{RoadMaterialResource}.mat is missing (run RouteMaterialAssets.Create)");
var root = new GameObject(RootName);
root.transform.SetParent(terrain.transform, false);
root.transform.position = Vector3.zero; // children are in world space
var assets = root.AddComponent<MapRuntimeAssets>();
var ribbons = new GameObject(RibbonsName);
ribbons.transform.SetParent(root.transform, false);
var data = terrain.terrainData; var origin = terrain.transform.position;
// One group per display window, in the order the windows open (deterministic names and draw order).
var plans = Plan(routes);
var geometry = Geometries(plans, frame, data, origin, baked);
GameObject? holder = null, corridors = null;
for (int i = 0; i < plans.Count; i++)
{
var plan = plans[i];
if (holder == null || !plans[i - 1].Window.Equals(plan.Window))
{
holder = new GameObject($"Window {plan.Window}");
holder.transform.SetParent(ribbons.transform, false);
holder.AddComponent<RouteGroup>().Window = plan.Window;
holder.SetActive(plan.Window.Covers(date));
}
var mesh = assets.Own(geometry[i].ToMesh(plan.MeshName));
mesh.UploadMeshData(true);
var go = new GameObject(plan.Look);
go.transform.SetParent(holder.transform, false);
go.AddComponent<MeshFilter>().sharedMesh = mesh;
var r = go.AddComponent<MeshRenderer>();
r.sharedMaterial = plan.RailGrade ? rail : road;
r.shadowCastingMode = UnityEngine.Rendering.ShadowCastingMode.Off;
r.receiveShadows = true;
// A route a corridor follows (#792; each is alone in its ribbon, tools/tests/test_route_ribbon_bake.py): its
// dated ribbon is marked, and each segment gets a ribbon of its own, outside the dated groups, which the GDD
// loop shows once the segment is built (ShowAt).
for (int k = 0; k < plan.Routes.Count; k++)
{
var span = geometry[i].Routes[k];
if (span.Segments.Length < 2) continue;
go.AddComponent<RouteSegment>().Route = span.Id;
if (corridors == null) { corridors = new GameObject("Corridors"); corridors.transform.SetParent(ribbons.transform, false); }
for (int s = 0; s + 1 < span.Segments.Length; s++)
{
var part = assets.Own(geometry[i].SegmentMesh(k, s, $"{plan.MeshName} {span.Id} {s + 1}"));
part.UploadMeshData(true);
var seg = new GameObject($"{span.Id} {s + 1}");
seg.transform.SetParent(corridors.transform, false);
seg.AddComponent<MeshFilter>().sharedMesh = part;
var sr = seg.AddComponent<MeshRenderer>();
sr.sharedMaterial = r.sharedMaterial;
sr.shadowCastingMode = UnityEngine.Rendering.ShadowCastingMode.Off;
sr.receiveShadows = true;
var mark = seg.AddComponent<RouteSegment>();
mark.Route = span.Id; mark.Index = s;
}
}
}
ShowSegments(ribbons.transform, map != null ? map.RouteSegmentsBuilt : null);
assets.OnTeardown(VisualToggles.Register(RoutesToggle, on => { if (ribbons != null) ribbons.SetActive(on); }));
if (map != null) RoadVehicles.Create(root.transform, map, routes, date);
var trainRoute = routes.FirstOrDefault(r => r.Id == TrainRoute);
if (trainRoute != null && train == TrainMode.Service)
{
// Normal play: nothing is built or fetched before the route's service date (issue #668). No service (the YAML
// fallback carries none, or it was refused with a warning): no train.
if (trainRoute.Service != null)
{
var service = ServiceTrain.Create(root.transform, assets, frame, trainRoute, data, origin, date);
assets.OnTeardown(VisualToggles.Register(TrainToggle, on => { if (service != null) service.gameObject.SetActive(on); }));
}
}
else if (trainRoute != null && train != TrainMode.None)
{
var go = RouteTrain.Spawn(root.transform, assets, World(frame, trainRoute), data, origin,
frame.ToWorld(TrainTurnAt.lon, TrainTurnAt.lat, 0), frame.ToWorld(RouteTrain.StillAt.lon, RouteTrain.StillAt.lat, 0),
train == TrainMode.Still);
assets.OnTeardown(VisualToggles.Register(TrainToggle, on => { if (go != null) go.SetActive(on); }));
}
return root;
}
/// <summary>The plans' ribbons: from the bake when <paramref name="baked"/> is given and the bake is for those inputs,
/// else derived.</summary>
static List<RibbonGeometry> Geometries(List<RibbonPlan> plans, GeoFrame frame, TerrainData data, Vector3 origin, RouteRibbonFile.Source? baked)
{
if (baked is { } source && plans.Count > 0)
{
var asset = Resources.Load<TextAsset>(RouteRibbonFile.Resource);
string why = "missing";
if (asset != null)
{
bool ok = RouteRibbonFile.TryRead(asset.bytes, source, data.size, origin, plans, out var read, out why);
if (!Application.isEditor) Resources.UnloadAsset(asset); // its bytes were copied; drop the native copy
if (ok) return read;
}
Debug.LogWarning($"ROUTES {RouteRibbonFile.AssetPath}: {why}; deriving the route ribbons at load");
}
return plans.ConvertAll(p => Derive(p, frame, data, origin));
}
/// <summary>A route's points in world metres (x east, z north).</summary>
public static List<Vector2> World(GeoFrame frame, RoutePath route)
{
var w = new List<Vector2>(route.Points.Count);
foreach (var p in route.Points)
{
var v = frame.ToWorld(p[0], p[1], 0);
var q = new Vector2(v.x, v.z);
if (w.Count == 0 || (q - w[w.Count - 1]).sqrMagnitude > 1e-4f) w.Add(q);
}
return w;
}
/// <summary>A route's line as the map draws its ribbon: <see cref="World"/>, with a road's or a railway's ends
/// cut at the walls of Jerusalem's symbolic Old City (#319). The walled square (SettlementKits.OldCityWalls) is 4 km
/// across, about 4 times the real Old City, so the real 1948 roads that start outside the real walls, by New Gate and
/// Jaffa Gate, and the Jaffa-Jerusalem railway's station, also outside them, fall inside it. Cut there, each line
/// ends on the wall line, where the walls leave it a gap (the railway on the owner's ruling, "Cut it at the walls"),
/// and the traced data keeps the real lines. Only a line's ends are cut: one that ran through the square would keep
/// its middle, and RouteTests.TheRoadsAndTheRailwayStopAtTheOldCityWalls fails on it. Tracks are not cut (none comes
/// near). The corridors (<see cref="Corridors"/>) keep the traced lines, so the kits and the units stand where
/// they did: inside the walls the roads' clear ways read as the streets from the gates.</summary>
public static List<Vector2> Drawn(GeoFrame frame, RoutePath route)
{
var line = World(frame, route);
if (route.Kind == RoutePaths.Track) return line;
var (centre, half) = Kits.SettlementKits.OldCityWalls(frame);
return TrimEndsInside(line, centre, half);
}
/// <summary><paramref name="line"/> without its leading and trailing runs inside the square (centre
/// <paramref name="c"/>, half side <paramref name="half"/>), each cut where it crosses the square's edge. A line wholly
/// inside comes back empty, one wholly outside unchanged.</summary>
public static List<Vector2> TrimEndsInside(List<Vector2> line, Vector2 c, float half)
{
bool Inside(Vector2 p) => Mathf.Abs(p.x - c.x) < half && Mathf.Abs(p.y - c.y) < half;
int first = line.FindIndex(p => !Inside(p)), last = line.FindLastIndex(p => !Inside(p));
if (first < 0) return new List<Vector2>();
if (first == 0 && last == line.Count - 1) return line;
var cut = new List<Vector2>(last - first + 3);
void Add(Vector2 q) { if (cut.Count == 0 || (q - cut[cut.Count - 1]).sqrMagnitude > 1e-4f) cut.Add(q); }
if (first > 0) Add(Exit(line[first - 1], line[first], c, half));
for (int i = first; i <= last; i++) Add(line[i]);
if (last < line.Count - 1) Add(Exit(line[last + 1], line[last], c, half));
return cut;
}
/// <summary>Where the segment from <paramref name="a"/> (inside the square) to <paramref name="b"/> (outside) crosses
/// its edge.</summary>
static Vector2 Exit(Vector2 a, Vector2 b, Vector2 c, float half)
{
var d = b - a; float t = 1f;
if (d.x != 0f) t = Mathf.Min(t, ((d.x > 0f ? c.x + half : c.x - half) - a.x) / d.x);
if (d.y != 0f) t = Mathf.Min(t, ((d.y > 0f ? c.y + half : c.y - half) - a.y) / d.y);
return a + d * Mathf.Max(0f, t);
}
/// <summary>Points every <paramref name="step"/> metres along a polyline, its last point included, and the
/// distance along it of each.</summary>
public static (List<Vector2> points, List<float> along) Resample(IReadOnlyList<Vector2> line, float step)
{
var pts = new List<Vector2>(); var along = new List<float>();
if (line.Count == 0) return (pts, along);
pts.Add(line[0]); along.Add(0f);
float s = 0f, next = step;
for (int i = 1; i < line.Count; i++)
{
var a = line[i - 1]; var b = line[i]; float len = (b - a).magnitude;
while (next <= s + len && len > 0f)
{
pts.Add(Vector2.Lerp(a, b, (next - s) / len)); along.Add(next);
next += step;
}
s += len;
}
if (s - along[along.Count - 1] > 1e-3f) { pts.Add(line[line.Count - 1]); along.Add(s); }
return (pts, along);
}
/// <summary>A ribbon's height (world y) at line point <paramref name="q"/>: <see cref="ClearanceM"/> above the highest
/// ground at q and a quarter step (30 m) along the line either way (<paramref name="along"/>, unit). The line's own grade: no
/// sample across it, so the gorge walls beside the line do not lift it (review B15). A railway cross-section takes
/// this height across (raised only where the ground would rise under its rails), and the train's wheels too
/// (review M4).</summary>
public static float GradeHeight(TerrainData data, Vector3 origin, Vector2 q, Vector2 along) =>
Mathf.Max(Ground(data, origin, q), Mathf.Max(Ground(data, origin, q + along * (StepM / 4)), Ground(data, origin, q - along * (StepM / 4))))
+ ClearanceM;
/// <summary>How far ground may lie below a cross-section before the section narrows (m, world): a ribbon edge floating
/// higher than this over a falling slope would read as a shelf.</summary>
public const float FallToleranceM = 60f;
/// <summary>How far ground may rise above a cross-section before it narrows (m, world): an edge running under a
/// little higher ground reads as a cutting, and the rails are kept clear by the lift (RailSpanShare). Without it,
/// any rise over the clearance narrowed the band on the rolling foothills too, not only in the gorges.</summary>
public const float RiseToleranceM = 40f;
/// <summary>The narrowest a cross-section gets, as a share of the ribbon's width (a gorge floor).</summary>
public const float MinWidthShare = 0.25f;
/// <summary>Samples per side when a cross-section looks for where it must stop.</summary>
internal const int NarrowSamples = 8;
/// <summary>The half-width (m) a cross-section at <paramref name="q"/> (flat at <paramref name="y"/>) may span. A sample
/// leaves the tolerance where the ground is more than <see cref="RiseToleranceM"/> above the section or more than
/// <see cref="FallToleranceM"/> below it. Where the ground leaves it on both sides within the half-width (a gorge floor, a
/// gorge side, a ridge), the section is cut back symmetrically (so the rails stay centred) to the last sample before
/// the first one that leaves it, on either side, but never under <see cref="MinWidthShare"/> of the width. Where it leaves
/// it on one side only (one hill or one drop beside the line), the full <paramref name="half"/>: that edge reads as a
/// cutting or an embankment, and cutting both sides for it narrowed the foothill lines to about 70% (#252). Railways
/// only (RailHalfWidths smooths it along the line): in the Sorek gorge the band keeps to the floor instead of riding up
/// the walls (review B15); on the plains nothing changes.</summary>
public static float FlatHalfWidth(TerrainData data, Vector3 origin, Vector2 q, Vector2 side, float y, float half)
{
int left = 0, right = 0; // the first sample out of tolerance each side
for (int k = 1; k <= NarrowSamples && (left == 0 || right == 0); k++)
{
float o = half * k / NarrowSamples;
if (left == 0 && OutOfTolerance(Ground(data, origin, q - side * o), y)) left = k;
if (right == 0 && OutOfTolerance(Ground(data, origin, q + side * o), y)) right = k;
}
if (left == 0 || right == 0) return half;
return Mathf.Max(half * (Math.Min(left, right) - 1) / NarrowSamples, half * MinWidthShare);
}
static bool OutOfTolerance(float ground, float y) => ground > y + RiseToleranceM || ground < y - FallToleranceM;
/// <summary>The ground height (world y) under (x, z), clamped to the terrain.</summary>
public static float Ground(TerrainData data, Vector3 origin, Vector2 p) =>
origin.y + data.GetInterpolatedHeight(Mathf.Clamp01((p.x - origin.x) / data.size.x), Mathf.Clamp01((p.y - origin.z) / data.size.z));
/// <summary>A road vertex's height (world y) at <paramref name="q"/>: <see cref="ClearanceM"/> above the highest ground at
/// q and half a step along and half a vertex spacing across, either way, so terrain between vertices cannot rise
/// through the ribbon. Roads drape over the ground this way (each vertex on its own ground); their pale band has
/// no rails or sleepers to warp, so they keep main's rule (review A-I1: narrowing them thinned and beaded every
/// hill road).</summary>
public static float DrapeHeight(TerrainData data, Vector3 origin, Vector2 q, Vector2 along, float spacing)
{
var side = new Vector2(along.y, -along.x);
float y = Ground(data, origin, q);
foreach (var d in new[] { along * (StepM / 2), -along * (StepM / 2), side * (spacing / 2), -side * (spacing / 2) })
y = Mathf.Max(y, Ground(data, origin, q + d));
return y + ClearanceM;
}
/// <summary>The largest step (m) of a rail band's half-width from one cross-section to the next: 5% of the full width,
/// so its width changes by at most a tenth between sections and narrows in a ramp, never in beads (review A-I1).</summary>
public const float HalfWidthStepShare = 0.05f;
/// <summary>The share of the half-width, either side of the line, that must stay clear of the ground: the rails
/// (Route.shader's RailOffset 0.12 plus RailHalfWidth 0.018 of the width, so 0.276 of the half-width, rounded up;
/// review A-I2). Clearing the whole sleeper span (0.58) lifted the narrowed gorge band a median 39 m off the floor;
/// the sleepers' outer ends may meet a gorge wall, as a cutting's would.</summary>
public const float RailSpanShare = 0.3f;
/// <summary>Clearance (m, world) of the rails over the highest ground under them, where a section had to be lifted.</summary>
public const float RailClearanceM = 3f;
/// <summary>Ground samples each side of the line when a section checks the ground under its rails (<see cref="RailSpanShare"/>).</summary>
internal const int LiftSamples = 4;
/// <summary>The half-widths of a rail line's sections (centre points <paramref name="pts"/>, unit directions
/// <paramref name="dirs"/>, heights <paramref name="ys"/>), smoothed along the line: FlatHalfWidth per section, then
/// the minimum over two sections each way, then limited to <see cref="HalfWidthStepShare"/> of the width per step
/// (forward and backward passes, which only narrow, so a narrow spot stays narrow and its neighbours ramp to it).</summary>
public static float[] RailHalfWidths(TerrainData data, Vector3 origin, IReadOnlyList<Vector2> pts, IReadOnlyList<Vector2> dirs,
IReadOnlyList<float> ys, float width)
{
int n = pts.Count; float half = width / 2f, step = HalfWidthStepShare * width;
var raw = new float[n];
for (int i = 0; i < n; i++) raw[i] = FlatHalfWidth(data, origin, pts[i], new Vector2(dirs[i].y, -dirs[i].x), ys[i], half);
var h = new float[n];
for (int i = 0; i < n; i++)
{
float m = raw[i];
for (int k = Math.Max(0, i - 2); k <= Math.Min(n - 1, i + 2); k++) m = Mathf.Min(m, raw[k]);
h[i] = m;
}
for (int i = 1; i < n; i++) h[i] = Mathf.Min(h[i], h[i - 1] + step);
for (int i = n - 2; i >= 0; i--) h[i] = Mathf.Min(h[i], h[i + 1] + step);
return h;
}
/// <summary>One mesh for several ribbons. Along each line, a cross-section every <see cref="StepM"/>, square to the
/// line's direction (averaged over two steps each way, so a tight bend fans instead of folding); across it,
/// <see cref="Across"/> vertices. UV: u across (0 left edge, 1 right), v along (m).
/// <list type="bullet">
/// <item>Roads (<paramref name="railGrade"/> false) drape: each vertex at <see cref="DrapeHeight"/>, with the terrain's
/// normal at that vertex (main's rule).</item>
/// <item>Railways (<paramref name="railGrade"/> true) are flat across at the line's own grade (<see cref="GradeHeight"/>,
/// review B15), so the rails and sleepers never warp; their width follows <see cref="RailHalfWidths"/> (full on the
/// plains, ramping down to a gorge floor); and a section is lifted, if need be, so the ground never rises under the
/// rails (<see cref="RailSpanShare"/>; review A-I2). Normal: the terrain's at the line.</item>
/// </list></summary>
public static Mesh Ribbon(IEnumerable<(List<Vector2> line, float width)> lines, TerrainData data, Vector3 origin, string name,
bool railGrade = false) =>
Geometry(lines.Select(l => ("", l.line, l.width)), data, origin, railGrade).ToMesh(name);
/// <summary><see cref="Ribbon"/>'s arrays before they become a mesh, with each line's vertex and index range under its
/// route id (<see cref="RibbonGeometry.Routes"/>).</summary>
public static RibbonGeometry Geometry(IEnumerable<(string id, List<Vector2> line, float width)> lines, TerrainData data, Vector3 origin,
bool railGrade = false)
{
var verts = new List<Vector3>(); var normals = new List<Vector3>(); var uvs = new List<Vector2>(); var tris = new List<int>();
var spans = new List<RouteSpan>();
foreach (var (id, line, width) in lines)
{
if (line.Count < 2) { spans.Add(new RouteSpan(id, verts.Count, 0, tris.Count, 0)); continue; }
var (pts, along) = Resample(line, StepM);
int n = pts.Count, first = verts.Count, firstIndex = tris.Count;
var dirs = new Vector2[n];
for (int i = 0; i < n; i++) dirs[i] = (pts[Math.Min(n - 1, i + 2)] - pts[Math.Max(0, i - 2)]).normalized;
if (railGrade)
{
var ys = new float[n];
for (int i = 0; i < n; i++) ys[i] = GradeHeight(data, origin, pts[i], dirs[i]);
var halves = RailHalfWidths(data, origin, pts, dirs, ys, width);
for (int i = 0; i < n; i++)
{
var side = new Vector2(dirs[i].y, -dirs[i].x); // right of the direction of travel
float y = ys[i], span = RailSpanShare * halves[i];
for (int k = -LiftSamples; k <= LiftSamples; k++) y = Mathf.Max(y, Ground(data, origin, pts[i] + side * (span * k / (float)LiftSamples)) + RailClearanceM);
var normal = data.GetInterpolatedNormal(Mathf.Clamp01((pts[i].x - origin.x) / data.size.x), Mathf.Clamp01((pts[i].y - origin.z) / data.size.z));
for (int j = 0; j < Across; j++)
{
float a = (float)j / (Across - 1);
var q = pts[i] + side * ((a - 0.5f) * 2f * halves[i]);
verts.Add(new Vector3(q.x, y, q.y)); normals.Add(normal); uvs.Add(new Vector2(a, along[i]));
}
}
}
else
{
float spacing = width / (Across - 1);
for (int i = 0; i < n; i++)
{
var side = new Vector2(dirs[i].y, -dirs[i].x);
for (int j = 0; j < Across; j++)
{
float a = (float)j / (Across - 1);
var q = pts[i] + side * ((a - 0.5f) * width);
verts.Add(new Vector3(q.x, DrapeHeight(data, origin, q, dirs[i], spacing), q.y));
normals.Add(data.GetInterpolatedNormal(Mathf.Clamp01((q.x - origin.x) / data.size.x), Mathf.Clamp01((q.y - origin.z) / data.size.z)));
uvs.Add(new Vector2(a, along[i]));
}
}
}
for (int i = 0; i + 1 < n; i++)
for (int j = 0; j + 1 < Across; j++)
{
int a = first + i * Across + j, b = a + 1, c = a + Across, d = c + 1;
tris.AddRange(new[] { a, c, b, b, c, d }); // the shader draws both faces
}
spans.Add(new RouteSpan(id, first, verts.Count - first, firstIndex, tris.Count - firstIndex));
}
return new RibbonGeometry(verts.ToArray(), normals.ToArray(), uvs.ToArray(), tris.ToArray(), spans.ToArray());
}
}
}