GFAudioClip¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/utilities/audio/gf_audio_clip.gd - 模块：
Standard - 继承：
Resource - API：
public - 类别：资源定义 (
resource_definition) - 首次版本：
3.17.0
可资源化的音频播放配置。 支持直接引用 AudioStream，也支持提供资源路径交给 GFAudioUtility 按需加载。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 属性 | path |
var path: String = "" |
| 属性 | stream |
var stream: AudioStream |
| 属性 | bus_name |
var bus_name: String = "" |
| 属性 | volume_db |
var volume_db: float = 0.0 |
| 属性 | pitch_scale |
var pitch_scale: float = 1.0 |
| 属性 | weight |
var weight: float = 1.0 |
| 属性 | pitch_random_min |
var pitch_random_min: float = 1.0 |
| 属性 | pitch_random_max |
var pitch_random_max: float = 1.0 |
| 属性 | spatial_settings |
var spatial_settings: Resource = null |
| 属性 | metadata |
var metadata: Dictionary = {} |
| 方法 | has_source |
func has_source() -> bool: |
| 方法 | resolve_bus |
func resolve_bus(default_bus: String) -> String: |
| 方法 | resolve_pitch |
func resolve_pitch(rng: RandomNumberGenerator = null) -> float: |
| 方法 | has_metadata_value |
func has_metadata_value(key: Variant) -> bool: |
| 方法 | set_metadata_value |
func set_metadata_value(key: Variant, value: Variant) -> void: |
| 方法 | get_metadata_value |
func get_metadata_value(key: Variant, default_value: Variant = null) -> Variant: |
| 方法 | duplicate_metadata |
func duplicate_metadata() -> Dictionary: |
属性¶
path¶
- API：
public
音频资源路径。stream 为空时使用该路径加载。
stream¶
- API：
public
音频流资源。
bus_name¶
- API：
public
音频总线。为空时由播放方法使用默认 BGM/SFX 总线。
volume_db¶
- API：
public
播放音量，单位 dB。
pitch_scale¶
- API：
public
播放音高。
weight¶
- API：
public
在同一片段 ID 存在多个候选时的抽取权重；小于等于 0 表示不参与随机抽取。
pitch_random_min¶
- API：
public
播放音高随机下限，会乘到 pitch_scale 上。
pitch_random_max¶
- API：
public
播放音高随机上限，会乘到 pitch_scale 上。
spatial_settings¶
- API：
public - 首次版本：
3.19.0
可选空间播放设置。为空时空间 SFX 使用 GF 默认空间参数，并保留区域掩码 layer 1。
结构：
spatial_settings: GFAudioSpatialSettings or compatible Resource with apply_to_2d/apply_to_3d methods.
metadata¶
- API：
public - 首次版本：
5.1.0
可选音频元数据，供导入器、编辑器或项目层扩展使用。
结构：
metadata: Dictionary，保存项目或工具附加到片段的通用元数据；GF 不解释具体键。
方法¶
has_source¶
- API：
public
检查该配置是否有可播放来源。
返回：有 stream 或 path 时返回 true。
resolve_bus¶
- API：
public
解析实际总线名称。
参数：
| 名称 | 说明 |
|---|---|
default_bus |
默认总线。 |
返回：实际总线名称。
resolve_pitch¶
- API：
public
解析本次播放使用的实际音高。
参数：
| 名称 | 说明 |
|---|---|
rng |
可选随机数生成器；为空时使用确定性的 pitch_scale。 |
返回：实际播放音高。
has_metadata_value¶
- API：
public - 首次版本：
5.1.0
检查指定元数据键是否存在。
参数：
| 名称 | 说明 |
|---|---|
key |
元数据键。 |
返回：存在返回 true。
结构：
key: Variant，推荐使用 String 或 StringName。
set_metadata_value¶
- API：
public - 首次版本：
5.1.0
设置元数据项。
参数：
| 名称 | 说明 |
|---|---|
key |
元数据键。 |
value |
元数据值。 |
结构：
key: Variant，推荐使用 String 或 StringName。value: Variant，推荐使用可序列化的标量、Array、Dictionary 或 Resource 引用。
get_metadata_value¶
- API：
public - 首次版本：
5.1.0
获取元数据项。
参数：
| 名称 | 说明 |
|---|---|
key |
元数据键。 |
default_value |
缺少键时返回的默认值。 |
返回：元数据值或默认值。
结构：
key: Variant，推荐使用 String 或 StringName。default_value: Variant 默认值。return: Variant 元数据值。
duplicate_metadata¶
- API：
public - 首次版本：
5.1.0
创建元数据深拷贝。
返回：元数据副本。
结构：
return: Dictionary 元数据副本。