Skip to content

ImageFont Guide

Jump to bottom
Peter Robinson edited this page Apr 4, 2016 · 3 revisions

NOTE: As of version 3.3, ImageFont has been replaced by TextSprite and FontAsset. TextSprite supports variable width characters and text wrapping, along with a host of other useful features.

Introduction

All scene objects are known engine types that allow instances to be created at runtime. The "ImageFont", 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 ImageFont provides a basic way to display text within a Scene. This is done through the use of bitmap fonts. A Bitmap font is simply a collection of raster images of glyphs. To use an ImageFont, it must be assigned a valid "ImageAsset" that contains a minimum of 96 frames.

TorqueScript Bindings

Exposed Fields

The ImageFont 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:

  • Image
  • setImage(assetId)
  • getImage()
  • Text
  • setText(string)
  • getText()
  • TextAlignment
  • setTextAlignment(enum)
  • getTextAlignment()
  • FontSize
  • setFontSize(float)
  • getFontSize()
  • FontPadding
  • setFontPadding(float)
  • getFontPadding()

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

Image (assetId)

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

%font = new ImageFont();
%font.Image = "ToyAssets:FancyFont";

For more information on creating an appropriate asset, see the ImageAsset 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";

TextAlignment (enum)

Aligns the text within the object's AABB relative to position. There are 3 alignments to choose from: Left, Center, Right. The default alignment is Center.

%font.TextAlignment = "Left";

As a reminder, it is the text's position that is aligned and not the ImageFont AABB. If we set the ImageFont's position to 0,0 then "Left" would place the text to the left of 0,0 - "Right" to the right of 0,0 - and "Center" would naturally center the text at 0,0.

FontSize (float)

Sets the font size for both the X and Y axis. This can be given as a single value that applies to both axis or as two seperate values.

%font.FontSize = "2 2";

The size values are in world units and have no relation to any font "points" that are typical in word processing software. The default value is 1 world unit in each axis.

FontPadding (float)

This field relates to the space added between each character. Font padding is specified in world units and is set to 0 by default.

%font.FontPadding = 1;

TAML Format

Using TorqueScript and the exposed fields or methods described in the previous section, you can programmatically create and configure an ImageFont. 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 ImageFont TAML file in XML format:

<ImageFont
    BodyType="Static"
    Image="@asset=ToyAssets:font"
    text="Test Text"
    fontSize="2 2" />

The same example in JSON format:

{
    "ImageFont": {
        "BodyType": "Static",
        "Image": "@asset=ToyAssets:font",
        "text": "Test Text",
        "fontSize": "2 2"
    }
}

Additional Information

ImageAsset

As mentioned in the introduction, to create a valid ImageFont you need to use an ImageAsset that contains at least 96 frames. This correspondes to the printable 7-bit ASCII character set. The engine does not support any of the control codes below code 32 or any extended codes above code 127. There is of course nothing stopping you from substituting a different bitmap glyph for one of the valid ASCII codes. Likewise, you do not need to provide a glyph for each valid code. If you are only interested in the alpha-numeric characters, you can simply point the other frames to an empty region of the image. To reduce the image size, you can even point multiple unused characters to the same empty frame.

Bitmap Font Generators

To easily create bitmap fonts for use within T2D, there are many free or paid software programs out there for either Windows or OSX. A simple web search will give you plently of options. Ideally, one of the export formats should be PNG.

ImageFont Properties

As a child class of SceneObject, it is also worth noting that an ImageFont has full access to the physics simulation. Since text is typically used as a GUI element and not a game object, the ImageFont defaults to the "static" body-type so it is not affected by gravity or other forces. If you wish to make the text move or rotate, remember to change the body-type to "dynamic". An ImageFont also automatically sizes itself according to its alignment, font size, and text - you cannot change its AABB with the Size field or the setSize methods.

Clone this wiki locally