Lumberyard
User Guide (Version 1.21)

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

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 text's alpha blending

  • dst – Destination color value for 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

  • srcolor or src_color

  • invdstcolor or inv_dst_color

  • invsrccolor or inv_src_color

Uses the following values for the type attribute:

  • modulatesrc_alpha and inv_src_alpha (one minus source alpha) blending

  • additivesrc_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
<font path="Vera.ttf" w="512" h="512" 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 width and height slots 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 hintstyle tag to use the default hinting.

  • light – Fuzzier appearance that might more accurately represent the shape of the 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 blurring 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.

On this page: