GFAudioUtility¶

路径：addons/gf/standard/utilities/audio/gf_audio_utility.gd
模块：Standard
继承：GFUtility
API：public
类别：运行时服务 (runtime_service)
首次版本：3.17.0

全局音频管理器。管理 BGM 和 SFX 的播放与音量。注册 GFObjectPoolUtility 时会复用 AudioStreamPlayer，未注册时使用普通播放器。支持通过 GFAssetUtility 异步加载音频资源。

成员概览¶

类型	名称	签名
信号	`bgm_finished`	`signal bgm_finished(history_key: String)`
枚举	`SFXOverflowPolicy`	`enum SFXOverflowPolicy`
常量	`BGM_BUS_NAME`	`const BGM_BUS_NAME: String = "BGM"`
常量	`SFX_BUS_NAME`	`const SFX_BUS_NAME: String = "SFX"`
常量	`SILENCE_VOLUME_DB`	`const SILENCE_VOLUME_DB: float = -80.0`
属性	`max_sfx_players`	`var max_sfx_players: int = 32`
属性	`sfx_overflow_policy`	`var sfx_overflow_policy: SFXOverflowPolicy = SFXOverflowPolicy.SKIP_NEW`
属性	`bgm_crossfade_seconds`	`var bgm_crossfade_seconds: float = 0.0`
属性	`max_bgm_history`	`var max_bgm_history: int = 16`
方法	`init`	`func init() -> void:`
方法	`dispose`	`func dispose() -> void:`
方法	`play_bgm`	`func play_bgm(path: String, crossfade_seconds: float = -1.0) -> void:`
方法	`play_bgm_with_options`	`func play_bgm_with_options(path: String, options: Dictionary = {}) -> void:`
方法	`play_bgm_clip`	`func play_bgm_clip(clip: GFAudioClip, crossfade_seconds: float = -1.0) -> void:`
方法	`play_bgm_from_bank`	`func play_bgm_from_bank(bank: GFAudioBank, clip_id: StringName, crossfade_seconds: float = -1.0) -> void:`
方法	`play_bgm_event`	`func play_bgm_event( event_id: StringName, bank_id: StringName = &"", crossfade_seconds: float = -1.0 ) -> void:`
方法	`stop_bgm`	`func stop_bgm(fade_seconds: float = 0.0) -> void:`
方法	`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:`
方法	`get_bgm_history`	`func get_bgm_history() -> PackedStringArray:`
方法	`get_current_bgm_key`	`func get_current_bgm_key() -> String:`
方法	`clear_bgm_history`	`func clear_bgm_history() -> void:`
方法	`register_audio_bank`	`func register_audio_bank(bank_id: StringName, bank: GFAudioBank) -> void:`
方法	`unregister_audio_bank`	`func unregister_audio_bank(bank_id: StringName) -> void:`
方法	`clear_audio_banks`	`func clear_audio_banks() -> void:`
方法	`mount_audio_bank`	`func mount_audio_bank( bank_id: StringName, bank: GFAudioBank, restore_previous_bank: bool = true ) -> int:`
方法	`unmount_audio_bank`	`func unmount_audio_bank(bank_id: StringName, mount_token: int) -> bool:`
方法	`get_audio_bank`	`func get_audio_bank(bank_id: StringName) -> GFAudioBank:`
方法	`set_audio_backend`	`func set_audio_backend(backend: GFAudioBackend) -> void:`
方法	`get_audio_backend`	`func get_audio_backend() -> GFAudioBackend:`
方法	`clear_audio_backend`	`func clear_audio_backend(dispose_backend: bool = true) -> void:`
方法	`post_audio_event`	`func post_audio_event(event: GFAudioEvent, options: Dictionary = {}) -> GFAudioEmitterHandle:`
方法	`set_audio_parameter`	`func set_audio_parameter(parameter: GFAudioParameter) -> bool:`
方法	`set_audio_state`	`func set_audio_state(state: GFAudioState) -> bool:`
方法	`set_audio_switch`	`func set_audio_switch(audio_switch: GFAudioSwitch) -> bool:`
方法	`play_ambient`	`func play_ambient(path: String, channel: StringName = &"default", fade_seconds: float = 0.0) -> void:`
方法	`play_ambient_clip`	`func play_ambient_clip( clip: GFAudioClip, channel: StringName = &"default", fade_seconds: float = 0.0 ) -> void:`
方法	`play_ambient_from_bank`	`func play_ambient_from_bank( bank: GFAudioBank, clip_id: StringName, channel: StringName = &"default", fade_seconds: float = 0.0 ) -> void:`
方法	`play_ambient_event`	`func play_ambient_event( event_id: StringName, channel: StringName = &"default", bank_id: StringName = &"", fade_seconds: float = 0.0 ) -> void:`
方法	`stop_ambient`	`func stop_ambient(channel: StringName = &"default", fade_seconds: float = 0.0) -> void:`
方法	`stop_all_ambient`	`func stop_all_ambient(fade_seconds: float = 0.0) -> void:`
方法	`is_ambient_playing`	`func is_ambient_playing(channel: StringName = &"default") -> bool:`
方法	`stop_all_sfx`	`func stop_all_sfx(fade_seconds: float = 0.0) -> void:`
方法	`play_sfx`	`func play_sfx(path: String) -> void:`
方法	`play_sfx_handle`	`func play_sfx_handle(path: String) -> GFAudioEmitterHandle:`
方法	`play_sfx_clip`	`func play_sfx_clip(clip: GFAudioClip) -> void:`
方法	`play_sfx_clip_handle`	`func play_sfx_clip_handle(clip: GFAudioClip) -> GFAudioEmitterHandle:`
方法	`play_sfx_from_bank`	`func play_sfx_from_bank(bank: GFAudioBank, clip_id: StringName) -> void:`
方法	`play_sfx_from_bank_handle`	`func play_sfx_from_bank_handle(bank: GFAudioBank, clip_id: StringName) -> GFAudioEmitterHandle:`
方法	`play_sfx_event`	`func play_sfx_event(event_id: StringName, bank_id: StringName = &"") -> void:`
方法	`play_sfx_event_handle`	`func play_sfx_event_handle(event_id: StringName, bank_id: StringName = &"") -> GFAudioEmitterHandle:`
方法	`play_sfx_event_2d`	`func play_sfx_event_2d( event_id: StringName, source: Node2D, bank_id: StringName = &"", follow_source: bool = false ) -> AudioStreamPlayer2D:`
方法	`play_sfx_event_2d_handle`	`func play_sfx_event_2d_handle( event_id: StringName, source: Node2D, bank_id: StringName = &"", follow_source: bool = false ) -> GFAudioEmitterHandle:`
方法	`play_sfx_event_3d`	`func play_sfx_event_3d( event_id: StringName, source: Node3D, bank_id: StringName = &"", follow_source: bool = false ) -> AudioStreamPlayer3D:`
方法	`play_sfx_event_3d_handle`	`func play_sfx_event_3d_handle( event_id: StringName, source: Node3D, bank_id: StringName = &"", follow_source: bool = false ) -> GFAudioEmitterHandle:`
方法	`play_sfx_clip_2d`	`func play_sfx_clip_2d( clip: GFAudioClip, source: Node2D, follow_source: bool = false ) -> AudioStreamPlayer2D:`
方法	`play_sfx_clip_2d_handle`	`func play_sfx_clip_2d_handle( clip: GFAudioClip, source: Node2D, follow_source: bool = false ) -> GFAudioEmitterHandle:`
方法	`play_sfx_clip_3d`	`func play_sfx_clip_3d( clip: GFAudioClip, source: Node3D, follow_source: bool = false ) -> AudioStreamPlayer3D:`
方法	`play_sfx_clip_3d_handle`	`func play_sfx_clip_3d_handle( clip: GFAudioClip, source: Node3D, follow_source: bool = false ) -> GFAudioEmitterHandle:`
方法	`get_ambient_handle`	`func get_ambient_handle(channel: StringName = &"default") -> GFAudioEmitterHandle:`
方法	`set_bus_volume_db`	`func set_bus_volume_db(bus_name: String, volume_db: float, transition_seconds: float = 0.0) -> bool:`
方法	`get_bus_volume_db`	`func get_bus_volume_db(bus_name: String) -> float:`
方法	`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:`
方法	`capture_mix_snapshot`	`func capture_mix_snapshot(bus_names: PackedStringArray = PackedStringArray()) -> Dictionary:`
方法	`apply_mix_snapshot`	`func apply_mix_snapshot(snapshot: Dictionary, transition_seconds: float = 0.0) -> Dictionary:`
方法	`duck_bus`	`func duck_bus( bus_name: String = BGM_BUS_NAME, amount: float = 0.5, transition_seconds: float = 0.25, duck_id: StringName = &"default" ) -> bool:`
方法	`restore_ducked_bus`	`func restore_ducked_bus( bus_name: String = BGM_BUS_NAME, transition_seconds: float = 0.25, duck_id: StringName = &"default" ) -> bool:`
方法	`set_bus_volume`	`func set_bus_volume(bus_name: String, volume_linear: float) -> void:`
方法	`get_bus_volume`	`func get_bus_volume(bus_name: String) -> float:`
方法	`get_debug_snapshot`	`func get_debug_snapshot() -> Dictionary:`

信号¶

`bgm_finished`¶

API：public

signal bgm_finished(history_key: String)

当前 BGM 自然播放结束时发出。

参数：

名称	说明
`history_key`	播放请求记录的 BGM key。

枚举¶

`SFXOverflowPolicy`¶

API：public

enum SFXOverflowPolicy { ## 跳过新的 SFX 请求。 SKIP_NEW, ## 停止最早播放的 SFX，并播放新的请求。 STOP_OLDEST, }

SFX 超出并发上限时的处理策略。

常量¶

`BGM_BUS_NAME`¶

API：public

const BGM_BUS_NAME: String = "BGM"

默认 BGM 音频总线名。

`SFX_BUS_NAME`¶

API：public

const SFX_BUS_NAME: String = "SFX"

默认 SFX 音频总线名。

`SILENCE_VOLUME_DB`¶

API：public

const SILENCE_VOLUME_DB: float = -80.0

GF 默认视为静音下限的 dB 值。

属性¶

`max_sfx_players`¶

API：public

var max_sfx_players: int = 32

同时播放的 SFX 数量上限；小于等于 0 表示不限制。

`sfx_overflow_policy`¶

API：public

var sfx_overflow_policy: SFXOverflowPolicy = SFXOverflowPolicy.SKIP_NEW

SFX 超出并发上限时采用的处理策略。

`bgm_crossfade_seconds`¶

API：public

var bgm_crossfade_seconds: float = 0.0

默认 BGM 淡入淡出秒数。单次播放传入负数时使用该值。

`max_bgm_history`¶

API：public

var max_bgm_history: int = 16

BGM 历史记录最大数量。

方法¶

`init`¶

API：public

func init() -> void:

初始化音频播放器、运行时状态和默认播放根节点。

`dispose`¶

API：public

func dispose() -> void:

释放播放器、后端、环境音和 SFX 运行时状态。

`play_bgm`¶

API：public

func play_bgm(path: String, crossfade_seconds: float = -1.0) -> void:

播放 BGM（背景音乐）

参数：

名称	说明
`path`	音频资源的路径
`crossfade_seconds`	淡入淡出秒数；小于 0 时使用默认值。

`play_bgm_with_options`¶

API：public

func play_bgm_with_options(path: String, options: Dictionary = {}) -> void:

使用选项播放 BGM。

参数：

名称	说明
`path`	音频资源路径或后端事件路径。
`options`	支持 crossfade_seconds、history_key、loop、bus_name、volume_db 和 pitch_scale。

结构：

options: Dictionary，可包含 crossfade_seconds、history_key、loop、bus_name、volume_db 和 pitch_scale 字段。

`play_bgm_clip`¶

API：public

func play_bgm_clip(clip: GFAudioClip, crossfade_seconds: float = -1.0) -> void:

播放资源化 BGM 配置。

参数：

名称	说明
`clip`	音频片段配置。
`crossfade_seconds`	淡入淡出秒数；小于 0 时使用默认值。

`play_bgm_from_bank`¶

API：public

func play_bgm_from_bank(bank: GFAudioBank, clip_id: StringName, crossfade_seconds: float = -1.0) -> void:

从音频集合播放 BGM。

参数：

名称	说明
`bank`	音频集合。
`clip_id`	片段标识。
`crossfade_seconds`	淡入淡出秒数；小于 0 时使用默认值。

`play_bgm_event`¶

API：public

func play_bgm_event( event_id: StringName, bank_id: StringName = &"", crossfade_seconds: float = -1.0 ) -> void:

按事件 ID 播放注册音频集合中的 BGM。

参数：

名称	说明
`event_id`	音频事件标识。
`bank_id`	音频集合标识；为空时搜索全部注册集合。
`crossfade_seconds`	淡入淡出秒数；小于 0 时使用默认值。

`stop_bgm`¶

API：public

func stop_bgm(fade_seconds: float = 0.0) -> void:

停止当前 BGM。

参数：

名称	说明
`fade_seconds`	淡出秒数。

`pause_bgm`¶

API：public

func pause_bgm(fade_seconds: float = 0.0) -> bool:

暂停当前 BGM。

参数：

名称	说明
`fade_seconds`	淡出到暂停的秒数。

返回：成功暂停或后端已处理时返回 true。

`resume_bgm`¶

API：public

func resume_bgm(from_position: float = -1.0, fade_seconds: float = 0.0) -> bool:

恢复当前 BGM。

参数：

名称	说明
`from_position`	大于等于 0 时从指定秒数恢复。
`fade_seconds`	淡入秒数。

返回：成功恢复或后端已处理时返回 true。

`seek_bgm`¶

API：public

func seek_bgm(position_seconds: float) -> bool:

跳转当前 BGM 播放位置。

参数：

名称	说明
`position_seconds`	目标秒数。

返回：成功跳转或后端已处理时返回 true。

`get_bgm_playback_position`¶

API：public

func get_bgm_playback_position() -> float:

获取当前 BGM 播放位置。

返回：当前播放秒数；无可查询播放器时返回 0。

`is_bgm_paused`¶

API：public

func is_bgm_paused() -> bool:

查询当前 BGM 是否暂停。

返回：暂停时返回 true。

`get_bgm_history`¶

API：public

func get_bgm_history() -> PackedStringArray:

获取 BGM 播放历史。

返回：从旧到新的历史 key。

`get_current_bgm_key`¶

API：public

func get_current_bgm_key() -> String:

获取当前 BGM key。

返回：当前 BGM key；无播放时为空。

`clear_bgm_history`¶

API：public

func clear_bgm_history() -> void:

清空 BGM 历史。

`register_audio_bank`¶

API：public

func register_audio_bank(bank_id: StringName, bank: GFAudioBank) -> void:

注册一个全局音频集合，供事件式播放接口使用。

参数：

名称	说明
`bank_id`	音频集合标识。
`bank`	音频集合。

`unregister_audio_bank`¶

API：public

func unregister_audio_bank(bank_id: StringName) -> void:

移除一个全局音频集合。

参数：

名称	说明
`bank_id`	音频集合标识。

`clear_audio_banks`¶

API：public

func clear_audio_banks() -> void:

清空全局音频集合注册表。

`mount_audio_bank`¶

API：public

func mount_audio_bank( bank_id: StringName, bank: GFAudioBank, restore_previous_bank: bool = true ) -> int:

挂载一个临时音频集合，并返回用于卸载的挂载令牌。

参数：

名称	说明
`bank_id`	音频集合标识。
`bank`	音频集合。
`restore_previous_bank`	卸载顶层挂载时是否恢复同 ID 的上一层音频集合。

返回：挂载令牌；失败时返回 0。

`unmount_audio_bank`¶

API：public

func unmount_audio_bank(bank_id: StringName, mount_token: int) -> bool:

卸载由 mount_audio_bank() 创建的临时音频集合。

参数：

名称	说明
`bank_id`	音频集合标识。
`mount_token`	mount_audio_bank() 返回的挂载令牌。

返回：找到并卸载对应挂载时返回 true。

`get_audio_bank`¶

API：public

func get_audio_bank(bank_id: StringName) -> GFAudioBank:

获取全局音频集合。

参数：

名称	说明
`bank_id`	音频集合标识。

返回：音频集合；不存在时返回 null。

`set_audio_backend`¶

API：public

func set_audio_backend(backend: GFAudioBackend) -> void:

设置可插拔音频后端。传入 null 时恢复默认 Godot 播放路径。

参数：

名称	说明
`backend`	音频后端。

`get_audio_backend`¶

API：public

func get_audio_backend() -> GFAudioBackend:

获取当前音频后端。

返回：音频后端；未设置时返回 null。

`clear_audio_backend`¶

API：public

func clear_audio_backend(dispose_backend: bool = true) -> void:

清除当前音频后端。

参数：

名称	说明
`dispose_backend`	是否调用后端 dispose()。

`post_audio_event`¶

API：public

func post_audio_event(event: GFAudioEvent, options: Dictionary = {}) -> GFAudioEmitterHandle:

发布资源化音频事件。

参数：

名称	说明
`event`	音频事件资源。
`options`	请求选项。

返回：控制句柄；不需要或无法返回句柄时返回 null。

结构：

options: Dictionary，作为事件请求附加选项，会与 GFAudioEvent.to_request_options() 的结果合并。

`set_audio_parameter`¶

API：public

func set_audio_parameter(parameter: GFAudioParameter) -> bool:

写入音频参数。

参数：

名称	说明
`parameter`	参数请求。

返回：后端已处理返回 true。

`set_audio_state`¶

API：public

func set_audio_state(state: GFAudioState) -> bool:

写入音频状态。

参数：

名称	说明
`state`	状态请求。

返回：后端已处理返回 true。

`set_audio_switch`¶

API：public

func set_audio_switch(audio_switch: GFAudioSwitch) -> bool:

写入音频开关。

参数：

名称	说明
`audio_switch`	开关请求。

返回：后端已处理返回 true。

`play_ambient`¶

API：public

func play_ambient(path: String, channel: StringName = &"default", fade_seconds: float = 0.0) -> void:

播放环境音。

参数：

名称	说明
`path`	音频资源路径。
`channel`	环境音通道。
`fade_seconds`	淡入秒数。

`play_ambient_clip`¶

API：public

func play_ambient_clip( clip: GFAudioClip, channel: StringName = &"default", fade_seconds: float = 0.0 ) -> void:

播放资源化环境音配置。

参数：

名称	说明
`clip`	音频片段配置。
`channel`	环境音通道。
`fade_seconds`	淡入秒数。

`play_ambient_from_bank`¶

API：public

func play_ambient_from_bank( bank: GFAudioBank, clip_id: StringName, channel: StringName = &"default", fade_seconds: float = 0.0 ) -> void:

从音频集合播放环境音。

参数：

名称	说明
`bank`	音频集合。
`clip_id`	片段标识。
`channel`	环境音通道。
`fade_seconds`	淡入秒数。

`play_ambient_event`¶

API：public

func play_ambient_event( event_id: StringName, channel: StringName = &"default", bank_id: StringName = &"", fade_seconds: float = 0.0 ) -> void:

按事件 ID 播放注册音频集合中的环境音。

参数：

名称	说明
`event_id`	音频事件标识。
`channel`	环境音通道。
`bank_id`	音频集合标识；为空时搜索全部注册集合。
`fade_seconds`	淡入秒数。

`stop_ambient`¶

API：public

func stop_ambient(channel: StringName = &"default", fade_seconds: float = 0.0) -> void:

停止指定环境音通道。

参数：

名称	说明
`channel`	环境音通道。
`fade_seconds`	淡出秒数。

`stop_all_ambient`¶

API：public

func stop_all_ambient(fade_seconds: float = 0.0) -> void:

停止所有环境音通道。

参数：

名称	说明
`fade_seconds`	淡出秒数。

`is_ambient_playing`¶

API：public

func is_ambient_playing(channel: StringName = &"default") -> bool:

检查环境音通道是否正在播放。

参数：

名称	说明
`channel`	环境音通道。

返回：正在播放时返回 true。

`stop_all_sfx`¶

API：public

func stop_all_sfx(fade_seconds: float = 0.0) -> void:

停止全部普通 SFX 与空间 SFX。

参数：

名称	说明
`fade_seconds`	淡出秒数。

`play_sfx`¶

API：public

func play_sfx(path: String) -> void:

播放 SFX（音效），自动从池中分配播放器

参数：

名称	说明
`path`	音频资源的路径

`play_sfx_handle`¶

API：public

func play_sfx_handle(path: String) -> GFAudioEmitterHandle:

播放 SFX 并返回控制句柄。

参数：

名称	说明
`path`	音频资源的路径。

返回：控制句柄；路径为空时返回 null。

`play_sfx_clip`¶

API：public

func play_sfx_clip(clip: GFAudioClip) -> void:

播放资源化 SFX 配置。

参数：

名称	说明
`clip`	音频片段配置。

`play_sfx_clip_handle`¶

API：public

func play_sfx_clip_handle(clip: GFAudioClip) -> GFAudioEmitterHandle:

播放资源化 SFX 配置并返回控制句柄。

参数：

名称	说明
`clip`	音频片段配置。

返回：控制句柄；片段无播放来源时返回 null。

`play_sfx_from_bank`¶

API：public

func play_sfx_from_bank(bank: GFAudioBank, clip_id: StringName) -> void:

从音频集合播放 SFX。

参数：

名称	说明
`bank`	音频集合。
`clip_id`	片段标识。

`play_sfx_from_bank_handle`¶

API：public

func play_sfx_from_bank_handle(bank: GFAudioBank, clip_id: StringName) -> GFAudioEmitterHandle:

从音频集合播放 SFX 并返回控制句柄。

参数：

名称	说明
`bank`	音频集合。
`clip_id`	片段标识。

返回：控制句柄；无法播放时返回 null。

`play_sfx_event`¶

API：public

func play_sfx_event(event_id: StringName, bank_id: StringName = &"") -> void:

按事件 ID 播放注册音频集合中的 SFX。

参数：

名称	说明
`event_id`	音频事件标识。
`bank_id`	音频集合标识；为空时搜索全部注册集合。

`play_sfx_event_handle`¶

API：public

func play_sfx_event_handle(event_id: StringName, bank_id: StringName = &"") -> GFAudioEmitterHandle:

按事件 ID 播放注册音频集合中的 SFX 并返回控制句柄。

参数：

名称	说明
`event_id`	音频事件标识。
`bank_id`	音频集合标识；为空时搜索全部注册集合。

返回：控制句柄；无法播放时返回 null。

`play_sfx_event_2d`¶

API：public

func play_sfx_event_2d( event_id: StringName, source: Node2D, bank_id: StringName = &"", follow_source: bool = false ) -> AudioStreamPlayer2D:

按事件 ID 在 2D 节点位置播放注册音频集合中的 SFX。

参数：

名称	说明
`event_id`	音频事件标识。
`source`	2D 声源节点。
`bank_id`	音频集合标识；为空时搜索全部注册集合。
`follow_source`	为 true 时播放器会作为 source 子节点跟随移动。

返回：创建的播放器；无法播放时返回 null。

`play_sfx_event_2d_handle`¶

API：public

func play_sfx_event_2d_handle( event_id: StringName, source: Node2D, bank_id: StringName = &"", follow_source: bool = false ) -> GFAudioEmitterHandle:

按事件 ID 在 2D 节点位置播放注册音频集合中的 SFX，并返回控制句柄。

参数：

名称	说明
`event_id`	音频事件标识。
`source`	2D 声源节点。
`bank_id`	音频集合标识；为空时搜索全部注册集合。
`follow_source`	为 true 时播放器会作为 source 子节点跟随移动。

返回：控制句柄；无法播放时返回 null。

`play_sfx_event_3d`¶

API：public

func play_sfx_event_3d( event_id: StringName, source: Node3D, bank_id: StringName = &"", follow_source: bool = false ) -> AudioStreamPlayer3D:

按事件 ID 在 3D 节点位置播放注册音频集合中的 SFX。

参数：

名称	说明
`event_id`	音频事件标识。
`source`	3D 声源节点。
`bank_id`	音频集合标识；为空时搜索全部注册集合。
`follow_source`	为 true 时播放器会作为 source 子节点跟随移动。

返回：创建的播放器；无法播放时返回 null。

`play_sfx_event_3d_handle`¶

API：public

func play_sfx_event_3d_handle( event_id: StringName, source: Node3D, bank_id: StringName = &"", follow_source: bool = false ) -> GFAudioEmitterHandle:

按事件 ID 在 3D 节点位置播放注册音频集合中的 SFX，并返回控制句柄。

参数：

名称	说明
`event_id`	音频事件标识。
`source`	3D 声源节点。
`bank_id`	音频集合标识；为空时搜索全部注册集合。
`follow_source`	为 true 时播放器会作为 source 子节点跟随移动。

返回：控制句柄；无法播放时返回 null。

`play_sfx_clip_2d`¶

API：public

func play_sfx_clip_2d( clip: GFAudioClip, source: Node2D, follow_source: bool = false ) -> AudioStreamPlayer2D:

在 2D 节点位置播放资源化 SFX 配置。

参数：

名称	说明
`clip`	音频片段配置。
`source`	2D 声源节点。
`follow_source`	为 true 时播放器会作为 source 子节点跟随移动。

返回：创建的播放器；无法播放时返回 null。

`play_sfx_clip_2d_handle`¶

API：public

func play_sfx_clip_2d_handle( clip: GFAudioClip, source: Node2D, follow_source: bool = false ) -> GFAudioEmitterHandle:

在 2D 节点位置播放资源化 SFX 配置，并返回控制句柄。

参数：

名称	说明
`clip`	音频片段配置。
`source`	2D 声源节点。
`follow_source`	为 true 时播放器会作为 source 子节点跟随移动。

返回：控制句柄；无法播放时返回 null。

`play_sfx_clip_3d`¶

API：public

func play_sfx_clip_3d( clip: GFAudioClip, source: Node3D, follow_source: bool = false ) -> AudioStreamPlayer3D:

在 3D 节点位置播放资源化 SFX 配置。

参数：

名称	说明
`clip`	音频片段配置。
`source`	3D 声源节点。
`follow_source`	为 true 时播放器会作为 source 子节点跟随移动。

返回：创建的播放器；无法播放时返回 null。

`play_sfx_clip_3d_handle`¶

API：public

func play_sfx_clip_3d_handle( clip: GFAudioClip, source: Node3D, follow_source: bool = false ) -> GFAudioEmitterHandle:

在 3D 节点位置播放资源化 SFX 配置，并返回控制句柄。

参数：

名称	说明
`clip`	音频片段配置。
`source`	3D 声源节点。
`follow_source`	为 true 时播放器会作为 source 子节点跟随移动。

返回：控制句柄；无法播放时返回 null。

`get_ambient_handle`¶

API：public

func get_ambient_handle(channel: StringName = &"default") -> GFAudioEmitterHandle:

获取环境音通道的控制句柄。

参数：

名称	说明
`channel`	环境音通道。

返回：控制句柄；通道不存在时返回 null。

`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`	总线名称，如 "Master", "BGM", "SFX"。
`volume_db`	目标 dB 音量；小于等于 SILENCE_VOLUME_DB 时会静音该总线。
`transition_seconds`	平滑过渡秒数；小于等于 0 时立即应用。

返回：成功应用或已交给后端处理时返回 true。

`get_bus_volume_db`¶

API：public

func get_bus_volume_db(bus_name: String) -> float:

获取音频总线 dB 音量。

参数：

名称	说明
`bus_name`	总线名称。

返回：dB 音量；总线不存在时返回 SILENCE_VOLUME_DB。

`set_bus_mute`¶

API：public

func set_bus_mute(bus_name: String, muted: bool) -> bool:

设置音频总线静音状态。

参数：

名称	说明
`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`	效果索引、resource_name、类名或类名片段。
`property_name`	要写入的效果属性名。
`value`	目标属性值。
`transition_seconds`	平滑过渡秒数；小于等于 0 时立即应用。

返回：成功应用或已交给后端处理时返回 true。

结构：

effect_ref: int 表示效果索引；String/StringName 会匹配效果 resource_name、get_class() 或类名片段。
value: 目标属性值；数值属性可按 transition_seconds 平滑过渡，其他类型会立即应用。

`capture_mix_snapshot`¶

API：public

func capture_mix_snapshot(bus_names: PackedStringArray = PackedStringArray()) -> Dictionary:

捕获当前总线混音快照。

参数：

名称	说明
`bus_names`	要捕获的总线名；为空时捕获全部 Godot 总线。

返回：混音快照。

结构：

return: Dictionary，包含 buses 字典；每个总线条目包含 volume_db、volume_linear 和 muted。

`apply_mix_snapshot`¶

API：public

func apply_mix_snapshot(snapshot: Dictionary, transition_seconds: float = 0.0) -> Dictionary:

应用混音快照。

参数：

名称	说明
`snapshot`	混音快照。
`transition_seconds`	默认平滑过渡秒数；单个效果条目可覆盖。

返回：应用报告。

结构：

snapshot: Dictionary，可包含 buses 字典和 effects 数组；buses 条目支持 volume_db、volume_linear、muted，effects 条目支持 bus、effect、property、value、transition_seconds。
return: Dictionary，包含 ok、applied、failed 和 warnings 字段。

`duck_bus`¶

API：public

func duck_bus( bus_name: String = BGM_BUS_NAME, amount: float = 0.5, transition_seconds: float = 0.25, duck_id: StringName = &"default" ) -> bool:

按比例压低总线音量，并记住恢复基准。

参数：

名称	说明
`bus_name`	总线名称。
`amount`	压低强度，0.0 不变化，1.0 最多压低 18 dB。
`transition_seconds`	平滑过渡秒数。
`duck_id`	同一总线上的压低作用域标识。

返回：成功应用时返回 true。

`restore_ducked_bus`¶

API：public

func restore_ducked_bus( bus_name: String = BGM_BUS_NAME, transition_seconds: float = 0.25, duck_id: StringName = &"default" ) -> bool:

恢复被 duck_bus() 压低的总线。

参数：

名称	说明
`bus_name`	总线名称。
`transition_seconds`	平滑过渡秒数。
`duck_id`	同一总线上的压低作用域标识。

返回：找到恢复基准并开始恢复时返回 true。

`set_bus_volume`¶

API：public

func set_bus_volume(bus_name: String, volume_linear: float) -> void:

设置音频总线音量

参数：

名称	说明
`bus_name`	总线名称，如 "Master", "BGM", "SFX"
`volume_linear`	线性音量 (0.0 到 1.0)

`get_bus_volume`¶

API：public

func get_bus_volume(bus_name: String) -> float:

获取音频总线音量

参数：

名称	说明
`bus_name`	总线名称

返回：线性音量 (0.0 到 1.0)

`get_debug_snapshot`¶

API：public

func get_debug_snapshot() -> Dictionary:

获取音频工具调试快照。

返回：调试快照。

结构：

return: Dictionary，包含 backend、backend_snapshot、backend_capabilities、current_bgm_key、current_bgm_loop、bgm_paused、bgm_position、bgm_history、active_sfx_count、active_spatial_sfx_count、max_sfx_players、ambient_channels、audio_bank_count、ducked_bus_count 和 active_mix_tween_count 字段。

GFAudioUtility¶

成员概览¶

信号¶

bgm_finished¶

枚举¶

SFXOverflowPolicy¶

常量¶

BGM_BUS_NAME¶

SFX_BUS_NAME¶

SILENCE_VOLUME_DB¶

属性¶

max_sfx_players¶

sfx_overflow_policy¶

bgm_crossfade_seconds¶

max_bgm_history¶

方法¶

init¶

dispose¶

play_bgm¶

play_bgm_with_options¶

play_bgm_clip¶

play_bgm_from_bank¶

play_bgm_event¶

stop_bgm¶

pause_bgm¶

resume_bgm¶

seek_bgm¶

get_bgm_playback_position¶

is_bgm_paused¶

get_bgm_history¶

get_current_bgm_key¶

clear_bgm_history¶

register_audio_bank¶

unregister_audio_bank¶

clear_audio_banks¶

mount_audio_bank¶

unmount_audio_bank¶

get_audio_bank¶

set_audio_backend¶

get_audio_backend¶

clear_audio_backend¶

post_audio_event¶

set_audio_parameter¶

set_audio_state¶

set_audio_switch¶

play_ambient¶

play_ambient_clip¶

play_ambient_from_bank¶

play_ambient_event¶

stop_ambient¶

stop_all_ambient¶

is_ambient_playing¶

stop_all_sfx¶

play_sfx¶

play_sfx_handle¶

play_sfx_clip¶

play_sfx_clip_handle¶

play_sfx_from_bank¶

play_sfx_from_bank_handle¶

play_sfx_event¶

play_sfx_event_handle¶

play_sfx_event_2d¶

play_sfx_event_2d_handle¶

play_sfx_event_3d¶

play_sfx_event_3d_handle¶

play_sfx_clip_2d¶

play_sfx_clip_2d_handle¶

play_sfx_clip_3d¶

play_sfx_clip_3d_handle¶

get_ambient_handle¶

set_bus_volume_db¶

get_bus_volume_db¶

set_bus_mute¶

set_bus_effect_property¶

capture_mix_snapshot¶

apply_mix_snapshot¶

duck_bus¶

restore_ducked_bus¶

set_bus_volume¶

get_bus_volume¶

`bgm_finished`¶

`SFXOverflowPolicy`¶

`BGM_BUS_NAME`¶

`SFX_BUS_NAME`¶

`SILENCE_VOLUME_DB`¶

`max_sfx_players`¶

`sfx_overflow_policy`¶

`bgm_crossfade_seconds`¶

`max_bgm_history`¶

`init`¶

`dispose`¶

`play_bgm`¶

`play_bgm_with_options`¶

`play_bgm_clip`¶

`play_bgm_from_bank`¶

`play_bgm_event`¶

`stop_bgm`¶

`pause_bgm`¶

`resume_bgm`¶

`seek_bgm`¶

`get_bgm_playback_position`¶

`is_bgm_paused`¶

`get_bgm_history`¶

`get_current_bgm_key`¶

`clear_bgm_history`¶

`register_audio_bank`¶

`unregister_audio_bank`¶

`clear_audio_banks`¶

`mount_audio_bank`¶

`unmount_audio_bank`¶

`get_audio_bank`¶

`set_audio_backend`¶

`get_audio_backend`¶

`clear_audio_backend`¶

`post_audio_event`¶

`set_audio_parameter`¶

`set_audio_state`¶

`set_audio_switch`¶

`play_ambient`¶

`play_ambient_clip`¶

`play_ambient_from_bank`¶

`play_ambient_event`¶

`stop_ambient`¶

`stop_all_ambient`¶

`is_ambient_playing`¶

`stop_all_sfx`¶

`play_sfx`¶

`play_sfx_handle`¶

`play_sfx_clip`¶

`play_sfx_clip_handle`¶

`play_sfx_from_bank`¶

`play_sfx_from_bank_handle`¶

`play_sfx_event`¶

`play_sfx_event_handle`¶

`play_sfx_event_2d`¶

`play_sfx_event_2d_handle`¶

`play_sfx_event_3d`¶

`play_sfx_event_3d_handle`¶

`play_sfx_clip_2d`¶

`play_sfx_clip_2d_handle`¶

`play_sfx_clip_3d`¶

`play_sfx_clip_3d_handle`¶

`get_ambient_handle`¶

`set_bus_volume_db`¶

`get_bus_volume_db`¶

`set_bus_mute`¶

`set_bus_effect_property`¶

`capture_mix_snapshot`¶

`apply_mix_snapshot`¶

`duck_bus`¶

`restore_ducked_bus`¶

`set_bus_volume`¶

`get_bus_volume`¶

`get_debug_snapshot`¶