Class MaterialUtil

Creates and configures physically-based Lit UnityEngine.Material instances at runtime, mapping pipeline-neutral surface parameters (base color, metallic, smoothness, emission, PBR texture channels, surface blend mode, and double-sided rendering) onto whichever Lit shader the active render pipeline provides: Universal Render Pipeline/Lit (URP), HDRP/Lit (HDRP), or the Built-in Standard shader.

Inheritance
object
MaterialUtil
Inherited Members
Namespace: Scylla.Core.Util
Assembly: ScyllaCore.dll
Syntax
public static class MaterialUtil
Remarks

Unlike LightUtil and CameraUtil, which bind to pipeline-specific component types and therefore reach the pipeline through reflection, materials are addressed entirely by shader name (Find(string)) and by shader-property name. This utility therefore references no render-pipeline assembly, and one compiled build serves every pipeline. Property setters resolve their target by presence (HasProperty(int)), so a call that targets a property the active shader does not expose is a safe no-op rather than an error.

Materials returned by the CreateLitMaterial overloads are new instances owned by the caller. Destroy them with Object.Destroy (or Object.DestroyImmediate in the editor) when they are no longer needed, or they leak. For a shared read-only material that never needs per-instance tweaks, use GetDefaultLit() instead.

The surface-mode mapping is complete for URP and Built-in Standard. The HDRP mapping is best-effort: the core surface properties are set, but some HDRP transparency edge cases depend on HDRP's own material validation pass that this utility does not run. Metallic and occlusion texture channels are separate maps on URP and Standard and a single packed mask map on HDRP (see LitMaterialDescriptor).

Methods

CreateLitMaterial(in LitMaterialDescriptor)

Creates a new Lit UnityEngine.Material from a LitMaterialDescriptor. The descriptor's scalar parameters, PBR texture channels, surface blend mode, and double-sided flag are mapped to the active render pipeline's Lit shader. The material is owned by the caller.

Declaration
public static Material CreateLitMaterial(in LitMaterialDescriptor descriptor)
Parameters
Type Name Description
LitMaterialDescriptor descriptor

The pipeline-neutral surface parameters to apply.
Returns
Type Description
Material

A new material owned by the caller, or null if no Lit shader could be resolved.

CreateLitMaterial(Color, float, float)

Creates a new opaque Lit UnityEngine.Material tinted with baseColor and configured with the given metallic and smoothness values. The material uses the active render pipeline's Lit shader and is owned by the caller.

Declaration
public static Material CreateLitMaterial(Color baseColor, float metallic = 0, float smoothness = 0.5)
Parameters
Type Name Description
Color baseColor

The albedo / base color of the surface.
float metallic

The metallic value, clamped to [0, 1]. Defaults to 0 (dielectric).
float smoothness

The smoothness value, clamped to [0, 1]. Defaults to 0.5.
Returns
Type Description
Material

A new material owned by the caller, or null if no Lit shader could be resolved.

GetDefaultLit()

Returns a shared, lazily created default Lit material (opaque white, non-metallic, mid smoothness). The instance is marked UnityEngine.HideFlags.HideAndDontSave and is reused across calls, so callers must not mutate it directly; apply per-renderer color via a UnityEngine.MaterialPropertyBlock instead, or use CreateLitMaterial(in LitMaterialDescriptor) for an owned instance.

Declaration
public static Material GetDefaultLit()
Returns
Type Description
Material

The shared default material, or null if no Lit shader could be resolved.

ResolveLitShader(out ScyllaRenderPipeline)

Resolves the Lit shader for the active render pipeline, preferring HDRP Lit, then URP Lit, then the Built-in Standard shader. The chain naturally lands on the first shader present, since Find(string) returns null for a pipeline whose package is not installed.

Declaration
public static Shader ResolveLitShader(out ScyllaRenderPipeline pipeline)
Parameters
Type Name Description
ScyllaRenderPipeline pipeline

Receives the pipeline classification of the resolved shader.
Returns
Type Description
Shader

The resolved Lit shader, or null if none could be located.

SetAlbedoMap(Material, Texture)

Sets the albedo / base color texture of material, targeting whichever base map property the shader exposes (_BaseMap on URP, _BaseColorMap on HDRP, _MainTex on the Built-in Standard shader), with unit tiling.

Declaration
public static void SetAlbedoMap(Material material, Texture texture)
Parameters
Type Name Description
Material material

The material to modify. Null is a no-op.
Texture texture

The albedo texture to apply.

SetAlbedoMap(Material, Texture, Vector2, Vector2)

Sets the albedo / base color texture of material with an explicit tiling and offset, targeting whichever base map property the shader exposes.

Declaration
public static void SetAlbedoMap(Material material, Texture texture, Vector2 tiling, Vector2 offset)
Parameters
Type Name Description
Material material

The material to modify. Null is a no-op.
Texture texture

The albedo texture to apply.
Vector2 tiling

The texture tiling (scale).
Vector2 offset

The texture offset.

SetBaseColor(Material, Color)

Sets the base / albedo color of material, targeting whichever base color property the material's shader exposes (_BaseColor on URP and HDRP Lit, _Color on the Built-in Standard shader).

Declaration
public static void SetBaseColor(Material material, Color color)
Parameters
Type Name Description
Material material

The material to modify. Null is a no-op.
Color color

The base color to apply.

SetDoubleSided(Material, bool)

Enables or disables backface culling on material. Sets _Cull to Off (double-sided) or Back (single-sided) where the property exists (URP and HDRP Lit), and toggles HDRP's _DoubleSidedEnable where present. The Built-in Standard shader exposes no cull property, so double-sided has no effect there.

Declaration
public static void SetDoubleSided(Material material, bool doubleSided)
Parameters
Type Name Description
Material material

The material to modify. Null is a no-op.
bool doubleSided

Whether the surface renders from both sides.

SetEmission(Material, Color)

Sets the emissive color of material and toggles the emission keyword. A non-black color enables emission and writes the color to whichever emissive property the shader exposes (_EmissionColor on URP and Standard, _EmissiveColor on HDRP); UnityEngine.Color.black disables emission.

Declaration
public static void SetEmission(Material material, Color emissionColor)
Parameters
Type Name Description
Material material

The material to modify. Null is a no-op.
Color emissionColor

The emissive color. UnityEngine.Color.black disables emission.
Remarks

HDRP treats the emissive color as an HDR, intensity-scaled value, so a plain low dynamic range color produces only a dim glow there.

SetEmissionMap(Material, Texture)

Sets the emission map of material and enables emission. Targets _EmissionMap on URP and Standard or _EmissiveColorMap on HDRP. Pair with SetEmission(Material, Color) to control the emissive color and intensity.

Declaration
public static void SetEmissionMap(Material material, Texture texture)
Parameters
Type Name Description
Material material

The material to modify. Null is a no-op.
Texture texture

The emission map to apply.

SetMaskMap(Material, Texture)

Sets the pre-packed HDRP mask map of material (R = metallic, G = ambient occlusion, A = smoothness) and enables the mask map keyword. Applies only when the shader exposes _MaskMap (HDRP Lit); a no-op under URP and Built-in Standard, which use the separate metallic and occlusion maps.

Declaration
public static void SetMaskMap(Material material, Texture texture)
Parameters
Type Name Description
Material material

The material to modify. Null is a no-op.
Texture texture

The pre-packed mask map to apply.

SetMetallic(Material, float)

Sets the metallic value of material (the _Metallic property, shared by all three Lit shaders). The value is clamped to [0, 1].

Declaration
public static void SetMetallic(Material material, float metallic)
Parameters
Type Name Description
Material material

The material to modify. Null is a no-op.
float metallic

The metallic value, clamped to [0, 1].

SetMetallicMap(Material, Texture)

Sets the metallic / smoothness map of material and enables the matching keyword. Applies only when the shader exposes _MetallicGlossMap (URP and Built-in Standard); under HDRP this channel is carried by the mask map, so the call is a no-op there. Use SetMaskMap(Material, Texture) for HDRP.

Declaration
public static void SetMetallicMap(Material material, Texture texture)
Parameters
Type Name Description
Material material

The material to modify. Null is a no-op.
Texture texture

The metallic / smoothness map (metallic in RGB, smoothness in alpha).

SetNormalMap(Material, Texture, float)

Sets the tangent-space normal map of material and enables the normal mapping keyword. Targets _BumpMap on URP and Standard or _NormalMap on HDRP, and applies scale to the matching scale property.

Declaration
public static void SetNormalMap(Material material, Texture texture, float scale = 1)
Parameters
Type Name Description
Material material

The material to modify. Null is a no-op.
Texture texture

The normal map to apply.
float scale

The normal map intensity. Defaults to 1.

SetOcclusionMap(Material, Texture, float)

Sets the ambient occlusion map of material and enables the occlusion keyword. Applies only when the shader exposes _OcclusionMap (URP and Built-in Standard); under HDRP occlusion is carried by the mask map, so the call is a no-op there. Use SetMaskMap(Material, Texture) for HDRP.

Declaration
public static void SetOcclusionMap(Material material, Texture texture, float strength = 1)
Parameters
Type Name Description
Material material

The material to modify. Null is a no-op.
Texture texture

The occlusion map to apply.
float strength

The occlusion intensity, clamped to [0, 1]. Defaults to 1.

SetSmoothness(Material, float)

Sets the smoothness value of material, targeting whichever property the shader exposes (_Smoothness on URP and HDRP Lit, _Glossiness on the Built-in Standard shader). The value is clamped to [0, 1].

Declaration
public static void SetSmoothness(Material material, float smoothness)
Parameters
Type Name Description
Material material

The material to modify. Null is a no-op.
float smoothness

The smoothness value, clamped to [0, 1].

SetSurfaceType(Material, ScyllaMaterialSurface, float)

Configures the surface blend mode of material (opaque, transparent, or cutout): blend factors, depth write, render queue, and the surface-related keywords. The correct configuration is chosen from the shader family the material uses (URP Lit, Built-in Standard, or HDRP Lit).

Declaration
public static void SetSurfaceType(Material material, ScyllaMaterialSurface surface, float alphaCutoff = 0.5)
Parameters
Type Name Description
Material material

The material to modify. Null is a no-op.
ScyllaMaterialSurface surface

The target surface blend mode.
float alphaCutoff

The alpha cutoff threshold used by Cutout, clamped to [0, 1]. Defaults to 0.5.
Remarks

URP and Built-in Standard are configured fully. The HDRP path is best-effort: it sets the core surface properties but does not run HDRP's material validation pass, so some HDRP transparency edge cases may still need manual adjustment.

See Also