UI 音效 API

客户端 UI 脚本使用全局对象 Sound（大写）控制 UI 音效。

Quick Start

// 播放一次确认音效
Sound.play("ui/confirm")

// 在坐标处循环播放
Sound.playAt("ambient/forest/day", 0, 70, 0, 0.8, 1.0, true)

// 停止指定音效
Sound.stop("ambient/forest/day")

API Reference

Sound.play(id, volume = 1.0, pitch = 1.0, loop = false)

播放一个 UI 音效。

• 默认总线：UI
• 默认源：MASTER
• 相对播放：true（非坐标音）

参数	类型	必填	说明
id	string	是	音效路径（sound/ 下相对路径）
volume	number	否	音量，默认 1.0
pitch	number	否	音高，默认 1.0
loop	boolean	否	是否循环，默认 false

Sound.play("ui/quest_accept")
Sound.play("ui/confirm", 0.8, 1.2, false)

Sound.playAt(id, x, y, z, volume = 1.0, pitch = 1.0, loop = false)

在世界坐标播放音效。

• 默认总线：UI
• 默认源：MASTER
• 相对播放：false（坐标衰减）

参数	类型	必填	说明
id	string	是	音效路径（sound/ 下相对路径）
x	number	是	X 坐标
y	number	是	Y 坐标
z	number	是	Z 坐标
volume	number	否	音量，默认 1.0
pitch	number	否	音高，默认 1.0
loop	boolean	否	是否循环，默认 false

Sound.playAt("ambient/forest/day", 0, 70, 0, 0.8, 1.0, true)

Sound.stop(id)

停止指定音效。

参数	类型	必填	说明
id	string	是	音效路径（sound/ 下相对路径）

Sound.stop("ambient/forest/day")

路径规则（强制）

id 只能写相对路径：

• 正确："ui/confirm"
• 错误："behemiron:ui/confirm"、"sound/ui/confirm"、"sounds/ui/confirm"

路径不合法时，调用会被拒绝并输出警告日志。