Skip to content

FontAsset Guide

Jump to bottom
Peter Robinson edited this page Aug 18, 2026 · 3 revisions

Introduction

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

The FontAsset provides a way to refer to a bitmap font file so that it can be used by the TextSprite object.

TorqueScript Bindings

Exposed Fields

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

  • FontFile
  • setFontFile(string)
  • getFontFile()

Simple, right? Here's an example of a FontAsset:

<FontAsset
 AssetName="ArialFont"
 FontFile="Arial.fnt"
/>

This will produce an asset known as "ArialFont" from the bitmap font file specified, which it expects to be located in the same folder as the XML FontAsset file. As seen in this example, there is no need to make the asset name match the font name, but having matching names can make keeping the revelent files together on disk easier with an alphabetic file sort.

The bitmap font file itself has references to the image or images that contain the actual characters for the font. These images need to be present where the file says they are with an image type that the engine can read (such as .png or .jpg). The FontAsset will read the bitmap font file, find the reference to the images, and automatically load them into the engine. There's no need to create ImageAssets for these files.

You can refer to sub-folders, but do not use the "." to indicate the current folder as this is already implicitly assumed. You can however use ".." to indicate a parent folder but it is highly discouraged to store fonts in parent folders.

You can quickly create bitmap font files using Angle Code's Bitmap Font Generator. There's a config file that will help you get the correct options set located in the ToyAssets module in the font folder. You can also find examples of working bitmap fonts in this folder. When making bitmap fonts, we suggest using white characters on a transparent background. This will allow you to use the blend color to set the color of the font when you use it.

Asking a font about itself

A FontAsset can tell you what it loaded. These are all read-only — you can't change a font from script, only look at it.

When your text doesn't show up

This is the useful one. A .fnt file doesn't contain the letters; it names the image files that do, and those are called pages. If one of those images is missing or misnamed, the font loads, your TextSprite says nothing is wrong, and some or all of your characters are simply invisible.

These two methods find that:

%font = AssetDatabase.acquireAsset( "ToyAssets:ArialFont" );

if ( %font.getLoadedPageCount() < %font.getPageCount() )
    echo( "A page image named in the .fnt file is missing!" );
  • getPageCount() - How many page images the .fnt file says it needs.
  • getLoadedPageCount() - How many of them actually loaded. Fewer than getPageCount() means a page image is missing — check that every image named inside the .fnt is sitting next to it and spelled the same way.
  • getGlyphCount() - How many characters the font holds. Zero means the font didn't load at all, which usually means the .fnt file itself is missing or isn't really a .fnt.

Measurements

Useful if you're laying text out by hand rather than letting a TextSprite do it.

  • getFontSize() - The size the font was generated at, in pixels. A font drawn much larger than this goes blurry, because it's a picture being stretched.
  • getLineHeight() - The distance from one line of text to the next, in pixels.
  • getBaseline() - The distance from the top of a line down to the baseline — the line the letters sit on. The difference between this and the line height is the room left for the descending tails of letters like g and y.

The files

  • getFontFile() - The .fnt file this asset points at.
  • getRelativeFontFile() - The same path, written relative to the asset file rather than in full. This is what gets written into the .asset.taml, and it's why a module stays movable.
  • getPageFile(%pageIndex) - The image file for a page, exactly as named inside the .fnt. Pages are numbered from 0. Returns an empty string if there's no such page.
  • getPageWidth(%pageIndex) / getPageHeight(%pageIndex) - The size of a page's loaded image, in pixels. Both return zero if that page didn't load — the same warning as above, one page at a time.

Clone this wiki locally