SuperAPI AI 工具集

bevy-audio-systems

编程与开发

查看项目

更新于 10-16 10:37

技能介绍

用途

本技能用于在 Bevy 引擎(目标版本 0.20+)中处理音频播放。当需要让一段音频开始、循环、暂停或改变音量时,可加载本技能。其依据是 Bevy 0.20 的 bevy::audio 模块以及官方 audio_control 示例。

主要能力

  • 播放:通过生成 AudioPlayer::new(asset_server.load(...)) 来播放音频。AudioPlayer<Source> 持有 Handle<Source>,其中 Source: Asset + Decodable。若资源尚未就绪,播放会在资源就绪后开始。AudioPlayer 需要搭配 PlaybackSettings。
  • 播放设置:PlaybackSettings 用于配置起始播放行为。PlaybackSettings::LOOP 和 .with_spatial(true) 出现在空间音频示例中。对 PlaybackSettings 的修改不会影响已经在播放的音频。PlaybackMode 可取 Once、Loop、Despawn 或 Remove。
  • 播放控制:播放开始时,Bevy 会插入 AudioSink。控制示例会查询 AudioSink 并调用 pause、toggle_mute、set_volume、set_speed 和 position。SpatialAudioSink 是空间音频对应的类型。
  • 重播:非循环音频播放结束且 sink 被清空后,该 AudioPlayer 无法复用。需要移除音频组件再重新添加。
  • 调度:可在 Startup 中生成,或从拥有 Res<AssetServer> 和 Commands 的系统中生成。控制类系统在读取 ButtonInput<KeyCode> 和 Res<Time> 的位置运行。

使用方式

播放相关惯用法:

需求 Bevy 惯用法
启动一个文件 AudioPlayer::new 加 AssetServer::load
循环 PlaybackSettings::LOOP
播放中暂停、静音或调音量 同一实体上的 AudioSink 方法
播放后应离开世界的一次性音效 PlaybackMode::Despawn 或 Remove
位置化发声体 带 with_spatial(true) 的 PlaybackSettings 和 SpatialAudioSink

依赖声明:

[dependencies]
bevy = "0.20"

AudioPlayer 在句柄就绪时开始播放。PlaybackSettings 仅在开始时生效。AudioSink 在播放开始后插入,是实时控制入口。

use bevy::audio::{AudioSinkPlayback, Volume};

fn spawn_music(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn((
        AudioPlayer::new(asset_server.load("audio/music.ogg")),
        PlaybackSettings::LOOP.with_volume(Volume::Linear(0.6)),
    ));
}

fn spawn_oneshot(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn((
        AudioPlayer::new(asset_server.load("audio/ui.ogg")),
        PlaybackSettings::DESPAWN,
    ));
}

fn duck_music(mut sinks: Query<&mut AudioSink>) {
    for mut sink in &mut sinks {
        sink.set_volume(Volume::Linear(0.25));
        sink.pause();
    }
}

位置化发声体设置 with_spatial(true) 和一个 Transform。对该发声体的实时控制使用 SpatialAudioSink。

use bevy::audio::{AudioSinkPlayback, Volume};

fn spawn_footstep(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn((
        AudioPlayer::new(asset_server.load("audio/step.ogg")),
        PlaybackSettings::ONCE.with_spatial(true),
        Transform::from_xyz(3.0, 0.0, 1.0),
    ));
}

fn quiet_nearby(mut sinks: Query<&mut SpatialAudioSink>) {
    for mut sink in &mut sinks {
        sink.set_volume(Volume::Linear(0.5));
    }
}

已结束的非循环播放器无法复用。移除播放器和 sink,然后用同一句柄重新插入。

use bevy::audio::AudioSinkPlayback;

fn replay_when_empty(mut commands: Commands, playing: Query<(Entity, &AudioPlayer, &AudioSink)>) {
    for (entity, player, sink) in &playing {
        if !sink.empty() {
            continue;
        }
        let handle = player.0.clone();
        commands.entity(entity).remove::<AudioPlayer>().remove::<AudioSink>();
        commands.entity(entity).insert((
            AudioPlayer::new(handle),
            PlaybackSettings::ONCE,
        ));
    }
}

适用场景

  • 游戏背景音乐:使用 PlaybackSettings::LOOP 循环播放,并通过 AudioSink 实时调节音量或暂停。
  • UI 音效:使用 PlaybackSettings::DESPAWN 让一次性音效播放后自动从世界移除。
  • 位置音效:为脚步等声音设置 with_spatial(true) 和 Transform,并用 SpatialAudioSink 控制。
  • 需要重播的非循环音效:在 sink 清空后移除并重新插入音频组件。

限制

  • 对 PlaybackSettings 的修改不会影响已经在播放的音频;实时控制必须使用 AudioSink。
  • 非循环音频播放结束且 sink 被清空后,AudioPlayer 不能复用,必须移除组件后重新添加。
  • 本技能只使用 Bevy 官方文档中记录的 API,不涉及第三方音频 crate,也不包含音量曲线或混音器节点。
  • 不要在文档 URL 中固定 /0.20.0/;链接保持 latest,0.20 目标仅在正文中说明一次。
  • 不要从两个无序系统中可变查询同一组件;除非用 .chain() 排序,否则调度会并行运行系统。
  • 本技能不涉及物理、导航、网络或 XR crate。

参考

官方文档:

  • Assets:官方资源目录。
  • Examples:latest 分支上的示例树。
  • Audio examples:播放、空间和控制的示例。
  • ECS:Component、系统、Query、Startup、Update 和 .chain()。

相关技能: