SuperAPI AI 工具集

bevy-ui-text

编程与开发

查看项目

更新于 10-16 11:40

技能介绍

用途

bevy-ui-text 用于在 Bevy 0.20 中处理 UI 文本与 2D 世界文本。当 HUD 节点或 2D 名称牌需要显示字符串时加载该技能。布局相关的内容归属 bevy-ui-layout。

主要能力

UI 文本

在实体上 spawn Text,它需要 Node、TextFont、TextColor 与 TextLayout。Text 上的字符串是第一个 span。bevy_text 随 DefaultPlugins 提供;default_font 特性内嵌默认 ASCII 字体,因此没有自定义 Font 句柄的 Text 仍能绘制。

Text 是 HUD 字符串,Node 决定其位置。字符串的后续编辑由单个系统负责。

世界文本

Text2d 需要 TextFont、TextColor、TextLayout、TextBounds、Anchor 与 Transform。Text2dShadow 会偏移一份字形副本形成阴影。

多 span 与强调

额外的 span 是挂有 TextSpan 的子实体,每个子实体保有自己的 TextFont 与 TextColor;父级 TextLayout 负责整块布局。Underline 与 Strikethrough 是需要该标记的 span 上的组件。

字体与阴影

自定义字体是存于 TextFont 上的 AssetServer 句柄。UI 投影阴影使用 TextShadow,世界文本阴影使用 Text2dShadow。

使用方式

系统在字符串或样式变化后由引擎在 PostUpdate 中运行 update_text2d_layout。游戏系统写入 Text、Text2d、TextSpan、TextFont 与 TextColor,不运行第二次布局。

依赖配置:

[dependencies]
bevy = "0.20"

选择文本实体:

需求 生成 不要
HUD 或菜单字符串 在 Node 上的 Text,加 TextFont 与 TextColor 在 Text 变化后再跑一个布局系统
2D 世界中的名称牌 Text2d、Anchor 与 Text2dShadow 用 Justify 作为世界位置
一行中两种样式 子 TextSpan 实体,带自己的字体、颜色、Underline 或 Strikethrough 由引擎解析的标记字符串

适用场景

  • 显示 HUD 分数、状态行等 UI 字符串。
  • 在 2D 世界中显示角色名称牌。
  • 在同一行内组合不同字体、颜色或强调样式。
  • 加载自定义字体资源并应用投影。

限制与约束

  • 文档面向 Bevy 0.20+。
  • 不要在文档 URL 中固定 /0.20.0/。
  • 不要从两个未排序的系统可变查询同一组件;调度会并行运行系统,除非用 .chain() 排序。
  • 不要在此发明物理、导航、网络或 XR crate;该技能只命名有文档的 Bevy crate 与模块。
  • 不要把强调存入标记字符串;Underline 与 Strikethrough 是 Text 或 TextSpan 上的组件。
  • 不要让两个系统写入同一 Text 或 TextSpan;字符串只有一个所有者,第二个写入者会与格式系统竞争。
  • 不要使用臆造的 API 或未命名第三方 crate 作为解决方案。
  • 涉及物理步长、状态归属等 ECS 细节时,参考文档的 ownership 表和 references/ecs-ownership.md。

相关技能

前置:bevy-master(枢纽与调度)、bevy-ecs-composition(组件与系统)、bevy-ui-layout(承载文本的节点)。互补:bevy-dialogue-system(行字符串)、bevy-ui-theming(字符串周边颜色)。

参考文档

官方文档包含 Assets、Examples(latest 分支)、ECS、Plugins、UI examples。库固定版本保持 0.20。