Scripting API
Scripting API
MaterialSpec
Struct in Abyss.Core, from Abyss.Core.
How a surface should look, in the part of PBR the engine can write down.
public struct MaterialSpecRemarks
Everything here is a number or an asset id, which is the whole selection rule and is what makes a material a thing a file can hold in full. It is wide enough to carry what a glTF material says — two colors, the scalars that make a surface metal or chalk, the transparency rule, and five texture slots — so a surface somebody authored in a modeling tool survives being read.
What is left out is left out because the engine could not describe it honestly: clearcoat, transmission, index of refraction, anisotropy and UV transforms are all in Bevy's StandardMaterial and none of them is in a file this engine can round-trip yet.
Use MaterialSpec.Default as a starting point rather than default: a zeroed material is black and fully transparent, which is the same failure mode a zeroed transform has.
Properties
Default
public static MaterialSpec Default { get; }White, dielectric, fairly rough — Bevy's own default material.
Fields
public static IReadOnlyList<MaterialField> Fields { get; }Where every number a person can edit actually sits, measured rather than written.
Nobody wrote an offset down here either. Each one is the distance between the address of a real instance and the address of one of its fields, so it is whatever this build's compiler chose — the same rule the engine's own field tables follow, and the same rule that caught Transform storing its quaternion first.
This struct is LayoutKind.Sequential against a #[repr(C)] twin, so the two are meant to agree by construction rather than by luck; the size is asserted on both sides so that a field added to one and not the other is a failing test rather than a material read out of the wrong bytes.
Transparency
public AlphaKind Transparency { readonly get; set; }Which transparency rule this surface is drawn under.
Methods
Read
public readonly double Read(MaterialField field, int element)One element of one field, as a number.
Parameters
field: Which field, fromMaterialSpec.Fields.element: Which of its values: 0 for a scalar, 0..3 for a color.
With
public readonly MaterialSpec With(int offset, FieldKind kind, double value)The same material with one number, at one offset, changed.
Parameters
offset: Byte offset from the start of the spec.kind: What kind of value sits there.value: The number to store.
Exceptions
ArgumentOutOfRangeException: The range is not inside the spec.
A copy rather than a mutation, because a spec is the thing that crosses the boundary: what an editor holds is the surface it is about to ask for, and a half-applied one is not a surface anybody meant.
An offset and a kind rather than a field and an element, because that is what an edit knows — the same three values a component edit carries — so nothing between the box and here has to keep hold of which field a number came out of.
Matches
public readonly bool Matches(MaterialSpec other)Whether two specs describe the same surface, byte for byte.
Parameters
other: The spec to compare against.
Bytes rather than field by field, because that is what actually crosses and because it cannot fall behind a field being added. It is what an editor compares a value it wrote against a value that came back, so the comparison has to be exact: a float that was rounded on the way through is a different surface, and treating it as the same one would leave the panel holding an edit the world never took.
WithTexture
public readonly MaterialSpec WithTexture(ulong image)The same material with an image on it.
Parameters
image
Colored
public static MaterialSpec Colored(float red, float green, float blue, float alpha = 1)The same material in a different color.
Parameters
redgreenbluealpha
Fields
Red
public float RedLinear red, 0..1.
Green
public float GreenLinear green, 0..1.
Blue
public float BlueLinear blue, 0..1.
Alpha
public float AlphaAlpha, 0..1.
EmissiveRed
public float EmissiveRedLinear red the surface emits regardless of lighting.
EmissiveGreen
public float EmissiveGreenLinear green the surface emits regardless of lighting.
EmissiveBlue
public float EmissiveBlueLinear blue the surface emits regardless of lighting.
EmissiveAlpha
public float EmissiveAlphaEmissive alpha, which Bevy carries and does not blend with.
Metallic
public float Metallic0 for a dielectric, 1 for a metal.
PerceptualRoughness
public float PerceptualRoughness0 for a mirror, 1 for chalk.
Reflectance
public float ReflectanceHow much light a non-metal reflects head on. Bevy's default of 0.5 is about 4%.
AlphaCutoff
public float AlphaCutoffThe threshold AlphaKind.Mask compares against; ignored by every other rule.
Unlit
public uint UnlitNon-zero to ignore lighting entirely, which is how a scene with no light is still visible.
DoubleSided
public uint DoubleSidedNon-zero to draw both faces of every triangle rather than culling the back one.
FlipNormalMapY
public uint FlipNormalMapYNon-zero if the normal map's green channel points the other way, as some exporters write it.
AlphaMode
public uint AlphaModeWhich AlphaKind this surface is drawn under.
BaseColorTexture
public ulong BaseColorTextureAn image id to tint by, or Assets.None.
A texture that has not finished loading is not a problem here. The material is built with the handle either way and Bevy draws a fallback until the bytes arrive, so a scene can be assembled on the first frame — which is when scenes are assembled — and becomes correct on the frame the file lands. The same is true of every other slot.
EmissiveTexture
public ulong EmissiveTextureAn image id whose colors are emitted, multiplied by the emissive color.
MetallicRoughnessTexture
public ulong MetallicRoughnessTextureAn image id holding roughness in green and metalness in blue, as glTF packs them.
NormalMapTexture
public ulong NormalMapTextureAn image id holding tangent-space normals.
OcclusionTexture
public ulong OcclusionTextureAn image id whose red channel darkens ambient light, as glTF bakes it.
