用途
当运行中的应用需要打印日志,或需要记录帧时间、实体数量、进程 CPU 与内存占用时,使用本技能。它面向 Bevy 0.20+,聚焦于日志与诊断(diagnostics)相关的 ECS 用法。
主要能力
日志
LogPlugin 是 DefaultPlugins 的一部分。可以通过 DefaultPlugins.set(LogPlugin { level, filter, .. }) 覆盖它。示例使用 Level::DEBUG 以及类似 wgpu=error,bevy_render=info,bevy_ecs=trace 的过滤字符串。同样的过滤字符串也可用作 RUST_LOG。若要接入自己的收集器,可在 DefaultPlugins 上禁用该插件。
诊断核心
DiagnosticsPlugin 添加核心资源。DiagnosticsStore 保存采集到的数据。Diagnostic 是由 DiagnosticPath 寻址的 DiagnosticMeasurement 值组成的时间线。RegisterDiagnostic 在 App 上添加 register_diagnostic。
内置插件
FrameTimeDiagnosticsPlugin:添加帧时间、fps 和帧计数。EntityCountDiagnosticsPlugin:添加实体数量。SystemInformationDiagnosticsPlugin:添加cpu_usage和mem_usage百分比。LogDiagnosticsPlugin:把诊断信息打印到控制台。FrameCount/FrameCountPlugin:统计自启动以来的帧数。
顺序与调度
日志诊断示例把这些插件添加在 DefaultPlugins 之后,因为它们需要时间插件来生成时间戳。内置插件自行进行测量。当 HUD 需要最新样本时,读取 DiagnosticsStore。只有需要自己测量的值才注册 Diagnostic。
使用方式
依赖声明:
[dependencies]
bevy = "0.20"
LogPlugin 随 DefaultPlugins 一起提供。当默认的 info 输出过少或过多时,替换其级别与过滤器:
use bevy::log::{Level, LogPlugin};
fn main() {
App::new()
.add_plugins(DefaultPlugins.set(LogPlugin {
filter: "wgpu=error,bevy_render=info,bevy_ecs=trace".into(),
level: Level::DEBUG,
..default()
}))
.run();
}
帧时间、实体数量、进程 CPU 与内存以及控制台输出是四个插件。把它们添加在 DefaultPlugins 之后,以便时间戳存在:
use bevy::diagnostic::{
EntityCountDiagnosticsPlugin, FrameTimeDiagnosticsPlugin, LogDiagnosticsPlugin,
SystemInformationDiagnosticsPlugin,
};
fn main() {
App::new()
.add_plugins((
DefaultPlugins,
FrameTimeDiagnosticsPlugin::default(),
EntityCountDiagnosticsPlugin {
max_history_length: 60,
},
SystemInformationDiagnosticsPlugin,
LogDiagnosticsPlugin::default(),
))
.run();
}
HUD 从 store 读取平滑后的帧时间样本。路径常量位于记录它们的插件上:
use bevy::diagnostic::{DiagnosticsStore, FrameTimeDiagnosticsPlugin};
fn read_frame_time(store: Res<DiagnosticsStore>) {
let Some(frame) = store.get(&FrameTimeDiagnosticsPlugin::FRAME_TIME) else {
return;
};
let Some(ms) = frame.smoothed() else {
return;
};
info!("frame {ms:.2} ms");
}
自定义计数器由一个 DiagnosticPath 加 register_diagnostic 组成。一个系统写入测量值,其他任何地方都不修改该路径:
use bevy::diagnostic::{Diagnostic, DiagnosticPath, Diagnostics, RegisterDiagnostic};
const LIVE_ENEMIES: DiagnosticPath = DiagnosticPath::const_new("game/live_enemies");
#[derive(Component)]
struct Enemy;
fn install(app: &mut App) {
app.register_diagnostic(Diagnostic::new(LIVE_ENEMIES).with_max_history_length(60));
}
fn measure_enemies(mut diagnostics: Diagnostics, enemies: Query<(), With<Enemy>>) {
let count = enemies.iter().count() as f64;
diagnostics.add_measurement(&LIVE_ENEMIES, || count);
}
适用场景
- 需要在运行时观察日志输出并调整日志级别与过滤规则。
- 需要在 HUD 或控制台查看帧时间、fps、帧计数、实体数量、进程 CPU 与内存占用。
- 需要为游戏自定义指标(例如存活敌人数)建立可查询的诊断时间线。
限制
- 逐系统火焰图与 Tracy 不在本技能范围内;
LogPlugin只覆盖级别与过滤器。 - 自定义测量使用上文示例中的
Diagnostic、DiagnosticPath和register_diagnostic。 - 本技能不把诊断转发到渲染应用。
- 不涉及物理、导航、网络或 XR crate;不涉及第三方性能分析 crate。
- 文档 URL 不固定
/0.20.0/版本路径,官方页面保持在未版本化的站点上。
相关背景(ECS 所有权要点)
目标版本为 Bevy 0.20+。核心 ECS 类型包括 Component、Resource、Query、Commands、Startup、Update、Fixed / FixedMain(bevy::time)、.chain()、Plugin、DefaultPlugins、MinimalPlugins。消息与观察者属于另一个所有权槽位,其 API 见 bevy-events-messaging。除非用 .chain() 对冲突的系统排序,否则系统并行运行。
状态所有权:单个实体上的数据由 Component 承载,一个系统通过 Query 修改;整个应用的一个值由 Resource 承载,一个系统修改;生成由 Commands 在生成系统中完成;不能竞争的顺序由 .chain() 约束;插件边界由 Plugin 的 build 注册系统与资源。借用规则:两个系统若都可变查询同一组件,必须排序(.chain())或拆分,使只有一个写入;无关系统保持并行。
决策要点:按实体数据用 Component + Query;应用级配置或时钟用 Resource;稳定模拟步长用 FixedMain 与 Fixed 时钟;启动生成用 Startup 中的 Commands;跨系统通知且非共享状态用消息或观察者;文档集之外的 API 应查阅官方 Bevy 页面。