Table of Contents

Class FontFile

Namespace
Godot
Assembly
GodotSharp.dll

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.

var f = ResourceLoader.Load<FontFile>("res://BarlowCondensed-Bold.ttf");
  GetNode("Label").AddThemeFontOverride("font", f);
  GetNode("Label").AddThemeFontSizeOverride("font_size", 64);
public class FontFile : Font, IDisposable
Inheritance
FontFile
Implements
Inherited Members

Constructors

FontFile() 

public FontFile()

Properties

AllowSystemFallback

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

public bool AllowSystemFallback { get; set; }

Property Value

bool

Antialiasing

Font anti-aliasing mode.

public TextServer.FontAntialiasing Antialiasing { get; set; }

Property Value

TextServer.FontAntialiasing

Data

Contents of the dynamic font source file.

public byte[] Data { get; set; }

Property Value

byte[]

FixedSize

Font size, used only for the bitmap fonts.

public int FixedSize { get; set; }

Property Value

int

FixedSizeScaleMode

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

public TextServer.FixedSizeScaleMode FixedSizeScaleMode { get; set; }

Property Value

TextServer.FixedSizeScaleMode

FontName

Font family name.

public string FontName { get; set; }

Property Value

string

FontStretch

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

public int FontStretch { get; set; }

Property Value

int

FontStyle

Font style flags, see TextServer.FontStyle.

public TextServer.FontStyle FontStyle { get; set; }

Property Value

TextServer.FontStyle

FontWeight

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

public int FontWeight { get; set; }

Property Value

int

ForceAutohinter

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).

public bool ForceAutohinter { get; set; }

Property Value

bool

GenerateMipmaps

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

public bool GenerateMipmaps { get; set; }

Property Value

bool

Hinting

Font hinting mode. Used by dynamic fonts only.

public TextServer.Hinting Hinting { get; set; }

Property Value

TextServer.Hinting

MsdfPixelRange

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

public int MsdfPixelRange { get; set; }

Property Value

int

MsdfSize

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.

public int MsdfSize { get; set; }

Property Value

int

MultichannelSignedDistanceField

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, MsdfPixelRange 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.

public bool MultichannelSignedDistanceField { get; set; }

Property Value

bool

OpentypeFeatureOverrides

Font OpenType feature set override.

public Dictionary OpentypeFeatureOverrides { get; set; }

Property Value

Dictionary

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).

public float Oversampling { get; set; }

Property Value

float

StyleName

Font style name.

public string StyleName { get; set; }

Property Value

string

SubpixelPositioning

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 Auto to automatically enable it based on the font size.

public TextServer.SubpixelPositioning SubpixelPositioning { get; set; }

Property Value

TextServer.SubpixelPositioning

Methods

ClearCache()

Removes all font cache entries.

public void ClearCache()

ClearGlyphs(int, Vector2I)

Removes all rendered glyphs information from the cache entry.

Note: This function will not remove textures associated with the glyphs, use RemoveTexture(int, Vector2I, int) to remove them manually.

public void ClearGlyphs(int cacheIndex, Vector2I size)

Parameters

cacheIndex int
size Vector2I

ClearKerningMap(int, int)

Removes all kerning overrides.

public void ClearKerningMap(int cacheIndex, int size)

Parameters

cacheIndex int
size int

ClearSizeCache(int)

Removes all font sizes from the cache entry

public void ClearSizeCache(int cacheIndex)

Parameters

cacheIndex int

ClearTextures(int, Vector2I)

Removes all textures from font cache entry.

Note: This function will not remove glyphs associated with the texture, use RemoveGlyph(int, Vector2I, int) to remove them manually.

public void ClearTextures(int cacheIndex, Vector2I size)

Parameters

cacheIndex int
size Vector2I

GetCacheAscent(int, int)

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

public float GetCacheAscent(int cacheIndex, int size)

Parameters

cacheIndex int
size int

Returns

float

GetCacheCount()

Returns number of the font cache entries.

public int GetCacheCount()

Returns

int

GetCacheDescent(int, int)

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

public float GetCacheDescent(int cacheIndex, int size)

Parameters

cacheIndex int
size int

Returns

float

GetCacheScale(int, int)

Returns scaling factor of the color bitmap font.

public float GetCacheScale(int cacheIndex, int size)

Parameters

cacheIndex int
size int

Returns

float

GetCacheUnderlinePosition(int, int)

Returns pixel offset of the underline below the baseline.

public float GetCacheUnderlinePosition(int cacheIndex, int size)

Parameters

cacheIndex int
size int

Returns

float

GetCacheUnderlineThickness(int, int)

Returns thickness of the underline in pixels.

public float GetCacheUnderlineThickness(int cacheIndex, int size)

Parameters

cacheIndex int
size int

Returns

float

GetCharFromGlyphIndex(int, int)

Returns character code associated with glyphIndex, or 0 if glyphIndex is invalid. See GetGlyphIndex(int, long, long).

public long GetCharFromGlyphIndex(int size, int glyphIndex)

Parameters

size int
glyphIndex int

Returns

long

GetEmbolden(int)

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

public float GetEmbolden(int cacheIndex)

Parameters

cacheIndex int

Returns

float

GetExtraSpacing(int, SpacingType)

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

public long GetExtraSpacing(int cacheIndex, TextServer.SpacingType spacing)

Parameters

cacheIndex int
spacing TextServer.SpacingType

Returns

long

GetFaceIndex(int)

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

public long GetFaceIndex(int cacheIndex)

Parameters

cacheIndex int

Returns

long

GetGlyphAdvance(int, int, int)

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.

public Vector2 GetGlyphAdvance(int cacheIndex, int size, int glyph)

Parameters

cacheIndex int
size int
glyph int

Returns

Vector2

GetGlyphIndex(int, long, long)

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

public int GetGlyphIndex(int size, long @char, long variationSelector)

Parameters

size int
char long
variationSelector long

Returns

int

GetGlyphList(int, Vector2I)

Returns list of rendered glyphs in the cache entry.

public int[] GetGlyphList(int cacheIndex, Vector2I size)

Parameters

cacheIndex int
size Vector2I

Returns

int[]

GetGlyphOffset(int, Vector2I, int)

Returns glyph offset from the baseline.

public Vector2 GetGlyphOffset(int cacheIndex, Vector2I size, int glyph)

Parameters

cacheIndex int
size Vector2I
glyph int

Returns

Vector2

GetGlyphSize(int, Vector2I, int)

Returns glyph size.

public Vector2 GetGlyphSize(int cacheIndex, Vector2I size, int glyph)

Parameters

cacheIndex int
size Vector2I
glyph int

Returns

Vector2

GetGlyphTextureIdx(int, Vector2I, int)

Returns index of the cache texture containing the glyph.

public int GetGlyphTextureIdx(int cacheIndex, Vector2I size, int glyph)

Parameters

cacheIndex int
size Vector2I
glyph int

Returns

int

GetGlyphUVRect(int, Vector2I, int)

Returns rectangle in the cache texture containing the glyph.

public Rect2 GetGlyphUVRect(int cacheIndex, Vector2I size, int glyph)

Parameters

cacheIndex int
size Vector2I
glyph int

Returns

Rect2

GetKerning(int, int, Vector2I)

Returns kerning for the pair of glyphs.

public Vector2 GetKerning(int cacheIndex, int size, Vector2I glyphPair)

Parameters

cacheIndex int
size int
glyphPair Vector2I

Returns

Vector2

GetKerningList(int, int)

Returns list of the kerning overrides.

public Array<Vector2I> GetKerningList(int cacheIndex, int size)

Parameters

cacheIndex int
size int

Returns

Array<Vector2I>

GetLanguageSupportOverride(string)

Returns true if support override is enabled for the language.

public bool GetLanguageSupportOverride(string language)

Parameters

language string

Returns

bool

GetLanguageSupportOverrides()

Returns list of language support overrides.

public string[] GetLanguageSupportOverrides()

Returns

string[]

GetScriptSupportOverride(string)

Returns true if support override is enabled for the script.

public bool GetScriptSupportOverride(string script)

Parameters

script string

Returns

bool

GetScriptSupportOverrides()

Returns list of script support overrides.

public string[] GetScriptSupportOverrides()

Returns

string[]

GetSizeCacheList(int)

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

public Array<Vector2I> GetSizeCacheList(int cacheIndex)

Parameters

cacheIndex int

Returns

Array<Vector2I>

GetTextureCount(int, Vector2I)

Returns number of textures used by font cache entry.

public int GetTextureCount(int cacheIndex, Vector2I size)

Parameters

cacheIndex int
size Vector2I

Returns

int

GetTextureImage(int, Vector2I, int)

Returns a copy of the font cache texture image.

public Image GetTextureImage(int cacheIndex, Vector2I size, int textureIndex)

Parameters

cacheIndex int
size Vector2I
textureIndex int

Returns

Image

GetTextureOffsets(int, Vector2I, int)

Returns a copy of the array containing glyph packing data.

public int[] GetTextureOffsets(int cacheIndex, Vector2I size, int textureIndex)

Parameters

cacheIndex int
size Vector2I
textureIndex int

Returns

int[]

GetTransform(int)

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

public Transform2D GetTransform(int cacheIndex)

Parameters

cacheIndex int

Returns

Transform2D

GetVariationCoordinates(int)

Returns variation coordinates for the specified font cache entry. See GetSupportedVariationList() for more info.

public Dictionary GetVariationCoordinates(int cacheIndex)

Parameters

cacheIndex int

Returns

Dictionary

HasGodotClassMethod(in godot_string_name)

Check if the type contains a method with the given name. This method is used by Godot to check if a method exists before invoking it. Do not call or override this method.

protected override bool HasGodotClassMethod(in godot_string_name method)

Parameters

method godot_string_name

Name of the method to check for.

Returns

bool

HasGodotClassSignal(in godot_string_name)

Check if the type contains a signal with the given name. This method is used by Godot to check if a signal exists before raising it. Do not call or override this method.

protected override bool HasGodotClassSignal(in godot_string_name signal)

Parameters

signal godot_string_name

Name of the signal to check for.

Returns

bool

InvokeGodotClassMethod(in godot_string_name, NativeVariantPtrArgs, out godot_variant)

Invokes the method with the given name, using the given arguments. This method is used by Godot to invoke methods from the engine side. Do not call or override this method.

protected override bool InvokeGodotClassMethod(in godot_string_name method, NativeVariantPtrArgs args, out godot_variant ret)

Parameters

method godot_string_name

Name of the method to invoke.

args NativeVariantPtrArgs

Arguments to use with the invoked method.

ret godot_variant

Value returned by the invoked method.

Returns

bool

LoadBitmapFont(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.

public Error LoadBitmapFont(string path)

Parameters

path string

Returns

Error

LoadDynamicFont(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.

public Error LoadDynamicFont(string path)

Parameters

path string

Returns

Error

RemoveCache(int)

Removes specified font cache entry.

public void RemoveCache(int cacheIndex)

Parameters

cacheIndex int

RemoveGlyph(int, Vector2I, int)

Removes specified rendered glyph information from the cache entry.

Note: This function will not remove textures associated with the glyphs, use RemoveTexture(int, Vector2I, int) to remove them manually.

public void RemoveGlyph(int cacheIndex, Vector2I size, int glyph)

Parameters

cacheIndex int
size Vector2I
glyph int

RemoveKerning(int, int, Vector2I)

Removes kerning override for the pair of glyphs.

public void RemoveKerning(int cacheIndex, int size, Vector2I glyphPair)

Parameters

cacheIndex int
size int
glyphPair Vector2I

RemoveLanguageSupportOverride(string)

Remove language support override.

public void RemoveLanguageSupportOverride(string language)

Parameters

language string

RemoveScriptSupportOverride(string)

Removes script support override.

public void RemoveScriptSupportOverride(string script)

Parameters

script string

RemoveSizeCache(int, Vector2I)

Removes specified font size from the cache entry.

public void RemoveSizeCache(int cacheIndex, Vector2I size)

Parameters

cacheIndex int
size Vector2I

RemoveTexture(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 RemoveGlyph(int, Vector2I, int).

public void RemoveTexture(int cacheIndex, Vector2I size, int textureIndex)

Parameters

cacheIndex int
size Vector2I
textureIndex int

RenderGlyph(int, Vector2I, int)

Renders specified glyph to the font cache texture.

public void RenderGlyph(int cacheIndex, Vector2I size, int index)

Parameters

cacheIndex int
size Vector2I
index int

RenderRange(int, Vector2I, long, long)

Renders the range of characters to the font cache texture.

public void RenderRange(int cacheIndex, Vector2I size, long start, long end)

Parameters

cacheIndex int
size Vector2I
start long
end long

SetCacheAscent(int, int, float)

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

public void SetCacheAscent(int cacheIndex, int size, float ascent)

Parameters

cacheIndex int
size int
ascent float

SetCacheDescent(int, int, float)

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

public void SetCacheDescent(int cacheIndex, int size, float descent)

Parameters

cacheIndex int
size int
descent float

SetCacheScale(int, int, float)

Sets scaling factor of the color bitmap font.

public void SetCacheScale(int cacheIndex, int size, float scale)

Parameters

cacheIndex int
size int
scale float

SetCacheUnderlinePosition(int, int, float)

Sets pixel offset of the underline below the baseline.

public void SetCacheUnderlinePosition(int cacheIndex, int size, float underlinePosition)

Parameters

cacheIndex int
size int
underlinePosition float

SetCacheUnderlineThickness(int, int, float)

Sets thickness of the underline in pixels.

public void SetCacheUnderlineThickness(int cacheIndex, int size, float underlineThickness)

Parameters

cacheIndex int
size int
underlineThickness float

SetEmbolden(int, float)

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

public void SetEmbolden(int cacheIndex, float strength)

Parameters

cacheIndex int
strength float

SetExtraSpacing(int, SpacingType, long)

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

public void SetExtraSpacing(int cacheIndex, TextServer.SpacingType spacing, long value)

Parameters

cacheIndex int
spacing TextServer.SpacingType
value long

SetFaceIndex(int, long)

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

public void SetFaceIndex(int cacheIndex, long faceIndex)

Parameters

cacheIndex int
faceIndex long

SetGlyphAdvance(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.

public void SetGlyphAdvance(int cacheIndex, int size, int glyph, Vector2 advance)

Parameters

cacheIndex int
size int
glyph int
advance Vector2

SetGlyphOffset(int, Vector2I, int, Vector2)

Sets glyph offset from the baseline.

public void SetGlyphOffset(int cacheIndex, Vector2I size, int glyph, Vector2 offset)

Parameters

cacheIndex int
size Vector2I
glyph int
offset Vector2

SetGlyphSize(int, Vector2I, int, Vector2)

Sets glyph size.

public void SetGlyphSize(int cacheIndex, Vector2I size, int glyph, Vector2 glSize)

Parameters

cacheIndex int
size Vector2I
glyph int
glSize Vector2

SetGlyphTextureIdx(int, Vector2I, int, int)

Sets index of the cache texture containing the glyph.

public void SetGlyphTextureIdx(int cacheIndex, Vector2I size, int glyph, int textureIdx)

Parameters

cacheIndex int
size Vector2I
glyph int
textureIdx int

SetGlyphUVRect(int, Vector2I, int, Rect2)

Sets rectangle in the cache texture containing the glyph.

public void SetGlyphUVRect(int cacheIndex, Vector2I size, int glyph, Rect2 uVRect)

Parameters

cacheIndex int
size Vector2I
glyph int
uVRect Rect2

SetKerning(int, int, Vector2I, Vector2)

Sets kerning for the pair of glyphs.

public void SetKerning(int cacheIndex, int size, Vector2I glyphPair, Vector2 kerning)

Parameters

cacheIndex int
size int
glyphPair Vector2I
kerning Vector2

SetLanguageSupportOverride(string, bool)

Adds override for IsLanguageSupported(string).

public void SetLanguageSupportOverride(string language, bool supported)

Parameters

language string
supported bool

SetScriptSupportOverride(string, bool)

Adds override for IsScriptSupported(string).

public void SetScriptSupportOverride(string script, bool supported)

Parameters

script string
supported bool

SetTextureImage(int, Vector2I, int, Image)

Sets font cache texture image.

public void SetTextureImage(int cacheIndex, Vector2I size, int textureIndex, Image image)

Parameters

cacheIndex int
size Vector2I
textureIndex int
image Image

SetTextureOffsets(int, Vector2I, int, int[])

Sets array containing glyph packing data.

public void SetTextureOffsets(int cacheIndex, Vector2I size, int textureIndex, int[] offset)

Parameters

cacheIndex int
size Vector2I
textureIndex int
offset int[]

SetTransform(int, Transform2D)

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

public void SetTransform(int cacheIndex, Transform2D transform)

Parameters

cacheIndex int
transform Transform2D

SetVariationCoordinates(int, Dictionary)

Sets variation coordinates for the specified font cache entry. See GetSupportedVariationList() for more info.

public void SetVariationCoordinates(int cacheIndex, Dictionary variationCoordinates)

Parameters

cacheIndex int
variationCoordinates Dictionary
Edit this page