Unison Engine API

Appearance

unison.wwise — 音频引擎 ​

Wwise 音频中间件的 Python 封装，提供完整的音频控制功能。

使用方式 ​

python
from unison import wwise

初始化 ​

python
# 初始化 Wwise
wwise.initialize(base_path="SoundBanks/", vfs_paths=["SoundBanks/"])

# 加载音频库
wwise.load_bank("Init.bnk")
wwise.load_bank("UI.bnk")
wwise.load_bank("Music.bnk")

# 注册游戏对象
wwise.register_game_object(1, "Player")
wwise.register_game_object(100, "Listener")

生命周期 ​

函数说明
initialize(base_path, vfs_paths)初始化 Wwise 引擎
shutdown()关闭 Wwise
is_initialized()是否已初始化
render_audio()每帧渲染音频

Bank 管理 ​

python
wwise.load_bank("UI.bnk")
wwise.unload_bank("UI.bnk")
wwise.unload_all_banks()
函数说明
load_bank(name)加载音频库
unload_bank(name)卸载音频库
unload_all_banks()卸载全部

游戏对象 ​

python
wwise.register_game_object(id, name)
wwise.unregister_game_object(id)
wwise.unregister_all_game_objects()

事件 ​

python
# 触发事件
playing_id = wwise.post_event("Play_Footstep", game_object_id=1)
wwise.post_event("Play_Music", 1)
wwise.post_event("Play_UI_Click", 1)

# 停止事件
wwise.stop_event("Play_Music", 1, transition_time_ms=500)
wwise.stop_all()                    # 停止所有事件
wwise.stop_playing_id(playing_id, transition_time_ms=200)
函数说明
post_event(event_name, game_object_id)触发事件，返回 playing_id
stop_event(event_name, game_object_id, transition_time_ms)停止指定事件
stop_all(game_object_id)停止所有事件
stop_playing_id(playing_id, transition_time_ms)通过 ID 停止

RTPC (实时参数控制) ​

python
wwise.set_rtpc_value("Volume_Master", 0.8, game_object_id=1)
value = wwise.get_rtpc_value("Volume_Master", 1)
函数说明
set_rtpc_value(rtpc_name, value, game_object_id)设置 RTPC 值
get_rtpc_value(rtpc_name, game_object_id)获取 RTPC 值

Switch / State ​

python
# Switch（按对象）
wwise.set_switch("Material", "Concrete", game_object_id=1)
wwise.set_switch("Material", "Metal", game_object_id=1)

# State（全局）
wwise.set_state("RoomSize", "Large")
wwise.set_state("RoomSize", "Small")
函数说明
set_switch(group, state, game_object_id)设置对象开关
set_state(group, state)设置全局状态

3D 定位 ​

python
# 设置发射源位置
wwise.set_position(
    game_object_id=1,
    x=10.0, y=0.0, z=5.0,
    orient_x=0.0, orient_y=0.0, orient_z=-1.0
)

# 设置监听者位置（通常为摄像机）
wwise.set_listener_position(
    x=0.0, y=1.5, z=0.0,
    front_x=0.0, front_y=0.0, front_z=-1.0,
    top_x=0.0, top_y=1.0, top_z=0.0
)

# 管理监听者关系
wwise.set_listeners(emitter_id=1, listener_ids=[100])
wwise.add_listener(emitter_id=1, listener_id=101)
wwise.remove_listener(emitter_id=1, listener_id=101)
函数说明
set_position(id, x, y, z, orient_x, orient_y, orient_z)设置对象 3D 位置
set_listener_position(x, y, z, front_x, front_y, front_z, top_x, top_y, top_z)设置监听者位置
set_listeners(emitter_id, listener_ids)设置发射者的监听者列表
add_listener(emitter_id, listener_id)添加监听者
remove_listener(emitter_id, listener_id)移除监听者

音量与遮挡 ​

python
wwise.set_volume(0.8)                    # 全局音量 0~1
volume = wwise.get_volume()

# 输出总线音量
wwise.set_game_object_output_bus_volume(emitter_id=1, listener_id=100, volume=0.5)

# 阻挡和遮挡 (0~1)
wwise.set_obstruction_and_occlusion(emitter_id=1, listener_id=100, obstruction=0.3, occlusion=0.7)

路径管理 ​

python
wwise.set_base_path("SoundBanks/")
wwise.add_base_path("DLC/SoundBanks/")
wwise.add_vfs_search_path("SoundBanks/")