A light source that can be attached to a node to illuminate the scene.


@interface SCNLight : NSObject


You illuminate your scene by attaching lights to SCNNode objects using their light property.

You set a light’s type using its type property. Depending on a light’s type, its position and direction may affect its behavior—you control the light’s position and direction through the node that the light is attached to. The direction of a light, if applicable to its type, is along the negative z-axis of its node’s local coordinate system.

A light’s other properties affect how it illuminates a scene. All lights have a color property, which interacts with SCNMaterial objects to produce the pixel colors in a rendered scene. Other properties, such as attenuation, shadowing, and spot angle, can affect the behavior of certain types of lights.

The number and type of lights in a scene is a key factor in SceneKit’s rendering performance. For efficient rendering, follow these tips:

  • Use SceneKit lights only for dynamic light sources or lights that affect moving objects. For statically lit portions of your scene, create a light map texture in an external 3D authoring tool (also known as baked lighting) and apply it to objects in the scene using the multiply material property.

  • Minimize the number of lights on each element of the scene. You can achieve most common lighting effects using no more than three lights, and you only need a single ambient light source. SceneKit only uses up to eight light sources per node when rendering, ignoring any additional lights. If you set the attenuationEndDistance property on a spotlight or omnidirectional light to limit its area of effect, SceneKit ignores the light (and its performance cost) when rendering objects outside that area. You can also use the categoryBitMask property to choose which nodes are illuminated by a light.


Creating a Light

+ light

Creates a new light object.

+ lightWithMDLLight:

Creates a light from the specified Model I/O light object.

Modifying a Light’s Appearance


A constant identifying the general behavior of the light.


Constants specifying the general behavior of a light, used by the type property.


The color of the light. Animatable.


The color temperature, in degrees Kelvin, of the light source. Animatable.


The luminous flux, in lumens, or total brightness of the light. Animatable.


Data describing the estimated lighting environment in all directions for a light probe.

Managing Light Attributes


A name associated with the light.

- attributeForKey:

Returns the value of a lighting attribute.

- setAttribute:forKey:

Sets the value for a lighting attribute.

Lighting Attribute Keys

Keys for specifying the behavior of a light using the attributeForKey: and setAttribute:forKey: methods.

Managing Light Attenuation


The distance from the light at which its intensity begins to diminish. Animatable.


The distance from the light at which its intensity is completely diminished. Animatable.


The transition curve for the light’s intensity between its attenuation start and end distances. Animatable.

Managing Spotlight Extent


The angle, in degrees, of the area fully lit by a spotlight. Animatable.


The angle, in degrees, of the area partially lit by a spotlight. Animatable.


An image or other visual content affecting the shape and color of a light’s illuminated area.

Managing Shadows Cast by the Light


A Boolean value that determines whether the light casts shadows.


A number that specifies the amount of blurring around the edges of shadows cast by the light. Animatable.


The color of shadows cast by the light. Animatable.


The size of the shadow map image that SceneKit renders when creating shadows.


The number of samples from the shadow map that SceneKit uses to render each pixel.


The mode SceneKit uses to render shadows.


Options for SceneKit’s rendering of shadows cast by a light, used by the shadowMode property.


The amount of correction to apply to the shadow to prevent rendering artifacts.


The orthographic scale SceneKit uses when rendering the shadow map for a directional light.


The maximum distance between the light and a visible surface for casting shadows.


The minimum distance between the light and a visible surface for casting shadows. Animatable.

Choosing Nodes to be Illuminated by the Light


A mask that defines which categories this light belongs to.

Managing Photometric Lights


The URL for a file that contains photometry data describing the intended appearance of the light.


Inherits From

See Also

Lighting, Cameras, and Shading


A set of camera attributes that can be attached to a node to provide a point of view for displaying the scene.


A set of shading attributes that define the appearance of a geometry's surface when rendered.


A container for the color or texture of one of a material’s visual properties.