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:

```csharp
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):**
```csharp
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):**
```csharp
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

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

**CRITICAL COMMENT (lines 311-313):**
```csharp
// 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

```glsl
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:**
```csharp
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.