GFAudioBackend¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/utilities/audio/gf_audio_backend.gd - 模块：
Standard - 继承：
RefCounted - API：
public - 类别：协议与扩展点 (
protocol) - 首次版本：
3.17.0
GFAudioUtility 的可插拔音频后端协议。 默认实现不处理任何请求。项目或扩展可继承它，把部分音频事件转交给 外部中间件、平台接口或自定义混音系统；未声明可处理的请求会回退到 Godot 默认播放器。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 属性 | capabilities |
var capabilities: GFAudioBackendCapability = GFAudioBackendCapability.new() |
| 方法 | dispose |
func dispose() -> void: |
| 方法 | get_host |
func get_host() -> Object: |
| 方法 | get_capabilities |
func get_capabilities() -> GFAudioBackendCapability: |
| 方法 | has_capability |
func has_capability(capability_id: StringName) -> bool: |
| 方法 | can_handle_path |
func can_handle_path(_path: String, _channel: StringName, _context: Dictionary = {}) -> bool: |
| 方法 | can_handle_clip |
func can_handle_clip(_clip: GFAudioClip, _channel: StringName, _context: Dictionary = {}) -> bool: |
| 方法 | play_bgm_path |
func play_bgm_path(_path: String, _options: Dictionary = {}) -> bool: |
| 方法 | play_bgm_clip |
func play_bgm_clip(_clip: GFAudioClip, _options: Dictionary = {}) -> bool: |
| 方法 | stop_bgm |
func stop_bgm(_fade_seconds: float = 0.0) -> bool: |
| 方法 | pause_bgm |
func pause_bgm(_fade_seconds: float = 0.0) -> bool: |
| 方法 | resume_bgm |
func resume_bgm(_from_position: float = -1.0, _fade_seconds: float = 0.0) -> bool: |
| 方法 | seek_bgm |
func seek_bgm(_position_seconds: float) -> bool: |
| 方法 | get_bgm_playback_position |
func get_bgm_playback_position() -> float: |
| 方法 | is_bgm_paused |
func is_bgm_paused() -> bool: |
| 方法 | play_ambient_path |
func play_ambient_path(_path: String, _channel: StringName = &"default", _options: Dictionary = {}) -> bool: |
| 方法 | play_ambient_clip |
func play_ambient_clip(_clip: GFAudioClip, _channel: StringName = &"default", _options: Dictionary = {}) -> bool: |
| 方法 | stop_ambient |
func stop_ambient(_channel: StringName = &"default", _fade_seconds: float = 0.0) -> bool: |
| 方法 | stop_all_ambient |
func stop_all_ambient(_fade_seconds: float = 0.0) -> bool: |
| 方法 | is_ambient_playing |
func is_ambient_playing(_channel: StringName = &"default") -> bool: |
| 方法 | play_sfx_path |
func play_sfx_path(_path: String, _options: Dictionary = {}) -> GFAudioEmitterHandle: |
| 方法 | play_sfx_clip |
func play_sfx_clip(_clip: GFAudioClip, _options: Dictionary = {}) -> GFAudioEmitterHandle: |
| 方法 | stop_all_sfx |
func stop_all_sfx(_fade_seconds: float = 0.0) -> bool: |
| 方法 | play_spatial_sfx_clip |
func play_spatial_sfx_clip( _clip: GFAudioClip, _source: Node, _follow_source: bool = false, _options: Dictionary = {} ) -> GFAudioEmitterHandle: |
| 方法 | can_handle_event |
func can_handle_event(_event: GFAudioEvent, _options: Dictionary = {}) -> bool: |
| 方法 | post_event |
func post_event(_event: GFAudioEvent, _options: Dictionary = {}) -> GFAudioEmitterHandle: |
| 方法 | set_parameter |
func set_parameter(_parameter: GFAudioParameter) -> bool: |
| 方法 | set_state |
func set_state(_state: GFAudioState) -> bool: |
| 方法 | set_switch |
func set_switch(_switch: GFAudioSwitch) -> bool: |
| 方法 | set_bus_volume |
func set_bus_volume(_bus_name: String, _volume_linear: float) -> bool: |
| 方法 | set_bus_volume_db |
func set_bus_volume_db(_bus_name: String, _volume_db: float, _transition_seconds: float = 0.0) -> bool: |
| 方法 | set_bus_mute |
func set_bus_mute(_bus_name: String, _muted: bool) -> bool: |
| 方法 | set_bus_effect_property |
func set_bus_effect_property( _bus_name: String, _effect_ref: Variant, _property_name: StringName, _value: Variant, _transition_seconds: float = 0.0 ) -> bool: |
| 方法 | apply_mix_snapshot |
func apply_mix_snapshot(_snapshot: Dictionary, _transition_seconds: float = 0.0) -> bool: |
| 方法 | get_bus_volume |
func get_bus_volume(_bus_name: String) -> float: |
| 方法 | get_debug_snapshot |
func get_debug_snapshot() -> Dictionary: |
属性¶
capabilities¶
- API：
public
后端能力声明。
方法¶
dispose¶
- API：
public
释放后端状态。
get_host¶
- API：
public
获取宿主音频工具。
返回：宿主对象；不存在时返回 null。
get_capabilities¶
- API：
public
获取后端能力声明副本。
返回：后端能力声明。
has_capability¶
- API：
public
检查后端是否声明了指定能力。
参数：
| 名称 | 说明 |
|---|---|
capability_id |
能力标识。 |
返回：支持返回 true。
can_handle_path¶
- API：
public
判断后端是否可处理指定资源路径。
参数：
| 名称 | 说明 |
|---|---|
_path |
音频资源路径或后端事件路径。 |
_channel |
通道标识，如 bgm、sfx、ambient。 |
_context |
请求上下文。 |
返回：可处理时返回 true。
结构：
_context: 请求上下文 Dictionary；键和值由 GFAudioUtility 或具体后端约定。
can_handle_clip¶
- API：
public
判断后端是否可处理指定音频片段。
参数：
| 名称 | 说明 |
|---|---|
_clip |
音频片段配置。 |
_channel |
通道标识，如 bgm、sfx、ambient。 |
_context |
请求上下文。 |
返回：可处理时返回 true。
结构：
_context: 请求上下文 Dictionary；键和值由 GFAudioUtility 或具体后端约定。
play_bgm_path¶
- API：
public
播放 BGM 路径。
参数：
| 名称 | 说明 |
|---|---|
_path |
音频资源路径或后端事件路径。 |
_options |
请求选项。 |
返回：已处理返回 true。
结构：
_options: 请求选项 Dictionary；常见字段包含 volume_db、pitch_scale、fade_seconds、loop 和 metadata。
play_bgm_clip¶
- API：
public
播放 BGM Clip。
参数：
| 名称 | 说明 |
|---|---|
_clip |
音频片段配置。 |
_options |
请求选项。 |
返回：已处理返回 true。
结构：
_options: 请求选项 Dictionary；常见字段包含 volume_db、pitch_scale、fade_seconds、loop 和 metadata。
stop_bgm¶
- API：
public
停止 BGM。
参数：
| 名称 | 说明 |
|---|---|
_fade_seconds |
淡出秒数。 |
返回：已处理返回 true。
pause_bgm¶
- API：
public
暂停 BGM。
参数：
| 名称 | 说明 |
|---|---|
_fade_seconds |
淡出到暂停的秒数。 |
返回：已处理返回 true。
resume_bgm¶
- API：
public
恢复 BGM。
参数：
| 名称 | 说明 |
|---|---|
_from_position |
大于等于 0 时从指定秒数恢复。 |
_fade_seconds |
淡入秒数。 |
返回：已处理返回 true。
seek_bgm¶
- API：
public
跳转当前 BGM 播放位置。
参数：
| 名称 | 说明 |
|---|---|
_position_seconds |
目标秒数。 |
返回：已处理返回 true。
get_bgm_playback_position¶
- API：
public
获取当前 BGM 播放位置。
返回：播放秒数；负数表示后端不处理该查询。
is_bgm_paused¶
- API：
public
查询 BGM 是否暂停。
返回：已暂停返回 true。
play_ambient_path¶
- API：
public
func play_ambient_path(_path: String, _channel: StringName = &"default", _options: Dictionary = {}) -> bool:
播放环境音路径。
参数：
| 名称 | 说明 |
|---|---|
_path |
音频资源路径或后端事件路径。 |
_channel |
环境音通道。 |
_options |
请求选项。 |
返回：已处理返回 true。
结构：
_options: 请求选项 Dictionary；常见字段包含 volume_db、pitch_scale、fade_seconds 和 metadata。
play_ambient_clip¶
- API：
public
func play_ambient_clip(_clip: GFAudioClip, _channel: StringName = &"default", _options: Dictionary = {}) -> bool:
播放环境音 Clip。
参数：
| 名称 | 说明 |
|---|---|
_clip |
音频片段配置。 |
_channel |
环境音通道。 |
_options |
请求选项。 |
返回：已处理返回 true。
结构：
_options: 请求选项 Dictionary；常见字段包含 volume_db、pitch_scale、fade_seconds 和 metadata。
stop_ambient¶
- API：
public
停止环境音通道。
参数：
| 名称 | 说明 |
|---|---|
_channel |
环境音通道。 |
_fade_seconds |
淡出秒数。 |
返回：已处理返回 true。
stop_all_ambient¶
- API：
public
停止全部环境音。
参数：
| 名称 | 说明 |
|---|---|
_fade_seconds |
淡出秒数。 |
返回：已处理返回 true。
is_ambient_playing¶
- API：
public
查询环境音通道是否播放中。
参数：
| 名称 | 说明 |
|---|---|
_channel |
环境音通道。 |
返回：后端通道正在播放时返回 true。
play_sfx_path¶
- API：
public
播放 SFX 路径。
参数：
| 名称 | 说明 |
|---|---|
_path |
音频资源路径或后端事件路径。 |
_options |
请求选项。 |
返回：控制句柄；未处理返回 null。
结构：
_options: 请求选项 Dictionary；常见字段包含 volume_db、pitch_scale、owner、channel 和 metadata。
play_sfx_clip¶
- API：
public
播放 SFX Clip。
参数：
| 名称 | 说明 |
|---|---|
_clip |
音频片段配置。 |
_options |
请求选项。 |
返回：控制句柄；未处理返回 null。
结构：
_options: 请求选项 Dictionary；常见字段包含 volume_db、pitch_scale、owner、channel 和 metadata。
stop_all_sfx¶
- API：
public
停止全部 SFX。
参数：
| 名称 | 说明 |
|---|---|
_fade_seconds |
淡出秒数。 |
返回：已处理返回 true。
play_spatial_sfx_clip¶
- API：
public
func play_spatial_sfx_clip( _clip: GFAudioClip, _source: Node, _follow_source: bool = false, _options: Dictionary = {} ) -> GFAudioEmitterHandle:
播放空间 SFX Clip。
参数：
| 名称 | 说明 |
|---|---|
_clip |
音频片段配置。 |
_source |
2D 或 3D 声源节点。 |
_follow_source |
是否跟随声源。 |
_options |
请求选项。 |
返回：控制句柄；未处理返回 null。
结构：
_options: 请求选项 Dictionary；常见字段包含 volume_db、pitch_scale、owner、channel、follow_source、spatial_settings 和 metadata。
can_handle_event¶
- API：
public
判断后端是否可处理资源化音频事件。
参数：
| 名称 | 说明 |
|---|---|
_event |
音频事件。 |
_options |
请求选项。 |
返回：可处理时返回 true。
结构：
_options: 请求选项 Dictionary；键和值由 GFAudioUtility 或具体后端约定。
post_event¶
- API：
public
发布资源化音频事件。
参数：
| 名称 | 说明 |
|---|---|
_event |
音频事件。 |
_options |
请求选项。 |
返回：控制句柄；未处理返回 null。
结构：
_options: 请求选项 Dictionary；键和值由 GFAudioUtility 或具体后端约定。
set_parameter¶
- API：
public
设置音频参数。
参数：
| 名称 | 说明 |
|---|---|
_parameter |
参数请求。 |
返回：已处理返回 true。
set_state¶
- API：
public
设置音频状态。
参数：
| 名称 | 说明 |
|---|---|
_state |
状态请求。 |
返回：已处理返回 true。
set_switch¶
- API：
public
设置音频开关。
参数：
| 名称 | 说明 |
|---|---|
_switch |
开关请求。 |
返回：已处理返回 true。
set_bus_volume¶
- API：
public
设置总线音量。
参数：
| 名称 | 说明 |
|---|---|
_bus_name |
总线名或后端通道名。 |
_volume_linear |
线性音量。 |
返回：已处理返回 true。
set_bus_volume_db¶
- API：
public
func set_bus_volume_db(_bus_name: String, _volume_db: float, _transition_seconds: float = 0.0) -> bool:
设置总线 dB 音量。
参数：
| 名称 | 说明 |
|---|---|
_bus_name |
总线名或后端通道名。 |
_volume_db |
dB 音量。 |
_transition_seconds |
平滑过渡秒数。 |
返回：已处理返回 true。
set_bus_mute¶
- API：
public
设置总线静音状态。
参数：
| 名称 | 说明 |
|---|---|
_bus_name |
总线名或后端通道名。 |
_muted |
是否静音。 |
返回：已处理返回 true。
set_bus_effect_property¶
- API：
public
func set_bus_effect_property( _bus_name: String, _effect_ref: Variant, _property_name: StringName, _value: Variant, _transition_seconds: float = 0.0 ) -> bool:
设置总线效果属性。
参数：
| 名称 | 说明 |
|---|---|
_bus_name |
总线名或后端通道名。 |
_effect_ref |
效果索引、名称或后端自定义效果引用。 |
_property_name |
效果属性名。 |
_value |
属性值。 |
_transition_seconds |
平滑过渡秒数。 |
返回：已处理返回 true。
结构：
_effect_ref: int/String/StringName 或后端自定义引用。_value: 属性值 Variant；键和值由后端或 GFAudioUtility 约定。
apply_mix_snapshot¶
- API：
public
应用混音快照。
参数：
| 名称 | 说明 |
|---|---|
_snapshot |
混音快照。 |
_transition_seconds |
默认平滑过渡秒数。 |
返回：已处理返回 true。
结构：
_snapshot: Dictionary，可包含 buses 和 effects 字段，或后端自定义字段。
get_bus_volume¶
- API：
public
获取总线音量。返回负数表示未处理。
参数：
| 名称 | 说明 |
|---|---|
_bus_name |
总线名或后端通道名。 |
返回：线性音量；负数表示后端不处理该总线。
get_debug_snapshot¶
- API：
public
获取后端调试快照。
返回：调试数据。
结构：
return: 调试快照 Dictionary；键和值由具体后端约定。