islaApocalypse-v2/Core/Scripts/CurveAnchors.cs

namespace IslaApocalypse.Core
{
	/// <summary>
	/// The redistribution curve's fixed OUTPUT anchors — the elevations the bands are mapped ONTO.
	///
	/// ═══ INPUT KNOTS vs OUTPUT ANCHORS — the distinction the whole curve rests on ═══
	///
	///   <see cref="CurveKnots"/>  — WHERE the land distribution is cut. Percentiles. Measured.
	///   <see cref="CurveAnchors"/> — WHAT HEIGHT each cut lands at. Storm-ladder. Chosen.
	///
	/// Re-measuring the knots moves how much land is in each band. Moving the anchors moves how HIGH
	/// each band sits. They are independent, and conflating them is how a "recalibration" turns into
	/// an unnoticed reshape.
	///
	/// ═══ ⚠ WHY THIS IS A PARAMETER OBJECT AND NOT A WALL OF CONSTANTS ═══
	///
	/// The reference held these as <c>const</c> fields on <c>HeightCurve</c> and passed only the
	/// per-column modulated values (<c>benchLo</c>, <c>benchSpan</c>, …) as arguments. That made the
	/// storm-ladder anchors unreachable from config: A/B-ing the 420 m cap meant editing and
	/// rebuilding.
	///
	/// Here every anchor is an explicit parameter, in the spirit of D-035 ("every per-column input
	/// and the knot set are explicit PARAMETERS"). <see cref="Default"/> reproduces the reference's
	/// constants bit-for-bit, so this is an exposure, not a change.
	///
	/// ⚠⚠ THE BAND COUNT AND THE SEGMENT SHAPES ARE NOT EXPOSED, DELIBERATELY. Adding a knot,
	/// steepening a segment or reallocating the shares is the RESHAPE — a later task with its own
	/// gate. This type exposes the existing seven-band curve's dials and nothing more.
	///
	/// Every metre-denominated anchor is derived through <see cref="WorldScale.RawFromMetres"/> —
	/// the single yardstick — never a literal <c>/251f</c>.
	/// </summary>
	public sealed class CurveAnchors
	{
		// ---- the frozen band ceilings (raw height units) ---------------------

		/// <summary>
		/// Sea level in raw units. ⚠ ALSO THE CURVE'S IDENTITY THRESHOLD: at and below this the
		/// curve returns its input untouched, which is what keeps the waterline, the Trench
		/// guarantee and (later) every water body invariant under the curve. Reference: 0.15f.
		/// </summary>
		public float Sea = 0.15f;

		/// <summary>Top of the toe/orange band. Reference: 0.206f.</summary>
		public float OrangeCeil = 0.206f;

		/// <summary>Top of the red band — the floor the foothill riser climbs from. Reference: 0.27f.</summary>
		public float RedCeil = 0.27f;

		// ---- the modulated shelf anchors -------------------------------------

		/// <summary>Bench centre, raw. Reference: <c>SEA + 100 m</c>.</summary>
		public float BenchBase = 0.15f + WorldScale.RawFromMetres(100f);

		/// <summary>Bench modulation amplitude, raw. Reference: <c>±12 m</c>.</summary>
		public float BenchAmp = WorldScale.RawFromMetres(12f);

		/// <summary>Plateau centre, raw. Reference: <c>SEA + 220 m</c>.</summary>
		public float PlateauBase = 0.15f + WorldScale.RawFromMetres(220f);

		/// <summary>Plateau modulation amplitude, raw. Reference: <c>±20 m</c>.</summary>
		public float PlateauAmp = WorldScale.RawFromMetres(20f);

		/// <summary>
		/// Narrowest a shelf band may be, raw. Reference: <c>6 m</c> (v4 was 2 m — "corner fix 3":
		/// a pronounced shelf keeps a gentle tilt, flat to build on but never snooker-table flat).
		/// </summary>
		public float ShelfSpanMin = WorldScale.RawFromMetres(6f);

		/// <summary>Widest a shelf band may be, raw. Reference: 0.10f (≈ 25 m).</summary>
		public float ShelfSpanMax = 0.10f;

		// ---- the ceiling and its tail ---------------------------------------

		/// <summary>
		/// The peak cap, raw. Reference: <c>SEA + 420 m</c>. The summit spike maps
		/// <c>[K6, spikeMax]</c> onto <c>[plateauTop, PeakCap]</c>, so this is the island's
		/// nominal ceiling — exact, not statistical, because K6 never moves under the edge warp.
		/// </summary>
		public float PeakCap = 0.15f + WorldScale.RawFromMetres(420f);

		/// <summary>
		/// Slope above <c>spikeMax</c>. Reference: 0.25f. ⚠ A gentle TAIL, not a hard clip — a seed
		/// whose max exceeds the spike range still rises, just slowly.
		/// </summary>
		public float TailSlope = 0.25f;

		/// <summary>
		/// Minimum spike span, raw. Reference: 0.01f. Guarantees a non-degenerate summit band on a
		/// seed whose map-wide max lands at or below K6.
		/// </summary>
		public float SpikeMinSpan = 0.01f;

		// ---- the modulation fields' identity ---------------------------------
		//
		// ⚠ THESE ARE SEED OFFSETS, NOT COORDINATE OFFSETS. The reference decorrelated its curve
		// modulation fields by seeding each one at `resolvedSeed + offset` and sampling all of them
		// at the bare (x, y) — there is no `GetNoise2D(x + 1000, …)` anywhere in this path. So the
		// raw-pixel-offset hazard GenerationScale warns about does NOT apply here, and there is
		// nothing to normalize. (Verified against every MakeModulationNoise call site; recorded
		// because the absence of a bug is only reassuring if someone checked.)

		/// <summary>Bench-anchor field seed offset. Reference: 7101.</summary>
		public int BenchSeedOffset = 7101;

		/// <summary>Plateau-anchor field seed offset. Reference: 7207.</summary>
		public int PlateauSeedOffset = 7207;

		/// <summary>Shelf-strength field seed offset. Reference: 7303.</summary>
		public int StrengthSeedOffset = 7303;

		/// <summary>
		/// Anchor-field frequency, in periods per MAP WIDTH. Reference: 3.0f — a very low frequency,
		/// so the bench and plateau elevations drift across the island rather than flickering.
		/// ⚠ Already scale-safe by construction: stated per map width, not per pixel.
		/// </summary>
		public float ElevFreqPerMapWidth = 3.0f;

		/// <summary>Shelf-strength field frequency, periods per map width. Reference: 5.0f.</summary>
		public float StrengthFreqPerMapWidth = 5.0f;

		/// <summary>
		/// The reference's shipped anchors, reproduced bit-for-bit. Every metre value goes through
		/// <see cref="WorldScale.RawFromMetres"/>, which divides — matching the reference's
		/// <c>420f / 251f</c> exactly rather than approximating it with a reciprocal multiply.
		/// </summary>
		public static CurveAnchors Default => new CurveAnchors();

		public CurveAnchors Clone() => (CurveAnchors)MemberwiseClone();

		/// <summary>
		/// The anchors as the storm ladder states them — metres above sea. For a run header, where
		/// raw units mean nothing to a reader.
		/// </summary>
		public string DescribeMetres() =>
			$"sea {Sea:F3} raw · orange {WorldScale.MetresFromRaw(OrangeCeil - Sea):F0} m · " +
			$"red {WorldScale.MetresFromRaw(RedCeil - Sea):F0} m · " +
			$"bench {WorldScale.MetresFromRaw(BenchBase - Sea):F0}±{WorldScale.MetresFromRaw(BenchAmp):F0} m · " +
			$"plateau {WorldScale.MetresFromRaw(PlateauBase - Sea):F0}±{WorldScale.MetresFromRaw(PlateauAmp):F0} m · " +
			$"cap {WorldScale.MetresFromRaw(PeakCap - Sea):F0} m";
	}
}