Overview

CCLabelTTF displays text rendered using a TrueType (TTF, OTF) font.

Attributed strings are supported on Mac and iOS6+ which allow for greater text formatting control.

Performance Note

Each time the label’s string property changes a new CCLabelTTF texture is created and rendered, and the previous one discarded. This adds a huge performance penalty on every text change. If you need to frequently update a label’s text, you have two options:

• Use CCLabelBMFont which does not incur such a penalty. Requires creating a font with an external bitmap font editing tool.
• Create and cache all possible string variants as individual CCLabelTTF. Only suitable if the number of possible string permutations is low and all strings are known beforehand. For example, assuming you use a fixed-width font you could use label nodes with digits 0 through 9 and create your own digit counter node using n times ten label nodes, where n stands for the total number of digits you expect to display at most. However consider the next paragraph.

Memory Usage Note

Each label, even when using the same string and font and all other properties being identical, will still create its own texture.

So if you have 100 label nodes with a “Hello” string you will have 100 “Hello” textures in memory. This behavior is unlike other nodes, for instace sprites created from the same image file load and share identical textures.

If you use many labels in the same scene you should look into bitmap fonts and CCLabelBMFont.

iOS Fonts List

Here’s a list of fonts built into iOS and their font names. Fonts not in this list will have iOS automatically pick the font that closely resembles the desired font, or a default font.

Custom Fonts

It is possible to add custom truetype fonts to an iOS application and use the font with CCLabelTTF. For instructions and troubleshooting carefully read this Q&A post.

Note that a very common mistake is to assume the font filename or family name as the fontName property. Assuming you have a font named “Avenir Condensed” then you need to find out the actual font identifier, which may be labelled AvenirNextCondensed-HeavyItalic. That’s the identifier you need to use. A typical giveaway that you got the wrong identifier is if the string contains a space character.