Working With Material Assets In 3D

That means you can:

• create a Material asset from the asset browser
• choose whether it is Lit or Unlit
• optionally point that material at a custom Shader asset
• assign a base color
• tune Specular and Smoothness for the shared lit shader
• optionally assign a base texture
• assign that material to built-in 3D renderers from the Inspector

Materials pair with scene ambient light plus DirectionalLight and PointLight, so projects can move past flat per-component color alone.

What This Guide Covers

The material workflow is strongest for:

• CubeRenderer
• SphereRenderer
• CapsuleRenderer
• CylinderRenderer
• PlaneRenderer
• MeshRenderer
• ModelRenderer

Material behavior in this workflow:

• built-in primitive renderers use the material's base color
• the richer shared lit response now covers the built-in primitive renderer set
• MeshRenderer can use the material's base color and base texture
• ModelRenderer uses the material's base color
• when no material is assigned, built-in 3D renderers use their renderer base color consistently in Scene view and Play mode

Selecting a material asset now also renders a preview sphere in the Inspector using the same shared Lit / Unlit shader path, so Base Color, Specular, Smoothness, and textures can be judged without entering play mode.

Creating a Material Asset

1. In the Assets panel, create a new Material asset.
2. Give it a name that matches its role, such as PlayerBall, Pickup, or Ground.
3. Select the material asset to edit it in the Inspector.

The material Inspector exposes:

• Name
• Shader
• Shader Asset
• Base Texture
• Base Color
• Specular
• Smoothness
• a live preview sphere

Shader is still the built-in fallback mode.

Shader Asset is the custom programmable path.

Custom shader assets support this Surface3D shape:

• Domain = Surface3D
• Surface Mode = Unlit
• GLSL vertex and fragment source files

If the custom shader asset is invalid or unsupported, the material falls back to its built-in Shader mode instead of breaking rendering outright.

Assigning a Material to a Renderer

1. Select a game object with a built-in 3D renderer.
2. In the renderer card, find the Material field.
3. Pick a material asset or drag one onto the field.

That material reference is then serialized with the scene, so it round-trips cleanly through edit, save, and runtime load.

If the Material field is empty, Lenga falls back to the renderer's own base color. That fallback is shared by the editor preview and runtime, so a new cube, sphere, plane, mesh, or model should not change color just because you press Play.

Using A Custom Shader Asset

1. Create a Shader asset in the Assets panel.
2. Open the shader asset and assign its Vertex Source and Fragment Source.
3. Select a material asset.
4. Set Shader Asset to the shader you just created.
5. Assign that material to a 3D renderer.

Material preview now validates and compiles the referenced shader asset, so compile problems show up in the Inspector instead of only surfacing later at runtime.

To verify a custom shader-backed material, create a small material test scene with a cube, sphere, plane, mesh, or model that uses the material. Compare the Scene view and Play view so you know the shader, material values, and runtime fallbacks agree.

PHP Example

use Lenga\Engine\Core\Behaviour;
use Lenga\Engine\Core\MeshRenderer;

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

        $renderer->materialPath = 'Assets/Materials/Ground.material.json';
    }
}

The same materialPath pattern works across the built-in 3D renderer surface.

Lit vs Unlit

Lit and Unlit are the standard material modes.

Currently supported:

• Unlit is the right choice when you want predictable flat presentation
• Lit works with scene ambient plus DirectionalLight and PointLight

Lit works with scene ambient plus DirectionalLight and PointLight.

Limits to Keep in Mind

This guide focuses on reusable material assets, shared lighting, and editor preview support.