bevy-capture

bevy-capture — 录制 Bevy 0.19 摄像机

何时使用此技能

• 录制确定性的游戏玩法、电影片段或渲染测试证据。
• 将无头 Camera2d/Camera3d 捕获为 MP4、GIF 或编号 PNG。
• 在进程内 OpenH264、ffmpeg 和无损帧输出之间进行选择。
• 排查缺少编码器模块、输出为空或录制未完成刷新的问题。

bevy_capture = "0.6" 原生面向 Bevy 0.19。不要沿用适用于 Bevy 旧版本的 0.4.x，也不要使用旧版 CameraTargetHeadless API。

标准模式

[dependencies]
bevy = "0.19"
bevy_capture = { version = "0.6", features = ["mp4_openh264"] }

use bevy::{
    app::{RunMode, ScheduleRunnerPlugin},
    camera::RenderTarget,
    prelude::*,
    render::RenderPlugin,
    winit::WinitPlugin,
};
use bevy_capture::{
    encoder::mp4_openh264::Mp4Openh264Encoder,
    Capture, CaptureBundle, CapturePlugin, RenderTargetHeadless,
};
use std::fs::{self, File};

const WIDTH: u16 = 1280;
const HEIGHT: u16 = 720;

fn main() -> AppExit {
    App::new()
        .add_plugins((
            DefaultPlugins.build().disable::<WinitPlugin>().set(RenderPlugin {
                synchronous_pipeline_compilation: true,
                ..default()
            }),
            ScheduleRunnerPlugin {
                run_mode: RunMode::Loop { wait: None },
            },
            CapturePlugin,
        ))
        .add_systems(Startup, setup)
        .add_systems(Update, record)
        .run()
}

fn setup(mut commands: Commands, mut images: ResMut<Assets<Image>>) {
    commands.spawn((
        Camera2d,
        RenderTarget::target_headless(WIDTH.into(), HEIGHT.into(), &mut images),
        CaptureBundle::default(),
    ));
}

fn record(
    mut captures: Query<&mut Capture>,
    mut waited_for_pipeline: Local<bool>,
    mut frame: Local<u32>,
) {
    // Allow the render pipeline one frame to become ready.
    if !*waited_for_pipeline {
        *waited_for_pipeline = true;
        return;
    }

    let Ok(mut capture) = captures.single_mut() else { return };
    if !capture.is_capturing() && *frame == 0 {
        fs::create_dir_all("captures").expect("create captures directory");
        let encoder = Mp4Openh264Encoder::new(
            File::create("captures/run.mp4").expect("create output"),
            WIDTH,
            HEIGHT,
        )
        .expect("initialize OpenH264");
        capture.start(encoder);
    }

    *frame += 1;
    if *frame == 300 {
        capture.stop(); // drops the encoder and finalizes the MP4
    }
}

编码器选择

编码器	功能	外部程序	最适用途
Mp4Openh264Encoder	mp4_openh264	否	进程内 H.264
Mp4FfmpegCliEncoder	mp4_ffmpeg_cli	ffmpeg	短片段／离线片段
Mp4FfmpegCliPipeEncoder	mp4_ffmpeg_cli_pipe	ffmpeg	长时间流式捕获
GifEncoder	gif	否	小型预览
FramesEncoder	无	否	无损 PNG 序列

选择生产环境编解码器或分发模式前，请参阅编码器详情。

注意事项

• RenderTargetHeadless 为 RenderTarget 实现；请调用 RenderTarget::target_headless(...)。Camera 上的旧辅助方法已过时。
• 将 Camera2d/Camera3d、无头 RenderTarget 和 CaptureBundle 挂载到同一实体。
• 至少等待一帧再开始。同步编译管线可提升批量捕获的确定性，但可能会延长启动时间。
• 编码器模块受功能门控。请仅启用你导入的功能。
• 调用 Capture::stop() 或丢弃 Capture 会完成编码器的收尾工作。进程突然终止可能导致 MP4 或 GIF 无效。
• ffmpeg 编码器要求 PATH 中存在 ffmpeg；构造函数会返回 Result。
• 确保编码器尺寸与无头目标匹配。OpenH264 使用 u16。
• 浏览器 WASM 没有常规文件系统或子进程。请明确设计 JS 下载／流式传输路径，而不要假定这些编码器可以正常工作。

另请参阅

• bevy-cameras — 摄像机和渲染目标。
• bevy-cargo-features — 功能选择。
• bevy-wasm-webgpu — 浏览器限制。
• 编码器对比。
• 0.19 兼容性。