Cocos2d Dynamic Lighting Tutorial

What you are going to learn

  • Creating a lighted scene in SpriteBuilder
  • Creating normal maps using SpriteIlluminator
  • Using CCLightNode and CCEffectLight
  • Setting parameters for directional and point lights
  • Complete code is on GitHub

Required skills

  • Basic skills in SpriteBuilder and cocos2d
  • Basic skills in Objective-C or Swift

Creating a lighted scene in SpriteBuilder

Start by creating a new SpriteBuilder project. You decide which programming language you are going to use - this tutorial covers both: Objective-C and Swift.

Add the resources

Clean the main scene: Remove the default CCNodeGradient and CCLabelTTF from the scene.

You need 2 files for dynamic lighting:

  • A sprite - containing the color information
  • A normal map - containing the direction of each pixel in the sprite

I've created both files for you — for a fast start. You are going to learn now you can easily create normal maps later. Download them now:

character original sprite character.png character normal map character_n.png

Add both to your project's ccbResources. The sprite is designed for Retina iPads. Set Scale from to a value of 4x for both - the normal map and the sprite. See image on the right.

Spritebuilder scaling settings

Create a normal mapped sprite

Drag the sprite from the ccbResources onto the stage to create a CCSprite

To attach the normal map, you simply have to select the sprite. In the right panel under the section, CCSprite is a combo box named Normal map. Use it to select character_n.png.

So — this is your first normal mapped sprite... not really impressive — I have to admit!

The reason is simple: You have to enable the CCEffectLight on the sprite to see any difference.

Spritebuilder adding a normal map to a sprite

Enabling the light effect - CCEffectLight

With the sprite selected press the +Add button at the top of the Effects list.

From the drop down menu select Lighting.

This adds a CCEffectLight to the sprite. You have to add this to all sprites that you want to be effected by lighting.

I'll explain the settings for the effect a bit later — you have to set up the light source first. The scene is currently lighted with SpriteBuilder's default light.

Opening this project in XCode will show you a black screen. This is because you have not yet added a real light source in form of a CCLightNode.

Spritebuilder enabling light settings

Add a light source - CCLightNode

Spritebuilder adds a CCLightNode

Open SpriteBuilder's Node Library View, drag and drop a Light Node on your stage.

Drag the node around to see the character lighted from different angles.

This is much better!

Opening the scene in XCode now also gives you a lighted scene. The light source object is only visible in SpriteBuilder - in the XCode it is not.

To create a visible light object in XCode, you can use a sprite and set the CCLightNode as a child.

XCode's iPhone Simulator has some trouble with the light effects. The framerate in the simulator is poor. Build for the real device to get full framerate.
Spritebuilder: Scene with light

Customizing your light source

A light source comes with a whole bunch of settings.

Light Type

The point light is a light source which emits radial light from a single spot. You can think of it as a candle or light bulb. It's light range is usually limited.

The directional light is a light source that emits parallel light. Think of it as a big, distant light source like the sun. It's light is not limited by distance.

Light Groups
Setting a light group allows you to filter the sprites which are effected by the light source. You can set the group on the CCEffectLight and restrict the effect to only matching sprites and lights.
Diffuse Color + Intensity
The color and intensity that is used for diffuse lighting. Diffuse light creates a soft light on the surface.
Specular Color + Intensity
The color and intensity of the highlights through directly reflected light. The amount of specular highlights is also effected by the Shininess and Specular Color set on the sprite's CCEffectLight
Ambient Color + Intensity
The color and intensity of the background light. All parts of the sprite are equally lighted by this.
Cutoff Radius
The radius around the point light which is lighted.
Half Radius
The distance in which the light reaches 50% intensity. The value is relative to the Cutoff Radius. Set it to 1.0 to get a hard-edged light. The lower the value the softer the light. Only works with point light.
The z-value of the light. Positive values are closer to the user, negative values are behind the scene.
Spritebuilder light settings
Light settings

Customizing your sprite's material

The sprite's material can be customized in the CCEffectLight's settings attached to the sprite.

The amount of light that is directly reflected from the light source to the user or player.
Specular color
The color of the reflected light.
Light groups
Values here must correspond to the CCLightNode's Light groups if you want the sprite to be effected by that source.

Shininess and Specular color interact with the light's Specular color and Specular intensity.

Spritebuilder effect light settings
Sprite's light effect settings

Creating different scenarios: Parameters for CCLightNode

Animating the light source is easy - it simply behaves like any other CCNode in Cocos2d. You can even attach it to some game object as sub-node — e.g. a torch.

The following scenarios are all implemented in the demo project on GitHub:

Point light scenario

cocos2d point light scene

Settings for this scenario:

  • Point light
  • Ambient light:  
  • Diffuse light:  

Campfire scenario

cocos2d point light scene with particles

Settings for this scenario:

  • Point light
  • Ambient light:  
  • Diffuse light:  
  • Particle emitter to simulate fire
  • Light source position is randomly animated around the fire emitter's center

Summer scenario

cocos2d directional light scene

Settings for this scenario:

  • Directional light
  • Ambient light:  
  • Diffuse light:  

Winter scenario

cocos2d directional light scene with particles

Settings for this scenario:

  • Directional light
  • Ambient light:  
  • Diffuse light:  
  • Some snow particles

I think that you've now seen what you can accomplish with dynamic lighting. And best of all: There's really not much work involved.

Now there's one question left:

How can I create NormalMaps?

We've created a tool for this: It's called SpriteIlluminator. You can download a trial version from here:

Install and start the application. It'll automatically activate a 7 days trial which you can use to experiment with dynamic lighting.

spriteilluminator screenshot

1. Add sprites

Drag & drop your character.png sprite onto the left panel. You can add multiple sprites to a project.

2. Apply effects

For a quick start choose the Bevel effect from the tools palette to extrude the shape.

3. Publish the sprite

Press Publish. The normal map is created in your sprite's path containing the suffix _n. In this example, it'll be character_n.png

You can change this behavior using the Publish as

What are you waiting for? Start Experimenting now!

The source code contains an ObjC and Swift version.
Thanks to collidernyc from Cocos2d Forum for creating the Swift port.

Did you like the tutorial? Please share!

Source code available for download

The source code is available on GitHub. Clone it using git:

git clone

or download one of the archives: cocos2d-dynamic-lighting-with-normal-maps.tar.gz