Lighting 3D Scenes

• scene ambient light
• DirectionalLight
• PointLight
• basic directional shadows
• scene skyboxes
• Lit and Unlit material modes
• reusable Material assets on built-in 3D renderers

Use these features to move 3D scenes beyond flat debug-looking geometry and toward a more complete lit authoring workflow inside Lenga.

What This Workflow Covers

The shared 3D lighting path supports:

• scene-level Ambient Color
• scene-level Ambient Intensity
• DirectionalLight
• PointLight
• directional-light shadows
• Skybox assets assigned at the scene level
• a bundled default engine skybox when a scene does not assign its own
• material Specular
• material Smoothness
• the richer shared lit response on CubeRenderer, SphereRenderer, PlaneRenderer, MeshRenderer, and ModelRenderer
• shared directional shadows across the built-in 3D renderer surface

That means you can:

1. Create a material asset.
2. Assign that material to a sphere, cube, plane, mesh, or model renderer.
3. Add a Directional Light game object to the scene.
4. Add one or more Point Light game objects where you want local accents.
5. Enable shadows on the directional light when the scene needs stronger grounding.
6. Tune ambient light at the scene level.
7. Assign a scene skybox, or rely on the bundled default.
8. See lit 3D geometry at runtime.

Authoring Ambient Light

Scene ambient is part of the scene settings.

Scene fields:

• Ambient Color
• Ambient Intensity

Use ambient light to keep shadow-facing surfaces readable. Keep it modest. The directional light should still do most of the shaping.

Adding A Directional Light

Use this authoring flow:

1. Create a new light game object.
2. Add a DirectionalLight component.
3. Rotate the game object to aim the light.
4. Set Color and Intensity.
5. Enable and tune shadows if the scene needs them.

The light direction comes from the game object's transform. There is no separate direction vector field to maintain.

Directional shadows are owned by DirectionalLight. The supported shadow workflow includes:

• one shared shadow map
• directional-light shadows only
• no point-light shadows
• no cascades

That gives scenes much better grounding while keeping the shadow workflow simple and predictable.

Directional Shadows

Directional shadows are authored on the DirectionalLight component.

Directional shadow controls:

• Cast Shadows
• Shadow Strength
• Shadow Bias
• Shadow Size
• Shadow Distance

Recommended starting values:

• Cast Shadows: on
• Shadow Strength: around 0.55 to 0.75
• Shadow Bias: around 0.0015 to 0.0035
• Shadow Size: around 14 to 24
• Shadow Distance: around 20 to 36

Shadow Size controls the orthographic coverage of the shadow camera. Smaller values give tighter, sharper shadows for compact scenes. Larger values cover more space, but the same map resolution has to stretch farther.

Shadow Distance controls how far from the active game camera the directional shadow solution tries to cover.

Adding A Point Light

Use a point light when you want local color and shape instead of whole-scene sunlight.

1. Create a new game object.
2. Add a PointLight component.
3. Move it to the area you want to accent.
4. Tune Color, Intensity, and Range.

Point lights are especially useful for:

• collectibles
• goal pads
• interior props
• cool/warm fill near the player

Recommended Starting Setup

For a clean stylized scene:

• Ambient Intensity: around 0.2 to 0.35
• DirectionalLight Intensity: around 1.0 to 1.3
• PointLight Intensity: around 0.8 to 1.6
• PointLight Range: around 4 to 10
• a slightly warm light color for sunlight
• a cooler ambient color for fill

That gives a readable scene without flattening everything back out.

Pairing Materials With Light

Lit materials are the normal choice for 3D gameplay surfaces.

The material asset inspector now also exposes:

• Specular
• Smoothness

Those let you decide whether a surface should read as soft and chalky or glossy and rounded under the shared lit shader.

Use them for:

• ground
• player ball
• pickups
• blockers
• simple props

Use Unlit materials when you intentionally want flat presentation, UI-like 3D accents, or debug visuals.

Scene Skyboxes

Skyboxes are now scene-level authoring, not a sample-only trick.

Skybox workflow:

1. Create a Skybox asset from the asset browser if you want a custom sky, or use one of the bundled engine skyboxes.
2. Select the scene itself in the Inspector.
3. Set the Skybox field in the scene lighting/backdrop section.
4. If you are editing a custom skybox asset, choose a mode:
   • Procedural
   • Panorama
   • Cubemap

If you leave the scene Skybox field empty, Lenga uses the bundled engine default skybox automatically. That default is sourced from res/images/StandardCubeMap.png during development and bundled into exported builds.

Lenga also ships with a small bundled cubemap catalog from Screaming Brain Studios. Search for SBS Cloudy Sky in the scene Skybox picker to try those out-of-the-box skies. They are credited in the editor under Help -> Credits... and copied into exported builds with their license file.

PHP Example

use Lenga\Engine\Core\Behaviour;
use Lenga\Engine\Core\DirectionalLight;
use Lenga\Engine\Core\PointLight;

final class SunTweaker extends Behaviour
{
    public function start(): void
    {
        $light = $this->gameObject->getComponent(DirectionalLight::class);
        if (!$light instanceof DirectionalLight) {
            return;
        }

        $light->intensity = 1.15;
        $light->shadowsEnabled = true;
        $light->shadowStrength = 0.65;
        $light->shadowBias = 0.0025;
        $light->setColor(255, 241, 214, 255);
    }
}

final class PickupLightTweaker extends Behaviour
{
    public function start(): void
    {
        $light = $this->gameObject->getComponent(PointLight::class);
        if (!$light instanceof PointLight) {
            return;
        }

        $light->intensity = 1.35;
        $light->range = 6.0;
        $light->setColor(255, 213, 122, 255);
    }
}

The lighting workflow includes scene ambient light, DirectionalLight, PointLight, shadows, skyboxes, and material-aware editor previews.