GFAudioBankTools¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/utilities/audio/gf_audio_bank_tools.gd - 模块：
Standard - 继承：
RefCounted - API：
public - 类别：运行时服务 (
runtime_service) - 首次版本：
3.17.0
音频集合扫描、导入和校验辅助。 面向编辑器工具和构建脚本复用；它只生成 GFAudioBank / GFAudioClip 配置，不接管运行时播放策略。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 枚举 | ClipIdMode |
enum ClipIdMode |
| 常量 | AUDIO_EXTENSIONS |
const AUDIO_EXTENSIONS: PackedStringArray = ["wav", "ogg", "mp3", "opus"] |
| 常量 | DEFAULT_EXCLUDED_PATHS |
const DEFAULT_EXCLUDED_PATHS: PackedStringArray = ["res://addons"] |
| 常量 | DEFAULT_MAX_SCAN_DEPTH |
const DEFAULT_MAX_SCAN_DEPTH: int = 32 |
| 常量 | DEFAULT_MAX_AUDIO_PATHS |
const DEFAULT_MAX_AUDIO_PATHS: int = 10000 |
| 方法 | is_audio_path |
static func is_audio_path(path: String, extensions: PackedStringArray = AUDIO_EXTENSIONS) -> bool: |
| 方法 | scan_audio_paths |
static func scan_audio_paths(root_path: String = "res://", options: Dictionary = {}) -> PackedStringArray: |
| 方法 | create_bank_from_paths |
static func create_bank_from_paths(paths: PackedStringArray, options: Dictionary = {}) -> GFAudioBank: |
| 方法 | create_bank_from_scan |
static func create_bank_from_scan(root_path: String = "res://", options: Dictionary = {}) -> GFAudioBank: |
| 方法 | add_paths_to_bank |
static func add_paths_to_bank( bank: GFAudioBank, paths: PackedStringArray, options: Dictionary = {} ) -> GFValidationReport: |
| 方法 | sync_bank_from_scan |
static func sync_bank_from_scan( bank: GFAudioBank, root_path: String = "res://", options: Dictionary = {} ) -> GFValidationReport: |
| 方法 | validate_bank_playback |
static func validate_bank_playback(bank: GFAudioBank, options: Dictionary = {}) -> GFValidationReport: |
| 方法 | make_clip_id |
static func make_clip_id(path: String, options: Dictionary = {}) -> StringName: |
枚举¶
ClipIdMode¶
- API：
public
enum ClipIdMode { ## 使用文件名，不包含扩展名。 BASENAME, ## 使用相对 base_path 的路径，不包含扩展名。 RELATIVE_PATH, ## 使用完整资源路径，不包含扩展名。 FULL_PATH, }
从音频路径生成片段 ID 的方式。
常量¶
AUDIO_EXTENSIONS¶
- API：
public
默认音频扩展名白名单，不包含点号。
DEFAULT_EXCLUDED_PATHS¶
- API：
public
默认排除的扫描路径。
DEFAULT_MAX_SCAN_DEPTH¶
- API：
public
默认递归扫描深度上限。
DEFAULT_MAX_AUDIO_PATHS¶
- API：
public
默认单次扫描收集的音频路径数量上限。
方法¶
is_audio_path¶
- API：
public
判断路径是否指向 GF 默认支持的音频扩展名。
参数：
| 名称 | 说明 |
|---|---|
path |
资源路径或文件名。 |
extensions |
可选扩展名白名单，不包含点号。 |
返回：是音频路径时返回 true。
scan_audio_paths¶
- API：
public
static func scan_audio_paths(root_path: String = "res://", options: Dictionary = {}) -> PackedStringArray:
递归扫描音频路径。
参数：
| 名称 | 说明 |
|---|---|
root_path |
扫描起点，通常是 res:// 下的目录。 |
options |
可选项，支持 recursive、include_addons、excluded_paths、extensions、max_scan_depth 与 max_audio_paths。 |
返回：按字典序排序的音频路径。
结构：
options: Dictionary，可包含 recursive、include_addons、excluded_paths、extensions、max_scan_depth 和 max_audio_paths 字段。
create_bank_from_paths¶
- API：
public
static func create_bank_from_paths(paths: PackedStringArray, options: Dictionary = {}) -> GFAudioBank:
从路径列表创建新的音频集合。
参数：
| 名称 | 说明 |
|---|---|
paths |
音频资源路径列表。 |
options |
可选项，支持 id_mode、base_path、path_separator、strip_extension、bus_name、volume_db、pitch_scale。 |
返回：新建的音频集合。
结构：
options: Dictionary，可包含 id_mode、base_path、path_separator、strip_extension、bus_name、volume_db、pitch_scale 和 overwrite 字段。
create_bank_from_scan¶
- API：
public
static func create_bank_from_scan(root_path: String = "res://", options: Dictionary = {}) -> GFAudioBank:
扫描目录并创建新的音频集合。
参数：
| 名称 | 说明 |
|---|---|
root_path |
扫描起点，通常是 res://audio。 |
options |
可选项，同时传给 scan_audio_paths() 与 create_bank_from_paths()。 |
返回：新建的音频集合。
结构：
options: Dictionary，可同时包含扫描选项和片段导入选项。
add_paths_to_bank¶
- API：
public
static func add_paths_to_bank( bank: GFAudioBank, paths: PackedStringArray, options: Dictionary = {} ) -> GFValidationReport:
将路径列表加入音频集合。
参数：
| 名称 | 说明 |
|---|---|
bank |
要写入的音频集合。 |
paths |
音频资源路径列表。 |
options |
可选项，支持 id_mode、base_path、path_separator、strip_extension、overwrite、bus_name、volume_db、pitch_scale。 |
返回：导入报告。
结构：
options: Dictionary，可包含 id_mode、base_path、path_separator、strip_extension、overwrite、bus_name、volume_db 和 pitch_scale 字段。
sync_bank_from_scan¶
- API：
public
static func sync_bank_from_scan( bank: GFAudioBank, root_path: String = "res://", options: Dictionary = {} ) -> GFValidationReport:
扫描目录并同步到已有音频集合。
参数：
| 名称 | 说明 |
|---|---|
bank |
要写入的音频集合。 |
root_path |
扫描起点，通常是 res://audio。 |
options |
可选项，同时传给 scan_audio_paths() 与 add_paths_to_bank()。 |
返回：导入报告。
结构：
options: Dictionary，可同时包含扫描选项和片段导入选项。
validate_bank_playback¶
- API：
public
static func validate_bank_playback(bank: GFAudioBank, options: Dictionary = {}) -> GFValidationReport:
校验音频集合是否适合交给 GFAudioUtility 播放。
参数：
| 名称 | 说明 |
|---|---|
bank |
要校验的音频集合。 |
options |
可选项，支持 check_resource_exists、check_bus_exists、extensions。 |
返回：校验报告。
结构：
options: Dictionary，可包含 check_resource_exists、check_bus_exists 和 extensions 字段。
make_clip_id¶
- API：
public
按选项从路径生成稳定片段 ID。
参数：
| 名称 | 说明 |
|---|---|
path |
音频资源路径。 |
options |
可选项，支持 id_mode、base_path、path_separator、strip_extension。 |
返回：片段 ID。
结构：
options: Dictionary，可包含 id_mode、base_path、path_separator 和 strip_extension 字段。