fix(sky): retail-faithful sun-vector magnitude for SunColor / AmbientColor

Two independent investigations (in-house decomp re-check + two
external agent reports) converged on the same root cause for the
"too blue-white sky" symptom:

acdream computed SunColor = DirColor × DirBright and AmbientColor =
AmbColor × AmbBright. Retail computes them from the magnitude of a
specially-shaped sun vector instead. Per the named retail decomp:

  SkyDesc::GetLighting at 0x00500ac9 (decomp 261343-261353):
    sunVec.x = sin(H_rad) × DirBright × cos(P_rad)
    sunVec.y = cos(P_rad)                    ← NOT scaled by DirBright
    sunVec.z = DirBright × sin(P_rad)

  PrimD3DRender::UpdateLightsInternal at 0x0059b57c (decomp 424118):
    D3DLIGHT9.Diffuse.r = sunlight_color.r × sqrt(x²+y²+z²)

  SmartBox::SetWorldAmbientLight callsite at 0x0050560b (decomp 267117):
    SetWorldAmbientLight(sqrt(|sunVec|²) × 0.2 + ambient_level, ...)

Y stays unscaled by DirBright on purpose, so |sunVec| ≠ DirBright in
general — the magnitude varies with sun pitch/heading. That's what
gives retail's "sun feels stronger when it's overhead, ambient warms
up at midday" behavior we were missing.

Added SkyStateProvider.RetailSunVector(kf) that builds the vector
verbatim. SkyKeyframe.SunColor / AmbientColor now compose via |sunVec|.
SunDirectionFromKeyframe normalizes the same vector (replaces our
geometrically-clean spherical convention which didn't match retail's
deliberate Y-decoupled-from-heading shape).

Tests:
- Replaced the linear-interp assumption in
  Interpolate_BetweenKeyframes_LerpsColors with a test on the RAW
  inputs (DirColor, AmbBright, etc.) — those still lerp linearly;
  the composite SunColor doesn't, intentionally.
- Added 4 golden-value tests for the new formulas
  (RetailSunVector_AtZenith, _AtHorizonNorth,
  SunColor_UsesRetailMagnitudeNotDirBrightDirectly,
  AmbientColor_BoostsByTwentyPercentOfSunVectorLength).
- Updated stale LoadFromRegion_SunColor_IsPrepreMultipliedByBrightness
  test to LoadFromRegion_SunColor_UsesRetailSunVectorMagnitude
  with the new expected magnitude.

User visually verified — acdream's sky shifted from blue-white toward
the warm tint retail shows at the same keyframe.

1227 tests pass.

src/AcDream.Core/World/SkyState.cs

@@ -67,19 +67,48 @@ public readonly record struct SkyKeyframe(
     FogMode FogMode  = FogMode.Linear)
 {
     /// <summary>
-    /// Final directional sun color used by the shader =
+    /// Final directional sun color the shader feeds into N·L lighting.
-    /// <see cref="DirColor"/> × <see cref="DirBright"/>. Computed property
+    /// Retail-faithful magnitude formula:
-    /// so the storage stays as separate channels (for retail-faithful
+    /// <code>SunColor = DirColor × |sunVec|</code>
-    /// keyframe interpolation) while the shader interface stays simple.
+    /// where <c>sunVec</c> is retail's heading+pitch+brightness vector
+    /// (see <see cref="SkyStateProvider.RetailSunVector"/>).
+    ///
+    /// <para>
+    /// Why <c>|sunVec|</c> instead of <c>DirBright</c> directly: retail's
+    /// <c>PrimD3DRender::UpdateLightsInternal</c> at <c>0x0059b57c</c>
+    /// (decomp line 424118-424119) computes
+    /// <code>D3DLIGHT9.Diffuse.r = sunlight_color.r × sqrt(x²+y²+z²)</code>
+    /// from the sun vector <c>SkyDesc::GetLighting</c> built at
+    /// <c>0x00500ac9</c> (decomp lines 261343-261353):
+    /// <code>
+    ///   sunVec.x = sin(H) × DirBright × cos(P)
+    ///   sunVec.y = cos(P)                    // NOT scaled by DirBright
+    ///   sunVec.z = DirBright × sin(P)
+    /// </code>
+    /// Because Y is unscaled by <c>DirBright</c>, <c>|sunVec|</c> ≠
+    /// <c>DirBright</c> in general — it varies with sun pitch and heading.
+    /// Using <c>DirBright</c> alone underweighted the warm directional
+    /// term, letting the cool ambient/fog dominate ⇒ acdream rendered
+    /// blue-white at keyframes where retail looked warm-gray.
+    /// </para>
     /// </summary>
-    public Vector3 SunColor => DirColor * DirBright;
+    public Vector3 SunColor => DirColor * SkyStateProvider.RetailSunVector(this).Length();
 
     /// <summary>
-    /// Final ambient color used by the shader =
+    /// Final ambient color the shader feeds into the per-vertex tint.
-    /// <see cref="AmbColor"/> × <see cref="AmbBright"/>. See
+    /// Retail-faithful magnitude formula:
-    /// <see cref="SunColor"/> for the rationale.
+    /// <code>AmbientColor = AmbColor × (AmbBright + 0.2 × |sunVec|)</code>
+    /// matching <c>SmartBox::SetWorldAmbientLight</c> as called at
+    /// <c>0x0050560b</c> (decomp line 267117):
+    /// <code>SetWorldAmbientLight(sqrt(|sunVec|²) × 0.2 + ambient_level, ambient_color)</code>
+    /// Retail boosts the ambient brightness by 20% of the sun-vector
+    /// magnitude — i.e. ambient feels warmer when the sun is up, cooler
+    /// at night. acdream previously used <c>AmbBright</c> alone, which
+    /// is roughly 44% too dim mid-day ⇒ contributed to the blue-white
+    /// bias because the warm fill was missing.
     /// </summary>
-    public Vector3 AmbientColor => AmbColor * AmbBright;
+    public Vector3 AmbientColor =>
+        AmbColor * (AmbBright + 0.2f * SkyStateProvider.RetailSunVector(this).Length());
 }
 
 /// <summary>
@@ -271,22 +300,52 @@ public sealed class SkyStateProvider
         return aDeg + delta * u;
     }
 
+    /// <summary>
+    /// Retail's raw sun vector (NOT normalized) — the same vector
+    /// <c>SkyDesc::GetLighting</c> writes at <c>0x00500ac9</c>
+    /// (decomp lines 261343, 261352, 261353):
+    /// <code>
+    ///   sunVec.x = sin(H_rad) × DirBright × cos(P_rad)
+    ///   sunVec.y = cos(P_rad)                    // NOT scaled by DirBright
+    ///   sunVec.z = DirBright × sin(P_rad)
+    /// </code>
+    /// Y is unscaled by brightness on purpose — that's what makes
+    /// <c>|sunVec|</c> ≠ <c>DirBright</c> in general (the magnitude varies
+    /// with pitch/heading, which is the basis for retail's "sun is brighter
+    /// in some configurations than others" lighting behavior). The shader's
+    /// <c>uSunDir</c> uniform uses the NORMALIZED vector for N·L; the
+    /// magnitude feeds <see cref="SkyKeyframe.SunColor"/> intensity and
+    /// the ambient brightness boost in <see cref="SkyKeyframe.AmbientColor"/>.
+    /// </summary>
+    public static Vector3 RetailSunVector(SkyKeyframe kf)
+    {
+        float h = kf.SunHeadingDeg * (MathF.PI / 180f);
+        float p = kf.SunPitchDeg * (MathF.PI / 180f);
+        float cosP = MathF.Cos(p);
+        float sinP = MathF.Sin(p);
+        float B = kf.DirBright;
+        return new Vector3(
+            MathF.Sin(h) * B * cosP,    // x = sin(H) × B × cos(P)
+            cosP,                        // y = cos(P)        ← unscaled by B
+            B * sinP);                   // z = B × sin(P)
+    }
+
     /// <summary>
     /// World-space sun direction unit vector pointing FROM the surface
-    /// TOWARDS the sun. Derived from heading + pitch in the returned
+    /// TOWARDS the sun, derived from <see cref="RetailSunVector"/> and
-    /// keyframe — shader sunDir uniform should use -this so lighting
+    /// normalized. The shader sunDir uniform should use this directly
-    /// math (N·L) works correctly for the side facing the sun.
+    /// (or -this if the lighting math wants the L-vector pointing AT the
+    /// surface). The previous implementation used standard spherical
+    /// coordinates (sin(H)cos(P), cos(H)cos(P), sin(P)) which didn't match
+    /// retail's deliberate Y-decoupled-from-heading convention. Switching
+    /// to the retail vector subtly tilts the lighting on objects but
+    /// matches retail's screenshots when both clients view the same scene.
     /// </summary>
     public static Vector3 SunDirectionFromKeyframe(SkyKeyframe kf)
     {
-        float yaw = kf.SunHeadingDeg * (MathF.PI / 180f);
+        var v = RetailSunVector(kf);
-        float pit = kf.SunPitchDeg * (MathF.PI / 180f);
+        float len = v.Length();
-        // Heading 0 = +Y (north), +X=east. Pitch up from horizon.
+        return len > 1e-6f ? v / len : Vector3.UnitZ;
-        float cosP = MathF.Cos(pit);
-        return new Vector3(
-            MathF.Sin(yaw) * cosP,
-            MathF.Cos(yaw) * cosP,
-            MathF.Sin(pit));
     }
 }
 

tests/AcDream.Core.Tests/World/SkyDescLoaderTests.cs

@@ -73,15 +73,26 @@ public sealed class SkyDescLoaderTests
     }
 
     [Fact]
-    public void LoadFromRegion_SunColor_IsPrepreMultipliedByBrightness()
+    public void LoadFromRegion_SunColor_UsesRetailSunVectorMagnitude()
     {
+        // The loader stores DirColor and DirBright RAW. The SunColor property
+        // composes them via |sunVec| per retail's UpdateLightsInternal at
+        // 0x59b57c (decomp 424118) — the diffuse magnitude is sqrt(x²+y²+z²)
+        // where the sun vector is built from heading/pitch/brightness with
+        // Y unscaled by brightness (decomp 261352).
+        //
+        // For this region:  H=180°, P=70°, B=1.5
+        //   sunVec = (sin(180)*1.5*cos(70), cos(70), 1.5*sin(70))
+        //          = (0, 0.342, 1.410)
+        //   |sunVec| = sqrt(0 + 0.117 + 1.988) = 1.4509
+        // DirColor.X = 200/255 = 0.7843
+        // SunColor.X = 0.7843 × 1.4509 = 1.138
         var region = MakeRegion(dirBright: 1.5f, rBgrOrder: 200);
         var loaded = SkyDescLoader.LoadFromRegion(region);
         Assert.NotNull(loaded);
 
         var kf = loaded!.DayGroups[0].SkyTimes[0].Keyframe;
-        // R was 200/255 ≈ 0.784, times dirBright 1.5 = 1.176
+        Assert.InRange(kf.SunColor.X, 1.13f, 1.15f);
-        Assert.InRange(kf.SunColor.X, 1.17f, 1.19f);
     }
 
     [Fact]

tests/AcDream.Core.Tests/World/SkyStateTests.cs

@@ -25,17 +25,105 @@ public sealed class SkyStateTests
     }
 
     [Fact]
-    public void Interpolate_BetweenKeyframes_LerpsColors()
+    public void Interpolate_BetweenKeyframes_LerpsRawInputs()
     {
         var sky = SkyStateProvider.Default();
         var dawn  = sky.Interpolate(0.25f);
         var noon  = sky.Interpolate(0.5f);
         var midPt = sky.Interpolate(0.375f);
 
-        // Midpoint should fall between dawn & noon for sun color Y (green channel).
+        // The RAW per-channel inputs (DirColor, AmbColor, brightness scalars)
-        float low  = System.Math.Min(dawn.SunColor.Y, noon.SunColor.Y);
+        // lerp linearly between adjacent keyframes — that's the retail-faithful
-        float high = System.Math.Max(dawn.SunColor.Y, noon.SunColor.Y);
+        // separate-channel interpolation. The composite SunColor / AmbientColor
-        Assert.InRange(midPt.SunColor.Y, low, high);
+        // properties intentionally do NOT lerp linearly (their magnitude
+        // depends nonlinearly on heading/pitch/brightness via the retail
+        // sun-vector formula), so we assert on the raw inputs here.
+        float low  = System.Math.Min(dawn.DirColor.Y, noon.DirColor.Y);
+        float high = System.Math.Max(dawn.DirColor.Y, noon.DirColor.Y);
+        Assert.InRange(midPt.DirColor.Y, low, high);
+    }
+
+    [Fact]
+    public void RetailSunVector_AtZenith_HasMagnitudeEqualToBrightness()
+    {
+        // Sun straight up (P=90°): cos(P)=0, sin(P)=1.
+        //   sunVec = (sin(H)×B×0, 0, B×1) = (0, 0, B)
+        //   |sunVec| = B
+        var kf = new SkyKeyframe(
+            Begin: 0.5f,
+            SunHeadingDeg: 0f,
+            SunPitchDeg:   90f,
+            DirColor:      Vector3.One,
+            DirBright:     1.5f,
+            AmbColor:      Vector3.One,
+            AmbBright:     0.3f,
+            FogColor:      Vector3.One,
+            FogDensity:    0f);
+
+        var v = SkyStateProvider.RetailSunVector(kf);
+        Assert.InRange(v.Length(), 1.49f, 1.51f);
+    }
+
+    [Fact]
+    public void RetailSunVector_AtHorizonNorth_MagnitudeIsOne()
+    {
+        // Sun on horizon to the north (H=0°, P=0°): cos(P)=1, sin(P)=0.
+        //   sunVec = (sin(0)×B×1, 1, B×0) = (0, 1, 0)
+        //   |sunVec| = 1   regardless of B   (because Y is unscaled by B)
+        var kf = new SkyKeyframe(
+            Begin: 0f,
+            SunHeadingDeg: 0f,
+            SunPitchDeg:   0f,
+            DirColor:      Vector3.One,
+            DirBright:     2.0f,           // anything
+            AmbColor:      Vector3.One,
+            AmbBright:     1f,
+            FogColor:      Vector3.One,
+            FogDensity:    0f);
+
+        var v = SkyStateProvider.RetailSunVector(kf);
+        Assert.InRange(v.Length(), 0.99f, 1.01f);
+    }
+
+    [Fact]
+    public void SunColor_UsesRetailMagnitudeNotDirBrightDirectly()
+    {
+        // At sun pitch 90° (zenith) with H=0, B=2: |sunVec| = 2.
+        // SunColor = DirColor × |sunVec| = (0.5, 0.5, 0.5) × 2 = (1, 1, 1).
+        var kf = new SkyKeyframe(
+            Begin: 0.5f,
+            SunHeadingDeg: 0f,
+            SunPitchDeg:   90f,
+            DirColor:      new Vector3(0.5f, 0.5f, 0.5f),
+            DirBright:     2.0f,
+            AmbColor:      Vector3.One,
+            AmbBright:     0.3f,
+            FogColor:      Vector3.One,
+            FogDensity:    0f);
+
+        Assert.InRange(kf.SunColor.X, 0.99f, 1.01f);
+        Assert.InRange(kf.SunColor.Y, 0.99f, 1.01f);
+        Assert.InRange(kf.SunColor.Z, 0.99f, 1.01f);
+    }
+
+    [Fact]
+    public void AmbientColor_BoostsByTwentyPercentOfSunVectorLength()
+    {
+        // |sunVec| = 1 (horizon north), AmbBright = 0.4, AmbColor = (1,1,1).
+        // AmbientColor = AmbColor × (AmbBright + 0.2 × |sunVec|)
+        //              = (1,1,1) × (0.4 + 0.2) = (0.6, 0.6, 0.6).
+        var kf = new SkyKeyframe(
+            Begin: 0f,
+            SunHeadingDeg: 0f,
+            SunPitchDeg:   0f,
+            DirColor:      Vector3.One,
+            DirBright:     1f,
+            AmbColor:      Vector3.One,
+            AmbBright:     0.4f,
+            FogColor:      Vector3.One,
+            FogDensity:    0f);
+
+        Assert.InRange(kf.AmbientColor.X, 0.59f, 0.61f);
     }
 
     [Fact]