feat(core): add progressive runtime environment light capture

[GuoLei1990]

Summary

• Add EnvironmentLightCapture to progressively capture the active Scene.background.sky into diffuse L2 SH and a GGX-prefiltered specular cubemap.
• Spread six source-face captures, source-mipmap generation, and twelve GGX work slices across frames, then publish the double-buffered diffuse/specular result together through Scene.ambientLight.
• Keep SH projection and consumption on the GPU with Transform Feedback and a uniform buffer, avoiding a GPU-to-CPU readback during runtime updates.
• Support ordinary skybox materials and custom procedural sky materials through a frozen Material snapshot plus Scene.sun snapshot.

API and ownership

const capture = new EnvironmentLightCapture(scene, {
  resolution: 128,
  sampleCount: 64,
  includeSun: false
});

capture.requestUpdate();

// Call once from the application's frame update while work is pending.
capture.update();

V1 is deliberately On Demand: requestUpdate() records the newest sky revision and update() submits one scheduled work slice. A newer pending revision replaces an older pending one without interrupting the revision already in flight.

AmbientLight remains the authoritative owner consumed by PBR shading. EnvironmentLightCapture owns only the capture transaction, staging resources, and publication schedule. Only one capture object can own an AmbientLight at a time, and publication switches SH plus the specular cubemap in the same update.

Custom skies and the sun disk

Unity HDRP exposes the equivalent context as SkyRenderer.RenderSky(..., renderForCubemap, renderSunDisk). Galacean skies are Material/shader based rather than SkyRenderer subclasses, so this change provides the shader equivalents:

• SCENE_ENVIRONMENT_CAPTURE
• SCENE_ENVIRONMENT_CAPTURE_INCLUDE_SUN

The built-in procedural sky now keeps atmospheric scattering in the capture but omits its analytic solar disk by default. Direct sunlight still comes from Scene.sun. A custom procedural sky can use the same macros around its analytic disk; a disk already authored into a static cubemap cannot be removed after capture.

Each requested revision clones the sky Material and snapshots Scene.sun. Capture-varying custom parameters should live in Material shader data. Opaque Scene shader data is not copied into the private capture Scene because it also contains unrelated lighting, fog, and render-state ownership.

References:

• Unity HDRP SkyRenderer: https://github.com/Unity-Technologies/Graphics/blob/master/Packages/com.unity.render-pipelines.high-definition/Runtime/Sky/SkyRenderer.cs
• Unity HDRP SkySettings update modes and includeSunInBaking: https://docs.unity3d.com/cn/Packages/com.unity.render-pipelines.high-definition%407.4/api/UnityEngine.Rendering.HighDefinition.SkySettings.html
• Unreal Engine 5.8 Sky Light capture and Real Time Capture: https://dev.epicgames.com/documentation/en-us/unreal-engine/sky-lights-in-unreal-engine

Scope

• This is distant-sky environment lighting (diffuse SH plus specular IBL), not dynamic-geometry GI, DDGI, SSR, or local reflection probes.
• The implementation requires WebGL2 and renderable half-float textures. The public capture contract does not expose WebGL objects, leaving room for a future WebGPU implementation.
• Target-mobile GPU timing and final quality presets are intentionally left for follow-up profiling; the default 128 resolution and 64 GGX samples are initial quality parameters, not measured performance claims.

Verification

• corepack pnpm build
• corepack pnpm lint (0 errors; existing repository warnings remain)
• corepack pnpm vitest run tests/src/core/EnvironmentLightCapture.test.ts tests/src/core/RealtimeIBLPrefilterSchedule.test.ts tests/src/core/RealtimeIBLSourceMipmapSchedule.test.ts (3 files, 4 tests)
• git diff --check origin/dev/2.0...HEAD

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: da5ca691-ad88-4390-97a1-695882cd066f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 92.42820% with 87 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.66%. Comparing base (bd34daa) to head (8e3d46a).

Files with missing lines	Patch %	Lines
...rc/lighting/environment/EnvironmentLightCapture.ts	92.51%	50 Missing ⚠️
...ghting/environment/RealtimeIBLPrefilterSchedule.ts	88.47%	25 Missing ⚠️
...hting/environment/RealtimeSphericalHarmonicsGPU.ts	93.68%	6 Missing ⚠️
...ing/environment/RealtimeIBLSourceMipmapSchedule.ts	94.28%	4 Missing ⚠️
packages/core/src/lighting/environment/index.ts	0.00%	0 Missing and 1 partial ⚠️
packages/core/src/sky/index.ts	0.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           dev/2.0    #3089      +/-   ##
===========================================
+ Coverage    85.42%   85.66%   +0.24%     
===========================================
  Files          811      816       +5     
  Lines        94654    95800    +1146     
  Branches     11512    11712     +200     
===========================================
+ Hits         80854    82069    +1215     
+ Misses       13710    13640      -70     
- Partials        90       91       +1     

Flag	Coverage Δ
unittests	85.66% <92.42%> (+0.24%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.