Class FontFile

Holds font source data and prerendered glyph cache, imported from a dynamic or a bitmap font.

Inheritance

Font

Resource

RefCounted

Object

FontFile

Remarks

FontFile contains a set of glyphs to represent Unicode characters imported from a font file, as well as a cache of rasterized glyphs, and a set of fallback Fonts to use.

Use FontVariation to access specific OpenType variation of the font, create simulated bold / slanted version, and draw lines of text.

For more complex text processing, use FontVariation in conjunction with TextLine or TextParagraph.

Supported font formats:

• Dynamic font importer: TrueType (.ttf), TrueType collection (.ttc), OpenType (.otf), OpenType collection (.otc), WOFF (.woff), WOFF2 (.woff2), Type 1 (.pfb, .pfm).

• Bitmap font importer: AngelCode BMFont (.fnt, .font), text and binary (version 3) format variants.

• Monospace image font importer: All supported image formats.

Note: A character is a symbol that represents an item (letter, digit etc.) in an abstract way.

Note: A glyph is a bitmap or a shape used to draw one or more characters in a context-dependent manner. Glyph indices are bound to the specific font data source.

Note: If none of the font data sources contain glyphs for a character used in a string, the character in question will be replaced with a box displaying its hexadecimal code.

• gdscript
• C#

var f = load("res://BarlowCondensed-Bold.ttf")
$Label.add_theme_font_override("font", f)
$Label.add_theme_font_size_override("font_size", 64)

See Also

Runtime file loading and saving

Properties

allow_system_fallback

If set to true, system fonts can be automatically used as fallbacks.

var allow_system_fallback : bool = true

Property Value

bool

Remarks

• void set_allow_system_fallback(bool value)
• bool is_allow_system_fallback

antialiasing

Font anti-aliasing mode.

var antialiasing : int = 1

Property Value

int

Remarks

• void set_antialiasing(int value)
• int get_antialiasing

data

Contents of the dynamic font source file.

var data : PackedByteArray = PackedByteArray()

Property Value

PackedByteArray

Remarks

• void set_data(PackedByteArray value)
• PackedByteArray get_data

disable_embedded_bitmaps

If set to true, embedded font bitmap loading is disabled (bitmap-only and color fonts ignore this property).

var disable_embedded_bitmaps : bool = true

Property Value

bool

Remarks

• void set_disable_embedded_bitmaps(bool value)
• bool get_disable_embedded_bitmaps

fixed_size

Font size, used only for the bitmap fonts.

var fixed_size : int = 0

Property Value

int

Remarks

• void set_fixed_size(int value)
• int get_fixed_size

fixed_size_scale_mode

Scaling mode, used only for the bitmap fonts with fixed_size greater than zero.

var fixed_size_scale_mode : int = 0

Property Value

int

Remarks

• void set_fixed_size_scale_mode(int value)
• int get_fixed_size_scale_mode

font_name

Font family name.

var font_name : String = ""

Property Value

String

Remarks

• void set_font_name(String value)
• String get_font_name

font_stretch

Font stretch amount, compared to a normal width. A percentage value between 50% and 200%.

var font_stretch : int = 100

Property Value

int

Remarks

• void set_font_stretch(int value)
• int get_font_stretch

font_style

Font style flags, see FontStyle.

var font_style : int = 0

Property Value

int

Remarks

• void set_font_style(int value)
• int get_font_style

font_weight

Weight (boldness) of the font. A value in the 100...999 range, normal font weight is 400, bold font weight is 700.

var font_weight : int = 400

Property Value

int

Remarks

• void set_font_weight(int value)
• int get_font_weight

force_autohinter

If set to true, auto-hinting is supported and preferred over font built-in hinting. Used by dynamic fonts only (MSDF fonts don't support hinting).

var force_autohinter : bool = false

Property Value

bool

Remarks

• void set_force_autohinter(bool value)
• bool is_force_autohinter

generate_mipmaps

If set to true, generate mipmaps for the font textures.

var generate_mipmaps : bool = false

Property Value

bool

Remarks

• void set_generate_mipmaps(bool value)
• bool get_generate_mipmaps

hinting

Font hinting mode. Used by dynamic fonts only.

var hinting : int = 1

Property Value

int

Remarks

• void set_hinting(int value)
• int get_hinting

keep_rounding_remainders

If set to true, when aligning glyphs to the pixel boundaries rounding remainders are accumulated to ensure more uniform glyph distribution. This setting has no effect if subpixel positioning is enabled.

var keep_rounding_remainders : bool = true

Property Value

bool

Remarks

• void set_keep_rounding_remainders(bool value)
• bool get_keep_rounding_remainders

msdf_pixel_range

The width of the range around the shape between the minimum and maximum representable signed distance. If using font outlines, msdf_pixel_range must be set to at least twice the size of the largest font outline. The default msdf_pixel_range value of 16 allows outline sizes up to 8 to look correct.

var msdf_pixel_range : int = 16

Property Value

int

Remarks

• void set_msdf_pixel_range(int value)
• int get_msdf_pixel_range

msdf_size

Source font size used to generate MSDF textures. Higher values allow for more precision, but are slower to render and require more memory. Only increase this value if you notice a visible lack of precision in glyph rendering.

var msdf_size : int = 48

Property Value

int

Remarks

• void set_msdf_size(int value)
• int get_msdf_size

multichannel_signed_distance_field

If set to true, glyphs of all sizes are rendered using single multichannel signed distance field (MSDF) generated from the dynamic font vector data. Since this approach does not rely on rasterizing the font every time its size changes, this allows for resizing the font in real-time without any performance penalty. Text will also not look grainy for Controls that are scaled down (or for Label3Ds viewed from a long distance). As a downside, font hinting is not available with MSDF. The lack of font hinting may result in less crisp and less readable fonts at small sizes.

Note: If using font outlines, msdf_pixel_range must be set to at least twice the size of the largest font outline.

Note: MSDF font rendering does not render glyphs with overlapping shapes correctly. Overlapping shapes are not valid per the OpenType standard, but are still commonly found in many font files, especially those converted by Google Fonts. To avoid issues with overlapping glyphs, consider downloading the font file directly from the type foundry instead of relying on Google Fonts.

var multichannel_signed_distance_field : bool = false

Property Value

bool

Remarks

• void set_multichannel_signed_distance_field(bool value)
• bool is_multichannel_signed_distance_field

opentype_feature_overrides

Font OpenType feature set override.

var opentype_feature_overrides : Dictionary = {}

Property Value

Dictionary

Remarks

• void set_opentype_feature_overrides(Dictionary value)
• Dictionary get_opentype_feature_overrides

oversampling

Font oversampling factor. If set to 0.0, the global oversampling factor is used instead. Used by dynamic fonts only (MSDF fonts ignore oversampling).

var oversampling : float = 0.0

Property Value

float

Remarks

• void set_oversampling(float value)
• float get_oversampling

style_name

Font style name.

var style_name : String = ""

Property Value

String

Remarks

• void set_font_style_name(String value)
• String get_font_style_name

subpixel_positioning

Font glyph subpixel positioning mode. Subpixel positioning provides shaper text and better kerning for smaller font sizes, at the cost of higher memory usage and lower font rasterization speed. Use TextServer.SUBPIXEL_POSITIONING_AUTO to automatically enable it based on the font size.

var subpixel_positioning : int = 1

Property Value

int

Remarks

• void set_subpixel_positioning(int value)
• int get_subpixel_positioning

Methods

clear_cache

Removes all font cache entries.

void clear_cache

clear_glyphs(int, Vector2i)

Removes all rendered glyph information from the cache entry.

Note: This function will not remove textures associated with the glyphs, use FontFile.remove_texture to remove them manually.

void clear_glyphs(int cache_index, Vector2i size)

Parameters

cache_index int

size Vector2i

clear_kerning_map(int, int)

Removes all kerning overrides.

void clear_kerning_map(int cache_index, int size)

Parameters

cache_index int

size int

clear_size_cache(int)

Removes all font sizes from the cache entry.

void clear_size_cache(int cache_index)

Parameters

cache_index int

clear_textures(int, Vector2i)

Removes all textures from font cache entry.

Note: This function will not remove glyphs associated with the texture, use FontFile.remove_glyph to remove them manually.

void clear_textures(int cache_index, Vector2i size)

Parameters

cache_index int

size Vector2i

get_cache_ascent(int, int)

Qualifiers: const

Returns the font ascent (number of pixels above the baseline).

float get_cache_ascent(int cache_index, int size)

Parameters

cache_index int

size int

get_cache_count

Qualifiers: const

Returns number of the font cache entries.

int get_cache_count

get_cache_descent(int, int)

Qualifiers: const

Returns the font descent (number of pixels below the baseline).

float get_cache_descent(int cache_index, int size)

Parameters

cache_index int

size int

get_cache_scale(int, int)

Qualifiers: const

Returns scaling factor of the color bitmap font.

float get_cache_scale(int cache_index, int size)

Parameters

cache_index int

size int

get_cache_underline_position(int, int)

Qualifiers: const

Returns pixel offset of the underline below the baseline.

float get_cache_underline_position(int cache_index, int size)

Parameters

cache_index int

size int

get_cache_underline_thickness(int, int)

Qualifiers: const

Returns thickness of the underline in pixels.

float get_cache_underline_thickness(int cache_index, int size)

Parameters

cache_index int

size int

get_char_from_glyph_index(int, int)

Qualifiers: const

Returns character code associated with glyph_index, or 0 if glyph_index is invalid. See FontFile.get_glyph_index.

int get_char_from_glyph_index(int size, int glyph_index)

Parameters

size int

glyph_index int

get_embolden(int)

Qualifiers: const

Returns embolden strength, if is not equal to zero, emboldens the font outlines. Negative values reduce the outline thickness.

float get_embolden(int cache_index)

Parameters

cache_index int

get_extra_baseline_offset(int)

Qualifiers: const

Returns extra baseline offset (as a fraction of font height).

float get_extra_baseline_offset(int cache_index)

Parameters

cache_index int

get_extra_spacing(int, int)

Qualifiers: const

Returns spacing for spacing (see SpacingType) in pixels (not relative to the font size).

int get_extra_spacing(int cache_index, int spacing)

Parameters

cache_index int

spacing int

get_face_index(int)

Qualifiers: const

Returns an active face index in the TrueType / OpenType collection.

int get_face_index(int cache_index)

Parameters

cache_index int

get_glyph_advance(int, int, int)

Qualifiers: const

Returns glyph advance (offset of the next glyph).

Note: Advance for glyphs outlines is the same as the base glyph advance and is not saved.

Vector2 get_glyph_advance(int cache_index, int size, int glyph)

Parameters

cache_index int

size int

glyph int

get_glyph_index(int, int, int)

Qualifiers: const

Returns the glyph index of a char, optionally modified by the variation_selector.

int get_glyph_index(int size, int char, int variation_selector)

Parameters

size int

char int

variation_selector int

get_glyph_list(int, Vector2i)

Qualifiers: const

Returns list of rendered glyphs in the cache entry.

PackedInt32Array get_glyph_list(int cache_index, Vector2i size)

Parameters

cache_index int

size Vector2i

get_glyph_offset(int, Vector2i, int)

Qualifiers: const

Returns glyph offset from the baseline.

Vector2 get_glyph_offset(int cache_index, Vector2i size, int glyph)

Parameters

cache_index int

size Vector2i

glyph int

get_glyph_size(int, Vector2i, int)

Qualifiers: const

Returns glyph size.

Vector2 get_glyph_size(int cache_index, Vector2i size, int glyph)

Parameters

cache_index int

size Vector2i

glyph int

get_glyph_texture_idx(int, Vector2i, int)

Qualifiers: const

Returns index of the cache texture containing the glyph.

int get_glyph_texture_idx(int cache_index, Vector2i size, int glyph)

Parameters

cache_index int

size Vector2i

glyph int

get_glyph_uv_rect(int, Vector2i, int)

Qualifiers: const

Returns rectangle in the cache texture containing the glyph.

Rect2 get_glyph_uv_rect(int cache_index, Vector2i size, int glyph)

Parameters

cache_index int

size Vector2i

glyph int

get_kerning(int, int, Vector2i)

Qualifiers: const

Returns kerning for the pair of glyphs.

Vector2 get_kerning(int cache_index, int size, Vector2i glyph_pair)

Parameters

cache_index int

size int

glyph_pair Vector2i

get_kerning_list(int, int)

Qualifiers: const

Returns list of the kerning overrides.

Vector2i[] get_kerning_list(int cache_index, int size)

Parameters

cache_index int

size int

get_language_support_override(String)

Qualifiers: const

Returns true if support override is enabled for the language.

bool get_language_support_override(String language)

Parameters

language String

get_language_support_overrides

Qualifiers: const

Returns list of language support overrides.

PackedStringArray get_language_support_overrides

get_script_support_override(String)

Qualifiers: const

Returns true if support override is enabled for the script.

bool get_script_support_override(String script)

Parameters

script String

get_script_support_overrides

Qualifiers: const

Returns list of script support overrides.

PackedStringArray get_script_support_overrides

get_size_cache_list(int)

Qualifiers: const

Returns list of the font sizes in the cache. Each size is Vector2i with font size and outline size.

Vector2i[] get_size_cache_list(int cache_index)

Parameters

cache_index int

get_texture_count(int, Vector2i)

Qualifiers: const

Returns number of textures used by font cache entry.

int get_texture_count(int cache_index, Vector2i size)

Parameters

cache_index int

size Vector2i

get_texture_image(int, Vector2i, int)

Qualifiers: const

Returns a copy of the font cache texture image.

Image get_texture_image(int cache_index, Vector2i size, int texture_index)

Parameters

cache_index int

size Vector2i

texture_index int

get_texture_offsets(int, Vector2i, int)

Qualifiers: const

Returns a copy of the array containing glyph packing data.

PackedInt32Array get_texture_offsets(int cache_index, Vector2i size, int texture_index)

Parameters

cache_index int

size Vector2i

texture_index int

get_transform(int)

Qualifiers: const

Returns 2D transform, applied to the font outlines, can be used for slanting, flipping and rotating glyphs.

Transform2D get_transform(int cache_index)

Parameters

cache_index int

get_variation_coordinates(int)

Qualifiers: const

Returns variation coordinates for the specified font cache entry. See get_supported_variation_list for more info.

Dictionary get_variation_coordinates(int cache_index)

Parameters

cache_index int

load_bitmap_font(String)

Loads an AngelCode BMFont (.fnt, .font) bitmap font from file path.

Warning: This method should only be used in the editor or in cases when you need to load external fonts at run-time, such as fonts located at the user:// directory.

int load_bitmap_font(String path)

Parameters

path String

load_dynamic_font(String)

Loads a TrueType (.ttf), OpenType (.otf), WOFF (.woff), WOFF2 (.woff2) or Type 1 (.pfb, .pfm) dynamic font from file path.

Warning: This method should only be used in the editor or in cases when you need to load external fonts at run-time, such as fonts located at the user:// directory.

int load_dynamic_font(String path)

Parameters

path String

remove_cache(int)

Removes specified font cache entry.

void remove_cache(int cache_index)

Parameters

cache_index int

remove_glyph(int, Vector2i, int)

Removes specified rendered glyph information from the cache entry.

Note: This function will not remove textures associated with the glyphs, use FontFile.remove_texture to remove them manually.

void remove_glyph(int cache_index, Vector2i size, int glyph)

Parameters

cache_index int

size Vector2i

glyph int

remove_kerning(int, int, Vector2i)

Removes kerning override for the pair of glyphs.

void remove_kerning(int cache_index, int size, Vector2i glyph_pair)

Parameters

cache_index int

size int

glyph_pair Vector2i

remove_language_support_override(String)

Remove language support override.

void remove_language_support_override(String language)

Parameters

language String

remove_script_support_override(String)

Removes script support override.

void remove_script_support_override(String script)

Parameters

script String

remove_size_cache(int, Vector2i)

Removes specified font size from the cache entry.

void remove_size_cache(int cache_index, Vector2i size)

Parameters

cache_index int

size Vector2i

remove_texture(int, Vector2i, int)

Removes specified texture from the cache entry.

Note: This function will not remove glyphs associated with the texture. Remove them manually using FontFile.remove_glyph.

void remove_texture(int cache_index, Vector2i size, int texture_index)

Parameters

cache_index int

size Vector2i

texture_index int

render_glyph(int, Vector2i, int)

Renders specified glyph to the font cache texture.

void render_glyph(int cache_index, Vector2i size, int index)

Parameters

cache_index int

size Vector2i

index int

render_range(int, Vector2i, int, int)

Renders the range of characters to the font cache texture.

void render_range(int cache_index, Vector2i size, int start, int end)

Parameters

cache_index int

size Vector2i

start int

end int

set_cache_ascent(int, int, float)

Sets the font ascent (number of pixels above the baseline).

void set_cache_ascent(int cache_index, int size, float ascent)

Parameters

cache_index int

size int

ascent float

set_cache_descent(int, int, float)

Sets the font descent (number of pixels below the baseline).

void set_cache_descent(int cache_index, int size, float descent)

Parameters

cache_index int

size int

descent float

set_cache_scale(int, int, float)

Sets scaling factor of the color bitmap font.

void set_cache_scale(int cache_index, int size, float scale)

Parameters

cache_index int

size int

scale float

set_cache_underline_position(int, int, float)

Sets pixel offset of the underline below the baseline.

void set_cache_underline_position(int cache_index, int size, float underline_position)

Parameters

cache_index int

size int

underline_position float

set_cache_underline_thickness(int, int, float)

Sets thickness of the underline in pixels.

void set_cache_underline_thickness(int cache_index, int size, float underline_thickness)

Parameters

cache_index int

size int

underline_thickness float

set_embolden(int, float)

Sets embolden strength, if is not equal to zero, emboldens the font outlines. Negative values reduce the outline thickness.

void set_embolden(int cache_index, float strength)

Parameters

cache_index int

strength float

set_extra_baseline_offset(int, float)

Sets extra baseline offset (as a fraction of font height).

void set_extra_baseline_offset(int cache_index, float baseline_offset)

Parameters

cache_index int

baseline_offset float

set_extra_spacing(int, int, int)

Sets the spacing for spacing (see SpacingType) to value in pixels (not relative to the font size).

void set_extra_spacing(int cache_index, int spacing, int value)

Parameters

cache_index int

spacing int

value int

set_face_index(int, int)

Sets an active face index in the TrueType / OpenType collection.

void set_face_index(int cache_index, int face_index)

Parameters

cache_index int

face_index int

set_glyph_advance(int, int, int, Vector2)

Sets glyph advance (offset of the next glyph).

Note: Advance for glyphs outlines is the same as the base glyph advance and is not saved.

void set_glyph_advance(int cache_index, int size, int glyph, Vector2 advance)

Parameters

cache_index int

size int

glyph int

advance Vector2

set_glyph_offset(int, Vector2i, int, Vector2)

Sets glyph offset from the baseline.

void set_glyph_offset(int cache_index, Vector2i size, int glyph, Vector2 offset)

Parameters

cache_index int

size Vector2i

glyph int

offset Vector2

set_glyph_size(int, Vector2i, int, Vector2)

Sets glyph size.

void set_glyph_size(int cache_index, Vector2i size, int glyph, Vector2 gl_size)

Parameters

cache_index int

size Vector2i

glyph int

gl_size Vector2

set_glyph_texture_idx(int, Vector2i, int, int)

Sets index of the cache texture containing the glyph.

void set_glyph_texture_idx(int cache_index, Vector2i size, int glyph, int texture_idx)

Parameters

cache_index int

size Vector2i

glyph int

texture_idx int

set_glyph_uv_rect(int, Vector2i, int, Rect2)

Sets rectangle in the cache texture containing the glyph.

void set_glyph_uv_rect(int cache_index, Vector2i size, int glyph, Rect2 uv_rect)

Parameters

cache_index int

size Vector2i

glyph int

uv_rect Rect2

set_kerning(int, int, Vector2i, Vector2)

Sets kerning for the pair of glyphs.

void set_kerning(int cache_index, int size, Vector2i glyph_pair, Vector2 kerning)

Parameters

cache_index int

size int

glyph_pair Vector2i

kerning Vector2

set_language_support_override(String, bool)

Adds override for Font.is_language_supported.

void set_language_support_override(String language, bool supported)

Parameters

language String

supported bool

set_script_support_override(String, bool)

Adds override for Font.is_script_supported.

void set_script_support_override(String script, bool supported)

Parameters

script String

supported bool

set_texture_image(int, Vector2i, int, Image)

Sets font cache texture image.

void set_texture_image(int cache_index, Vector2i size, int texture_index, Image image)

Parameters

cache_index int

size Vector2i

texture_index int

image Image

set_texture_offsets(int, Vector2i, int, PackedInt32Array)

Sets array containing glyph packing data.

void set_texture_offsets(int cache_index, Vector2i size, int texture_index, PackedInt32Array offset)

Parameters

cache_index int

size Vector2i

texture_index int

offset PackedInt32Array

set_transform(int, Transform2D)

Sets 2D transform, applied to the font outlines, can be used for slanting, flipping, and rotating glyphs.

void set_transform(int cache_index, Transform2D transform)

Parameters

cache_index int

transform Transform2D

set_variation_coordinates(int, Dictionary)

Sets variation coordinates for the specified font cache entry. See get_supported_variation_list for more info.

void set_variation_coordinates(int cache_index, Dictionary variation_coordinates)

Parameters

cache_index int

variation_coordinates Dictionary