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.

ResourceImporterDynamicFont

继承: ResourceImporter < RefCounted < Object

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

描述

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

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

另请参见 ResourceImporterBMFontResourceImporterImageFont

教程

属性

bool

allow_system_fallback

true

int

antialiasing

1

bool

compress

true

bool

disable_embedded_bitmaps

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,则会对得到的字体使用无损压缩。


bool disable_embedded_bitmaps = true 🔗

如果为 true,则会禁用内嵌字体位图的加载(仅包含位图的字体以及彩色字体会禁用该属性)。


Array fallbacks = [] 🔗

如果在该动态字体中找不到字形,则要使用的字体后备列表。首先尝试位于数组开头的字体,最后尝试不支持字形语言和脚本的后备字体(请参阅 language_supportscript_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_fieldtrue 时有效。


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 🔗

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

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

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

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

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