Godot TextServerExtension 深入解析:自定义文本服务插件基类与 150+ 虚拟方法全指南

原创2026-10-15 10:41:011,326 阅读
文章标签:文档教程

Godot TextServerExtension 深入解析:自定义文本服务插件基类与 150+ 虚拟方法全指南

导读

TextServerExtension 是 Godot Engine 中所有外部自定义文本服务(TextServer)实现的基类,它把字体管理、复杂文本排版(shaping)、BiDi 双向文本、文本测量与绘制、断行断词、字符与数字本地化等能力抽象为一套约 150 个带下划线前缀的虚拟方法(virtual methods)。本文以 classes/class_textserverextension.rst 的完整类参考为主线,结合仓库中 TextServer、TextServerAdvanced、TextServerDummy、TextServerFallback 等兄弟类文档与国际化教程,系统讲解该基类的继承关系、方法分组、必需实现(required)与可选实现(virtual)的边界,以及每个核心虚拟方法的签名与语义,帮助你理解甚至独立实现一个自定义 TextServer 插件。

TextServerExtension 在 Godot 文本体系中的位置

继承链与兄弟类

TextServerExtension 处于 Godot 文本服务体系的中间层,其继承关系如下:

TextServerExtension
  └── TextServer  <──  RefCounted  <──  Object

从继承链可以看出,TextServerExtension 本身继承自 TextServer(后者又继承自 RefCounted 与 Object)。TextServer 是“面向使用者的 API 接口”,而 TextServerExtension 是“面向实现者的插件基类”。按照官方类参考的说明,外部 TextServer 实现应当继承自 TextServerExtension,而不是直接实现 TextServer。

在 Godot 官方代码库中,已经存在三个基于该基类的内置实现(见 class_textserverextension.rst 的 "Inherited By" 列表):

实现类 特点 文档来源
TextServerAdvanced Godot 默认主接口,基于 HarfBuzz、ICU 与 SIL Graphite,支持 BiDi、复杂文本布局与上下文相关的 OpenType 特性 classes/class_textserveradvanced.rst
TextServerFallback 回退实现,处理大量文本时更快,但不支持 BiDi 与复杂文本布局;不属于官方二进制的默认组成,需以 module_text_server_fb_enabled=yes 编译启用 classes/class_textserverfallback.rst
TextServerDummy 不渲染文本、不管理字体的空实现,用于节省内存或做 GUI 文本渲染性能对比 classes/class_textserverdummy.rst

与父类 TextServer 的分工

TextServer 被官方描述为“管理字体与渲染文本的服务接口(server interface)”,同时官方明确提示:

这是一个底层 API,建议优先考虑使用 TextLine、TextParagraph 和 Font 类,而不是直接操作该接口。

而获取当前激活 TextServer 实例的标准方式是:

var ts = TextServerManager.get_primary_interface()
var ts = TextServerManager.GetPrimaryInterface();

也就是说:上层控件(Label、RichTextLabel、LineEdit 等)通过 TextServer 的公开方法使用文本能力,而这些公开方法在底层会调用 TextServerExtension 提供的虚拟方法。因此,自定义文本服务的核心工作,就是把 TextServer 接口中对应的方法以带下划线前缀的虚拟方法形式逐一实现。

方法总览:分组与“必需 / 可选”语义

本类参考中列出的方法都带有 |virtual| 标记,其中一部分额外带有 |required| 标记。这两个标记的含义如下:

  • virtual:该方法通常需要用户覆写才有效果;
  • required:扩展该基类时必须覆写;
  • const:该方法没有副作用,不会修改实例的成员变量。

从方法命名与功能上,全部虚拟方法可以划分为以下几大分组:

  1. 服务生命周期与能力声明:_cleanup、_get_name、_get_short_name、_get_features、_has_feature、_free_rid、_has;
  2. 字体资源创建与缓存管理:_create_font、_create_font_linked_variation、_font_clear_*、_font_remove_*、_font_get_size_cache_list 等;
  3. 字体属性读写:_font_get/set_ascent、_font_get/set_descent、_font_get/set_weight、_font_get/set_style、_font_get/set_name、_font_get/set_spacing、_font_get/set_kerning 等;
  4. 字形(Glyph)栅格化与绘制:_font_render_glyph、_font_render_range、_font_draw_glyph、_font_draw_glyph_outline、_font_get_glyph_* 等;
  5. 字形纹理图集(texture atlas)管理:_font_set/get_texture_image、_font_get_texture_count、_font_get_glyph_uv_rect、_font_get_glyph_texture_rid 等;
  6. 复杂文本排版(shaping)缓冲区:_create_shaped_text、_shaped_text_add_string、_shaped_text_add_object、_shaped_text_shape、_shaped_get_*(run/span 查询)等;
  7. 排版结果查询与绘制:_shaped_text_get_glyphs、_shaped_text_get_size、_shaped_text_get_ascent/descent、_shaped_text_draw、_shaped_text_draw_outline 等;
  8. 断行、断词与对齐:_shaped_text_get_line_breaks、_shaped_text_get_word_breaks、_shaped_text_fit_to_width、_shaped_text_tab_align、_shaped_text_overrun_trim_to_width 等;
  9. 文本编辑辅助:_shaped_text_hit_test_position、_shaped_text_get_carets、_shaped_text_get_selection、_shaped_text_substr、_shaped_text_duplicate 等;
  10. Unicode / 本地化支持:_string_to_lower/upper/title、_string_get_character_breaks、_string_get_word_breaks、_format_number、_parse_number、_strip_diacritics、_spoof_check、_is_confusable 等;
  11. 支持数据(break iterator 数据库)管理:_get_support_data、_load_support_data、_save_support_data 等。

服务生命周期与能力声明(required 核心)

一个自定义 TextServer 插件必须首先声明“我是谁、我能做什么、如何管理资源”,这些方法大多带 |required| 标记:

  • _get_name() → String(required):返回服务器接口的名称,如 "Advanced"。
  • _get_short_name() → String(virtual):返回接口的短名。按约定应为 snake_case 的小写字符串。
  • _get_features() → int(required):返回文本服务器支持的 feature 位掩码,具体取值参见 TextServer.Feature 枚举。
  • `_has_feature(feature: Feature) → bool(required):查询服务器是否支持某个特定 feature。
  • _cleanup()(virtual):在文本服务器被注销(unregister)之前调用,用于释放全局资源。
  • `_free_rid(rid: RID)(required):释放本 TextServer 创建的任意对象(字体、排版缓冲区等)。
  • **_has(rid: RID) → bool(required)**:判断给定的 rid` 是否为本文本服务器拥有的有效资源。

以官方实现为参照:TextServerDummy 就是这些生命周期方法的极端例子——它“不渲染文本、不管理字体”,通过 TextServerManager.find_interface("Dummy") 获取后在不需要文本渲染时切换到主接口以节省内存:

var dummy_text_server = TextServerManager.find_interface("Dummy")
if dummy_text_server != null:
    TextServerManager.set_primary_interface(dummy_text_server)

字体缓存体系:从创建到属性读写

字体资源创建

  • `_create_font() → RID(required):创建一个新的、空的字体缓存条目(font cache entry)资源,返回其 RID。
  • `_create_font_linked_variation(font_rid: RID) → RID(virtual):基于已有字体创建一个变体(variation),该变体复用同一个字形缓存与字体数据。文档特别注明:可选实现,仅当字体支持额外的间距或基线偏移时才需要。

字体缓存的分层结构

TextServerExtension 的字体体系是一个典型的“缓存 + 尺寸 + 纹理图集”结构:

  • 每个字体 RID 对应一个 cache entry;
  • 每个 cache entry 可以包含 多个字号(size)与描边尺寸(outline size),每个尺寸是一个 Vector2i(x 为字号、y 为描边尺寸);
  • 每个尺寸对应一组 字形(glyph)信息 与一组 纹理图集(texture atlas)。

对应的方法组包括:

操作 方法
移除全部已渲染字形 _font_clear_glyphs(font_rid, size: Vector2i)(required)
移除全部字号 _font_clear_size_cache(font_rid)(required)
移除全部纹理 _font_clear_textures(font_rid, size: Vector2i)(required)
移除单个字形 _font_remove_glyph(font_rid, size: Vector2i, glyph)(required)
移除单个字号 _font_remove_size_cache(font_rid, size: Vector2i)(required)
移除单个纹理 _font_remove_texture(font_rid, size: Vector2i, texture_index)(required)
列出缓存中的字号 _font_get_size_cache_list(font_rid) → Array[Vector2i](required)
获取缓存统计信息 _font_get_size_cache_info(font_rid) → Array[Dictionary],每项包含 size_px(字号)、viewport_oversampling(视口过采样因子)、glyphs(已渲染字形数)、textures(纹理数)、textures_size(纹理数据字节数)

字体度量与风格属性

字体度量(metrics)是排版正确性的基础,以下方法成对出现且多为 required:

  • _font_get_ascent(font_rid, size) / _font_set_ascent(...):基线以上的像素数;
  • _font_get_descent(font_rid, size) / _font_set_descent(...):基线以下的像素数;
  • _font_get_underline_position / _font_set_underline_position:下划线相对基线的像素偏移;
  • _font_get_underline_thickness / _font_set_underline_thickness:下划线像素厚度;
  • _font_get_scale / _font_set_scale:彩色位图字体的缩放因子;
  • _font_get_fixed_size / _font_set_fixed_size:位图字体固定字号。若大于 0,则所有字号共用同一 cache entry;
  • _font_get_fixed_size_scale_mode / _font_set_fixed_size_scale_mode:位图字体缩放模式,仅当 fixed_size > 0 时生效。

风格类属性大多为非 required 的可选实现:

  • _font_get/set_name:字体族名;
  • _font_get/set_style(FontStyle 位掩码)与 _font_get/set_style_name:字体风格;
  • _font_get/set_weight:字重(粗度),取值 100...999,常规为 400,粗体为 700;
  • _font_get/set_stretch:相对常规宽度的拉伸百分比,范围 50%...200%;
  • _font_get/set_embolden:加粗强度,非零时加粗轮廓,负值减薄;
  • _font_get/set_antialiasing、_font_get/set_hinting、_font_get/set_subpixel_positioning:渲染质量相关(动态字体专用);
  • _font_get/set_transform:应用于字体轮廓的 2D 变换,可用于斜切、翻转与旋转字形;
  • _font_get/set_baseline_offset:额外基线偏移(以字体高度比例表示);
  • _font_get/set_spacing(SpacingType):按像素设置的字间距(不随字号缩放)。

语言与文字系统支持查询

  • `_font_has_char(font_rid, char) → bool(required):查询字体是否包含某个 Unicode 字符;
  • `_font_get_supported_chars(font_rid) → String(required):返回字体中全部可用字符组成的字符串;
  • `_font_get_supported_glyphs(font_rid) → PackedInt32Array(required):返回字体全部字形索引;
  • _font_is_language_supported(font_rid, language) → bool:按 ISO 639 语言码查询支持情况;
  • _font_is_script_supported(font_rid, script) → bool:按 ISO 15924 文字码查询支持情况;
  • _font_set_language_support_override / _font_set_script_support_override:为上述查询添加覆盖(override);
  • _font_get_face_count / _font_get_face_index / _font_set_face_index:TrueType/OpenType 集合(collection)中的 face 数量与激活 face 索引;
  • _font_get_ot_name_strings:返回 OpenType 字体名称字符串字典(本地化字体名、版本、描述、许可证、示例文本等);
  • _font_supported_feature_list / _font_supported_variation_list:返回支持的 OpenType feature / variation 坐标字典;
  • _font_get/set_variation_coordinates:可变字体(variable font)的 variation 坐标;
  • _font_get/set_opentype_feature_overrides:OpenType feature 集合覆盖。

字形索引与字距(Kerning)

  • `_font_get_glyph_index(font_rid, size, char, variation_selector) → int(required):返回字符(可附带变体选择符)对应的字形索引;
  • **_font_get_char_from_glyph_index(font_rid, size, glyph_index) → int(required)**:反向映射,无效索引返回 0`;
  • _font_get/set_kerning(font_rid, size, glyph_pair: Vector2i):查询/设置某字形对(glyph pair)的字距;
  • _font_get_kerning_list / _font_clear_kerning_map / _font_remove_kerning:管理全部字距覆盖项。

字形栅格化与纹理图集(glyph rasterization & texture atlas)

文本渲染性能的关键在于字形如何被栅格化并打包进纹理图集。TextServerExtension 将“渲染到缓存”与“从缓存绘制”分离:

渲染(写入缓存):

  • _font_render_glyph(font_rid, size: Vector2i, index):将指定字形栅格化到字体缓存纹理中;
  • _font_render_range(font_rid, size: Vector2i, start, end):将一段字符范围批量栅格化到缓存纹理。

字形信息读取(required 为主):

  • _font_get_glyph_list(font_rid, size: Vector2i) → PackedInt32Array:缓存条目中已渲染字形的列表;
  • _font_get_glyph_advance(font_rid, size, glyph) → Vector2:下一个字形的偏移(advance);
  • _font_get_glyph_offset(font_rid, size: Vector2i, glyph) → Vector2:字形相对基线的偏移;
  • _font_get_glyph_size(font_rid, size: Vector2i, glyph) → Vector2:字形尺寸;
  • _font_get_glyph_texture_idx / _font_get_glyph_texture_rid:字形所在缓存纹理的索引 / RID;
  • _font_get_glyph_uv_rect(font_rid, size: Vector2i, glyph) → Rect2:字形在缓存纹理中的 UV 矩形;
  • _font_get_glyph_contours(font_rid, size, index) → Dictionary:字形轮廓曲线数据(可用于矢量缩放)。

纹理管理:

  • _font_get/set_texture_image(font_rid, size: Vector2i, texture_index) → Image(required):读写缓存纹理图像数据;
  • _font_get_texture_count(font_rid, size: Vector2i) → int(required):缓存条目使用的纹理数量;
  • _font_get/set_texture_offsets(font_rid, size, texture_index) → PackedInt32Array:字形打包(packing)数据。

绘制(读出缓存):

  • _font_draw_glyph(font_rid, canvas, size, pos, index, color, oversampling)(required, const):将单个字形绘制到 canvas item 的指定位置。若 oversampling > 0 则用作字体过采样因子,否则使用视口过采样设置;
  • _font_draw_glyph_outline(...)(required, const):同上,但绘制的是 outline_size 大小的字形描边。

渲染模式选项:

  • _font_set_multichannel_signed_distance_field(font_rid, msdf: bool):启用 MSDF(多通道有符号距离场)渲染。启用后所有字号共用同一张由矢量数据生成的 MSDF 纹理,可在任意缩放比例下保持清晰、且字号变化时无需 CPU 重新栅格化;缺点是 MSDF 模式下没有字体 hinting,小字号可能不够清晰锐利。配套方法有 _font_get/set_msdf_size(生成 MSDF 纹理的源字号)与 _font_get/set_msdf_pixel_range(最小/最大可表示有符号距离之间的范围宽度);
  • _font_set_generate_mipmaps / _font_get_generate_mipmaps:字体纹理 mipmap 生成开关;
  • _font_set_disable_embedded_bitmaps / _font_get_disable_embedded_bitmaps:禁用字体内嵌位图;
  • _font_set_allow_system_fallback / _font_get_allow_system_fallback(即 _font_is_allow_system_fallback):是否允许自动使用系统字体作为回退,配套 _font_clear_system_fallback_cache() 释放自动加载的系统字体;
  • _font_set_force_autohinter / _font_is_force_autohinter:是否优先使用自动 hinting 而非字体内置 hinting;
  • _font_set_keep_rounding_remainders / _font_get_keep_rounding_remainders:字形对齐像素边界时是否累积舍入余数以获得更均匀的字形分布;启用亚像素定位时此设置无效;
  • _font_set_modulate_color_glyphs / _font_is_modulate_color_glyphs:是否对彩色字形应用颜色调制(否则仅对单色字形调制);
  • 颜色面板:_font_get_palette_count、_font_get_palette_name、_font_get_palette_colors、_font_get/set_palette_custom_colors(空数组表示重置覆盖,使用 Color(0, 0, 0, 0) 保留预定义面板中该位置的原始颜色)、_font_get/set_used_palette;
  • 过采样引用计数:_font_get_global_oversampling / _font_set_global_oversampling 管理全服务器共享的过采样因子;_reference_oversampling_level(oversampling) 与 _unreference_oversampling_level(oversampling) 由 Viewport 调用维护每个过采样级别的引用计数,当计数归零时释放对应字体缓存——文档明确提醒“不应直接调用”。

复杂文本排版缓冲区:Shaped Text 全流程

TextServerExtension 的核心能力是把字符串排版成可测量的字形序列。流程如下:

  1. 创建缓冲区:_create_shaped_text(direction: Direction, orientation: Orientation) → RID(required);
  2. 添加内容:_shaped_text_add_string(shaped, text, fonts: Array[RID], size, opentype_features: Dictionary, language, meta) → bool(required) 添加文本 span;_shaped_text_add_object(shaped, key, size, inline_align, length, baseline) → bool(required) 添加内联对象(如 RichTextLabel 中的图标),对象在文本中以 length 个对象替换字符表示,key 必须唯一;
  3. 执行 shaping:_shaped_text_shape(shaped) → bool(required),若缓冲区尚未排版则执行排版;
  4. 查询结果:通过 _shaped_get_* 与 _shaped_text_get_* 系列读取字形、run、span、尺寸与度量;
  5. 绘制:_shaped_text_draw(...) / _shaped_text_draw_outline(...) 输出到 canvas item。

span 与 run 的区别

  • span:通过 _shaped_text_add_string / _shaped_text_add_object 添加的、带有字体与元数据的源文本片段。_shaped_get_span_count()(required)返回 span 数量,_shaped_get_span_text、_shaped_get_span_meta、_shaped_get_span_object、_shaped_get_span_embedded_object 分别读取其源文本、元数据与内嵌对象;_shaped_set_span_update_font(shaped, index, fonts, size, opentype_features)(required)可在不改变文本的情况下更换 span 的字体、字号与 OpenType 特性;
  • run:排版后的视觉顺序片段。_shaped_get_run_count() 返回 run 数量,_shaped_get_run_direction、_shaped_get_run_font_rid、_shaped_get_run_font_size、_shaped_get_run_language、_shaped_get_run_glyph_range、_shaped_get_run_range、_shaped_get_run_text、_shaped_get_run_object 分别查询每个 run 的方向、字体、字号、语言、字形范围、源文本范围、源文本与内嵌对象。

字形与测量查询(required 为主)

  • _shaped_text_get_glyph_count / _shaped_text_get_glyphs(const Glyph*,按视觉顺序)与 _shaped_text_sort_logical(const Glyph*,按逻辑顺序);
  • _shaped_text_get_size → Vector2、_shaped_text_get_width → float(横排为宽度、竖排为高度);
  • _shaped_text_get_ascent / _shaped_text_get_descent:横排时表示基线上/下方像素数,竖排时表示基线左/右侧像素数;
  • _shaped_text_get_range → Vector2i:子串缓冲区在父缓冲区中的字符范围;
  • _shaped_text_get_parent → RID:子串来源的父缓冲区;
  • _shaped_text_get_direction、_shaped_text_get_inferred_direction(由 BiDi 算法推断的方向)、_shaped_text_get_dominant_direction_in_range、_shaped_text_get_orientation;
  • _shaped_text_get_spacing、_shaped_text_get_underline_position、_shaped_text_get_underline_thickness、_shaped_text_get_trim_pos(overrun 裁剪位置)。

内联对象管理

  • _shaped_text_get_object_glyph、_shaped_text_get_object_range、_shaped_text_get_object_rect、_shaped_text_get_objects、_shaped_text_has_object、_shaped_text_resize_object(均 required)。

断行、断词、对齐与裁剪

  • _shaped_text_get_line_breaks(shaped, width, start, break_flags) → PackedInt32Array:按宽度断行,返回每行字符范围;
  • _shaped_text_get_line_breaks_adv(shaped, width: PackedFloat32Array, start, once, break_flags):按多列宽度断行断列,返回每个片段范围;
  • _shaped_text_get_word_breaks(shaped, grapheme_flags, skip_grapheme_flags) → PackedInt32Array:断词;
  • _shaped_text_fit_to_width(shaped, width, justification_flags) → float:两端对齐到指定宽度,返回新的文本宽度;
  • _shaped_text_tab_align(shaped, tab_stops: PackedFloat32Array) → float:按制表位对齐;
  • _shaped_text_overrun_trim_to_width(shaped, width, trim_flags):超宽文本裁剪(配合 _shaped_text_get_custom_ellipsis / _shaped_text_set_custom_ellipsis 自定义省略号字符,以及 _shaped_text_get_custom_punctuation / _shaped_text_set_custom_punctuation 自定义断词标点);
  • _shaped_text_update_breaks(shaped) → bool:更新断点,由默认断行函数调用;
  • _shaped_text_update_justification_ops(shaped) → bool:更新对齐点,由默认对齐函数调用。

编辑与命中测试

  • _shaped_text_get_carets(shaped, position, r_caret: CaretInfo*):返回字符偏移 position 处光标的形状(1 像素宽的矩形),用于双向文本的光标绘制;
  • _shaped_text_hit_test_position(shaped, coord) → int:基线像素偏移对应的光标字符偏移,总是返回有效位置;
  • _shaped_text_hit_test_grapheme(shaped, coord) → int:命中测试到字素(grapheme)索引,未命中返回 -1;
  • _shaped_text_get_selection(shaped, start, end) → PackedVector2Array:指定字符范围的选区矩形;
  • _shaped_text_get_character_breaks、_shaped_text_closest_character_pos、_shaped_text_next_character_pos、_shaped_text_prev_character_pos:复合字符边界与前后导航;
  • _shaped_text_next_grapheme_pos、_shaped_text_prev_grapheme_pos、_shaped_text_get_grapheme_bounds:字素级导航与边界;
  • _shaped_text_substr(shaped, start, length) → RID(required):取子串排版缓冲区(含内联对象);
  • _shaped_text_duplicate(shaped) → RID(required):复制排版缓冲区;
  • _shaped_text_clear(shaped)(required):清空缓冲区;
  • _shaped_text_is_ready(shaped) → bool(required):缓冲区是否成功排版。

方向与 BiDi

  • _shaped_text_set_direction:设置期望方向,若为 TextServer.DIRECTION_AUTO 则根据缓冲区内容与当前 locale 自动检测;
  • _shaped_text_set_orientation:设置期望朝向(横排/竖排);
  • _shaped_text_set_bidi_override(shaped, override: Array):为结构化文本覆盖 BiDi 算法;
  • _parse_structured_text(parser_type: StructuredTextParser, args: Array, text) → Array<a href="https://link.gitcode.com/i/4050952ed48f07b68af1699511ab53ea" target="_blank">Vector3i]:BiDi 算法覆盖函数的默认实现。这与 [tutorials/i18n/internationalizing_gods.rst 中“结构化文本 BiDi 覆盖”一节介绍的机制对应——Unicode BiDi 算法对文件名、URI、邮箱地址、正则表达式、源码这类“高层级顺序”的文本无能为力,而结构化文本解析器把文本按段落拆分后逐段应用 BiDi,从而保证目录名等片段在任意语言下正确显示并保持顺序;
  • _shaped_text_set_preserve_control(shaped, enabled):是否显示控制字符;
  • _shaped_text_set_preserve_invalid(shaped, enabled):是否将无效字符显示为十六进制码(配合 _draw_hex_code_box 与 _get_hex_code_box_size,后者返回无效字符替身“十六进制码盒子”的尺寸)。

Unicode 处理与本地化支持方法

  • _string_to_lower(string, language) / _string_to_upper / _string_to_title:语言感知的大小写/标题转换;
  • _string_get_character_breaks(string, language) → PackedInt32Array:复合字符边界;
  • _string_get_word_breaks(string, language, chars_per_line) → PackedInt32Array:断词边界,返回数组元素是单词起止偏移,因此长度恒为偶数;
  • _strip_diacritics(string):去除变音符(diacritics);
  • _is_valid_identifier(string) → bool:字符串是否为合法标识符;
  • _is_valid_letter(unicode) → bool:Unicode 码点是否为合法字母(该方法的官方描述暂缺,可由实现补充);
  • _is_locale_right_to_left(locale) → bool:locale 是否为从右到左;
  • _is_locale_using_support_data(locale) → bool:该 locale 的断行/断词是否需要文本服务器支持数据;
  • _spoof_check(string) → bool:字符串是否疑似欺骗性文本(混淆阅读者);
  • _is_confusable(string, dict: PackedStringArray) → int:返回 dict 中第一个与 string 视觉上易混淆的字符串索引,无则返回 -1;
  • _format_number(number, language) / _parse_number(number, language):西方阿拉伯数字(0..9)与给定语言数字系统之间的转换。文档标注两者已弃用,应改用 TranslationServer.format_number() / TranslationServer.parse_number()。language 为空时使用当前激活 locale。国际化教程中也给出了对应的使用方式:tutorials/i18n/internationalizing_games.rst 中提到 ProgressBar、SpinBox 等控件会自动使用本地化数字系统,其他控件则调用 TextServer.format_number / parse_number 进行转换;
  • _percent_sign(language) → String:已弃用,改用 TranslationServer.get_percent_sign();
  • _name_to_tag(name) → int / _tag_to_name(tag) → String:OpenType feature/variation/script/language 可读名称与 OpenType tag 之间的双向转换。

支持数据(Support Data):断行断词数据库

部分语言不使用空格书写(如日语、泰语),其断行断词依赖 ICU 的规则与词典型 break iterator 数据。相关虚拟方法:

  • _get_support_data() → PackedByteArray:返回默认 TextServer 数据库(如 ICU break iterators 与词典);
  • _get_support_data_filename() → String:返回该数据库文件名;
  • _get_support_data_info() → String:返回数据库描述;
  • _load_support_data(filename) → bool:从文件加载可选数据库;
  • _save_support_data(filename) → bool:将数据库保存到文件。

这与国际化教程中“Adding break iterator data to exported project”一节相呼应:ICU 规则与词典型断行数据默认不包含在导出的项目中,需要在 Project > Project Settings > General > Internationalization > Locale 中启用 Include Text Server Data 后再导出,该数据约 4 MB。

自定义 TextServer 插件的实现要点

综合以上方法分组,实现一个自定义 TextServer 插件时需要特别关注以下几点:

  1. required 方法必须全部实现:_create_font、_create_shaped_text、_font_clear_glyphs、_font_clear_size_cache、_font_clear_textures、_font_get_ascent/descent/scale/fixed_size/fixed_size_scale_mode、_font_get_glyph_*、_font_has_char、_font_get_supported_chars/glyphs、_font_render_glyph、_font_set_*(字形相关)、_free_rid、_get_features、_get_name、_has、_has_feature、_shaped_get_span_*、_shaped_text_add_*、_shaped_text_shape、_shaped_text_* 的查询/管理方法等,都属于必需实现集合;
  2. 非 required 的 virtual 方法按能力声明取舍:例如 _create_font_linked_variation 仅在字体支持额外间距或基线偏移时需要;BiDi、断行、本地化等能力可通过 _get_features / _has_feature 声明,未声明的能力对应方法可以保持默认行为;
  3. RID 资源管理是核心:所有字体与排版缓冲区都以 RID 为句柄,_has 与 _free_rid 必须能正确校验与释放这些资源,否则会造成资源泄漏;
  4. 性能关键路径:字形栅格化结果缓存在字体 cache entry 的纹理图集中,_font_render_glyph 的批量渲染(_font_render_range)与过采样引用计数机制直接决定文本渲染的 CPU/GPU 开销;MSDF 模式则把“字号变化时的重栅格化成本”转移到 GPU 采样上,适合需要平滑缩放的场景;
  5. 与上层 API 协同:默认情况下开发者应使用 TextLine、TextParagraph、Font 等高层类,自定义 TextServer 插件通过 TextServerManager 注册为主接口后即可被这些高层类透明使用。官方现有的 TextServerFallback(更快但无 BiDi/复杂排版)与 TextServerDummy(完全不渲染,用于省内存与性能对比)是实现范例与测试基准。

延伸阅读

登录后查看全文
godot-docs