3D materials: assignment, color and transparency

Check assignment first

StandardMaterial3D describes a surface: base color, roughness, metallic response, textures and transparency. A lit material does not specify the final pixel color; lights, reflections and Environment also affect it.

A MeshInstance3D has several material assignment points. For an unexpected color, first identify the active one.

GetActiveMaterial(0) returns the selected first-surface base material, excluding MaterialOverlay. Assign null to clear an override. A surface index is not an entity ID or GridMap block number.

Native checks replace the red Mesh material with a blue surface override, then a green MaterialOverride. A transparent blue overlay adds over green, but GetActiveMaterial still returns green. Overlay verification covers an Alpha-transparent material.

Run a lit surface

Use LightingMaterials.cs below and LightingLab3D.cs from the lighting guide. Use C# SDK 1.0.0, net10.0 and an Entity3D-rooted .rscene level. Run dotnet build and attach LightingLab3D.cs to the root. A white cube, blue sphere and floor appear under a directional light.

using Reckfell;

public static class LightingMaterials
{
    public static StandardMaterial3D Surface(Color color, float roughness = 0.65f, float metallic = 0) => new()
    {
        AlbedoColor = color,
        Roughness = roughness,
        Metallic = metallic
    };

    public static StandardMaterial3D Unshaded(Color color) => new()
    {
        AlbedoColor = color,
        ShadingMode = BaseMaterial3D.ShadingModeEnum.Unshaded
    };

    public static Reckfell.Environment Environment() => new()
    {
        BackgroundMode = Reckfell.Environment.BGMode.Color,
        BackgroundColor = new Color(0.025f, 0.03f, 0.045f),
        AmbientLightSource = Reckfell.Environment.AmbientSource.Color,
        AmbientLightColor = Colors.White,
        AmbientLightEnergy = 0.12f,
        AmbientLightSkyContribution = 0,
        ReflectedLightSource = Reckfell.Environment.ReflectionSource.Disabled,
        TonemapMode = Reckfell.Environment.ToneMapper.Linear
    };
}

Surface creates a normal lit material; Unshaded removes ordinary light-source response. For a black object, a temporary Unshaded material helps distinguish lighting problems from missing geometry or incorrect assignment. It does not disable every environment effect or become a physical light emitter.

Configure primary properties

The sample cube uses roughness 0.65; the blue sphere uses 0.2 and Metallic=0.8. Sky reflection is intentionally disabled, so this demonstrates direct illumination rather than a full reflection-lit PBR setup. Increasing albedo alone is not a replacement for a missing reflective environment.

Color textures and data textures serve different purposes. Albedo contains color; normal, roughness and metallic encode surface data. Check import settings and channels rather than choosing arbitrary gamma values. Normal maps need suitable mesh normals/tangents and do not create geometric protrusions.

ORMMaterial3D uses a packed texture: R for occlusion, G for roughness, B for metallic. Shader-generation source confirms this layout; the example does not verify practical ORM import, normal-map channels or UV workflows. Incorrect packing changes the entire surface response.

Select transparency explicitly

AlbedoColor.A=0 alone is insufficient. Transparency=Disabled remains opaque, as verified in the rendered frame.

• Alpha blends alpha with the background. Use for translucency while accounting for sorting between intersecting transparent surfaces.
• AlphaScissor cuts at AlphaScissorThreshold. At threshold 0.5, alpha 0.2 disappears while 0.8 remains. This is a hard contour, not soft glass.
• Other modes, including AlphaHash and AlphaDepthPrePass, address separate quality/depth needs. Verify them in the target renderer; they are outside this runnable example.

Disabling culling for two-sided visibility does not repair incorrect normals or turn a plane into volumetric glass.

Avoid accidental shared edits

A material is a resource. Two instances sharing a Mesh and material both change when that material’s AlbedoColor changes. Assigning that same resource to MaterialOverride does not create a copy either.

For independent edits, Duplicate() the material, cast to its required type and assign the copy to the instance. Native checks confirm independent color changes. This does not guarantee deep independence of every nested texture/resource; inspect ownership separately.

Diagnosis

BaseMaterial3D API · MeshInstance3D API