Cocos2d Customize Labels and Fonts

cocos2d supports both TTF (True Type Fonts) labels, and texture atlas labels.

(Please note that from cocos2d Version .7+ on, the label is added to it's layer via addChild: and not add: e.g. [self addChild:myLabel];)

Pros and Cons of TTF labels: ( CCLabel )

*
+ All the pros of TTF fonts: any size, kerning support, etc.
*
+ Easy to use. No need to use an external editor.
*
- The creation/update is very slow since a new texture will be created

Pros and Cons of texture atlas labels: ( CCLabelAtlas, CCBitmapFontAtlas )

*
+ The creation / update is very fast, since they don't create a new texture.
*
+ Fonts can be customized (shadows, gradients, blur, etc)
*
- Depends on external editors: AngelCode / Hiero editor, GIMP / Photoshop

Creating labels: Simple way

The easiest way to create a label is by using the CCLabel object. Example:

CCLabel *label = [CCLabel labelWithString:@"Hello World" fontName:@"Marker Felt" fontSize:24];
[self add: label];

fontName is the TTF font name to be used.

You can use your own custom TTF file. You just need to add the .ttf file to the project. Example of custom TTF file:

CCLabel *label = [CCLabel labelWithString:@"Hello World" fontName:@"Schwarzwald Regular" fontSize:24];
[self add: label];

*
cocos2d will try to load the font trying to use the FontLabel library.
*
If it fails it will use the UIFont class

Important: The size of the OpenGL texture will be automatically calculated based on the font size and font name.
Creating labels: Complex way

You can also create textures using this API:

CCLabel *left = [CCLabel labelWithString:@"Hello World" dimensions:CGSizeMake(480,50) alignment:UITextAlignmentLeft fontName:@"Marker Felt" fontSize:32];
[self add: left];

If you use this way, you should pass the dimension of OpenGL texture to be used. If the texture is not big enough, then only some parts of the label will be rendered.

Possible alignments:

*
UITextAlignmentLeft (left alignment)
*
UITextAlignmentCenter (center alignment)
*
UITextAlignmentRight (right alignment)==== Updating ====

Like any object that implements the CCLabelProtocol protocol you can update it using the setString method. Example:

[label setString: @"Hello World 2"];

Important: Every time you call setString a NEW OpenGL texture will be created. This means that setString is as slow as creating a new CCLabel. So, DO NOT use CCLabel objects if you need to update them frequently. Instead use CCLabelAtlas or CCBitmapFontAtlas.
Color

You can change the color of your fonts by simply calling the color parameter like so:

label.color = ccc3(0,0,0);
//or
label.color = ccc4(0,0,0,0);

ccc3 Example Colors:

white - (255,255,255)

black - (0,0,0)

blue - (0,0,255)

green- (0,255,0)

red - (255,0,0)

Grey – (84,84,84)

Brown – (165,42,42)

Pink – (255,192,203)

Purple – (160,32,240)

Yellow – (255,255,0)

Gold – (255,215,0)
Alignment

If you want to modify the alignment you can use the anchorPoint property. Example:

//left alignment
[label setAnchorPoint: ccp(0, 0.5f)];

// right alignment
[label setAnchorPoint: ccp(1, 0.5f)];

// center aligment (default)
[label setAnchorPoint: ccp(0.5f, 0.5f)];

Texture Atlas labels

There are 2 types of labels based on texture atlas:

*
CCBitmapFontAtlas
*
CCLabelAtlas

Introduction

The CCBitmapFontAtlas is the suggested way to create fast labels since:

*
The bitmap (image) can be customized with the editors
*
You can update/init the label without penalty
*
It is very flexible. Each letter of the label can be treated like an CCSprite
*
It has kerning support

The CCBitmapFontAtlas label parses the Angel Code Font format to create a label. To create these kind of labels, you can use any of these editors:

*
http://www.n4te.com/hiero/hiero.jnlp (java version)
*
http://slick.cokeandcode.com/demos/hiero.jnlp (java version)
*
http://www.angelcode.com/products/bmfont/ (windows only)

Java editors vs. Windows editor:

*
The Windows editor is the official Angel Code editor
*
Java editors: run on Mac
*
Java editors: have additional features like shadow, gradient, blur

Creating a BitmapFontAtlas

To create a CCBitmapFontAtlas object you need to do:

CCBitmapFontAtlas *label = [CCBitmapFontAtlas bitmapFontAtlasWithString:@"Hello World" fntFile:@"bitmapFontTest.fnt"];
[self add:label]

Manipulating each character

Since CCBitmapFontAtlas is a subclass of CCSpriteSheet you can manipulate each character as an CCSprite. The 1st character will be added with tag = 0, the 2nd character will be added with tag=1, and so on. Example:

CCBitmapFontAtlas *label = [CCBitmapFontAtlas bitmapFontAtlasWithString:@"Bitmap Font Atlas" fntFile:@"bitmapFontTest.fnt"];
CCSprite *char_B = (CCSprite*) [label getChildByTag:0]; // character 'B'
CCSprite *char_m = (CCSprite*) [label getChildByTag:3]; // character 'm'

LabelAtlas

Introduction

CCLabelAtlas was the 1st fast label added into cocos2d. But it was superseded by CCBitmapFontAtlas. It is being maintained for backwards compatibility, but you should use CCBitmapFontAtlas instead.
Creating a LabelAtlas

CCLabelAtlas *label = [CCLabelAtlas labelAtlasWithString:@"Hello World" charMapFile:@"tuffy_bold_italic-charmap.png" itemWidth:48 itemHeight:64 startCharMap:' '];
[self add:label];

*
charMapFile is an image file that contains all the characters. Each character should be ordered according to its ASCII value and the image can't contain more than 256 characters.
*
itemWidth is the width of the characters in pixels
*
itemHeight is the height of the characters in pixels
*
startCharMap is the first character of the map.

Updating a LabelAtlas / BitmapFontAtlas

Like any object that implements the CCLabelProtocol protocol you can update it using the setString method.

[label setString:@"Hello World 2"];

It is worth noting that updating a CCLabelAtlas or a CCBitmapFontAtlas has almost no penalty.
Alignment in LabelAtlas / BitmapFontAtlas

If you want to modify the alignment you can use the anchorPoint property. Example:

//left alignment
[label setAnchorPoint: ccp(0, 0.5f)];

// right alignment
[label setAnchorPoint: ccp(1, 0.5f)];

// center aligment (default)
[label setAnchorPoint: ccp(0.5f, 0.5f)];