Construct 3 icon

Construct 3

Documentation

Sprite Font

Published 23 Aug, 2017
1,419 words
~6-9 mins

The Sprite Font object uses an image to display text. The "sprite font" is the object image, which contains a grid of every character that can be drawn. By drawing parts of this image in sequence, strings of text can be rendered. This allows complete artistic control over the appearance of text, rather than having to choose from existing fonts.

How a Sprite Font works

Comparison with Text object

Both the Sprite Font and Text objects can display text in the game. Typically the Text object shows monochrome characters from an existing font or web font, which can use a range of sizes and possibly also bold and italic options. On the other hand Sprite Font uses images for each character. While this means any kind of artwork can be used for text, notably allowing for multi-colored text, it has the trade-off that it only really supports one font size and one bold/italic setting (those that it is drawn with).

Another important difference is that traditional fonts as used by the Text object often have good support for unicode characters. This allows them to display a wide range of characters, including many alphabets and character sets from many different languages, as well as emoji. Sprite Fonts however can only use the characters for which an image has been drawn. It is very difficult to make a sprite font that covers much of the tens of thousands of possible unicode characters. If a Sprite Font is set to show some text which contains a character that has not been drawn, it will simply show an empty space for that character. If the entire string is in a different language which the sprite font does not cover, nothing will render at all. Bear in mind that if you allow user-inputted text, such as the player's name, or you wish to translate the game in future, then Text objects are probably more suitable.

Using BBCode

By default the SpriteFont object allows the use of BBCode, a simple way of marking up text for formatting. If you don't want such tags to affect the formatting of the text, you can opt-out of it by unchecking the Enable BBCode property.

BBCode uses "tags" in square brackets to mark the start and end of formatting. For example to hide a word, wrap it in [hide] and [/hide], e.g. [hide]Hello[/hide]. Some tags take a parameter, such as the scale, which is specified after an equals sign in the opening tag, e.g.[scale=2]Hello[/scale].

The following tags are supported. Note that due to the fact SpriteFonts render images for text, the supported BBCode tags differ from those used by the Text object.

  • [scalex=2]stretch wider[/scalex]
  • [scaley=2]stretch taller[/scaley]
  • [scale=2]stretch both axes[/scale]
  • [color=#ff0000]change text color[/color] - the color can be specified in the same way CSS colors are specified, e.g. hexadecimal, using rgb(), etc. Note that for SpriteFont, the color is applied as a tint. To ensure you can use any color text, use a SpriteFont with the characters drawn in a white color.
  • [opacity=50]change text opacity[/opacity]
  • [hide]invisible text[/hide] - this is useful for flashing effects, since the text still takes up the same width while invisible
  • [background=#ff0000]change background color[/background]
  • [offsetx=10]offset X[/offsetx] and [offsety=10]offset Y[/offsety] - move text by a number of pixels on each axis, useful for animated effects

Sprite font properties

Text

The initial text to display.

Sprite font

Click the Edit link to edit the source image that text characters are rendered from. The image can be any size, but it should fit the characters it contains exactly. Characters start in the top-left and the sequence moves to the right, wrapping down to the next line when it reaches the right edge of the image. If the character is narrower than the cell, and you change its width using Spacing data or the Set character width action, the image should be drawn left-aligned in the cell.

Character width

Character height

The size of each character's cell in the sprite font image. Individual characters can be displayed with a different width using Spacing data or the Set character width action. In this case, the character should be drawn left-aligned within its cell.

Character set

A string of characters that describes the sequence of letters in the sprite font image. This is used to map text to images. While the default starts with the English alphabet, it could be changed to another language or sequence and the image updated accordingly. Note however the Sprite Font can only display characters that are in the character set; any characters not in the character set with a corresponding image will appear as an empty space.

Spacing data

Some data in JSON format that lists the widths of individual characters. This allows improved text layout by using narrower spaces for narrower characters. The spacing data also affects the display of the text in the Layout View. The data is an array of pairs. Each pair is a width, and then a string of all the characters that width applies to. For example the pair [10, "aeou"] will set the width of the characters a, e, o and u to 10 pixels. The characters are case-sensitive, allowing you to choose different widths for uppercase characters. You can also set the width of the space character. Each pair must be listed in an array, e.g.

[[10, "aeou"], [12, "mvw"]]

.

Scale

A multiplier to scale the rendered text with, such as 0.5 for half as big or 2 for twice as big. This can be used to "fake" different font sizes, but remember it's only stretching images; you may want to draw the font again at a different size instead of using a scale.

Character spacing

Extra space in pixels to add horizontally between characters.

Line height

Extra space in pixels to add vertically between lines. 0 is the default size, negative values make lines closer together, and positive values space lines out further apart.

Horizontal alignment

The horizontal alignment of the text within the object bounding rectangle.

Vertical alignment

The vertical alignment of the text within the object bounding box.

Wrapping

Choose Word to only wrap entire space-separated words when reaching the end of a line. Choose Character to wrap at any character, which can break some words across lines half way through, but is more suitable for some languages.

Initially visible

Whether the object is initially visible or invisible when the layout starts.

Origin

Choose the position of the origin relative to its unrotated bounding rectangle.

Sprite font conditions

Compare text

Compare the current text the object is showing.

Is running typewriter text

True while text is being written out using the Typewriter text action.

On typewriter text finished

Triggered when text being written out using the Typewriter text action finishes writing out all the text.

Sprite font actions

Append text

Add some text to the end of the existing text.

Set character spacing

Set line height

Set scale

Set horizontal alignment

Set vertical alignment

Set the corresponding object properties. For more information, see Sprite font properties.

Set character width

Set the width of certain characters. Normally it is preferable to use the Spacing data property, since it displays with correct spacing in the Layout View. In this action you can specify multiple characters at the same time to set their widths simultaneously, including the space character.

Set text

Replace the current text with a new string.

Typewriter text

Set the text over time by starting with an empty string and gradually adding characters until the full text is written out, over a duration specified in seconds. Once the full text is written out, On typewriter text finished triggers. Note using Set text or Append text while text is being written out will cancel the effect.

Finish typewriter

If text is being written out with the Typewriter text action, force it to finish immediately.

Sprite font expressions

CharacterHeight

Return the sprite font cell height.

CharacterScale

CharacterSpacing

LineHeight

Return the corresponding object properties. For more information, see Sprite font properties.

CharacterWidth(char)

Return the width of a character. A character must be passed (as a string) so the Spacing data

or Set character width action can be taken in to account. Since the expression can only return one value, if there are multiple characters in the string, only the first is used.

Text

Return the object's current text.

TextWidth

TextHeight

Return the size of the actual text content within the text object's rectangle.