用途
本技能用于在 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()。
相关技能:
- 前置:bevy-master、bevy-asset-scenes。
- 补充:bevy-input-handling。
- 下游/消费者:暂无。
- 主技能:bevy-master。