Bevy Diagnostic Overlay

Bevy 0.19 在 bevy_dev_tools 中新增的运行时诊断覆盖层。它在屏幕角落叠一层只读 UI，实时显示 fps、frame_time、frame_count 等诊断测量值，定位是「不用接外部 profiler 就能看帧率」的轻量 开发工具。

该功能由 PR #22486 引入，#24433 修复初始化时序，#24611 修复点击穿透与 BSN 兼容并新增字体配置。

为什么重要

对 ZoOL 的 Bevy 项目（见 bevy-projects）而言，诊断覆盖层是 0.19 起内置的帧率/帧时间观测手段， 无需外挂工具即可在迭代时盯着性能。需要注意它默认开启，0.19 正式版前曾因此让底层 UI 不可交互—— 所以 0.19 上线务必带上 #24611 的修复。

核心组件清单

组件 / 资源	类型	作用
DiagnosticsOverlay	Component	覆盖层根组件；0.19 经 #24611 补全 Clone + Default（title: “Diagnostics”，items: 空 vec）后可在 bsn bsn! 宏中使用
DiagnosticsOverlayPlane	Component	全屏透明 Node 容器，承载文本；#24611 给它加了 Pickable { should_block_lower: false, ..Default::default() } 以放行点击事件
DiagnosticsOverlayItem	Component	单条诊断文本项（#24611 加 Clone）
DiagnosticsOverlayStyle	Resource（#24611 新增）	字体大小配置：title_font_size 默认 Px(12.0)、item_font_size 默认 Px(10.0)；在 Plugin build 中 init_resource

历史时间线

• **2024-03-18 — 12560：Diagnostic overlay dev-tool feature request 提出（open）。^[https://github.com/bevyengine/bevy/issues/12560]
• #22486（早期）：实现 Diagnostic Overlay 初版（closed）。^[https://github.com/bevyengine/bevy/pull/22486]
• **2026-05-22 — 24377：报告 “Diagnostics overlay is broken”（覆盖层不显示、折叠后消失）。^[https://github.com/bevyengine/bevy/issues/24377]
• **2026-05-29 — 24433（kfc35）：把 DiagnosticsOverlay 初始化移到 PreStartup，修复 #24377 的竞态；同时暴露出点击穿透问题。^[https://github.com/bevyengine/bevy/pull/24433]
• **2026-06-14 — 24611（cart）：修复点击穿透 + BSN 兼容 + 新增 DiagnosticsOverlayStyle；merged 2026-06-14T21:21:27Z，milestone 0.19。^[https://github.com/bevyengine/bevy/pull/24611]

#24611 的三项修复

1. 点击穿透（critical）：全屏 Node 默认 Pickable 会拦下所有指针事件，导致底层 UI 无法交互。 #24611 在 DiagnosticsOverlayPlane spawn 时加 Pickable { should_block_lower: false }。cart 原话： 不修则在默认配置下 “pretty broken”，必须随 0.19 ship（不需 RC，因功能默认禁用——实际默认开启故必修）。
2. BSN 兼容（important）：DiagnosticsOverlay 之前缺 Clone/Default，无法在 bsn! 宏里用。 补全 #[derive(Component, Clone)] + impl Default，DiagnosticsOverlayItem 加 Clone。
3. 字体可配置（important）：新增 DiagnosticsOverlayStyle Resource，rebuild_diagnostics_list() 与 build_overlay() 注入 style 参数，原先硬编码的 FontSize 全部替换为可配置值。

此外有一处 API 重命名：字段 diagnostic_overlay_items → items（含构造器、new()、fps()、 mesh_and_standard_material() 全文统一），属破坏性但影响面仅限该 dev tool 使用者。

配置方式

// 启用诊断覆盖层（bevy_dev_tools，0.19 起默认随 app）
app.add_plugins(bevy_dev_tools::ci_testing::CiTestingPlugin); // 示例占位，实际见 bevy_dev_tools 文档
 
// 自定义字体大小（#24611 新增 Resource）
app.insert_resource(DiagnosticsOverlayStyle {
    title_font_size: Px(14.0),
    item_font_size: Px(11.0),
});

注：具体插件名/启用方式以 0.19 正式版 bevy_dev_tools 文档为准；上例仅展示 DiagnosticsOverlayStyle 的用法。[待补充来源：0.19 正式版 bevy_dev_tools 启用 API]

Review 讨论

jbuehler23 在 #24611 review 中问为何不用 Feathers widget 实现，cart 回答是为了避免引入 feathers/scene 依赖、保持精简。

相关页面

• bevy — Bevy 引擎主页
• bsn — Bevy Scene Notation（#24611 的 BSN 兼容修复直接服务于 BSN 宏）
• cart — Carter Anderson，#24611 作者
• bevy-game-dev-2026-06 — 2026 年 6 月引擎变更追踪