iOS Developer Library — Prerelease

Developer

SpriteKit Framework Reference SKLightNode Class Reference

Options
Deployment Target:

On This Page
Language:

SKLightNode

A SKLightNode object is used to add lighting into a scene.

To use lighting, add a light node to the scene. Because lights are nodes, they can be moved or perform actions just like other nodes. However, light nodes are invisible except through their effects on sprite nodes configured to interact with them. When a sprite node is affected by a light, the lighting properties of the light node and the lighting properties of the sprite node determine what is rendered. Lighting may affect how unrelated portions of the scene are rendered. For example, if a sprite is configured to cast a shadow, the shadow is rendered on top of other content.

An SKLightNode object and an SKSpriteNode object add lighting to the scene if all of the following things are true:

  1. The light node and the sprite node are both in the scene.

  2. The light node’s enabled property is YEStrue.

  3. The light node’s lightCategoryBitMask property and one of the sprite’s lighting masks are logically combined using an AND operation, and the result is a nonzero number.

Table 1 describes the different kinds of effects that can be generated by a light, based on which mask is being tested on the sprite.

Table 1Lighting effects

Sprite Node Mask

Effect

lightingBitMask

The sprite is lit by the light with specular, diffuse, and ambient lighting.

shadowCastBitMask

When the light casts a ray that intersects the light, a shadow is projected past the sprite, rendered on top of any content that is below the sprite.

shadowedBitMask

If the sprite is inside a shadow cast by a light and the sprite has a lower z position than the light, the shadow affects how the sprite is lit.

If any of the criteria are not met, the sprite is considered unlit and is rendered using the default behavior.

  • A Boolean value that indicates whether the light is casting light.

    Declaration

    Swift

    var enabled: Bool

    Objective-C

    @property(nonatomic, getter=isEnabled) BOOL enabled

    Discussion

    If the value is YEStrue, the light is enabled and affects sprite nodes in the scene. The default is YEStrue.

    Availability

    Available in iOS 8.0 and later.

    See Also

    isLit
    light

  • A mask that defines which categories this light belongs to.

    Declaration

    Swift

    var categoryBitMask: UInt32

    Objective-C

    @property(nonatomic) uint32_t categoryBitMask

    Discussion

    Every light in a scene can be assigned to up to 32 different categories, each corresponding to a bit in the bit mask. Sprite Kit does not predefine any lighting categories, so it is up to you to define which values are used in your game. When a scene is rendered, a light’s lightCategoryBitMask property is compared to each sprite node’s lightingBitMask, shadowCastBitMask, and shadowedBitMask properties to determine whether that sprite interacts with the light.

    The default value is 0x00000001.

    Availability

    Available in iOS 8.0 and later.

  • The ambient color of the light.

    Declaration

    Swift

    var ambientColor: UIColor

    Objective-C

    @property(nonatomic, nonnull) UIColor *ambientColor

    Discussion

    The alpha value of the color is ignored. The default color is black, meaning that the light does not have an ambient component. The ambient component of the light is not affected by the light’s falloff property, nor is it affected by any normal map (normalTexture) on the sprite node.

    Availability

    Available in iOS 8.0 and later.

  • The diffuse and specular color of the light source.

    Declaration

    Swift

    var lightColor: UIColor

    Objective-C

    @property(nonatomic, nonnull) UIColor *lightColor

    Discussion

    The default value is white.

    If you are using custom shaders, you can substitute an SKUniform object instead.

    Availability

    Available in iOS 8.0 and later.

  • The color of any shadow cast by a sprite.

    Declaration

    Swift

    var shadowColor: UIColor

    Objective-C

    @property(nonatomic, nonnull) UIColor *shadowColor

    Discussion

    The default color is black with an opacity (alpha) of 0.5.

    When lighting is calculated, shadows are created as if a ray was cast out from the light node’s position. If a sprite casts a shadow, the rays are blocked when they intersect with the sprite’s physics body. Otherwise, the sprite’s texture is used to generate a mask, and any pixel in the sprite node’s texture that has an alpha value that is nonzero blocks the light.

    Shadows may be cast on content that is rendered prior to the sprite, even if that content does not otherwise interact with the light.

    Availability

    Available in iOS 8.0 and later.

  • The exponent for the rate of decay of the light source.

    Declaration

    Swift

    var falloff: CGFloat

    Objective-C

    @property(nonatomic) CGFloat falloff

    Discussion

    The default value is 1.0, which means the light decays linearly with distance. The value must be a positive number less than or equal to 1.0.

    Availability

    Available in iOS 8.0 and later.