UseLegacyLights or light rescaling: preserving brightness across three.js versions

Question

Brightness Preservation Choice in three.js Upgrades

When upgrading a three.js project, the same numeric light intensities produce different visual brightness depending on whether the renderer uses the legacy non‑physical scaling or the current physically correct lighting mode. The WebGLRenderer.useLegacyLights flag can restore the old behavior where it exists, but it has been deprecated and may be absent in newer releases.

For a fixed scene that must retain identical appearance across versions, the decision is whether to keep useLegacyLights = true (when available) or to abandon the flag and rescale light/material values to match the new default.

Because the flag’s presence, default value, and deprecation status vary between builds, it is unclear which approach yields a reliable, future‑proof solution.

In which three.js releases does useLegacyLights exist, what is its default, and does accessing it produce a warning?
If the flag is missing, does the renderer silently fall back to physically correct lighting or throw an error?

Tasadduq Burney · Answer

The Recommended Approach
To ensure a future-proof scene, you should abandon the useLegacyLights flag and rescale your light intensities to match the physically correct lighting model. Relying on the legacy flag is a temporary fix that will eventually fail as the property is removed from the WebGLRenderer.

Behavior of useLegacyLights
The useLegacyLights property was introduced as a bridge during the transition to physically correct lighting (based on real-world units like lumens and candelas). Its behavior across versions is as follows:

Availability: The flag existed in several versions during the transition period. In very recent releases, it has been removed entirely.
Default Value: The default shifted from true (legacy) to false (physically correct) as the library standardized its lighting model.
Warnings: In versions where the flag was deprecated but still present, setting or accessing it typically triggered a console warning.
Fallback: If the flag is missing (in newer versions), the renderer does not throw a runtime error. Instead, it silently defaults to physically correct lighting, which usually results in a significant visual change in brightness.

Migration Steps
If you are upgrading and find your scene has become too dark or too bright due to the removal of legacy lighting, follow these steps:

Remove the flag: Delete renderer.useLegacyLights = true; from your codebase.
Adjust Intensity: Physically correct lighting uses different scaling. You will likely need to increase the intensity values of your PointLight, SpotLight, and DirectionalLight objects.
Verify Color Space: Ensure your renderer is using the correct color management settings (e.g., outputColorSpace = THREE.SRGBColorSpace), as physical lighting is designed to work with linear-to-sRGB workflows.

Verification
You can verify the current state of your renderer by checking the object in the browser console:
console.log(renderer.useLegacyLights);
If the result is undefined, your version of three.js has fully moved to physically correct lighting, and any legacy intensity values must be manually rescaled.

Diagnostic Detail Needed: To provide specific scaling ratios, please provide the exact version of three.js you are upgrading from and to.

UseLegacyLights or light rescaling: preserving brightness across three.js versions

Brightness Preservation Choice in three.js Upgrades

1 answer

The Recommended Approach

Behavior of useLegacyLights

Migration Steps

Verification

Your perspective belongs here.

0 question comments