Introduction

The text object can be used to display written information. The text object supports:

• Horizontal and Vertical alignment

• Fonts from the installed font library on your machine

• Custom fonts using Bitmap Font Generator: http://www.angelcode.com/products/bmfont/

• Scaling independent of source font

Introduction

The Font variable sets the font family used by the text.

This dropdown appears only if Use Custom Font is set to false.

The Font dropdown has access to any font which is installed locally.

To use a font in Gum, download the font and install it by double-clicking or right-clicking on the font.

Font Generation and Font Cache

Gum performs rendering using rasterized fonts. In other words, it renders using pre-made .png files which contain all of the characters in a font.

You can view the Font Cache in your project by selecting Content -> View Font Cache.

This folder contains all font files used by your project.

Note that each font has three files:

• bmfc - Bitmap Font Generator configuration file. This can be opened in Bitmap Font Generator to see the settings that have been used to export the other files

• fnt - Bitmap Font Generator font file. This is a text file indicating the location of each character in the matching png files. It also includes kerning pairs.

• png - This is the image file containing the letters for the font. The font may contain multiple image files if the character set or font size are large enough.

Each PNG can be opened in an image editor to view the packed characters. For example, the following shows the Arial 24 font. The blue background has been added manually to make the white characters visible:

Font Cache Generation

Fonts are generated as needed by Gum. This happens whenever a property changes on a Text object requiring a new font. Gum only re-generates fonts if a matching font doesn't already exist. The following animation shows new fonts being generated as a Text's Font Size is changed.

Fonts are generated in response to any of the following properties changing:

• Font

• Font Size

• Outline Thickness

• Is Italic

• Is Bold

• Use Font Smoothing

The Green value controls the color of the Text object. The Green value has a range of 0 - 255. The Green value combines with the Blue and Red values to create the final color.

For more information on working with color, see the .

Introduction

The font scale property allows you to zoom a font in or out, effectively making the text larger or smaller. Unlike using the font size property, font scale will not re-create the font (when using standard fonts). Font scale is also necessary for resizing custom fonts.

Details

By default Text objects Font Scale value of 1.

Font scale can be increased, but doing so can make fonts pixellated. For example, setting the Font Scale value to 5 makes each pixel on the font 5x as large, resulting in a pixellated text object.

Similarly, FontScale can be set to a value smaller than 1, resulting in a shrunk font.

Introduction

Font Size controls how large a font appears on screen. Each font size and Font combination creates its own rasterized font, so using a lot of different font sizes will increase the amount of texture memory your game needs.

Example

The Font Size property can be set in Gum to make a text object's font larger or smaller. For example, the following shows a Text object with a font size of 18:

Changing the font size will increase the size of the Text object. For example, here is the same Text object with a Font Size of 36:

Font Cache

The first time a Font and Font Size combination are referenced, Gum creates a file in the FontCache folder. You may notice a small pause in Gum when setting Font and Font Size combinations for the first time as the file is created, but subsequent changes will be fast.

The FontCache folder is located in the following location:

/FontCache/

The Blue value controls the color of the Text object. The Blue value has a range of 0 - 255. The Blue value combines with the Red and Green values to create the final color.

For more information on working with color, see the .

Introduction

The Color value controls a Text object's color. The Color value is created by combining the Red, Green, and Blue values.

The Color value can be changed through the color picker, or by changing the individual Red, Green, and Blue color values.

Color Multiplication

For default Text objects, the Color value modifies the displayed Text color. Gum creates .fnt and .png files where the color is white. If the .png includes any colors that are not white, then the resulting color is produced by multiplying the color value with each pixel. Therefore, if a Font is outlined, then the black pixels remain black.

Introduction

OutlineThickness can be used to create an outline around a font. The outline is saved in the .png of the font itself, so each value for OutlineThickness results in a new .fnt file and associated .png files created in the FontCache folder.

Setting OutlineThickness

The OutlineThickness can be set on a Text object like any other variable.

OutlineThickness changes appear in the Gum window.

Introduction

Text Overflow Horizontal Mode controls how truncated words are treated. Horizontal truncation is only performed if the Text instance is using a Text Overflow Vertical Mode of Truncate Line. For information more see the Text Overflow Vertical Mode page.

Truncate Word

Truncate Word results in words which do not fit in the Text instance's bounds being completely removed.

The following animation shows words (and lines) truncated in response to changing a Text instance's size.

Ellipsis Letter

Ellipsis Letter results in letters which do not fit in the Text instance's bounds being replaced by an ellipsis (...) which fits in the bounds of the Text instance.

The following animation shows words (and lines) replaced by ellipsis in response to changing a Text instance's size.

Note that additional letters must be removed from the Text instance so the added ellipsis fits in the Text instance's bounds.

Introduction

The Is Bold value controls whether the Text instance uses an auto-generated font which is bold.

Introduction

This value controls the number of letters that the Text object will show. This value is used when displaying the text, but is not used when calculating the Text size or line wrapping.

If the value is <NULL>, then there is no maximum - all letters are displayed.

Example

Max Letters To Show limits the number of characters (including spaces). By default this value is <NULL>, which means a Text object will display its full string. Setting this value will adjust the display of the text, but it will not impact any layout values.

For example, by default a Text object displays all of its letters. Note that the Width is fixed, and the Height depends on the contained text - the Height is automatically set on the Text object according to the contents of the text.

Setting Max Letters To Show value to 30 restricts the Text object to displaying its first 30 characters, but the size and line wrapping do not change.

Max Letters To Show applies after all layout and text positioning has been applied. Therefore, centered text may appear off-center. The following text would appear centered if Max Letters To Show allowed the entire text to be displayed, but since it is cut-off, it appears off-center.

The Red value controls the color of the Text object. The Red value has a range of 0 - 255. The Red value combines with the Blue and Green values to create the final color.

For more information on working with color, see the .

Introduction

Text Overflow Vertical Mode controls whether lines of text can draw outside of the bounds of the Text object vertically.

Spill

Spill enables the drawing of text lines outside of the vertical bounds of a Text instance. The following image shows a Text instance with wrapped text using Spill.

Truncate Line

Truncate Line removes lines which fall outside of the bounds of the Text instance. The following animation shows lines of text truncating in response to changing the Text instance's height.

Note that if the Text instance's height becomes too small then all text disappears.

Introduction

Text objects have a Text property which controls the displayed text. By default this value is set to "Hello".

Changing Text

The Text property can be changed in the multi-line edit window.

Text will wrap according to the Text object's Width.

The enter key can be used to add new lines to text.

Using BBCode for Inline Styling

Gum text supports inline styling using BBCode-like syntax. To add inline styling, surround text with variable assignment tags as shown in the following screenshot:

The following table shows the available variables that can be used for inline styling:

Note that changing Font and FontSize results in new Fonts created in the Font Cache.

BBCode can span multiple lines, whether the newlines happen due to line wrapping or through the addition of newlines in the text.

Multiple tags can overlap each other allowing you to combine tags for a single piece of text. For example, the following sets text to both bold and orange:

This is [Color=Orange][IsBold=true]bold and orange[/Color][/IsBold] text.

Styles can contain other styles as many levels deep as necessary.

This [Color=Orange]is orange, [IsBold=true]bold[/IsBold], and [IsItalic=true]italic[/IsItalic][/Color] text.    

Introduction

The Is Italic value controls whether the Text instance uses an auto-generated font which is italicized.

Introduction

The Is Italic value controls whether the Text instance uses an auto-generated font which applies font smooth (anti-aliasing). This effect of this value can be easily observed if zoomed in.

This value is true by default because it usually produces more visually appealing fonts. If your project is using an intentionally pixelated font then you may want to disable this property to preserve the pixelated aesthetic.

Introduction

The Use Custom Font variable controls whether a Text object uses a premade .fnt file (if true) or if it Gum automatically creates font files according to the Text's Font, Font Size, and Outline Thickness variables.

Use Custom Font is false by default.

Example

If Use Custom Font is set to true, then Gum displays the Custom Font File variable, which can point to a .fnt file created by Bitmap Font Generator.

If Use Custom Font is set to true, then the Font, Font Size, and Outline Thickness variables can no longer be set - as they are part of the font file itself.

The Font Scale variable is still available when using custom fonts.

To set a custom font

1. Click the ... button

2. Navigate to the location of the desired .fnt file

3. Select the file and click Open

Custom font files are .fnt files created by BitmapFontGenerator. Gum automatically creates .fnt files whenever a font value changes when UseCustomFonts is unchecked.

Creating Fonts with BitmapFontGenerator

To create your own font file:

1. Download Bitmap Font Generator from https://angelcode.com/products/bmfont/

2. Select Options -> Font Settings

3. Use the dropdown to select the font you would like to use. All .ttf files installed on the current machine should appear in the dropdown. If you would like to install a new .ttf, restart Bitmap Font Generator after installing the font.
4. After changing the settings, click OK

5. Select which characters you would like included in your font. Adding characters can increase the font size, but may be required depending on which characters you intend to use.
6. Select Options->Export Options

7. Select a Bit depth of 32 (or else transparencies won’t come through).

8. Select the texture width and height. For best performance, select a size which will contain all of the characters you have selected. Also, many game engines prefer textures which are power of two such as 256, 512, 1024, or 2048. Sizes larger than 2048 may not render properly on some hardware.

9. Change the Textures option to png – Portable Network Graphics

10. Be sure to keep the Font descriptor as Text.

11. Press OK to apply the changes

Also, note that if you are using outline, you will want to have the following values:

• A: outline

• R: glyph

• G: glyph

• B: glyph

You can verify that the settings will produce a proper PNG by selecting Options -> Visualize. If you see “No Output!” then you need to select characters to export. See the above step for more information.

To save the font, select Options->Save bitmap font as… to save your .fnt and .png files.

Once you have saved your files, you can select the .fnt to use in your project.

Creating Fonts with Hiero

The Hiero tool can also be used to generate .fnt files:

To generate a font:

1. Download and open the Hiero tool

2. Set the values needed for your font, such as font type, size, and effects
3. Select File -> Save BMFont Files (text)...

4. Select the location to save the files, such as in your project's Contents folder, or the subfolder which contains your Gum project

This .fnt file can now be loaded in the Gum tool or in code just like any other .fnt file.