Skip to content
vgai Learn

Light a scene with an HDR skybox (IBL)

quick start Intermediate ⏱ 5 min vgai 0.1.0

Prerequisites: Installed vgai and run the editor

What you'll learn

  • Set an equirectangular HDR as a scene's skybox
  • Understand that the same map drives both the background and IBL
  • Tune the look with envMapIntensity and tone mapping

What you'll build: Three spheres (chrome, brushed metal, glossy dielectric) lit and reflecting a real HDR sky.

Walkthrough — Light a scene with an HDR skybox (IBL) · generated by site/media/lessons/learn-skybox.lesson.ts (4 steps)

An equirectangular HDR (a 2:1 panorama of the sky) is the cheapest way to make a scene look real: it becomes both the background you see and the lighting on every surface. You don’t place any lights — the sky is the light. Point environment.skybox at the file and the engine does the rest.

Steps

Section titled “Steps”

  1. The scene is already open. If you followed the link above, the skybox scene is loaded and rendering (in the local dev editor: VGAI_PROJECT=examples/feature-scenes npm run dev, then open scenes/learn-skybox.vscn.json). Three spheres sit under a real HDR sky. The engine loaded textures/learn-sky.hdr with RGBELoader, ran it through a PMREMGenerator, and assigned the result to both scene.background and scene.environment.

    Three spheres under an HDR sky
    One HDR file is the sky and the light.

  2. The chrome sphere mirrors the sky. A metalness: 1, roughness: 0.05 material is a near-mirror — its blue gradient is the sky reflected in the metal (remove the skybox and the same sphere goes dark). That reflection is the env map: image-based lighting (IBL).

    Chrome sphere reflecting the sky
    Pure metal mirrors scene.environment.

  3. The glossy red sphere picks up the sky. A dielectric (metalness: 0) with low roughness isn’t a mirror, but its specular highlight is the sky — so it still reads as lit by the environment.

    Glossy red sphere with a sky highlight
    Dielectrics catch the sky in their highlights.

  4. The brushed sphere shows blurred IBL. Raise roughness (0.45) and the reflection blurs — PMREM pre-filters the env map into mip levels so rough surfaces sample a softer sky. Same map, rougher look.

    Brushed metal sphere with blurred reflection
    Roughness blurs the reflection — pre-filtered IBL.
// the whole skybox setup is three lines of environment:
"environment": {
  "skybox": "textures/learn-sky.hdr",
  "envMapIntensity": 1.0,
  "toneMapping": { "mode": "aces", "exposure": 1.0 }
}

Recap

New functionality

  • Set an equirectangular HDR as the scene's skybox
  • Saw chrome / glossy / brushed spheres lit and reflecting it

New concepts & skills

  • environment.skybox → RGBELoader/TextureLoader → PMREM → scene.background + scene.environment
  • the same map is both the visible sky and the image-based lighting (no explicit lights)
  • roughness blurs the reflection (PMREM mip levels); envMapIntensity + toneMapping tune the look

Next lesson → Materials (manual)

On Your Own!

Extend what you built:

  • Swap in your own equirectangular HDR (any 2:1 panorama) and reload
  • Lower envMapIntensity to 0.3 — the spheres go dim; raise it for punchier reflections
  • Change a sphere's roughness and watch the reflection sharpen or blur

See also

Section titled “See also”