Material#

Namespace: PlushEngine

A material (shared datablock): values for its Shader's parameters. The shader is the material's type, built on a surface model. Every value lives in Values, resolved on load (the material's own value, else its shader's default); an absent one reads the model's default. Kinds: float (Number), sRGB hex string (Color), SpritePixels (Texture2D), MapChannel (Channel), EnvironmentMap (Environment). Lit's parameters also have typed properties, a view over the same values for gameplay and tools (material with { BaseColor = "#FF0000" }). Lit maps: base color sampled as sRGB; metallic, roughness and occlusion read one channel (R by default), so one packed map fills all three (MRAO: R/G/B; glTF ORM: B/G/R); normal maps are tangent-space XYZ, green up. Map values multiply the matching factor.

public sealed record Material

General: BaseColor · BaseColorMap · BreakSound · Channel · Color · Emissive · EmissiveStrength · Environment · FootstepSound · FromMesh · ImpactSound · Map · Maps · Metallic · MetallicChannel · MetallicMap · NormalMap · NormalStrength · Number · OcclusionChannel · OcclusionMap · OcclusionStrength · Porosity · Roughness · RoughnessChannel · RoughnessMap · Shader · SoundFor · Texture2D · Textures · TwoSided · Values · Vector2 · Vector3 · Vector4

Parameters: With · WithChannel · WithColor · WithEnvironment · WithNumber · WithTexture2D · WithVector2 · WithVector3 · WithVector4

General#

BaseColor#

public string BaseColor { get; init; }

Surface colour, sRGB hex such as "#C03020".

BaseColorMap#

public SpritePixels? BaseColorMap { get; init; }

Colour texture (sRGB), multiplied by BaseColor.

BreakSound#

public SoundReference BreakSound { get; init; }

The Sound an object of this material makes going to pieces (Matter fracture).

Channel#

public MapChannel Channel(string name);

A Channel parameter, or its declaration default. Unknown names and mismatched kinds throw ArgumentException.

Color#

public string Color(string name);

A Color parameter as sRGB hex, or its declaration default. Unknown names and mismatched kinds throw ArgumentException.

Emissive#

public string Emissive { get; init; }

Glow colour, sRGB hex; "#000000" for none.

EmissiveStrength#

public float EmissiveStrength { get; init; }

Glow brightness multiplier for Emissive.

Environment#

public EnvironmentMap? Environment(string name);

An Environment parameter, or null when unassigned. Unknown names and mismatched kinds throw ArgumentException.

FootstepSound#

public SoundReference FootstepSound { get; init; }

The Sound a step on this surface makes (unset: none): Scene.PlaySound(hit.Entity.Material.FootstepSound, hit.Point).

FromMesh#

public static Material FromMesh(MeshAsset mesh);

The material a mesh without one gets: its legacy base-color texture, fully rough.

ImpactSound#

public SoundReference ImpactSound { get; init; }

The Sound a hit against this surface makes (unset: none); rigid bodies of this material play it when they strike something.

Map#

public SpritePixels? Map(string name);

Compatibility name for Texture2D. New code uses Texture2D.

Maps#

public IEnumerable<SpritePixels> Maps { get; }

Compatibility name for Textures. New code uses Textures.

Metallic#

public float Metallic { get; init; }

0 for non-metals (wood, plastic, stone), 1 for bare metal.

MetallicChannel#

public MapChannel MetallicChannel { get; init; }

The channel of MetallicMap holding metallic (R by default).

MetallicMap#

public SpritePixels? MetallicMap { get; init; }

Metallic data map (one channel, see MetallicChannel).

NormalMap#

public SpritePixels? NormalMap { get; init; }

Tangent-space normal map, green up.

NormalStrength#

public float NormalStrength { get; init; }

How strongly the normal map bends lighting; 1 as authored, 0 off.

Number#

public float Number(string name);

A Number parameter by name, or its declaration default. Unknown names and mismatched kinds throw ArgumentException.

OcclusionChannel#

public MapChannel OcclusionChannel { get; init; }

The channel of OcclusionMap holding occlusion (R by default).

OcclusionMap#

public SpritePixels? OcclusionMap { get; init; }

Ambient-occlusion data map (one channel, see OcclusionChannel).

OcclusionStrength#

public float OcclusionStrength { get; init; }

How strongly the occlusion map darkens ambient light; 0 off, 1 full.

Porosity#

public float Porosity { get; init; }

How much the scene's water darkens and glosses it at and below the waterline (sand 1, stone ~0.3, metal 0).

Roughness#

public float Roughness { get; init; }

0 mirror-smooth, 1 fully matte.

RoughnessChannel#

public MapChannel RoughnessChannel { get; init; }

The channel of RoughnessMap holding roughness (R by default).

RoughnessMap#

public SpritePixels? RoughnessMap { get; init; }

Roughness data map (one channel, see RoughnessChannel).

Shader#

public Shader Shader { get; init; }

Initial value: Shader.Lit

The material's shader type (Lit by default).

SoundFor#

public SoundReference SoundFor(SurfaceSound kind);

The surface's Sound of a kind (unset when the material names none).

Texture2D#

public SpritePixels? Texture2D(string name);

A Texture2D parameter by name, or null when no image is assigned. Unknown names and mismatched kinds throw ArgumentException.

Textures#

public IEnumerable<SpritePixels> Textures { get; }

Every Texture2D image assigned to this material. Multiple parameters can refer to the same image.

TwoSided#

public bool TwoSided { get; init; }

Whether both orientations of the material's triangles draw. False culls back faces.

Values#

public ImmutableDictionary<string, object> Values { get; init; }

Initial value: ImmutableDictionary<string, object>.Empty

Every parameter value by name; the typed properties below are a view over the same values.

Vector2#

public Vector2 Vector2(string name);

A two-component shader value, falling back to its declared default. Unknown names and mismatched kinds throw ArgumentException.

Vector3#

public Vector3 Vector3(string name);

A three-component shader value, falling back to its declared default. This is not a color; unknown names and mismatched kinds throw ArgumentException.

Vector4#

public Vector4 Vector4(string name);

A four-component shader value, falling back to its declared default. Unknown names and mismatched kinds throw ArgumentException.

Parameters#

With#

public Material With(string name, object? value);

A copy with one declared parameter changed. Assign it to an object's Material to update that object; unknown names, incompatible types, non-finite values and values outside the declared range throw ArgumentException.

Remarks: Numbers accept C# integer, float, double and decimal values and are stored as floats. Colors are six-digit sRGB hex strings; vectors are linear values. Null removes the stored value and falls back to the parameter's declaration default (textures and environments become unassigned). This does not restore a loaded material's authored override.

WithChannel#

public Material WithChannel(string name, MapChannel value);

A copy with a data texture's channel changed to R, G, B or A. Throws ArgumentException for a wrong name, kind or channel.

WithColor#

public Material WithColor(string name, string value);

A copy with a Color parameter changed to a six-digit sRGB hex color. Throws ArgumentException for a wrong name, kind or color.

WithEnvironment#

public Material WithEnvironment(string name, EnvironmentMap? value);

A copy with an Environment parameter assigned a panorama, or cleared with null to use the scene's. Throws ArgumentException for a wrong name or kind.

WithNumber#

public Material WithNumber(string name, double value);

A copy with a Number parameter changed, in the declaration's units and range. Throws ArgumentException for a wrong name, kind or value.

WithTexture2D#

public Material WithTexture2D(string name, SpritePixels? value);

A copy with a Texture2D parameter assigned an image, or cleared with null. Throws ArgumentException for a wrong name or kind.

WithVector2#

public Material WithVector2(string name, Vector2 value);

A copy with a Vector2 parameter changed to finite linear components. Throws ArgumentException for a wrong name, kind or value.

WithVector3#

public Material WithVector3(string name, Vector3 value);

A copy with a Vector3 parameter changed to finite linear components. This does not convert sRGB colors; a wrong name, kind or value throws ArgumentException.

WithVector4#

public Material WithVector4(string name, Vector4 value);

A copy with a Vector4 parameter changed to finite linear components. Throws ArgumentException for a wrong name, kind or value.

EnvironmentMap · MapChannel · MeshAsset · Shader · SoundReference · SpritePixels · SurfaceSound

Source#

Material.Parameters.cs
Model3D.cs