Appearance

Material ​

Chainable builder for an inline material. Six kinds: unlit, pbr, occlusion, customShader, materialX, video. Use the matching factory (Material.unlit({...}), etc.) or new Material(kind).

Properties map to the underlying material data model with web-standard names: - Colors: color, emissive, sheenColor, specularColor – flat tint. - Maps: map, emissiveMap, roughnessMap, metalnessMap, normalMap, aoMap, specularMap, sheenMap, clearcoatMap, alphaMap – textures accept either a URL/asset-id string or { texture, scale }. - Scalars: roughness, metalness, clearcoat, opacity, emissiveIntensity. - Rendering: opaque, transparent, opacityThreshold, blendMode, faceCulling, wireframe, writesDepth, readsDepth.

Static Methods ​

unlit() ​

javascript
Material.unlit(opts?: Object): Material

Flat-shaded material. Renders the surface color regardless of scene lighting – useful for UI, billboards, vertex-colored point clouds, etc.

Parameters:

  • opts (Object) (optional) - Any chainable setter name as a key: color, map, opacity, alphaMap, disableToneMapping, faceCulling, blendMode, wireframe, target, name.

Returns: Material

pbr() ​

javascript
Material.pbr(opts?: Object): Material

Physically-Based material – the realistic-rendering default for surfaces that should respond to scene lighting.

Parameters:

  • opts (Object) (optional) - color, map, emissive, emissiveMap, emissiveIntensity, metalness, metalnessMap, roughness, roughnessMap, normalMap, aoMap, sheenColor, sheenMap, specularColor, specularMap, clearcoat, clearcoatMap, opacity, alphaMap, opacityThreshold, plus rendering state.

Returns: Material

occlusion() ​

javascript
Material.occlusion(opts?: Object): Material

Occlusion material – invisible itself but hides geometry behind it. Use for matte holdouts, real-world geometry masks, portals.

Parameters:

  • opts (Object) (optional) - receivesDynamicLighting, faceCulling.

Returns: Material

customShader() ​

javascript
Material.customShader(opts?: Object): Material

Custom shader material – author-supplied surface shader and/or geometry modifier from a compiled shader library.

Parameters:

  • opts (Object) (optional) - shaderLibrary, lightingModel, surfaceShader, geometryModifier, plus general rendering state.

Returns: Material

materialX() ​

javascript
Material.materialX(opts?: Object): Material

ShaderGraph material from a bundled .usdz. Reference by file path plus the /Root/<MaterialName> path inside.

Parameters:

  • opts (Object) (optional) - Typically use .materialXAsset(urlOrId, name) followed by .setParameter(name, value, typeHint?) calls.

Returns: Material

video() ​

javascript
Material.video(): Material

Video texture material. Use .videoSource(urlOrId) for the playback source and .videoOptions({ loops, streamContent, volume }) for playback config.

Returns: Material

Instance Methods ​

opacity() ​

javascript
opacity(): void

Material opacity. Values < 1 also flip isOpaque to false so the blending state matches.

Returns: void

materialXAsset() ​

javascript
materialXAsset(): void

MaterialX (ShaderGraph): URL or asset id of the .usdz, plus the path to the material inside it (e.g. "/Root/MyMaterial").

Returns: void

setParameter() ​

javascript
setParameter(name: string, value: any, typeHint?: Object): Material

Set a constant value on a shader parameter. Works on customShader and materialX kinds – routes to the right options blob automatically. Warns and no-ops on kinds without shader parameters.

For runtime variable bindings, use entity.representation.bindMaterialParameter(name, variableId, opts?).

Example:

javascript
Material.materialX('myAsset', '/Root/MyMat')
    .setParameter('intensity', 0.6)
    .setParameter('tintColor', '#FF00FF', { type: 'color' });

Parameters:

  • name (string) - Shader parameter name (case-sensitive, must match the shader graph input or Metal uniform).
  • value (any) - Number, boolean, string, array (vec2/3/4), or color-like object ('#RRGGBB', {r,g,b,a?}, {colorSpace,hex}).
  • typeHint (Object) (optional) - Override inferred type: { type: "float" | "int" | "vector2" | "vector3" | "vector4" | "color" | "boolean" | "string" }.

Returns: Material

clone() ​

javascript
clone(): void

Deep-copy the material with a fresh id. Use for the get → clone → tweak → apply pattern when overriding a library material for a single entity without mutating the library entry.

Returns: void

toString() ​

javascript
toString(): void

Useful per-kind summary for console.log(mat) – includes kind, id, name, and the meaningful state set on the material (channel colors, scalar values, shader params, etc.) so authors can see "what's on this material" at a glance. For the full serialized shape, use JSON.stringify(mat, null, 2).

Returns: void