defold-pbr

Reusable PBR shader library for Defold projects.

This asset provides a base metallic-roughness PBR material and shader stack that can be used directly, or included by another extension that adds features such as image based lighting.

Included Files

Base PBR material and programs:

• /defold-pbr/pbr.material
• /defold-pbr/shaders/pbr.vp
• /defold-pbr/shaders/pbr.fp

The shader uses Defold model PBR constants from the PbrMaterial uniform block and binds glTF textures by the sampler names populated by the model component. It supports metallic-roughness base color data, normal/occlusion/emissive textures, alpha cutoff/unlit flags, and directional/point/spot lights from Defold's light component buffer.

Image based lighting and additional glTF material extensions are intentionally left out of this base asset. Extension projects can include these shaders and inject extra lighting into PBRLightData before final composition.

Installing In A Project

Add this asset as a dependency in game.project:

[project]
dependencies#0 = https://github.com/defold/asset-pbr/archive/refs/heads/master.zip

If your project already has dependencies, use the next available dependency index instead of dependencies#0.

Fetch libraries from the Defold editor with Project > Fetch Libraries. After fetching, the asset is available under /defold-pbr.

Using The Material

Assign /defold-pbr/pbr.material to any model that should use the base PBR shader.

For imported glTF/glB content, keep the sampler names generated by Defold's model pipeline:

PbrMetallicRoughness_baseColorTexture
PbrMetallicRoughness_metallicRoughnessTexture
PbrMaterial_normalTexture
PbrMaterial_occlusionTexture
PbrMaterial_emissiveTexture

The material expects the standard Defold PBR material constants:

PbrMaterial
PbrMetallicRoughness

These are normally populated by the model component when using imported glTF material data.

Lighting

Use Defold's built-in light components for punctual lighting:

• directional light
• point light
• spot light

The shaders include /builtins/materials/lighting.glsl, so light data comes from Defold's LightBuffer instead of a custom uniform array. Ambient light is read from the built-in light_info.xyz value.

The base shader handles the same light loop shape as Defold's built-in lighting.glsl: it reads light_info.w for the active light count and loops over MAX_LIGHT_COUNT.

Render Script Requirements

Use a render script that draws models with a camera view/projection and allows Defold to provide the light buffer to materials. A typical model draw path is enough:

render.set_view(camera.view)
render.set_projection(camera.proj)
render.enable_state(graphics.STATE_DEPTH_TEST)
render.enable_state(graphics.STATE_CULL_FACE)
render.draw(self.model_predicate, camera.frustum)

No custom PBR light constants are required by this asset.

Extending The Shader

The base fragment shader is structured around PBRLightData:

PBRParams params = get_pbr_params();
MaterialInfo material = get_material_info(params);

PBRLightData pbr_data = calculate_pbr_light_data(params, material, var_position.xyz);
pbr_data.specular += calculate_custom_specular(params, material);

vec3 color = composite_pbr_light_data(pbr_data);

Useful extension points:

• PBRParams contains material flags, texture presence, view-space normal/view, and matching world-space position/normal/view vectors.
• MaterialInfo contains resolved base color, diffuse color, metallic, roughness, and specular values.
• PBRLightData separates diffuse, specular, emissive, occlusion, and alpha so extension shaders can add image based lighting or other terms before compositing.

An extension fragment shader can include the base lighting file and add its own lighting before calling composite_pbr_light_data():

#include "/defold-pbr/shaders/pbr_lighting.glsl"

void main()
{
    PBRParams params = get_pbr_params();
    MaterialInfo material = get_material_info(params);

    PBRLightData data = calculate_pbr_light_data(params, material, var_position.xyz);
    add_pbr_light_data(data, calculate_extra_light_data(params, material));

    out_fragColor = vec4(to_output(composite_pbr_light_data(data)), data.alpha);
}