islaApocalypse-v2/Tools/Scripts/Pass1Result.cs

using System.Collections.Generic;

namespace IslaApocalypse.Tools
{
	/// <summary>
	/// Everything pass 1 produces. → <see cref="Topography"/>.
	///
	/// ⭐ THREE OF THESE FIELDS ARE THE PHASE-2 SEAM. The reference computed them in pass 1 and
	/// consumed them in pass 2; exposing them now is what keeps the deferred ports clean, and it
	/// costs nothing to carry.
	/// </summary>
	public sealed class Pass1Result
	{
		/// <summary>Map side in columns.</summary>
		public readonly int MapSize;

		/// <summary>The resolved seed this was generated with. Always positive, always recorded.</summary>
		public readonly int Seed;

		/// <summary>
		/// The raw pass-1 height field, <c>[x, y]</c>. Pre-curve, pre-erosion, pre-crater.
		/// The reference's <c>finalH</c> (~:619) written to <c>_heightMap</c> (~:666).
		/// </summary>
		public readonly float[,] Height;

		/// <summary>
		/// ⭐ PHASE-2 SEAM — the falloff value captured BEFORE the <c>Pow(·, 2.5f)</c> and BEFORE the
		/// Trench wall (reference ~:591, <c>preTrenchFalloff</c>).
		///
		/// It is the "how far past the island body are we" number, uncontaminated by the power's
		/// curvature and by the Trench's additive ramp. The DEFERRED offshore-islet layer reads it
		/// as its distance mask (<c>OffshoreZoneWeight</c>), which is the only reason it is captured
		/// mid-computation rather than recomputed.
		///
		/// ⚠ A port that "tidies" the falloff chain into one expression destroys this capture point,
		/// and the loss would not show up until Phase 2's offshore mask moved. It is exposed here so
		/// that cannot happen quietly.
		/// </summary>
		public readonly float[,] PreTrenchFalloff;

		/// <summary>
		/// ⭐ PHASE-2 SEAM — the wobbled latitude scalar, <c>[x, y]</c>.
		///
		/// ⚠ THIS IS NOT A CLIMATE TEMPERATURE MAP. See <see cref="Topography"/> for the full note.
		/// It is a stage-1-local latitude field that terrain GEOMETRY reads. Phase 2 needs it if the
		/// latitude sea-level model is ever switched on (<c>SeaLevelModel = "field"</c>); under the
		/// shipped flat model it has no consumer beyond the spine.
		/// </summary>
		public readonly float[,] LatitudeField;

		/// <summary>
		/// ⭐ PHASE-2 SEAM — the maximum height over the whole map (reference <c>_hMaxSeed</c>, ~:665).
		///
		/// The reference's v2+ redistribution curve is SEED-DEPENDENT: its spike maps
		/// <c>[t4, hMaxSeed]</c> onto the peak band, so pass 2 cannot start until pass 1 has scanned
		/// every pixel. That is precisely why the pass-1/pass-2 boundary is a hard one and not an
		/// interleave. Carried here so Phase 2 inherits it rather than rediscovering the dependency.
		/// </summary>
		public readonly float HMaxSeed;

		/// <summary>The minimum height. Not a reference field — carried for the renderer's ramp and the report.</summary>
		public readonly float HMinSeed;

		/// <summary>
		/// ⚠ The map-wide max BEFORE the coast shelf and offshore islets ran (chat2/05). The
		/// reference takes <c>_hMaxSeed</c> AFTER both, inside the same loop; v2 now does too —
		/// <see cref="HMaxSeed"/> is the post-shelf/offshore value the curve normalizes against.
		/// This one is carried so the report can state whether the two differed (expected: no, an
		/// islet crest of ~34 m is far below any peak — but "expected" is measured, not assumed).
		/// </summary>
		public readonly float HMaxSeedBeforeOffshore;

		// ═══ ⭐ THE OFFSHORE TAG — chat2/05's one forward-looking piece ═══
		//
		// DATA, set here, carried downstream, READ BY NOTHING IN THIS PHASE. It exists so a later
		// pass (biome, fertility, placement) can find offshore-island land without re-deriving it
		// from geometry. Downstream that ignores it is unaffected; downstream that reads it gets a
		// clean flag. Both arrays are NULL when the offshore layer is off — a consumer checks for
		// null, not for all-false.

		/// <summary>
		/// Per column: is this land an offshore island (as opposed to mainland)? Set for every cell
		/// the islet layer lifted from below sea to at-or-above sea. Null when offshore is off.
		/// </summary>
		public readonly bool[,] IsOffshoreIsland;

		/// <summary>
		/// Per column: <see cref="OffshoreAnalysis.HemiNorth"/> / <see cref="OffshoreAnalysis.HemiSouth"/>
		/// for tagged cells, <see cref="OffshoreAnalysis.HemiNone"/> otherwise. The convention is the
		/// row midline — see <see cref="OffshoreAnalysis"/>. Null when offshore is off.
		/// </summary>
		public readonly byte[,] IslandHemisphere;

		/// <summary>Cells the islet layer lifted above sea. The reference printed this too.</summary>
		public readonly long OffshoreLiftedCells;

		/// <summary>The islet layer's numbers — thresholds, pre-guard count, guard ledger, final count. Null when offshore is off.</summary>
		public readonly OffshoreLedger OffshoreLedger;

		/// <summary>Lines worth printing from the shelf/offshore pass: thresholds, guard ledger, lifted counts.</summary>
		public readonly IReadOnlyList<string> Notes;

		/// <summary>Wall-clock milliseconds the pass took.</summary>
		public readonly ulong ElapsedMs;

		public Pass1Result(int mapSize, int seed, float[,] height, float[,] preTrenchFalloff,
			float[,] latitudeField, float hMaxSeed, float hMinSeed, ulong elapsedMs,
			float hMaxSeedBeforeOffshore = float.NaN,
			bool[,] isOffshoreIsland = null, byte[,] islandHemisphere = null,
			long offshoreLiftedCells = 0, IReadOnlyList<string> notes = null, OffshoreLedger offshoreLedger = null)
		{
			MapSize = mapSize;
			Seed = seed;
			Height = height;
			PreTrenchFalloff = preTrenchFalloff;
			LatitudeField = latitudeField;
			HMaxSeed = hMaxSeed;
			HMinSeed = hMinSeed;
			ElapsedMs = elapsedMs;
			HMaxSeedBeforeOffshore = float.IsNaN(hMaxSeedBeforeOffshore) ? hMaxSeed : hMaxSeedBeforeOffshore;
			IsOffshoreIsland = isOffshoreIsland;
			IslandHemisphere = islandHemisphere;
			OffshoreLiftedCells = offshoreLiftedCells;
			OffshoreLedger = offshoreLedger;
			Notes = notes ?? System.Array.Empty<string>();
		}

		/// <summary>Whether the offshore layer ran on this field (the tag arrays are present).</summary>
		public bool HasOffshoreTag => IsOffshoreIsland != null;

		/// <summary>Fraction of the map at or above the sea threshold. A cheap shape sanity number.</summary>
		public float LandFraction(float seaLevel)
		{
			long land = 0;
			for (int x = 0; x < MapSize; x++)
				for (int y = 0; y < MapSize; y++)
					if (Height[x, y] >= seaLevel) land++;
			return land / (float)((long)MapSize * MapSize);
		}
	}
}