<!--
{
  "availability" : [
    "iOS: 15.0.0 -",
    "iPadOS: 15.0.0 -",
    "macCatalyst: 15.0.0 -",
    "macOS: 12.0.0 -",
    "tvOS: 26.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "RealityKit",
  "identifier" : "/documentation/RealityKit/CustomMaterial/specular-swift.property",
  "metadataVersion" : "0.1.0",
  "role" : "Instance Property",
  "symbol" : {
    "kind" : "Instance Property",
    "modules" : [
      "RealityKit"
    ],
    "preciseIdentifier" : "s:17RealityFoundation14CustomMaterialV8specularAC8SpecularVvp"
  },
  "title" : "specular"
}
-->

# specular

The bright highlights to apply to the entity.

```
var specular: CustomMaterial.Specular { get set }
```

## Discussion

In physically based rendering (PBR), specular highlights primarily come
from the object’s [`roughness`](/documentation/RealityKit/PhysicallyBasedMaterial/roughness-swift.property)
value. RealityKit renders materials that have a low roughness value with
specular highlights based on the environment, lighting, and shape of the
entity. As a result, for most materials, you don’t need to specify a
`specular` value.

For some types of dielectric (nonmetallic) materials, like facet-cut
glass or gems, PBR algorithms don’t create bright enough specular
highlights using just roughness. To accurately simulate those types of
materials, the [`specular`](/documentation/RealityKit/PhysicallyBasedMaterial/specular-swift.property)
property allows you to specify additional specularity for the entity.

The following example demonstrates how to add specularity using a single
value for the entire material:

```swift
material.specular = .init(floatLiteral: 0.8)
```

The following code shows how to add specularity using a UV-mapped image
texture:

```swift
if let specularResource = try? TextureResource.load(named: "entity_specular") {
    let specularMap = MaterialParameters.Texture(specularResource)
    material.specular = .init(texture: specularMap)
}
```

With custom materials, the specular
[`scale`](/documentation/RealityKit/CustomMaterial/Specular-swift.struct/scale) and
[`texture`](/documentation/RealityKit/CustomMaterial/Specular-swift.struct/texture) are available to the
material’s shader functions, but RealityKit doesn’t automatically use
the values you set.
To render a custom material with additional specular highlights, 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_specular()`
from its surface shader.

The following Metal code demonstrates using the specular scale and
texture values, simulating the behavior of the shaders that render a
[`PhysicallyBasedMaterial`](/documentation/RealityKit/PhysicallyBasedMaterial):

```cpp
// Retrieve the opacity scale from the CustomMaterial.
float specularScale = params.material_constants().specular_scale();

// Retrieve the entity's texture coordinates.
float2 uv = params.geometry().uv0();

// Entities loaded from a USDZ or .reality file use texture coordinates
// with a flipped y-axis. This compensates for that.
uv.y = 1.0 - uv.y;

// Sample the specular texture.
auto tex = params.textures();
half specular = tex.specular().sample(textureSampler, uv).r;

// Multiply the tint and the sampled value from the texture and assign
// the result.
specular *= specularScale;
params.surface().set_specular(specular);
```

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 &copy; 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)