erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source 
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.
This commit is contained in:
Erik 2026-04-27 22:42:53 +02:00
parent 97fc1b51d8
commit 05a8a7209f
3 changed files with 186 additions and 28 deletions
Download patch file Download diff file Expand all files Collapse all files

99
src/AcDream.Core/World/SkyState.cs
View file

@ -67,19 +67,48 @@ public readonly record struct SkyKeyframe(
FogMode FogMode = FogMode.Linear)
{
/// <summary>
/// Final directional sun color used by the shader =
/// <see cref="DirColor"/> × <see cref="DirBright"/>. Computed property
/// so the storage stays as separate channels (for retail-faithful
/// keyframe interpolation) while the shader interface stays simple.
/// Final directional sun color the shader feeds into N·L lighting.
/// Retail-faithful magnitude formula:
/// <code>SunColor = DirColor × |sunVec|</code>
/// 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 =
/// <see cref="AmbColor"/> × <see cref="AmbBright"/>. See
/// <see cref="SunColor"/> for the rationale.
/// Final ambient color the shader feeds into the per-vertex tint.
/// Retail-faithful magnitude formula:
/// <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
/// keyframe — shader sunDir uniform should use -this so lighting
/// math (N·L) works correctly for the side facing the sun.
/// TOWARDS the sun, derived from <see cref="RetailSunVector"/> and
/// normalized. The shader sunDir uniform should use this directly
/// (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);
float pit = kf.SunPitchDeg * (MathF.PI / 180f);
// Heading 0 = +Y (north), +X=east. Pitch up from horizon.
float cosP = MathF.Cos(pit);
return new Vector3(
MathF.Sin(yaw) * cosP,
MathF.Cos(yaw) * cosP,
MathF.Sin(pit));
var v = RetailSunVector(kf);
float len = v.Length();
return len > 1e-6f ? v / len : Vector3.UnitZ;
}
}

17
tests/AcDream.Core.Tests/World/SkyDescLoaderTests.cs
View file

@ -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.17f, 1.19f);
Assert.InRange(kf.SunColor.X, 1.13f, 1.15f);
}
[Fact]

98
tests/AcDream.Core.Tests/World/SkyStateTests.cs
View file

@ -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).
float low = System.Math.Min(dawn.SunColor.Y, noon.SunColor.Y);
float high = System.Math.Max(dawn.SunColor.Y, noon.SunColor.Y);
Assert.InRange(midPt.SunColor.Y, low, high);
// The RAW per-channel inputs (DirColor, AmbColor, brightness scalars)
// lerp linearly between adjacent keyframes — that's the retail-faithful
// separate-channel interpolation. The composite SunColor / AmbientColor
// 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]