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 MaterialSpec

Remarks

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, from MaterialSpec.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

  • red
  • green
  • blue
  • alpha

Fields

Red

public float Red

Linear red, 0..1.

Green

public float Green

Linear green, 0..1.

Blue

public float Blue

Linear blue, 0..1.

Alpha

public float Alpha

Alpha, 0..1.

EmissiveRed

public float EmissiveRed

Linear red the surface emits regardless of lighting.

EmissiveGreen

public float EmissiveGreen

Linear green the surface emits regardless of lighting.

EmissiveBlue

public float EmissiveBlue

Linear blue the surface emits regardless of lighting.

EmissiveAlpha

public float EmissiveAlpha

Emissive alpha, which Bevy carries and does not blend with.

Metallic

public float Metallic

0 for a dielectric, 1 for a metal.

PerceptualRoughness

public float PerceptualRoughness

0 for a mirror, 1 for chalk.

Reflectance

public float Reflectance

How much light a non-metal reflects head on. Bevy's default of 0.5 is about 4%.

AlphaCutoff

public float AlphaCutoff

The threshold AlphaKind.Mask compares against; ignored by every other rule.

Unlit

public uint Unlit

Non-zero to ignore lighting entirely, which is how a scene with no light is still visible.

DoubleSided

public uint DoubleSided

Non-zero to draw both faces of every triangle rather than culling the back one.

FlipNormalMapY

public uint FlipNormalMapY

Non-zero if the normal map's green channel points the other way, as some exporters write it.

AlphaMode

public uint AlphaMode

Which AlphaKind this surface is drawn under.

BaseColorTexture

public ulong BaseColorTexture

An 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 EmissiveTexture

An image id whose colors are emitted, multiplied by the emissive color.

MetallicRoughnessTexture

public ulong MetallicRoughnessTexture

An image id holding roughness in green and metalness in blue, as glTF packs them.

NormalMapTexture

public ulong NormalMapTexture

An image id holding tangent-space normals.

OcclusionTexture

public ulong OcclusionTexture

An image id whose red channel darkens ambient light, as glTF bakes it.