Bitmap Fonts and Font Families

Rhea supports bitmap fonts described by BMFont text files (.fnt) and PNG texture atlases. A bitmap font contains glyphs rendered at one native pixel size. A font family groups several native sizes and lets a TextWidget or GUI widget select the closest available variant.

The text system keeps these responsibilities separate:

• BitmapFont describes one atlas at one native size.
• BitmapFontFamily groups related bitmap fonts.
• TextWidget requests a size and renders the font selected by the family.
• GUI widgets obtain the requested size and text color from CSS.

Bitmap glyphs are not resized to match an arbitrary requested size. The family selects the closest native atlas instead. This avoids distortion and keeps small UI text sharp.

Exporting a font with BMFont

Export one atlas for every size that should be available to the UI. Recommended BMFont settings are:

Setting	Recommended value
Descriptor format	Text
Texture format	PNG
Pages	One
Packing	Disabled
Smoothing	Enabled
ClearType	Disabled
Padding	2 pixels on every side
Spacing	2 pixels horizontally and vertically
Texture size	Large enough for one page, commonly 512 × 512

Padding is important when the texture uses filtering. Without a transparent border around each glyph, samples from neighboring glyphs can bleed into the rendered character.

A typical export produces two files:

Inter20.fnt
Inter20_0.png

Keep the file name referenced by the BMFont page record consistent with the PNG asset:

page id=0 file="Inter20_0.png"

Rhea currently expects a single-page atlas.

Declaring a bitmap font

Each exported size is declared as a separate BitmapFont resource:

[Inter20]
type="//meworla/bitmapfont"
texture="//rhea/fonts/Inter20_0.png"
font_info="//rhea/fonts/Inter20.fnt"

For BMFont descriptors, the native font size and line height are read from the file. The optional font_size scene value is therefore normally unnecessary.

The loader reads:

• Atlas dimensions from scaleW and scaleH
• Native font size from info size
• Line height from common lineHeight
• Glyph rectangles and UV coordinates
• Glyph bearings from xoffset and yoffset
• Cursor advances from xadvance

The native font size and line height are different metrics. For example, a font exported at size 20 can have a line height of 24. Rhea uses the native size for family selection and the line height for layout, wrapping, and cursor positioning.

Declaring a bitmap font family

A family maps native sizes to font resources:

[scene]
name="Inter"
type="//meworla/bitmapfontfamily"
default_size=20
font_12="Inter12"
font_16="Inter16"
font_20="Inter20"
font_32="Inter32"
font_48="Inter48"

[Inter12]
type="//meworla/bitmapfont"
texture="//rhea/fonts/Inter12_0.png"
font_info="//rhea/fonts/Inter12.fnt"

[Inter16]
type="//meworla/bitmapfont"
texture="//rhea/fonts/Inter16_0.png"
font_info="//rhea/fonts/Inter16.fnt"

[Inter20]
type="//meworla/bitmapfont"
texture="//rhea/fonts/Inter20_0.png"
font_info="//rhea/fonts/Inter20.fnt"

[Inter32]
type="//meworla/bitmapfont"
texture="//rhea/fonts/Inter32_0.png"
font_info="//rhea/fonts/Inter32.fnt"

[Inter48]
type="//meworla/bitmapfont"
texture="//rhea/fonts/Inter48_0.png"
font_info="//rhea/fonts/Inter48.fnt"

The key suffix defines the selectable size. For example, font_20 registers the referenced font as the size-20 variant.

When no requested size is provided, the family uses default_size. If no default is configured, it uses the smallest registered variant.

Size selection

BitmapFontFamily selects the native size with the smallest absolute distance from the requested size. If two variants are equally close, the larger variant is selected.

For this family:

16, 20, 32

the selections are:

Requested size	Selected atlas
16	16
18	20
20	20
25	20
28	32
32	32

The selected atlas is rendered at its native size. A request for 18 that resolves to the size-20 atlas is laid out and rendered as size 20.

Using a family in a scene

A TextWidget can reference a family directly:

[title]
type="//meworla/textwidget"
text="Settings"
font_family="//rhea/fonts/Inter"
font_size=32

The legacy font property remains available for directly referencing one BitmapFont:

[debug_text]
type="//meworla/textwidget"
text="Debug output"
font="//local/fonts/DebugFont"

Use a family for normal GUI text. Direct font references are useful for fixed-size debug fonts, icon atlases, or compatibility with existing scenes.

Using fonts from CSS

GUI widgets inherit the configured font family, font size, and text color. The standard CSS properties are:

Label {
  font-size: 20px;
  color: rgb(240, 240, 240);
}

A more specific rule can select a different size or color:

.dialog-title {
  font-size: 32px;
  color: rgb(255, 196, 96);
}

Input {
  font-size: 16px;
  color: rgb(230, 230, 230);
}