IN THIS ARTICLE

Configuring Font Properties

You can define the appearance of your UI font by configuring various properties that affect the font’s appearance and usage.

You define your font’s properties in the .font file, which is an XML file. The following example shows the default UI font XML file, located in Engine/Fonts/default-ui.font.

<fontshader>
    <font path="Vera.ttf" fontsize="32"/>
    <effect name="default">
        <pass>
        </pass>
    </effect>
    <effect name="drop_shadow">
        <pass>
        </pass>
        <pass>
            <color r="0" g="0" b="0" a="1"/>
            <pos x="1" y="1"/>
        </pass>
</effect>
</fontshader>

The default UI font XML uses the Vera font. It defines a font texture that can hold 128 unique character or glyphs that are 32x32 pixels. The font includes two representations that are defined with the effect tags default and drop_shadow. For the default effect, the font is rendered as is. For the drop_shadow effect, the font is first rendered as is. A second render pass produces the font in black with a 1-pixel offset from the first pass. This creates a basic shadowing effect of the characters.

Note:
Fonts can be part of a font family (with a .fontfamily extension), though you can use a standalone font that isn’t in a font family. For more information on font families, see Creating Font Families.

Use the following tags, attributes, and values to define key features of your font.

Tag	Description	Attributes
font	Contains critical attributes that define the path to the asset, size, and other font qualities.	See Font Tag Attributes.
effect	Acts as a parent tag to pass children tags. Groups the pass tags that comprises the effect.	name – Name of the effect.
effectfile	Specifies the path to an XML file that contains effect tags.	path – String that specifies the path to an XML file containing effect tags.
pass	A child tag of an effect tag. You can add multiple pass tags as the children of a single effect tag. Defines a render pass of the text with various parameters that affect the text’s rendering. The pass tags can be layered on top of each other, giving the effect a unique look.	Doesn’t have attributes. Parents the following child tags that define text effects: color pos or offset blend or blending
color	A text effect that is a child tag of the pass tag. Defines the text color.	Uses the following attributes to define the effect’s intensity with float point values: Minimum: `0.0` Maximum: `1.0f` r – Red g – Green b – Blue a – Alpha (`0` is transparent. `1.0f` is opaque)
pos or offset	A text effect that is a child tag of the pass tag. Sets the position of the text.	Uses the following attributes to set text position with integer values: x – Offsets text along X axis relative to the position of the text y – Offsets text along Y axis relative to the position of the text
blend or blending	A text effect that is a child tag of the pass tag. Defines alpha blending behavior of the text.	Uses the following attributes to define the text’s alpha blending behavior: src – Source color value for the text’s alpha blending dst – Destination color value for the text’s alpha blending type – Alpha blending behavior with preconfigured settings determined by value Uses the following values for the src and dst attributes: `zero` `one` `srcalpha` or `src_alpha` `invsrcalpha` or `inv_src_alpha` `dstalpha` or `dst_alpha` `invdstalpha` or `inv_dst_alpha` `dstcolor` or `dst_color` `srccolor` or `src_color` `invdstcolor` or `inv_dst_color` `invsrccolor` or `inv_src_color` Uses the following values for the type attribute: `modulate-src_alpha` and `inv_src_alpha` (one minus source alpha) blending `additive-src_alpha` and `one` (for destination) blending

Font Tag Attributes

Font tag attributes define critical attributes for a font, such as the path to the TTF/OTF asset used to display the font, and other attributes affecting font render quality.

Note:
Most of these attributes have a direct impact on font rendering quality. For more information, see Configuring Font Rendering Quality.

Attribute	Example	Description
path	<font path=“Vera.ttf” … />	Type: `String` Path to TTF or OTF font file asset.
fontsize	< … fontsize=“32”/>	Type: `Integer` Defines in pixels the square size of the slots used to store glyphs (characters) in the font texture. For pixel-perfect render quality, this size should match the size specified when rendering the font.
w	< … w=“512” h=“256” />	Type: `Integer` Defines in pixels the width of the font texture.
h	< … w=“512” h=“256” />	Type: `Integer` Defines in pixels the width of the font texture.
widthslots	… widthslots=“8” heightslots=“8” />	Type: `Integer` Default: `16` Defines the number of character or glyph slots along the X axis of the font texture. In the example, the font texture is `512x512`. The widthslots and heightslots are set to `8`. This gives a space of `64x64` for each character.
heightslots	< … widthslots=“8” heightslots=“8” />	Type: `Integer` Default: `8` Defines the number of character or glyph slots along the y-axis of the font texture.
sizeratio	< … sizeratio=“0.6” />	Type: `Float` Default: `0.8` Applies uniform scaling to characters or glyphs when rendered into the font texture. The default scaling is usually ideal. You can adjust this value for fonts with unusual proportions, such as very long or wide fonts.
sizebehavior	< … sizebehavior=“rerender” />	Type: `String` Value: `rerender` Renders text again at its new size. Improves font appearance quality when the text’s rendered size differs from the font texture’s glyph slot size. When text size changes, a simple transformation scale is applied. Quality degrades noticeably when text becomes larger or smaller. Rerendered text can improve that quality, depending on the font. Because rerendering takes time, it’s not ideal for some cases, such as for animated text that changes sizes often.
hintbehavior	< … hintbehavior=“nohinting” />	Type: `String` Configures hinting properties for the font. Possible values: `default` – Hinting behavior as provided by the font. You can also omit the hintbehavior tag to use the default hinting. `nohinting` – Disable hinting. `autohint` – Hinting behavior procedurally derived from the font.
hintstyle	< … hintstyle=“light” />	Type: `String` Configures hinted text’s appearance. Possible values: `normal` – Appearance as provided by the font. You can also omit the hintsytle tag to use the default hinting. `light` – Fuzzier appearance that might more accurately represent the shape of glyphs in the font.
smooth	< … smooth=“blur” smooth_amount=“3” />	Type: `String` Configures smoothing applied to the font. The amount of smoothing applied is defined by the smooth_amount attribute. Possible values: `blur` – Applies a simple burring effect to characters or glyphs stored in the font texture. Use smooth_amount to set the number of iterations to use for blurring. `supersample` – Super samples characters or glyphs in the font texture by smooth_amount: `1` for 2x, and `2` for 4x. `none` – Default. No smoothing applied.
smooth_amount	< … smooth=“supersample” smooth_amount=“1” />	Type: `Integer` Defines the amount of smoothing applied to the font. The type of smoothing applied is defined by the smooth attribute.