# metallic The reflectiveness of an entity. ``` var metallic: CustomMaterial.Metallic { get set } ``` ## Discussion In physically based rendering, the `metallic` property represents the reflectiveness of an entity. Use this property to specify whether the entity displays metallic qualities and reflects the surrounding environment, or displays dielectric qualities and doesn’t reflect the environment. With custom materials, RealityKit doesn’t automatically use the values set on this property. To render a custom material using the metallic property, set [`lightingModel`](/documentation/RealityKit/CustomMaterial/lightingModel-swift.property) to [`CustomMaterial.LightingModel.lit`](/documentation/RealityKit/CustomMaterial/LightingModel-swift.enum/lit) or [`CustomMaterial.LightingModel.clearcoat`](/documentation/RealityKit/CustomMaterial/LightingModel-swift.enum/clearcoat) and call `params.surface().set_roughness()` from its surface shader.  The following Swift code shows how to use an image and a scale to specify roughness: ```swift if let metallicResource = try? TextureResource.load(named:"entity_metallic") { let metallic = MaterialParameters.Texture(metallicResource) material.metallic = PhysicallyBasedMaterial.Metallic(scale: 1.0, texture:metallic) } ``` The following surface shader takes the scale and texture values from the [`metallic`](/documentation/RealityKit/CustomMaterial/metallic-swift.property) property, multiplies them together, and uses the result to specify the metallic value for rendering, which emulates the behavior of [`PhysicallyBasedMaterial`](/documentation/RealityKit/PhysicallyBasedMaterial). ```cpp #include #include using namespace metal; // Use samplers to retrieve a color value from a texture based on // the entity's UV coordinates. Samplers can be reused with different textures. // Surface shader functions should define no more than eight samplers. constexpr sampler textureSampler(address::clamp_to_edge, filter::bicubic); [[visible]] void mySurfaceShader(realitykit::surface_parameters params) { // Retrieve the metallic scale from the CustomMaterial. float metallicScale = params.material_constants().metallic_scale(); // Retrieve the entity's texture coordinates. float2 uv = params.geometry().uv0(); // Entities loaded from USDZ or .reality files have texture coordinates // with a flipped y-axis. This adjusts for that. uv.y = 1.0 - uv.y; // Sample the metallic texture based on the UV coordinates. auto tex = params.textures(); half metallic = tex.metallic().sample(textureSampler, uv).r; // Multiply the tint and the sampled value from the texture, // and assign the result to the shader's metallic property. metallic *= metallicScale; params.surface().set_metallic(metallic); } ``` For more information on creating custom materials and writing shader functions, see [Modifying RealityKit rendering using custom materials](/documentation/RealityKit/modifying-realitykit-rendering-using-custom-materials). --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)