SuperAPI AI 工具集

bevy-debugging-profiling

编程与开发

查看项目

更新于 10-16 10:37

技能介绍

用途

当运行中的应用需要打印日志,或需要记录帧时间、实体数量、进程 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 页面。