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
• 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

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.

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.

The RollerWorld sample project includes a working example:

• Assets/Shaders/PickupBands.shader.json
• Assets/Materials/Pickup.material.json

The pickups in Level1.scene.json and ObstacleCourse.scene.json use that custom shader-backed material.

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.