GFAudioEmitterHandle¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/utilities/audio/gf_audio_emitter_handle.gd - 模块：
Standard - 继承：
RefCounted - API：
public - 类别：运行时句柄 (
runtime_handle) - 首次版本：
3.17.0
一次音频播放的轻量控制句柄。 句柄只包装底层 AudioStreamPlayer 节点的通用生命周期和播放属性， 不规定音频事件、混音策略或业务含义。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 信号 | player_attached |
signal player_attached(handle: GFAudioEmitterHandle, player: Node) |
| 信号 | stopped |
signal stopped(handle: GFAudioEmitterHandle) |
| 属性 | channel |
var channel: StringName = &"" |
| 属性 | metadata |
var metadata: Dictionary = {} |
| 方法 | set_player |
func set_player(player: Node) -> void: |
| 方法 | set_release_callback |
func set_release_callback(release_callback: Callable) -> void: |
| 方法 | bind_to_owner |
func bind_to_owner(owner: Node, fade_seconds: float = 0.0) -> void: |
| 方法 | unbind_owner |
func unbind_owner() -> void: |
| 方法 | get_player |
func get_player() -> Node: |
| 方法 | is_valid |
func is_valid() -> bool: |
| 方法 | is_stop_requested |
func is_stop_requested() -> bool: |
| 方法 | is_playing |
func is_playing() -> bool: |
| 方法 | stop |
func stop(fade_seconds: float = 0.0) -> void: |
| 方法 | fade_to |
func fade_to(volume_db: float, fade_seconds: float) -> void: |
| 方法 | set_volume_db |
func set_volume_db(volume_db: float) -> void: |
| 方法 | get_volume_db |
func get_volume_db() -> float: |
| 方法 | set_pitch_scale |
func set_pitch_scale(pitch_scale: float) -> void: |
| 方法 | get_pitch_scale |
func get_pitch_scale() -> float: |
| 方法 | get_debug_snapshot |
func get_debug_snapshot() -> Dictionary: |
信号¶
player_attached¶
- API：
public
句柄绑定到底层播放器时发出。
参数：
| 名称 | 说明 |
|---|---|
handle |
当前句柄。 |
player |
绑定的播放器节点。 |
stopped¶
- API：
public
句柄主动停止并释放绑定时发出。
参数：
| 名称 | 说明 |
|---|---|
handle |
当前句柄。 |
属性¶
channel¶
- API：
public
可选通道标识。框架不解释该字段。
metadata¶
- API：
public
项目自定义元数据。框架不解释该字段。
结构：
metadata: 句柄元数据 Dictionary；键和值由调用方或后端约定。
方法¶
set_player¶
- API：
public
绑定底层播放器。
参数：
| 名称 | 说明 |
|---|---|
player |
要绑定的播放器节点。 |
set_release_callback¶
- API：
public
设置释放回调。
参数：
| 名称 | 说明 |
|---|---|
release_callback |
停止完成时调用的释放回调。 |
bind_to_owner¶
- API：
public
绑定一个拥有者节点，节点退出树时自动停止当前播放。
参数：
| 名称 | 说明 |
|---|---|
owner |
生命周期拥有者。 |
fade_seconds |
自动停止时使用的淡出秒数。 |
unbind_owner¶
- API：
public
取消拥有者生命周期绑定。
get_player¶
- API：
public
获取底层播放器。
返回：播放器节点；不存在或已释放时返回 null。
is_valid¶
- API：
public
检查句柄是否仍绑定有效播放器。
返回：有效时返回 true。
is_stop_requested¶
- API：
public
检查该句柄是否已经收到停止请求。
返回：已请求停止时返回 true。
is_playing¶
- API：
public
检查播放器是否正在播放。
返回：正在播放时返回 true。
stop¶
- API：
public
停止播放；传入淡出秒数时先淡出再释放。
参数：
| 名称 | 说明 |
|---|---|
fade_seconds |
淡出秒数。 |
fade_to¶
- API：
public
淡入淡出到指定音量。
参数：
| 名称 | 说明 |
|---|---|
volume_db |
目标音量，单位 dB。 |
fade_seconds |
淡入淡出秒数。 |
set_volume_db¶
- API：
public
设置当前音量。
参数：
| 名称 | 说明 |
|---|---|
volume_db |
音量，单位 dB。 |
get_volume_db¶
- API：
public
获取当前音量。
返回：音量，单位 dB；无播放器时返回 0。
set_pitch_scale¶
- API：
public
设置当前音高。
参数：
| 名称 | 说明 |
|---|---|
pitch_scale |
音高缩放。 |
get_pitch_scale¶
- API：
public
获取当前音高。
返回：音高缩放；无播放器时返回 1。
get_debug_snapshot¶
- API：
public
获取调试快照。
返回：调试快照。
结构：
return: 调试快照 Dictionary，包含 valid、playing、channel、volume_db、pitch_scale、owner_valid 和 metadata 字段。