Skip to content

TextSprite Guide

Jump to bottom
Peter Robinson edited this page Jul 5, 2020 · 2 revisions

Introduction

All scene objects are known engine types that allow instances to be created at runtime. The "TextSprite", like all other objects, is derived from a base type of "SceneObject". That means it includes all the fields from that type as well as adding its own fields specific to itself.

The TextSprite provides a complete solution for displaying text within a Scene. This is done through the use of bitmap fonts. A Bitmap font can be created quickly using any program that can save in Angle Code's bitmap font format. Then simply create a valid "FontAsset" and assign it to the TextSprite.

TorqueScript Bindings

Exposed Fields

The TextSprite type exposes the following fields in addition to those it inherits. Shown are the equivalent methods available that perform the same action in setting and getting the respective field:

  • Font
  • setFont(assetId)
  • getFont()
  • Text
  • setText(string)
  • getText()
  • FontSize
  • setFontSize(float)
  • getFontSize()
  • FontScaleX
  • setFontScaleX(float)
  • getFontScaleX()
  • FontScaleY
  • setFontScaleY(float)
  • getFontScaleY()
  • TextAlignment
  • setTextAlignment(enum)
  • getTextAlignment()
  • TextVAlignment
  • setTextVAlignment(enum)
  • getTextVAlignment()
  • OverflowModeX
  • setOverflowModeX(enum)
  • getOverflowModeX()
  • OverflowModeY
  • setOverflowModeY(enum)
  • getOverflowModeY()
  • AutoLineHeight
  • setAutoLineHeight(bool)
  • getAutoLineHeight()
  • CustomLineHeight
  • setCustomLineHeight(float)
  • getCustomLineHeight()
  • Kerning
  • setKerning(float)
  • getKerning()

The following is a complete description of each of these fields.

Font (assetId)

Sets the FontAsset that contains the bitmap font. This must be given in the form of a valid asset ID. A simple example:

%font = new TextSprite();
%font.Font = "ToyAssets:ArialFont";

For more information on creating an appropriate asset, see the FontAsset guide and further down in the Additional Information section.

Text (string)

This field contains the text that is to be displayed.

%font.Text = "Lorem ipsum dolor sit amet";

FontSize (float)

A single value that sets the size of the font in world units. This applies to the entire height of the glyphs which often have empty space above and below each character (this depends on the font). So the actual size from top to bottom of each character will likely be smaller than the size give. The width of each character will be correctly adjusted based on the character.

%font.FontSize = "3.5";

FontScaleX (float)

This value will be multiplied by the normal width of the line of text to get an adjusted width. It will affect both the width of the characters and size of the space between the characters. The default value is 1.

%font.FontScaleX = 1.5;

FontScaleY (float)

This value will be multiplied by the normal height of the line of text to get an adjusted height. The default value is 1.

%font.FontScaleY = 1.5;

Keep in mind that you're basically changing the font size in one direction so setting both scales to the same thing is pointless. For example, if the font size is 2 and you set both scales to 3 then the resulting text will look the same as setting the font size to 6 and leaving the scales alone. The scales become useful when you want to shrink or stretch the characters in one direction.

TextAlignment (enum)

Aligns the text within the object's box (AABB). There are 4 possible alignments to choose from: Left, Center, Right, and Justify. The default alignment is Left. Justify will adjust the kerning (distance between characters) to make each line of the text exactly fit the box. Because of this fact, kerning set on the TextSprite will be ignored if Justify is used.

%font.TextAlignment = "Center";

TextVAlignment (enum)

The "V" stands for vertical and refers to the way the text is aligned vertically in the box of the TextSprite. There are 3 possible vertical alignments to choose from: Top, Middle, and Bottom. The default alignment is Top.

%font.TextVAlignment = "Middle";

OverflowModeX (enum)

This tells the TextSprite what it should do when the characters overflow the box (AABB) of the TextSprite in the X direction. There are four options to choose from: Wrap, Visible, Hidden, and Shrink. The default setting is Wrap.

%font.OverflowModeX = "Visible";

Wrap causes the text to word wrap down to a new line if the text overflows the box. The line height by default will be equal to the font size but this can be changed (see below). It is still possible for the text to overflow the box when Wrap is active (for instance, because of a long word that doesn't fit in the box). In these cases the text will be visible.

The Visible setting will allow the text to simply overflow the box and keep going. The Hidden setting causes the characters to be hidden if they are outside the box. Shrink manipulates the width of each character so that the line fits in the box. This works well when characters sometimes slightly go outside the bounds of the box but will eventually become unreadable if the text needs to shrink too much.

OverflowModeY (enum)

This deals with overflow in the Y direction. There are three options to choose from: Visible, Hidden, and Shrink. The default setting is Hidden.

%font.OverflowMode = "Visible";

Visible allows the text to still be visible if the characters overflow in the Y direction and Hidden hides the characters. This is most useful when used in conjunction with the word wrap, but will apply even if the box is not tall enough for a single line. Shrink will manipulate the height of each character to get the text to fit in the Y direction.

AutoLineHeight(bool)

If this is true then the height of each line will automatically match the font size. If it is false then the custom line height will be used instead. Default is true.

%font.AutoLineHeight = false;

CustomLineHeight(float)

This is not the font size. It is the vertical distance between each line of text in world units. The custom line height is used when the AutoLineHeight is set to false. The default value is 1.

%font.CustomLineHeight = 3.5;

Kerning(float)

Kerning is the distance between each character. Bitmap font files can have kerning information in them that allow certain characters to be closer together. This data is supported by the TextSprite and is unrelated to this setting. The kerning setting allows you to put extra space between each character (or remove using a negative value). Kerning is automatically calculated when the TextSprite alignment is set to Justfiy in which case this setting will be ignored. The default value is 0.

%font.Kerning = 0.1;

TAML Format

Using TorqueScript and the exposed fields or methods described in the previous section, you can programmatically create and configure a TextSprite. You can then export this type to a TAML file or even create a TAML file manually and read it into your game at an appropriate time.

Here is an example TextSprite TAML file in XML format:

<TextSprite
    Font="@asset=ToyAssets:ArialFont"
    text="Hello World"
    fontSize="3" />

The same example in JSON format:

{
    "TextSprite": {
        "Font": "@asset=ToyAssets:ArialFont",
        "text": "Hello World",
        "fontSize": "3"
    }
}

Individual Character Manipulation

This is where things get cool. The TextSprite actually has additional methods that allow you to control the blend color, scale, and offset of any character! This allows you to do a number of cool effects with your text. The TextSprite Toy has some examples of text jumping, fading out certain letters to reveal hidden words, and even building a dialog box that shows one letter at a time. The following is a list of script function that make this possible.

ResetCharacterSettings()

Resets the color, scale, and offset of all characters. This is useful when you want everything to return to normal.

SetCharacterBlendColor(int, color)

This sets the blend color of a character to a custom blend color. After setting this value, the custom blend color will be used for this character instead of the TextSprite's blend color. Unfortunately you cannot use color names to set this.

The first parameter passed in is the zero-based index of the character.

GetCharacterBlendColor(int)

Returns the blend color for the requested character. If no custom blend color has been set for this character then the TextSprite's blend color will be returned.

GetCharacterHasBlendColor(int)

Returns true if a custom blend color has been set on a character.

ResetCharacterBlendColor(int)

Removes a custom blend color from a character so that the character starts using the TextSprite's blend color again.

SetCharacterScale(int, float / float)

Sets the scale for a character in the X and Y directions. This will be multiplied by the size of the font and the TextSprite's scales. Unlike the TextSprite's scales, these individual scales will not affect the distance between the characters. These scales will also not affect word wrapping calculations, but the characters will be correctly clipped if they should be hidden. Default values are both 1.

GetCharacterScale(int)

Returns the scale in the X and Y directions for a given character.

ResetCharacterScale(int)

Sets a character scale in both directions back to 1.

SetCharacterOffset(int, float / float)

The amount a character should be offset from it's final calculated position. This will be applied after all other positioning calculations. Characters will still be hidden if overflow modes are set to hidden. The default values are both zero.

GetCharacterOffset(int)

Returns the X and Y offsets of a given character.

ResetCharacterOffset(int)

Sets the offsets for a character to zero.

Additional Information

Blending

Unless you want text with multiple colors, we suggest you use a font with white letters and a transparent background. This causes the color of the letters to match the blend color of the font. Since the TextSprite is a normal SceneObject it can also use the fading routines to dynamically change its color over time.

Clone this wiki locally