Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

FontFile

繼承： Font < Resource < RefCounted < Object

存放字形來源資料和預算繪字形的快取，從動態字形或點陣字型匯入。

說明

FontFile 包含了一組字形，代表從字形檔中匯入的 Unicode 字元，還包含了光柵化字形的快取，以及一組備用的退回 Font。

要存取字形的 OpenType 變體，建立模擬的粗體/斜體版本，或者繪製文字行，請使用 FontVariation。

要進行更複雜的文字處理，請將 FontVariation 與 TextLine 或 TextParagraph 結合使用。

支援的字形格式：

動態字形匯入器：TrueType（.ttf）、TrueType 合集（.ttc）、OpenType（.otf）、OpenType 合集（.otc）、WOFF（.woff）、WOFF2（.woff2）、Type 1（.pfb，.pfm）。
點陣字型匯入器：AngelCode BMFont（.fnt，.font），支援文字和二進位（版本 3）格式變體。
等寬圖像字形匯入器：所有支援的圖像格式。

注意：字元（character）是一種表示某個專案（字母、數位等）的抽象符號。

注意：字形（glphy）是一種點陣圖或形狀，用於根據本文繪製一個或多個字符。字形索引綁定的是某個字形資料來源。

注意：如果所有字形資料來源都不包含字串中某個字元的字形，那麼該字元就會被替換為一個中間是對應十六進位碼的方框。

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

var f = ResourceLoader.Load<FontFile>("res://BarlowCondensed-Bold.ttf");
GetNode("Label").AddThemeFontOverride("font", f);
GetNode("Label").AddThemeFontSizeOverride("font_size", 64);

教學

執行時檔案載入與儲存

屬性

bool	allow_system_fallback	`true`
FontAntialiasing	antialiasing	`1`
PackedByteArray	data	`PackedByteArray()`
bool	disable_embedded_bitmaps	`true`
int	fixed_size	`0`
FixedSizeScaleMode	fixed_size_scale_mode	`0`
String	font_name	`""`
int	font_stretch	`100`
BitField[FontStyle]	font_style	`0`
int	font_weight	`400`
bool	force_autohinter	`false`
bool	generate_mipmaps	`false`
Hinting	hinting	`1`
bool	keep_rounding_remainders	`true`
bool	modulate_color_glyphs	`false`
int	msdf_pixel_range	`16`
int	msdf_size	`48`
bool	multichannel_signed_distance_field	`false`
Dictionary	opentype_feature_overrides	`{}`
float	oversampling	`0.0`
String	style_name	`""`
SubpixelPositioning	subpixel_positioning	`1`

方法

void	clear_cache()
void	clear_glyphs(cache_index: int, size: Vector2i)
void	clear_kerning_map(cache_index: int, size: int)
void	clear_size_cache(cache_index: int)
void	clear_textures(cache_index: int, size: Vector2i)
float	get_cache_ascent(cache_index: int, size: int) const
int	get_cache_count() const
float	get_cache_descent(cache_index: int, size: int) const
float	get_cache_scale(cache_index: int, size: int) const
float	get_cache_underline_position(cache_index: int, size: int) const
float	get_cache_underline_thickness(cache_index: int, size: int) const
int	get_char_from_glyph_index(size: int, glyph_index: int) const
float	get_embolden(cache_index: int) const
float	get_extra_baseline_offset(cache_index: int) const
int	get_extra_spacing(cache_index: int, spacing: SpacingType) const
int	get_face_index(cache_index: int) const
Vector2	get_glyph_advance(cache_index: int, size: int, glyph: int) const
int	get_glyph_index(size: int, char: int, variation_selector: int) const
PackedInt32Array	get_glyph_list(cache_index: int, size: Vector2i) const
Vector2	get_glyph_offset(cache_index: int, size: Vector2i, glyph: int) const
Vector2	get_glyph_size(cache_index: int, size: Vector2i, glyph: int) const
int	get_glyph_texture_idx(cache_index: int, size: Vector2i, glyph: int) const
Rect2	get_glyph_uv_rect(cache_index: int, size: Vector2i, glyph: int) const
Vector2	get_kerning(cache_index: int, size: int, glyph_pair: Vector2i) const
Array[Vector2i]	get_kerning_list(cache_index: int, size: int) const
bool	get_language_support_override(language: String) const
PackedStringArray	get_language_support_overrides() const
bool	get_script_support_override(script: String) const
PackedStringArray	get_script_support_overrides() const
Array[Vector2i]	get_size_cache_list(cache_index: int) const
int	get_texture_count(cache_index: int, size: Vector2i) const
Image	get_texture_image(cache_index: int, size: Vector2i, texture_index: int) const
PackedInt32Array	get_texture_offsets(cache_index: int, size: Vector2i, texture_index: int) const
Transform2D	get_transform(cache_index: int) const
Dictionary	get_variation_coordinates(cache_index: int) const
Error	load_bitmap_font(path: String)
Error	load_dynamic_font(path: String)
void	remove_cache(cache_index: int)
void	remove_glyph(cache_index: int, size: Vector2i, glyph: int)
void	remove_kerning(cache_index: int, size: int, glyph_pair: Vector2i)
void	remove_language_support_override(language: String)
void	remove_script_support_override(script: String)
void	remove_size_cache(cache_index: int, size: Vector2i)
void	remove_texture(cache_index: int, size: Vector2i, texture_index: int)
void	render_glyph(cache_index: int, size: Vector2i, index: int)
void	render_range(cache_index: int, size: Vector2i, start: int, end: int)
void	set_cache_ascent(cache_index: int, size: int, ascent: float)
void	set_cache_descent(cache_index: int, size: int, descent: float)
void	set_cache_scale(cache_index: int, size: int, scale: float)
void	set_cache_underline_position(cache_index: int, size: int, underline_position: float)
void	set_cache_underline_thickness(cache_index: int, size: int, underline_thickness: float)
void	set_embolden(cache_index: int, strength: float)
void	set_extra_baseline_offset(cache_index: int, baseline_offset: float)
void	set_extra_spacing(cache_index: int, spacing: SpacingType, value: int)
void	set_face_index(cache_index: int, face_index: int)
void	set_glyph_advance(cache_index: int, size: int, glyph: int, advance: Vector2)
void	set_glyph_offset(cache_index: int, size: Vector2i, glyph: int, offset: Vector2)
void	set_glyph_size(cache_index: int, size: Vector2i, glyph: int, gl_size: Vector2)
void	set_glyph_texture_idx(cache_index: int, size: Vector2i, glyph: int, texture_idx: int)
void	set_glyph_uv_rect(cache_index: int, size: Vector2i, glyph: int, uv_rect: Rect2)
void	set_kerning(cache_index: int, size: int, glyph_pair: Vector2i, kerning: Vector2)
void	set_language_support_override(language: String, supported: bool)
void	set_script_support_override(script: String, supported: bool)
void	set_texture_image(cache_index: int, size: Vector2i, texture_index: int, image: Image)
void	set_texture_offsets(cache_index: int, size: Vector2i, texture_index: int, offset: PackedInt32Array)
void	set_transform(cache_index: int, transform: Transform2D)
void	set_variation_coordinates(cache_index: int, variation_coordinates: Dictionary)

屬性說明

bool allow_system_fallback = true 🔗

void set_allow_system_fallback(value: bool)
bool is_allow_system_fallback()

如果設定為 true，則可以自動將系統字形作為退回使用。

FontAntialiasing antialiasing = 1 🔗

void set_antialiasing(value: FontAntialiasing)
FontAntialiasing get_antialiasing()

字形抗鋸齒模式。

PackedByteArray data = PackedByteArray() 🔗

void set_data(value: PackedByteArray)
PackedByteArray get_data()

動態字形原始檔案的內容。

Note: The returned array is copied and any changes to it will not update the original property value. See PackedByteArray for more details.

bool disable_embedded_bitmaps = true 🔗

void set_disable_embedded_bitmaps(value: bool)
bool get_disable_embedded_bitmaps()

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

int fixed_size = 0 🔗

void set_fixed_size(value: int)
int get_fixed_size()

字形大小，僅用於點陣字型。

FixedSizeScaleMode fixed_size_scale_mode = 0 🔗

void set_fixed_size_scale_mode(value: FixedSizeScaleMode)
FixedSizeScaleMode get_fixed_size_scale_mode()

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

String font_name = "" 🔗

void set_font_name(value: String)
String get_font_name()

字形家族名稱。

int font_stretch = 100 🔗

void set_font_stretch(value: int)
int get_font_stretch()

與正常寬度相比的字形的拉伸量。一個介於 50% 和 200% 之間的百分比值。

BitField[FontStyle] font_style = 0 🔗

void set_font_style(value: BitField[FontStyle])
BitField[FontStyle] get_font_style()

Font style flags.

int font_weight = 400 🔗

void set_font_weight(value: int)
int get_font_weight()

該字形的字重（粗度）。一個在 100...999 範圍內的值，正常字形字重為 400，粗體字形字重為 700。

bool force_autohinter = false 🔗

void set_force_autohinter(value: bool)
bool is_force_autohinter()

如果設定為 true，則支援自動提示並且優先於字形內建提示。僅由動態字形使用（MSDF 字形不支援提示）。

bool generate_mipmaps = false 🔗

void set_generate_mipmaps(value: bool)
bool get_generate_mipmaps()

如果設定為 true，則為字形紋理生成 mipmap。

Hinting hinting = 1 🔗

void set_hinting(value: Hinting)
Hinting get_hinting()

字形微調模式。僅由動態字形使用。

bool keep_rounding_remainders = true 🔗

void set_keep_rounding_remainders(value: bool)
bool get_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.

bool modulate_color_glyphs = false 🔗

void set_modulate_color_glyphs(value: bool)
bool is_modulate_color_glyphs()

If set to true, color modulation is applied when drawing colored glyphs, otherwise it's applied to the monochrome glyphs only.

int msdf_pixel_range = 16 🔗

void set_msdf_pixel_range(value: int)
int get_msdf_pixel_range()

最小和最大可表示的有符號距離之間的形狀周圍的範圍寬度。如果使用字形輪廓，msdf_pixel_range 必須至少設定為最大字形輪廓大小的兩倍。msdf_pixel_range 的預設值為 16，允許大小最大到 8 的輪廓看起來正確。

int msdf_size = 48 🔗

void set_msdf_size(value: int)
int get_msdf_size()

用於生成 MSDF 紋理的源字形大小。較高的值允許更高的精度，但算繪速度較慢並且需要更多記憶體。只有當注意到字形算繪中明顯缺乏精度時，才增加該屬性的值。

bool multichannel_signed_distance_field = false 🔗

void set_multichannel_signed_distance_field(value: bool)
bool is_multichannel_signed_distance_field()

如果被設定為 true，則所有大小的字形進行算繪時，都使用從動態字形向量資料中生成的單個多通道帶符號距離場（MSDF）。由於這種方法不依賴於在每次字體大小發生變化時，對字形進行柵格化，因此可以即時調整字形大小而不會造成任何性能損失。對於按比例縮小的 Control（或從遠距離查看的 Label3D），文字也不會看起來有顆粒感。有一個缺點，MSDF 不提供字形提示。缺少字形提示可能會導致大小較小的字形的清晰度和可讀性較差。

注意：如果使用字形輪廓，msdf_pixel_range 必須至少設定為最大字體輪廓大小的兩倍。

注意：MSDF 字形算繪不能正確算繪具有重疊形狀的字形。根據 OpenType 標准，重疊形狀是無效的，但在許多字形檔中仍然很常見，尤其是那些由 Google 字形轉換的字形檔。為避免字形重疊的問題，請考慮直接從字形開發公司下載字形檔，而不是依賴 Google 字形。

Dictionary opentype_feature_overrides = {} 🔗

void set_opentype_feature_overrides(value: Dictionary)
Dictionary get_opentype_feature_overrides()

字形 OpenType 功能集覆蓋。

float oversampling = 0.0 🔗

void set_oversampling(value: float)
float get_oversampling()

If set to a positive value, overrides the oversampling factor of the viewport this font is used in. See Viewport.oversampling. This value doesn't override the oversampling parameter of draw_* methods.

String style_name = "" 🔗

void set_font_style_name(value: String)
String get_font_style_name()

字形樣式名稱。

SubpixelPositioning subpixel_positioning = 1 🔗

void set_subpixel_positioning(value: SubpixelPositioning)
SubpixelPositioning get_subpixel_positioning()

字形字形的子圖元定位模式。子圖元定位為較小的字形提供了更清晰的文字和更好的字距調整，但代價是更高的記憶體佔用和更低的字形光柵化速度。使用 TextServer.SUBPIXEL_POSITIONING_AUTO 來根據字形大小自動啟用它。

方法說明

void clear_cache() 🔗

移除所有字形快取條目。

void clear_glyphs(cache_index: int, size: Vector2i) 🔗

Removes all rendered glyph information from the cache entry.

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

void clear_kerning_map(cache_index: int, size: int) 🔗

移除所有字距調整覆蓋。

void clear_size_cache(cache_index: int) 🔗

從快取條目中移除所有的字形大小。

void clear_textures(cache_index: int, size: Vector2i) 🔗

從字形快取條目中，移除所有紋理。

注意：該函式不會移除與紋理相關的字形，請使用 remove_glyph() 手動移除它們。

float get_cache_ascent(cache_index: int, size: int) const 🔗

返回字形的上升幅度（超出基線的圖元數）。

int get_cache_count() const 🔗

返回字形快取條目的數量。

float get_cache_descent(cache_index: int, size: int) const 🔗

返回字形的減少量（低於基線的圖元數）。

float get_cache_scale(cache_index: int, size: int) const 🔗

返回顏色點陣字型的縮放係數。

float get_cache_underline_position(cache_index: int, size: int) const 🔗

返回基線下方底線的圖元偏移。

float get_cache_underline_thickness(cache_index: int, size: int) const 🔗

返回底線的粗細度，單位為圖元。

int get_char_from_glyph_index(size: int, glyph_index: int) const 🔗

返回與 glyph_index 關聯的字元程式碼，如果 glyph_index 無效則返回 0。見 get_glyph_index()。

float get_embolden(cache_index: int) const 🔗

返回加粗強度，如果不等於零，則加粗字形輪廓。負值會減小輪廓粗細。

float get_extra_baseline_offset(cache_index: int) const 🔗

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

int get_extra_spacing(cache_index: int, spacing: SpacingType) const 🔗

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

int get_face_index(cache_index: int) const 🔗

返回 TrueType / OpenType 集合中的活動字形索引。

Vector2 get_glyph_advance(cache_index: int, size: int, glyph: int) const 🔗

返回字形前進量（下一個字形的偏移量）。

注意：字形輪廓的前進量，與基礎字形的前進量相同，不會被保存。

int get_glyph_index(size: int, char: int, variation_selector: int) const 🔗

返回 char 的字形索引，可以用 variation_selector 修改。

PackedInt32Array get_glyph_list(cache_index: int, size: Vector2i) const 🔗

返回快取條目中的已算繪字形列表。

Vector2 get_glyph_offset(cache_index: int, size: Vector2i, glyph: int) const 🔗

返回字形的基線偏移量。

Vector2 get_glyph_size(cache_index: int, size: Vector2i, glyph: int) const 🔗

返回字形大小。

int get_glyph_texture_idx(cache_index: int, size: Vector2i, glyph: int) const 🔗

返回包含該字形的快取紋理的索引。

Rect2 get_glyph_uv_rect(cache_index: int, size: Vector2i, glyph: int) const 🔗

返回包含該字形的快取紋理中的矩形。

Vector2 get_kerning(cache_index: int, size: int, glyph_pair: Vector2i) const 🔗

返回字形對的字距調整。

Array[Vector2i] get_kerning_list(cache_index: int, size: int) const 🔗

返回字距調整覆蓋的列表。

bool get_language_support_override(language: String) const 🔗

如果為 language 啟用了支援覆蓋，則返回 true。

PackedStringArray get_language_support_overrides() const 🔗

返回語言支援覆蓋的列表。

bool get_script_support_override(script: String) const 🔗

如果為 script 啟用了支援覆蓋，則返回 true。

PackedStringArray get_script_support_overrides() const 🔗

返回文字支援覆蓋的列表。

Array[Vector2i] get_size_cache_list(cache_index: int) const 🔗

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

int get_texture_count(cache_index: int, size: Vector2i) const 🔗

返回字形快取條目所使用的紋理數。

Image get_texture_image(cache_index: int, size: Vector2i, texture_index: int) const 🔗

返回字形快取紋理圖像的副本。

PackedInt32Array get_texture_offsets(cache_index: int, size: Vector2i, texture_index: int) const 🔗

返回包含字形打包資料的陣列副本。

Transform2D get_transform(cache_index: int) const 🔗

返回套用於字形輪廓的 2D 變換，可用於傾斜、翻轉和旋轉字形。

Dictionary get_variation_coordinates(cache_index: int) const 🔗

返回指定字形快取條目的變體座標。有關詳細資訊，請參閱 Font.get_supported_variation_list()。

Error load_bitmap_font(path: String) 🔗

從檔 path 中載入一個 AngelCode BMFont (.fnt, .font) 點陣字型。

警告：該方法只能在編輯器中或需要在運作時載入外部字形的情況下使用，例如位於 user:// 目錄的字形。

Error load_dynamic_font(path: String) 🔗

從檔 path 中載入 TrueType（.ttf）、OpenType（.otf）、WOFF（.woff）、WOFF2（.woff2）或 Type 1（.pfb、.pfm）動態字形。

警告：該方法只能在編輯器中或需要在運作時載入外部字形的情況下使用，例如位於 user:// 目錄的字形。

void remove_cache(cache_index: int) 🔗

刪除指定的字形快取條目。

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

從快取條目中移除指定的算繪的字形資訊。

注意：該函式不會移除與字形相關的紋理，請使用 remove_texture() 手動移除它們。

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

移除字形對的字距調整覆蓋。

void remove_language_support_override(language: String) 🔗

移除語言支援覆蓋。

void remove_script_support_override(script: String) 🔗

移除文字支援覆蓋。

void remove_size_cache(cache_index: int, size: Vector2i) 🔗

從快取條目中移除指定的字形大小。

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

從快取條目中移除指定的紋理。

注意：該函式不會移除與紋理相關的字形，請使用 remove_glyph() 手動移除它們。

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

將指定的字元算繪到字形快取紋理。

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

將範圍內的字元算繪到字形快取紋理。

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

設定字形的升部（基線上方的圖元數）。

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

設定字形的降部（基線下方的圖元數）。

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

設定彩色點陣字型的縮放係數。

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

設定基線下方底線的圖元偏移。

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

設定底線的粗細度，單位為圖元。

void set_embolden(cache_index: int, strength: float) 🔗

設定加粗強度，如果不等於零，則會加粗字形的輪廓。負值會減小輪廓的厚度。

void set_extra_baseline_offset(cache_index: int, baseline_offset: float) 🔗

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

void set_extra_spacing(cache_index: int, spacing: SpacingType, value: int) 🔗

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

void set_face_index(cache_index: int, face_index: int) 🔗

在 TrueType / OpenType 集合中設定活動字形索引。

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

設定字形前進量（下一個字形的偏移量）。

注意：字形輪廓的前進量與基礎字形的前進量相同，不會被保存。

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

設定字形相對於基線的偏移量。

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

設定字形大小。

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

設定包含該字形的快取紋理的索引。

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

設定包含該字形的快取紋理中，該字形的矩形區域。

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

設定字形對的字距調整。

void set_language_support_override(language: String, supported: bool) 🔗

為 Font.is_language_supported() 新增覆蓋。

void set_script_support_override(script: String, supported: bool) 🔗

為 Font.is_script_supported() 新增覆蓋。

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

設定字形快取紋理圖像。

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

設定包含字形打包資料的陣列。

void set_transform(cache_index: int, transform: Transform2D) 🔗

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

void set_variation_coordinates(cache_index: int, variation_coordinates: Dictionary) 🔗

為指定的字形快取條目設定變體座標。有關詳細資訊，請參閱 Font.get_supported_variation_list()。