acdream/docs/research/2026-04-21-sky-deep-audit.md

Deep Audit: Sky Rendering Bug

Date: 2026-04-21 Issue: Sky renders fully white despite keyframe data being pale blue/orange; framebuffer cleared to black. Hypothesis: At least one of 7 sky objects is painting white across the view; rendering pipeline produces white, not data.

Angle 1 — Retail Decompile: What the Sky Renderer Actually Does

Finding: Could Not Locate Retail Sky Render Function

Status: COULDN'T LOCATE

After search of chunk_00400000.c through chunk_007F0000.c, found only one match:

• docs/research/decompiled/chunk_00500000.c:7340 comment about GameTime effects on sky

No functions containing sky, Sky, SkyObjects, CEnvironment, or D3D render-state constants found.

---

Angle 2 — ACE: What Server Messages Drive Sky / Weather / Time?

Retail Source: EnvironChangeType Enum

• references/ACE/Source/ACE.Entity/Enum/EnvironChangeType.cs:4-48

Only fog overlays and sound effects; NO mesh/texture/geometry changes:

public enum EnvironChangeType {
    Clear, RedFog, BlueFog, WhiteFog, GreenFog, BlackFog, BlackFog2,
    RoarSound, ... /* sound effects only */
}

Sent via: GameMessageAdminEnvirons (admin-only, not broadcast)

Our Code: Network Handling

• src/AcDream.Core.Net/Messages/GameEvents.cs:1-481 — No sky/weather parsers
• src/AcDream.Core.Net/WorldSession.cs — No AdminEnvirons handler

Verdict: MISSING But the bug symptoms (fully white sky) are NOT consistent with WhiteFog overlay; this is client-side rendering failure, not a server message issue.

---

Angle 3 — ACME: Improved Sky Rendering

Finding: No ACME-Specific Sky Renderer

ACME contributes only animation/model reference; does not override WorldBuilder SkyboxRenderManager. We port vanilla WorldBuilder unchanged.

---

Angle 4 — WorldBuilder Vanilla: Re-read for Details

Key Finding: Per-Submesh Blend Mode Divergence

WorldBuilder (references/WorldBuilder/.../SkyboxRenderManager.cs:301-318):

foreach (var batch in renderData.Batches) {
    // ... bind texture, sampler ...
    _gl.DrawElementsInstancedBaseVertex(...);
    // NO BlendFunc call per batch
}

Our Code (src/AcDream.App/Rendering/Sky/SkyRenderer.cs:175-196):

foreach (var sub in subMeshes) {
    if (sub.IsAdditive)
        _gl.BlendFunc(BlendingFactor.SrcAlpha, BlendingFactor.One);
    else
        _gl.BlendFunc(BlendingFactor.SrcAlpha, BlendingFactor.OneMinusSrcAlpha);
    // ... draw
}

We set blend state PER SUBMESH; retail does NOT. This adds a failure point: if IsAdditive classification is wrong, one mesh renders with wrong blend mode.

---

Angle 5 — Our Code: End-to-End

A) Data Loading

src/AcDream.Core/World/SkyDescLoader.cs: MATCHES retail

Loads Region 0x13000000, parses 7 sky objects with correct color data.

B) Blend Mode Classification

src/AcDream.App/Rendering/Sky/SkyRenderer.cs:314

bool isAdditive = sm.Translucency == TranslucencyKind.Additive;

CRITICAL COMMENT (lines 311-313):

// NOTE: earlier revision also treated SurfaceType.Luminous = 0x40
// as additive, but that flag is present on the sky DOME itself and
// on cloud sheets — turning those additive blew the whole sky to
// white. Luminous means self-illuminated, not additive.

This documents a PAST WHITE-SKY BUG caused by misclassifying Luminous as additive.

Question: Is the current fix correct? Did we introduce a NEW misclassification?

C) Shader Luminosity

src/AcDream.App/Rendering/Shaders/sky.frag:36-59

vec3 rgb = sampled.rgb * uTint.rgb * uLuminosity;

If sampled texture is white (1,1,1) and uLuminosity=1, output is white.

---

Root-Cause Hypothesis Ranked by Confidence

Hypothesis 1 (HIGH CONFIDENCE): IsAdditive Misclassification

Evidence:

• Comment at SkyRenderer.cs:311-313 documents past white-sky incident from Luminous misclassification
• We changed code to only treat Additive=0x10000 as additive, skipping Luminous=0x40
• But IsAdditive is computed once at upload and NEVER re-checked or validated
• We diverge from retail by setting blend per submesh, creating a failure point

Symptom matches:

• Sky fully white = additive blend of white mesh over black framebuffer
• Black clear makes problem visible

Acceptance test: Log SurfaceType flags for all 7 sky objects and verify IsAdditive classification matches retail expectations.

Hypothesis 2 (MEDIUM CONFIDENCE): Texture Decode Produces White

Evidence:

• TextureCache.GetOrUpload at SkyRenderer.cs:188
• If surface texture is decoded incorrectly, white pixels result

Acceptance test: Compare decoded texture bytes against expected color data.

Hypothesis 3 (LOW CONFIDENCE): Luminosity Override

Evidence:

• Diag shows luminosity values max at 0.78 (not > 1)
• Shader applies multiplicatively; shouldn't blow white unless texture is already near-white

Less likely: Keyframe data is not driving the issue.

---

Next Fix: Verify IsAdditive Classification

Target: src/AcDream.App/Rendering/Sky/SkyRenderer.cs:276-325 (UploadSubMesh)

Action: Add logging to print SurfaceType flags and IsAdditive result for each sky mesh surface.

Concrete change:

private SubMeshGpu UploadSubMesh(GfxObjSubMesh sm) {
    // ... setup ...
    bool isAdditive = sm.Translucency == TranslucencyKind.Additive;
    
    System.Diagnostics.Debug.WriteLine(
        $"Sky Surface {sm.SurfaceId}: Translucency={sm.Translucency}, IsAdditive={isAdditive}");
    
    return new SubMeshGpu { ... };
}

Run test, check Debug output against SurfaceType enum definitions and retail behavior.

Acceptance test: No sky object shows:

• SurfaceType.Luminous (0x40) misclassified as IsAdditive=true
• SurfaceType.Additive (0x10000) misclassified as IsAdditive=false

---

Conclusion

Bug is client-side rendering pipeline, not data or server messages. Most likely cause: IsAdditive misclassification on a dominant sky mesh (dome or sun). The codebase already documents a past white-sky incident from this exact error.

Verify by logging SurfaceType flags for all 7 sky objects and comparing against retail specifications.