# `MaterialSpec`

> Contract 2.0.0 · package sha256 `a857eca95b35921109faf997094bb4192f12527d9d0fcd4be7e97f06425bad6e` · generated from `configurator-runtime.d.ts` by `services/onsite-scripter/scripts/build-contract-docs.mjs`; edit the source, not this file.

Interface · `import type { MaterialSpec } from '@holostep-configurators/runtime-client/contract';` · stable · since 2.0.0 · section 8. Materials and textures

glTF 2.0 and KHR names. As a stored MaterialNode, or a partial over a part, omitted fields keep
the underlying values (a map slot that brings an image: [`TextureSpec`](TextureSpec.md)); on a new mesh, the
defaults below apply.

## Members

| Member | Kind | Summary |
| --- | --- | --- |
| <a id="_schema"></a>[`$schema?`](MaterialSpec._schema.md) | property | The JSON Schema id, for editors and [`validate('material')`](validate.md). |
| <a id="name"></a>[`name?`](MaterialSpec.name.md) | property | Shown in exports and problems. |
| <a id="basecolor"></a>[`baseColor?`](MaterialSpec.baseColor.md) | property | The base colour (glTF `baseColorFactor`): it multiplies the `baseColor` map the slot wears under it, the GLB's own, a selected finish's or a rule's, so a colour over a textured finish tints it, and how dark it goes… |
| <a id="alpha"></a>[`alpha?`](MaterialSpec.alpha.md) | property | 0..1. |
| <a id="alphamode"></a>[`alphaMode?`](MaterialSpec.alphaMode.md) | property | 'mask' cuts holes (also in the shadow) below `alphaCutoff`. |
| <a id="alphacutoff"></a>[`alphaCutoff?`](MaterialSpec.alphaCutoff.md) | property | 0..1, for `alphaMode: 'mask'`. |
| <a id="metallic"></a>[`metallic?`](MaterialSpec.metallic.md) | property | 0..1. |
| <a id="roughness"></a>[`roughness?`](MaterialSpec.roughness.md) | property | 0..1. |
| <a id="emissive"></a>[`emissive?`](MaterialSpec.emissive.md) | property | The colour the surface gives off, unlit by the scene (glTF `emissiveFactor`); it multiplies the `emissive` map, and `emissiveStrength` scales it. |
| <a id="emissivestrength"></a>[`emissiveStrength?`](MaterialSpec.emissiveStrength.md) | property | KHR_materials_emissive_strength; 0 or more. |
| <a id="normalscale"></a>[`normalScale?`](MaterialSpec.normalScale.md) | property | Strength of the normal map. |
| <a id="occlusionstrength"></a>[`occlusionStrength?`](MaterialSpec.occlusionStrength.md) | property | Strength of the occlusion map, 0..1. |
| <a id="ior"></a>[`ior?`](MaterialSpec.ior.md) | property | KHR_materials_ior. |
| <a id="specular"></a>[`specular?`](MaterialSpec.specular.md) | property | KHR_materials_specular. |
| <a id="sheen"></a>[`sheen?`](MaterialSpec.sheen.md) | property | KHR_materials_sheen plus intensity. |
| <a id="clearcoat"></a>[`clearcoat?`](MaterialSpec.clearcoat.md) | property | KHR_materials_clearcoat. |
| <a id="transmission"></a>[`transmission?`](MaterialSpec.transmission.md) | property | KHR_materials_transmission and volume. |
| <a id="side"></a>[`side?`](MaterialSpec.side.md) | property | Which faces draw: 'front' culls the back faces, as glTF's single-sided; 'double' draws both, for open shells and thin sheets seen from both sides (glTF `doubleSided`); 'back' only the back ones. |
| <a id="lighting"></a>[`lighting?`](MaterialSpec.lighting.md) | property | 'unlit' skips lighting (KHR_materials_unlit). |
| <a id="exactcolor"></a>[`exactColor?`](MaterialSpec.exactColor.md) | property | Lit, but skips exposure and the tone curve, so white stays white (backdrop walls). |
| <a id="variant"></a>[`variant?`](MaterialSpec.variant.md) | property · labs | A KHR_materials_variants variant of the GLB the mesh comes from ([`AssetManifest.variants`](AssetManifest.variants.md)): the base this rule's fields merge over is that variant's material for the mesh instead of the one it wears, so … |
| <a id="maps"></a>[`maps?`](MaterialSpec.maps.md) | property | Per slot. |
| <a id="labs"></a>[`labs?`](MaterialSpec.labs.md) | property · labs | Labs fields: they may change in a minor. |

## Declaration

```ts
export interface MaterialSpec {
  $schema?: 'holostep.material/1';
  name?: string;
  baseColor?: ColorValue;
  alpha?: number;
  alphaMode?: 'opaque' | 'mask' | 'blend';
  alphaCutoff?: number;
  metallic?: number;
  roughness?: number;
  emissive?: ColorValue;
  emissiveStrength?: number;
  normalScale?: number;
  occlusionStrength?: number;
  ior?: number;
  specular?: {
    enabled?: boolean;
    factor?: number;
    color?: ColorValue;
  };
  sheen?: {
    enabled?: boolean;
    intensity?: number;
    color?: ColorValue;
    roughness?: number;
  };
  clearcoat?: {
    factor?: number;
    roughness?: number;
    normalScale?: number;
  };
  transmission?: {
    factor?: number;
    thickness?: number;
    attenuationColor?: ColorValue;
    attenuationDistance?: number;
  };
  side?: 'front' | 'back' | 'double';
  lighting?: 'lit' | 'unlit';
  exactColor?: boolean;
  variant?: string;
  maps?: Partial<Record<MapSlot, TextureSlot>>;
  labs?: {
    drawOrder?: number;
    depthPrepass?: boolean;
    envIntensity?: number;
    shading?: Shading;
  };
}
```

## Generic-API test (spec 3.1)

| Rule | Result |
| --- | --- |
| 1. Neutral name | pass: `MaterialSpec` names no product |
| 2. A precedent | pass: [glTF 2.0 metallic-roughness material](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#metallic-roughness-material) (row `K10`); [glTF KHR_materials_sheen](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_materials_sheen) (row `K10`); [glTF KHR_materials_transmission](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_materials_transmission) (row `K10`); [glTF KHR_materials_unlit](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_materials_unlit) (row `K10`) |
| 3. Two apps, or labs | pass: 28 apps (ledger: app-04c2774145, app-0c773a4ee3, app-37356bf09f, app-378d190f1b, app-4762caacdc, app-4f16d2f6da, app-4fd23bc869, app-510d750508 and 20 more; fleet cross-check: app-fc07850558) |
| 4. The cheaper fix first | decided per need in Appendix B: rows `K10` at tier stable (a member only where no rule, data, asset or app code serves the need) |