How to Properly Use createDefaultEnvironment for Skybox?

Questions
1

Hi everyone,

I’ve been trying to set up realistic lighting and background in my Babylon.js scene using an HDR environment map, but I’ve run into some confusing issues. Here’s what I’ve tried and where I’m stuck:

Initially, I used PhotoDome with a panoramic HDR image—it was super easy to get a spherical background working.

Later, I read that scene.createDefaultEnvironment() is supposed to be a more complete, “all-in-one” solution that handles environment lighting, skybox, and image-based lighting (IBL) automatically. So I switched to that, hoping it would simplify everything.

To optimize performance, I converted my original equirectangular HDR file into a prefiltered .env file (using standard IBL tools). At this point, I started noticing that environment lighting (reflections), glass transmission, and the skybox background are actually three separate things—not just “lighting vs. skybox” as I originally thought:

  1. Reflections appeared as soon as I created a CubeTexture.

  2. Correct glass/refraction rendering only worked after I assigned the texture to scene.environmentTexture.

  3. The skybox background needed to be set up separately.

Now, many sources claim that if you pass an environmentTexture to createDefaultEnvironment() and set createSkybox: true, it should automatically use the same texture for the skybox and keep everything aligned with the lighting.

But in practice, this doesn’t work with .env files. Even though the IBL (reflections and transmission) works perfectly, no skybox appears.

I tried explicitly passing the same .env file via the skyboxTexture option, using both:

  • CubeTexture.CreateFromPrefilteredData()

  • new CubeTexture()

Result? The skybox does show up when I provide skyboxTexture, but it’s visibly misaligned—the cube seams are obvious, and it looks like a literal box rather than a seamless environment.

Interestingly, when I use scene.createDefaultSkybox() directly (without createDefaultEnvironment), it works flawlessly and creates a proper seamless skybox.

So my question is:

Is createDefaultEnvironment() actually not suitable for creating a synchronized skybox + IBL setup when using .env files?

It’s supposed to be the “recommended integrated solution,” but it seems to have significant limitations in practice. Am I missing something? Or is it simply not designed to handle skybox rendering from .env files (which typically lack the base mip level needed for background display)?

Any guidance or best practices would be greatly appreciated!

Finally, here’s a link to my test code for reference: https://playground.babylonjs.com/?inspectorv2=true#BH23ZD#831

2

When you pass your own texture for the skybox to createDefaultEnvironment, the system uses it for the skybox material without doing any changes to it. It’s your responsibility to set the right projection mode for a skybox. Here, you should set it to TEXTURE_SKYBOX_MODE:

Note that I cloned the hdr texture so that the coordinate mode doesn’t change for the scene environment texture.

1 Like
3

Got it! The issue has been successfully resolved—thanks so much for the clear and helpful reply!

One small suggestion: it would be really helpful for future users if the line

skyTexture.coordinatesMode = BABYLON.Constants.TEXTURE_SKYBOX_MODE;

could be added to the “Using An HDR Environment For PBR” documentation section. That tiny detail makes all the difference when aligning the skybox with the environment lighting!

4

Want to add it yourself?

It’s very simple:

  • Go to the page in the documentation repository
  • Click on the “Github” icon at the bottom right of the page:
    image
    image163×115 969 Bytes

You can now edit the page, update it, and save your changes, which will automatically create a PR with those changes.

1 Like
5

I just ran a few more tests and now feel this documentation addition isn’t really appropriate for me to make.

Sure, I could fork the repo and add a note under either “Fast Build A World” or “Using An HDR Environment For PBR”, something like:

“If you want to use createDefaultEnvironment to set up both IBL and skybox simultaneously, you need to do X, Y, Z…”

But honestly, that might be more misleading than helpful.

The current implementation of createDefaultEnvironment is designed as an “all-in-one” environment helper, yet it treats the environment texture and skybox texture as two separate objects internally. This leads to unexpected behavior—for example, changing scene.environmentIntensity only affects the environmentTexture, not the skyboxTexture.

Earlier documentation and community guidance strongly implied (and still implies) that if you provide only environmentTexture and set createSkybox: true, createDefaultEnvironment should automatically use that same texture for the skybox. Even the two most detailed documentation sections about this method subtly reinforce that expectation: “Just give it your environment texture—everything else will be handled for you.”

Technically, there’s no major obstacle here. In fact, createDefaultSkybox already does exactly what most users actually need: it takes a single texture and correctly sets up both the skybox background and the environment lighting, with full synchronization (including environmentIntensity, rotation, etc.).

So in my view, createDefaultEnvironment isn’t quite living up to its original design intent. It’s supposed to simplify a complex setup—but instead, it cost me a whole week :sob:—and it’s not even clear why it needs to behave differently from createDefaultSkybox in this regard. If advanced users really need separate control over environmentTexture and skyboxTexture, Babylon already provides lower-level APIs for that.

In short: the ideal “batteries-included” helper already exists (createDefaultSkybox), and createDefaultEnvironment might be overcomplicating things without clear benefit.

6

No, it’s a lot simpler than that to update a page in the documentation, you don’t have to fork the repo: just click on the “Github” icon on the page when browsing the documentation repo (https://doc.babylonjs.com/), and you will be able to edit the page, make your changes and save them. This will automatically create a PR that you will only have to validate.

Anyway, I understand your frustation, let’s see what @PatrickRyan think about it and if we could improve things on the default environment front.

1 Like