Environments

An environment defines the lighting context for a scene — image-based lighting (IBL) cubemaps, a background panorama, and atmospheric conditions. Environment files live in engine_defaults/environments/ and are referenced from scene nodes via the environments:// URI scheme.

---

File Structure

{
    "description": "Neutral — flat grey IBL environment",
    "type": "ibl_environment",
    "ibl": {
        "specular": "textures://environments/neutral/ggx/specular.ktx2",
        "diffuse": "textures://environments/neutral/lambertian/diffuse.ktx2",
        "sheen": "textures://environments/neutral/charlie/sheen.ktx2",
        "brdf_lut": "textures://environments/neutral/outputLUT.ktx2",
        "mip_levels": 11
    },
    "background": {
        "panorama": "textures://environments/neutral/neutral.hdr"
    },
    "intensity": 1.0,
    "atmosphere": {
        "fogColor": [0.7, 0.75, 0.8],
        "fogDensity": 0.01,
        "fogStart": 10.0,
        "fogEnd": 200.0,
        "scatteringStrength": 0.0
    }
}

---

Top-Level Keys

Key	Type	Required	Description
description	string	No	Human-readable label
type	string	Yes	Must be "ibl_environment"
ibl	object	Yes	IBL cubemap references
background	object	No	Background panorama
intensity	float	No	Global IBL intensity multiplier (default 1.0)
atmosphere	object	No	Fog and aerial perspective settings

---

IBL Block

The engine uses a split-sum PBR IBL pipeline with separate cubemaps for each BRDF lobe.

Key	Type	Description
specular	string	GGX-filtered specular cubemap (KTX2). Used for metallic/dielectric reflections
diffuse	string	Lambertian-convolved irradiance cubemap (KTX2)
sheen	string	Charlie-filtered sheen cubemap (KTX2). Used for fabric/velvet materials
brdf_lut	string	Pre-computed BRDF integration LUT (KTX2)
mip_levels	int	Number of mip levels in the specular cubemap (controls roughness range)

All cubemap URIs use the textures:// scheme and point to KTX2 files with UASTC compression.

---

Background Block

Key	Type	Description
panorama	string	HDR equirectangular panorama used as the skybox background

---

Atmosphere Block

The atmosphere block defines the artistic intent for fog and aerial perspective. These values are the desired settings — the engine config's atmosphere section can clamp or disable them for performance.

Key	Type	Default	Description
fogColor	float[3]	[0.7, 0.75, 0.8]	Linear RGB fog color
fogDensity	float	0.01	Exponential fog density coefficient
fogStart	float	10.0	Distance (world units) where fog begins
fogEnd	float	200.0	Distance where fog reaches full opacity
scatteringStrength	float	0.0	Rayleigh/Mie scattering intensity (0 = no scattering, linear fog only)

note

When atmosphere.enabled is false in the engine config, the entire atmosphere block is ignored regardless of what the environment defines. When atmosphere.maxDistance is set in the engine config, fogEnd is clamped to that value.

---

Scene Node Usage

An environment is attached to a scene via an environment node:

{
    "name": "environment",
    "type": "environment",
    "environment": "environments://neutral.json",
    "properties": {
        "blur": 1.0
    }
}

Property	Type	Description
blur	float	Background blur level (0 = sharp, 1 = fully blurred)

---

Where to go next

• Quality Overrides — engine config settings that govern atmosphere and material LOD
• Scenes — how scenes reference environments
• Materials — PBR material system