<pc-material>

The <pc-material> tag is used to define a material that can be applied to <pc-render> components via their material attribute.

Usage

• It must be a direct child of <pc-app>.

The element wraps the engine's StandardMaterial and is metal/rough by default: unlike a bare StandardMaterial, the metalness workflow is enabled (use-metalness defaults to "true"), which is what the metalness-* attributes assume and what glTF and other PBR tools mean by PBR.

Gloss vs roughness

The roughness and roughness-map attributes are aliases for gloss and gloss-map that additionally invert the gloss channel. Use one family or the other on a given material — mixing them logs a console warning, because the two families disagree about inversion. The gloss-map-* modifiers carry no inversion of their own, so they are the supported way to configure a roughness-map.

Attributes

Attribute	Type	Default	Description
alpha-test	Number	"0"	Alpha test reference value. Fragments with an opacity below this value are discarded
alpha-to-coverage	Boolean	"false"	Whether to use alpha-to-coverage, which resolves transparency using multisampling
ao-intensity	Number	"1"	Strength of the ambient occlusion map, from 0 to 1
ao-map	String	-	id of a texture <pc-asset> used as the ambient occlusion map
blend-type	Enum	"none"	How the material is blended with the scene behind it: "none" | "normal" | "additive" | "additive-alpha" | "premultiplied" | "multiplicative" | "multiplicative-2x" | "screen" | "min" | "max" | "subtractive"
bumpiness	Number	"1"	Strength of the normal map, where 0 is flat and 1 is the map's full effect
cull	Enum	"back"	Which faces of a mesh are culled: "none" | "back" | "front" | "front-and-back"
depth-bias	Number	"0"	Offset applied to the depth of a fragment, used to resolve z-fighting
depth-test	Boolean	"true"	Whether fragments are tested against the depth buffer
depth-write	Boolean	"true"	Whether fragments write to the depth buffer
diffuse	Color	"1 1 1"	Diffuse color of the material
diffuse-map	String	-	id of a texture <pc-asset> used as the diffuse map
emissive	Color	"0 0 0"	Emissive color of the material
emissive-intensity	Number	"1"	Multiplier applied to the emissive color and map
emissive-map	String	-	id of a texture <pc-asset> used as the emissive map
enable-ggx-specular	Boolean	"false"	Whether to use the GGX specular model, which supports anisotropy
fresnel-model	Enum	"schlick"	Fresnel model used for specular reflections at grazing angles: "none" | "schlick"
gloss	Number	"0.25"	Glossiness of the material, from 0 (rough) to 1 (shiny). See roughness
gloss-invert	Boolean	"false"	Whether the gloss value and map are inverted, making the material treat them as roughness. Setting roughness or roughness-map enables this automatically
gloss-map	String	-	id of a texture <pc-asset> used as the gloss map
height-map	String	-	id of a texture <pc-asset> used as the height map
height-map-factor	Number	"1"	Strength of the parallax effect driven by the height map
id	String	-	Unique identifier used by other tags to reference this material
metalness	Number	"1"	How metallic the surface is, from 0 (dielectric) to 1 (metal)
metalness-map	String	-	id of a texture <pc-asset> used as the metalness map
normal-map	String	-	id of a texture <pc-asset> used as the normal map
occlude-direct	Boolean	"false"	Whether ambient occlusion also attenuates direct lighting
occlude-specular	Enum	"ao"	How specular reflections are occluded: "none" | "ao" | "gloss-dependent"
opacity	Number	"1"	Opacity of the material, from 0 (transparent) to 1 (opaque). Requires a blend-type other than "none" to have a visible effect
opacity-dither	Enum	"none"	Dithering used to render opacity, which approximates transparency without blending: "none" | "bayer8" | "bluenoise" | "ignnoise"
opacity-fades-specular	Boolean	"true"	Whether specular highlights fade out as the material becomes transparent
opacity-map	String	-	id of a texture <pc-asset> used as the opacity map
roughness	Number	-	Roughness of the material, from 0 (shiny) to 1 (rough). An alias for gloss that also sets gloss-invert, so do not combine it with the gloss attributes
roughness-map	String	-	id of a texture <pc-asset> used as the roughness map. An alias for gloss-map that also sets gloss-invert, so do not combine it with the gloss attributes
slope-depth-bias	Number	"0"	Depth offset applied in proportion to a surface's slope, used to resolve z-fighting
specular	Color	"0 0 0"	Specular color of the material. Applies only when the metalness workflow is disabled or use-metalness-specular-color is enabled
specularity-factor	Number	"1"	Strength of specular reflections at direct angles, from 0 to 1. Applies only when use-metalness-specular-color is enabled
two-sided-lighting	Boolean	"false"	Whether back faces are lit as though their normals were flipped
use-fog	Boolean	"true"	Whether the material is affected by scene fog
use-lighting	Boolean	"true"	Whether the material is affected by scene lights. When disabled, the material renders unlit using the diffuse color and map alone
use-metalness	Boolean	"true"	Whether to use the metalness workflow rather than the older specular workflow
use-metalness-specular-color	Boolean	"false"	Whether the specular color tints reflections while the metalness workflow is in use
use-skybox	Boolean	"true"	Whether the material is lit by the scene's skybox
use-tonemap	Boolean	"true"	Whether the camera's tone mapping is applied to the material

Texture Map Modifiers

Every *-map attribute above defines a texture slot, and each slot accepts a set of companion modifiers that configure how its texture is sampled. Replace <slot> with one of ao, diffuse, emissive, gloss, height, metalness, normal or opacity:

Attribute	Type	Default	Description
<slot>-map-channel	Enum	varies	Texture channel(s) to read the map from
<slot>-map-offset	Vector2	"0 0"	UV offset of the map
<slot>-map-rotation	Number	"0"	Rotation of the map in degrees
<slot>-map-tiling	Vector2	"1 1"	Tiling (repeat) of the map across the surface
<slot>-map-uv	Number	"0"	Index of the UV set used to sample the map

The -map-channel modifier varies by slot:

• The color maps (diffuse, emissive) accept "r" | "g" | "b" | "a" | "rgb" and default to "rgb".
• The scalar maps (ao, gloss, height, metalness) accept "r" | "g" | "b" | "a" and default to "g".
• The opacity map accepts "r" | "g" | "b" | "a" and defaults to "a".
• The normal map has no channel modifier — it always reads all three channels.

Example

<pc-app>
    <pc-asset src="assets/textures/dark-tiles.png" id="dark-tiles"></pc-asset>
    <pc-material id="crimson" diffuse="crimson"></pc-material>
    <pc-material id="gold" diffuse="#ffd700" metalness="1" roughness="0.3"></pc-material>
    <pc-material id="glass" blend-type="normal" opacity="0.4"></pc-material>
    <pc-material id="ground" diffuse-map="dark-tiles" diffuse-map-tiling="4 4"></pc-material>
    <pc-scene>
        <pc-entity name="box" position="-2 0 0">
            <pc-render type="box" material="crimson"></pc-render>
        </pc-entity>
        <pc-entity name="sphere">
            <pc-render type="sphere" material="gold"></pc-render>
        </pc-entity>
        <pc-entity name="capsule" position="2 0 0">
            <pc-render type="capsule" material="glass"></pc-render>
        </pc-entity>
        <pc-entity name="ground" scale="10 1 10">
            <pc-render type="plane" material="ground"></pc-render>
        </pc-entity>
    </pc-scene>
</pc-app>

A <pc-material> inserted at runtime (after the application has started) creates its material on insertion, so materials can be added dynamically from JavaScript. Attribute changes made at runtime also take effect immediately — a burst of changes is coalesced into a single material update — and removing a *-map attribute clears that texture slot.

JavaScript Interface

You can programmatically create and manipulate <pc-material> elements using the MaterialElement API.