用途
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。