Version:

# 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>
<pass>
</pass>
<pass>
<color r="0" g="0" b="0" a="1"/>
<pos x="1" y="1"/>
</pass>
</effect>


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.

TagDescriptionAttributes
fontContains critical attributes that define the path to the asset, size, and other font qualities.See Font Tag Attributes.
effectActs as a parent tag to pass children tags. Groups the pass tags that comprises the effect.name – Name of the effect.
effectfileSpecifies the path to an XML file that contains effect tags.path – String that specifies the path to an XML file containing effect tags.
passA 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
• colorA 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 offsetA 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 blendingA 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.
AttributeExampleDescription
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.