CocosSharp – Using CCLabel

This post is part of my Mobile Game Development series. Start at the beginning to catch up. This series was inspired by the things I learned developing a new game for Android and iOS called Mirror Maze.

There’s already documentation on CCLabel available from the CocosSharp team, so this won’t be a comprehensive post on the topic. However, there are some things I’d like to point out.

When I developed Mirror Maze, I wanted to use a custom font to give the game its own unique look-and-feel. There are a lot of places online to find free fonts which have licenses that allow usage in your projects. Using the font that I chose in CocosSharp was easy and just required making sure everything was set up as the engine expected.

The Setup

As I covered in the Foundation post, your GameView should be configured to look for your assets in the Content folder. One of the folders within the content folder is for your fonts and is aptly named, “Fonts”. Without this setup code, CocosSharp will never know where to find your font files, so make sure you have it configured properly before moving on.

Next, copy the .ttf file for your font to the Content/Fonts folder for both Android and iOS projects. I found that Xamarin Studio properly set the BuildAction for Android to AndroidAsset for me, but I had to manually set the BuildAction for iOS to BundleResource. Double check each of those to make sure yours is set correctly also, or CocosSharp won’t find the font at runtime. You’ll know whether you did this correctly when you run your game. CocosSharp will not error out when it can’t find your font, but it will revert to the default font.


Once you have your font included in your platform-specific projects, you can put it to use with a label instance.

Let me break this down a bit.

Parameter 1: “Hello World”
This is the initial text displayed by the label. It can be changed at run-time, which we will talk about in a bit. It’s important to note that, for sizing purposes, you have to have a value for this. Starting with an empty string will give you a width and height of 0, which can be problematic when it comes time to properly position the label, particularly if you are doing vertical positioning. If you have to start with dummy text, then change it at run-time, do it.

Parameter 2: “Fonts/myfont.ttf”
This is the location of the font file to use, within the Content folder. The file extension isn’t supposed to be required, but I found in practice that it is.

Parameter 3: 40 * Constants.FontSizeMultiplier
This is the font size. You can have this be a fixed size, but I found that font sizes need to scale just like sprite graphic files do. I covered the reasoning behind this in the Foundation post. Constants.FontSizeMultiplier is a static float that is set during the initial startup code.

Parameter 4: CCLabelFormat.SystemFont
This is the type of font being used. When you use your own font file that is included in the projects, you will use CCLabelFormat.SystemFont.

Making Run-Time Changes

Now that you’ve got an instance of a label, you can position it just like any other node. You may also find the need to update that label with different text, or even colors, at run-time. Either of these are simple to change.

The code above changes the text of the label. As simple as this is, there’s a gotcha that I found in practice with this: Every time I’ve changed the text of a label after it has been initially instantiated, I’ve found that a few bytes of memory are leaked. I haven’t taken the time yet to dive into the CocosSharp code to see why that might be the case, but I found it to be consistently true. A few bytes of memory leaked may not seem like a big deal. Do that enough times, however, and eventually the device can run out of memory, causing your game to crash. Just something to keep in mind.

The code above changes the color of the label to red. What’s important to note there is that the color in this case uses the CCColor3B struct, which is different from CCDrawNode (which uses CCColor4B). CCColor3B and CCColor4B both are very similar. However, in practice, I found that a label with a custom color will render as a slightly different color from the CCDrawNode rendered with the “same” custom color. Again, I haven’t looked into the CocosSharp code to find out why this is the case, but it is noticeable if you place the two next to each other.

That wraps up our discussion of CCLabel as well as the provided implementations of the CCNode class. In my next post, I’ll talk about what it takes to implement your own custom CCNode class.

Leave a Reply

Your email address will not be published. Required fields are marked *