Getting started with Text Box 2

Text Box 2 is a text solution for Unity that offers advanced layout and rendering functionality. It is currently in public beta. New features are released incrementally.

The package also includes a Utilities library with some useful stuff, which you can use in your own projects as well. For more information, go to the TextBox web page and the online code documentation.

Obtaining Bitmap Fonts

Before you can show text, you need a font. TTF fonts are avialable all over the web, both free and for sale. If you want to embed a font in your distributions, make sure you understand the licence of the font. Most fonts aren't allowed to be redistributed in any form. You'll have to contact the copyright holder of the font you want to use and negotiate a licence that covers your needs.

An example of a font that you can use is Comic Neue.

Now you might have a TTF font, but Text Box uses bitmap fonts. While you can use TTF fonts in Unity and it takes care of converting it to a bitmap representation, Text Box as its own format. You have to manually create a bitmap font yourself. While this is less convenient, it gives you a lot more control.

There are multiple free tools available for converting TTF fonts to bitmap fonts. Here are some of them.

There are also various commercial options, like bmglyph and Glyph Designer, both for OS X.

These tools all take a TTF file as input and output a FNT file containing character data and a PNG containing a font atlas. Make sure you export a square texture.

If you want to use any advanced shader effects, you have to generate a distance map from the font atlas. You can use the free Distance Map Generator tool for that. If you're going to use any effects that will make the text larger, like outlines or shadows, be sure to add a manual border between character when saving the bitmap font atlas.

Importing Bitmap Fonts

You can create a bitmap font in Unity via Assets / Create / Text Box / Bitmap Font. Click the Import FNT File and select the font you wish to import. The font asset will be filled with the data from the file.

After importing a font.

There are a few import setting that tweak how font data is imported. You might need these when imported fonts to which you added padding. Some tools incorrectly incorporates some padding into the font data in various ways, and the import settings allow you to compensate for this.

Now create a new material for your font. Select a shader and assign the font's texture to it. You can use one of the shaders found under Catlike Coding / Text Box. If you created a distance map, use one of the smooth shaders. Otherwise, use one of the alpha shaders.

Alpha blending material.

Text Box uses separate renderer objects to take of displaying its text. Create a new empty game object and a TextMeshRenderer component to it. You can find it in the menu at Component / Scripts / CatlikeCoding.TextBox / TextMeshRenderer. Turn it into a prefab and get rid of the instance in the scene.

Renderer prefab.

The font is now ready to be used.

Creating Text Styles

You can mix multiple fonts and styles in a text box, kind of like you use CSS in HTML, but more limited. You have to define a style collection asset where you define these styles. Create one via Assets / Create / Text Box / Style Collection.

The collection is simply an array of styles. You need to add at least one style, as the first one is used as the default style. You need to define all properties of this style. Make sure the color is not transparent. Additional styles will be applied on top of whatever is the current style, so only the values that you define will be adjusted.

A small style collection.

Creating a Text Box

Now you have everything you need to create a text box. Create a new game object and add a TextBox component via Component / Scripts / CatlikeCoding.TextBox / TextBox.

Make sure it has a style collection, otherwise no text will be shown. Also make sure that the maximum height allows for at least one line of text to be shown.

Any text that you type in the Default Text area should show up immediately. You can apply styles by using tags, like I want <stylename>styled</stylename> text! The tags should match the names of the styles you defined in your style collection, otherwise they are ignored.

Actually, you do not need to repeat the style name in the closing tag. A simple </> will do, everything after the slash is ignored.

rendered text text box inspector
A text box with styled text.

Scripting Text Content

You can change the contents of the text box via code with the SetText method. This does not replace the default text, only what is currently shown. You can pass it either a string or a StringBuilder object. The latter is very useful when you're working with dynamic text.

Setting the text won't automatically update the text box. After making any changes, you have to call the RenderText method. This will take care of updating the entire overflow chain that the box is part of.