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

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.

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.

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)

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)];

There are 2 types of labels based on texture atlas:

• CCLabelBMFont
• CCLabelAtlas

The CCLabelBMFont 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 CCLabelBMFont 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)
• http://glyphdesigner.71squared.com/ (Mac only)
• http://www.bmglyph.com (Mac only)
• http://tinyfont.com (Mac 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

To create a CCLabelBMFont object you need to do:

CCLabelBMFont *label = [CCLabelBMFont labelWithString:@"Hello World" fntFile:@"bitmapFontTest.fnt"];
[self addChild:label]

Since the font is a fixed size you will need to carefully consider which font sizes you will need. Having a separate font for each size may be inefficient due to the amount of texture memory it takes. In this case it might make sense to scale down labels made with a suitable large font to achieve different sizes. Since the label is just a CCNode, you can do this with the scale properly.

Since CCLabelBMFont 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:

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

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.

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.

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.

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)];