EnvironmentSyncSystem

Applies the scene-level Environment component to the THREE.js scene each frame — background color, gradient textures, HDRI environment maps, and fog.

Overview

EnvironmentSyncSystem runs every frame and is responsible for:

• Generating canvas-based gradient textures (linear, radial, angular) from the color stops defined in the Environment component and setting them as scene.background.
• Loading HDRI or image URLs via THREE.TextureLoader and assigning them as scene.background and/or scene.environment.
• Applying solid color backgrounds directly as THREE.Color.
• Configuring THREE.FogExp2 or THREE.Fog from the fog sub-state (near, far, density, color).
• Disposing previous textures when the background changes to prevent GPU memory leaks.

Queried components

Component	Access
Environment	Read (background type, colors, fog state)

Behavior notes

• Signature-based change detection — the system serializes the entire Environment state into a string signature each frame. Texture regeneration and scene assignments only happen when the signature changes, so frequent re-renders don't rebuild the background every frame.
• Gradient texture — generated on a 512×512 <canvas> element. In server-side or non-DOM environments a single-pixel DataTexture fallback is used instead.
• Fog clamping — fog near and far values are clamped so far > near + 0.001 and density is clamped to ≥ 0. Invalid values are replaced with safe defaults.
• Pending image URL — image/HDRI loads are queued via an internal pending URL field; a stale load result is discarded if the component signature changed again before the load finished.

API reference

• Class: Environment
• Source: core/systems/EnvironmentSyncSystem.ts