空间音频 API

空间音频 API#

FmodGeometry#

继承自： RefCounted

用于 3D 声音遮挡计算的 FMOD 几何体对象

描述#

FmodGeometry 封装 FMOD Geometry，用多边形描述场景中的墙体、地形、门板等遮挡物。FMOD 会根据声源与监听器之间的几何体计算直达声遮挡和混响遮挡，常用于让 3D 声音在墙后变闷、变小，或减少混响发送。

几何体通常通过 FmodSystem.create_geometry() 创建，也可以通过 FmodSystem.load_geometry() 从保存后的字节数据加载。

备注

几何遮挡通常需要在初始化 FMOD 系统时启用 FMOD_INIT_FLAG_CHANNEL_LOWPASS，否则低通遮挡效果不会按预期工作。

属性#

类型

名称

初始值

说明

bool

active

true

几何体是否参与遮挡计算

Vector3

position

Vector3()

几何体在世界空间中的位置

Vector3

rotation

Vector3()

几何体在世界空间中的旋转，编辑器中按角度显示

Vector3

scale

Vector3(1, 1, 1)

几何体缩放

方法#

有效性检查#

bool geometry_is_valid() const#

如果底层 FMOD Geometry 句柄有效，则返回 true。

bool geometry_is_null() const#

如果底层 FMOD Geometry 句柄为空或不可用，则返回 true。

多边形#

int add_polygon(direct_occlusion: float, reverb_occlusion: float, double_sided: bool, vertices: PackedVector3Array)#

向几何体添加一个遮挡多边形，并返回新多边形索引。direct_occlusion 控制直达声遮挡，reverb_occlusion 控制混响路径遮挡，范围通常为 0.0 到 1.0。

void set_polygon_attributes(index: int, direct_occlusion: float, reverb_occlusion: float, double_sided: bool)#

修改指定多边形的遮挡属性。

Dictionary get_polygon_attributes(index: int) const#

返回多边形属性字典，包含 direct_occlusion、reverb_occlusion 和 double_sided。

int get_polygon_num_vertices(index: int) const#

返回指定多边形的顶点数量。

void set_polygon_vertex(index: int, vertex_index: int, vertex: Vector3)#

设置指定多边形中的单个顶点位置。

Vector3 get_polygon_vertex(index: int, vertex_index: int) const#

返回指定多边形中的单个顶点位置。

Dictionary get_max_polygons() const#

返回几何体容量信息，通常包含 max_polygons 和 max_vertices。

变换#

void set_position(position: Vector3)#

设置几何体位置。

Vector3 get_position() const#

返回几何体位置。

void set_rotation(rotation: Vector3)#

设置几何体旋转。

Vector3 get_rotation() const#

返回几何体旋转。

void set_scale(scale: Vector3)#

设置几何体缩放。

Vector3 get_scale() const#

返回几何体缩放。

void set_transform(transform: Transform3D)#

一次性同步几何体的 3D 变换。

状态与资源#

void set_active(active: bool)#

启用或禁用几何体遮挡计算。

bool get_active() const#

如果几何体处于激活状态，则返回 true。

int get_save_size() const#

返回序列化当前几何体所需的字节数。

PackedByteArray save() const#

将几何体序列化为字节数组，可之后通过 FmodSystem.load_geometry() 加载。

void release()#

释放底层 FMOD Geometry。释放后该对象不应继续用于遮挡计算。

FmodReverb3D#

继承自： RefCounted

FMOD 3D 混响对象，用于在空间中创建球形混响区域

描述#

FmodReverb3D 表示一个低层级 3D 混响区域。它通过中心位置、最小距离和最大距离定义影响范围：声源在最小距离内获得完整混响，在最小距离到最大距离之间逐渐衰减，超过最大距离则基本不受影响。

通常使用 FmodSystem.create_reverb_3d() 创建此对象；如果希望直接放在场景树中并跟随节点位置，请使用 FmodReverbZone3D。

属性#

类型

名称

初始值

说明

bool

active

true

混响是否参与输出

float

decay_time

1500.0

混响衰减时间，单位为毫秒

float

density

100.0

后期混响密度，范围通常为 0.0 到 100.0

float

diffusion

50.0

回声扩散度，范围通常为 0.0 到 100.0

float

early_delay

7.0

早期反射延迟，单位为毫秒

float

early_late_mix

50.0

早期反射与后期混响的混合比例

float

hf_decay_ratio

50.0

高频衰减比例

float

hf_reference

5000.0

高频参考频率，单位为 Hz

float

high_cut

0.0

高频截止或衰减参数

float

late_delay

11.0

后期混响延迟，单位为毫秒

float

low_shelf_frequency

250.0

低频搁架参考频率，单位为 Hz

float

low_shelf_gain

0.0

低频搁架增益，单位为分贝

float

wet_level

-6.0

混响湿声电平，单位为分贝

方法#

空间范围#

void set_3d_attributes(position: Vector3, min_distance: float, max_distance: float)#

设置混响区域中心位置、完整混响半径和淡出结束半径。

Dictionary get_3d_attributes() const#

返回 3D 属性字典，包含 position、min_distance 和 max_distance。

void set_properties(properties: Dictionary)#

从字典批量设置混响参数。适合保存和恢复预设。

Dictionary get_properties() const#

返回当前混响参数字典。

参数#

方法

说明

set_decay_time(decay_time) / get_decay_time()

设置或返回混响衰减时间

set_early_delay(early_delay) / get_early_delay()

设置或返回早期反射延迟

set_late_delay(late_delay) / get_late_delay()

设置或返回后期混响延迟

set_hf_reference(hf_reference) / get_hf_reference()

设置或返回高频参考频率

set_hf_decay_ratio(hf_decay_ratio) / get_hf_decay_ratio()

设置或返回高频衰减比例

set_diffusion(diffusion) / get_diffusion()

设置或返回混响扩散度

set_density(density) / get_density()

设置或返回混响密度

set_low_shelf_frequency(low_shelf_frequency) / get_low_shelf_frequency()

设置或返回低频搁架参考频率

set_low_shelf_gain(low_shelf_gain) / get_low_shelf_gain()

设置或返回低频搁架增益

set_high_cut(high_cut) / get_high_cut()

设置或返回高频截止参数

set_early_late_mix(early_late_mix) / get_early_late_mix()

设置或返回早期/后期混响混合比例

set_wet_level(wet_level) / get_wet_level()

设置或返回混响湿声电平

状态与资源#

void set_active(active: bool)#

启用或禁用该混响区域。

bool get_active() const#

如果混响区域处于激活状态，则返回 true。

bool reverb_3d_is_valid() const#

如果底层 FMOD Reverb3D 句柄有效，则返回 true。

bool reverb_3d_is_null() const#

如果底层 FMOD Reverb3D 句柄为空或不可用，则返回 true。

void release()#

释放底层 FMOD Reverb3D。

FmodReverbZone3D#

继承自： Node3D

场景树中的 3D 混响区域节点

描述#

FmodReverbZone3D 是 FmodReverb3D 的节点封装。节点进入场景树后会创建内部混响对象，并使用节点的全局位置作为球形混响区域中心。启用 sync_transform 时，节点移动会同步到 FMOD 混响区域。

属性#

类型

名称

初始值

说明

bool

active

true

该混响区域是否参与输出

bool

sync_transform

true

是否每帧同步节点位置到内部混响对象

float

min_distance

5.0

完整混响半径

float

max_distance

20.0

混响淡出结束半径

Preset

preset

PRESET_GENERIC

混响预设；手动修改参数后会切换为 PRESET_CUSTOM

float

decay_time

1500.0

混响衰减时间，单位为毫秒

float

early_delay

7.0

早期反射延迟，单位为毫秒

float

late_delay

11.0

后期混响延迟，单位为毫秒

float

hf_reference

5000.0

高频参考频率，单位为 Hz

float

hf_decay_ratio

83.0

高频衰减比例

float

diffusion

100.0

扩散度

float

density

100.0

密度

float

low_shelf_frequency

250.0

低频搁架参考频率

float

low_shelf_gain

0.0

低频搁架增益

float

high_cut

14500.0

高频截止频率

float

early_late_mix

96.0

早期/后期混响混合比例

float

wet_level

-8.0

混响湿声电平，单位为分贝

方法#

FmodReverb3D get_reverb() const#

返回该节点内部创建并管理的 FmodReverb3D。如果节点尚未进入场景树或创建失败，则返回 null。

备注

其它属性均通过同名 getter / setter 暴露，例如 set_min_distance() / get_min_distance()、set_preset() / get_preset() 和 set_wet_level() / get_wet_level()。

枚举#

Preset#

成员

值

说明

PRESET_CUSTOM

0

自定义参数

PRESET_OFF

1

关闭混响

PRESET_GENERIC

2

通用混响

PRESET_PADDED_CELL

3

软包小房间

PRESET_ROOM

4

普通房间

PRESET_BATHROOM

5

浴室

PRESET_LIVING_ROOM

6

客厅

PRESET_STONE_ROOM

7

石室

PRESET_AUDITORIUM

8

礼堂

PRESET_CONCERT_HALL

9

音乐厅

PRESET_CAVE

10

洞穴

PRESET_ARENA

11

竞技场

PRESET_HANGAR

12

机库

PRESET_HALLWAY

13

走廊

PRESET_STONE_CORRIDOR

14

石质走廊

PRESET_ALLEY

15

小巷

PRESET_FOREST

16

森林

PRESET_CITY

17

城市

PRESET_MOUNTAINS

18

山地

PRESET_UNDERWATER

19

水下