Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

ResourceImporterDynamicFont

继承： ResourceImporter < RefCounted < Object

导入 TTF、TTC、OTF、OTC、WOFF、WOFF2 字体文件，用于能够适配任何大小的字体渲染。

描述

与位图字体不同，动态字体可以被调整为任意大小，并且看起来仍然清晰。动态字体还可以选择支持 MSDF 字体渲染，从而允许运行时缩放更改，且没有重新光栅化成本。

虽然 WOFF（尤其是 WOFF2）往往会产生较小的文件大小，但不存在普遍“更好”的字体格式。在大多数情况下，建议使用字体开发人员网站上提供的字体格式。

另请参见 ResourceImporterBMFont 和 ResourceImporterImageFont。

教程

• 动态字体——使用字体

属性

bool	allow_system_fallback	true
int	antialiasing	1
bool	compress	true
Array	fallbacks	[]
bool	force_autohinter	false
bool	generate_mipmaps	false
int	hinting	1
Dictionary	language_support	{}
int	msdf_pixel_range	8
int	msdf_size	48
bool	multichannel_signed_distance_field	false
Dictionary	opentype_features	{}
float	oversampling	0.0
Array	preload	[]
Dictionary	script_support	{}
int	subpixel_positioning	1

---

属性说明

bool allow_system_fallback = true

为 true 时，如果在该动态字体中找不到字形，则自动使用系统字体作为后备。这使得支持 CJK 字符或表情符号更加简单，因为你不需要在项目中包含 CJK/表情符号字体。另请参阅 fallbacks。

注意：系统字体的外观因平台而异。仅 Windows、macOS、Linux、Android 和 iOS 支持加载系统字体。

---

int antialiasing = 1

要使用的字体抗锯齿方法。

禁用：最适合像素艺术字体，如果字体文件创建良好并且字体以其预期大小的整数倍使用，则你不必更改默认的灰度抗锯齿。如果像素艺术字体在其预期大小下外观不佳，请尝试将 subpixel_positioning 设置为 Disabled。

灰度：使用灰度抗锯齿。这是 macOS、Android 和 iOS 上的操作系统使用的方法。

LCD 子像素：使用子像素模式的抗锯齿，使 LCD 显示器上的字体更加清晰。这是 Windows 和大多数 Linux 发行版上的操作系统使用的方法。缺点是这可能会在边缘产生“边缘”，尤其是在不使用标准 RGB 子像素的显示技术上（例如 OLED 显示器）。LCD 子像素布局由 ProjectSettings.gui/theme/lcd_subpixel_layout 全局控制，这也允许回退到灰度抗锯齿。

---

bool compress = true

如果为 true，则会对得到的字体使用无损压缩。

---

Array fallbacks = []

如果在该动态字体中找不到字形，则要使用的字体后备列表。首先尝试位于数组开头的字体，最后尝试不支持字形语言和脚本的后备字体（请参阅 language_support 和 script_support）。另请参阅 allow_system_fallback。

---

bool force_autohinter = false

如果为 true，则使用 FreeType 的自动提示器强制生成字体的提示数据。这将使 hinting 对不包含提示数据的字体有效。

---

bool generate_mipmaps = false

如果为 true，则该字体将生成 mipmap。这样可以防止文本在 Control 被按比例缩小或从远距离查看 Label3D 时看起来有颗粒感（如果 Label3D.texture_filter 被设置为显示 mipmap 的模式）。

启用 generate_mipmaps 会增加字体生成时间和内存使用量。请只在你确实需要时才启用此设置。

---

int hinting = 1

要使用的提示模式。这控制在光栅化字体时应如何积极地将字形边缘吸附到像素。根据个人喜好，你可能更喜欢使用一种提示模式而不是另一种。除 None 之外的提示模式仅在字体包含提示数据时才有效（请参阅 force_autohinter）。

None：最平滑的外观，这会使字体在小尺寸下看起来模糊。

Light：通过仅将字形边缘吸附到 Y 轴上的像素来获得清晰的结果。

Full：通过将字形边缘吸附到 X 轴和 Y 轴上的像素获得最清晰的结果。

---

Dictionary language_support = {}

覆盖该字体支持的语言列表。如果留空，则由字体元数据提供。通常无需更改该设置。另见 script_support。

---

int msdf_pixel_range = 8

最小和最大可表示的有符号距离之间的形状周围的范围宽度。如果使用字体轮廓，msdf_pixel_range 必须至少设置为最大字体轮廓大小的两倍。msdf_pixel_range 的默认值为 8，允许大小最大到 4 的轮廓看起来正确。

---

int msdf_size = 48

用于生成 MSDF 纹理的源字体大小。较高的值允许更高的精度，但渲染速度较慢并且需要更多内存。只有当注意到字形渲染中明显缺乏精度时，才增加该属性的值。仅在 multichannel_signed_distance_field 为 true 时有效。

---

bool multichannel_signed_distance_field = false

如果设置为 true，默认字体将使用多通道带符号距离场（MSDF），任何尺寸都能够进行清晰的渲染。由于这种方法不需要在每次字体大小更改时都对字体进行光栅化，因此可以实时调整字体大小，不会造成任何性能损失。对于按比例缩小的 Control（或从远距离查看的 Label3D），文本也不会看起来有颗粒感。

MSDF 字体渲染可以与 generate_mipmaps 结合使用，从而进一步提高缩小时的字体渲染质量。

---

Dictionary opentype_features = {}

要为这个字体启用、禁用或设值的 OpenType 特性。可以用来启用字体所提供的可选特性，例如合字和备选字形。不同字体所支持的 OpenType 特性列表各有不同。

---

float oversampling = 0.0

如果设为大于 0.0 的值，则会覆盖字体的过采样系数。可以用来在保持字体物理大小的前提下，使用比原计划更高或更低的分辨率渲染。大多数情况下应该保持为 0.0。

---

Array preload = []

要预渲染的字形范围。这可以避免在游戏过程中需要渲染新角色时出现卡顿，特别是在启用 subpixel_positioning 的情况下。使用预加载的缺点是初始项目加载时间会增加，内存使用量也会增加。

---

Dictionary script_support = {}

覆盖该字体支持的语言脚本列表。如果留空，则由字体元数据提供。通常无需更改该设置。另见 language_support。

---

int subpixel_positioning = 1

子像素定位可改善字体渲染外观，尤其是在较小的字体大小下。缺点是初始渲染字体需要更多时间，这可能会导致游戏过程中出现卡顿，特别是在使用大字体时。对于具有像素艺术外观的字体，应将其设置为禁用。

禁用：无子像素定位。质量最低，渲染最快。

自动：在小字体大小下使用子像素定位（所选质量根据字体大小而变化）。大字体不会使用子像素定位。这是性能和质量之间的良好权衡。

半像素：无论字体大小如何，始终执行中间子像素定位。质量高，渲染速度慢。

四分之一像素：无论字体大小如何，始终执行精确的子像素定位。质量最高，渲染最慢。