SoundService

概览

字段	值
Kind	Service · 服务 Service
Realm	common

继承关系

• Unit（4 属性 / 25 函数 / 6 事件）
  • [SoundService]（5 函数 / 1 事件）

> Service 继承 Unit 仅表示运行时类型关系；作者可用 API 以当前 Service 页面显式列出的成员为准，不自动包含 Unit 的创建、层级或销毁能力。

声音服务是全局单例，负责在客户端发起音频播放并按音组统一管理响度。它提供二维、三维与本地三种发声入口，其中二维与三维播放会在播放的同时创建并返回一个可继续操控的 SoundUnit 实例，用于后续调整播放状态、音量与速度；音组音量则通过设置与读取接口集中维护，并在变化时对外发出通知。

适用场景

当界面提示音、角色或世界物体的音效需要同时播放并按 BGM、SFX 等音组统一调节响度时，用它发起播放并管理音组音量；只需本端可闻的提示音则走本地播放入口。

使用要点

先通过 game:GetService("SoundService") 取得服务实例，界面或全局音效调用 Play2D 并接收其返回的 SoundUnit，需要随世界坐标发声时改用 Play3D，仅在当前端播放的提示音使用 PlayLocalSound。整体响度用 SetGroupVolume 设置、GetGroupVolume 查询，再通过 GroupVolumeChanged 感知音组音量变化。

注意事项

SoundService 的 Play2D/Play3D 会创建并返回 SoundUnit；当前 Meta 已声明该返回契约，可继续通过返回实例控制 Playing、Volume、Speed 等公开属性。

代码示例

音组音量监听与 2D 音效播放

-- @runtime client
local soundService = game:GetService("SoundService")
local sfxGroup = game:CreateUnit("SoundGroup", {
    Name = "SFX",
    Volume = 80,
    Parent = soundService,
})
if sfxGroup == nil then return end
print("音组已创建:", sfxGroup.Name, "初始音量:", sfxGroup.Volume)

soundService.GroupVolumeChanged:Once(function(name, volume)
    print("音组音量变化:", name, volume)
end)
soundService:SetGroupVolume("SFX", 60)
print("SFX 当前音量:", soundService:GetGroupVolume("SFX"))

local soundUnit = soundService:Play2D("official://audio/10001", 60, 1.0, false, false, 5)
if soundUnit ~= nil then
    soundUnit.Volume = 50
    soundUnit.Stopped:Once(function()
        print("音效停止:", soundUnit.SoundId)
    end)
end

关联类型

• Unit

事件 (1)

GroupVolumeChanged

签名：GroupVolumeChanged(name: String, volume: Float) 触发：local

当某个音组的音量发生变化时触发，携带音组名称和新的音量值。

回调参数	类型	说明
name	String	音组名称
volume	Float	新音量值（0~100）

示例代码

监听音组音量变化

-- @runtime client
-- 获取 SoundService 服务实例
local soundService = game:GetService("SoundService")

-- 监听 GroupVolumeChanged 事件，当任意音组音量改变时触发
soundService.GroupVolumeChanged:Once(function(name, volume)
    -- 打印变化的音组名称和当前音量
    print("音组名称: " .. name .. ", 当前音量: " .. volume)
end)

函数 (5)

Play2D

签名：Play2D(soundId: String, volume: Float, speed: Float, playerOrCampRoleId: Bool, campRoleId: Bool, duration: Float) -> SoundUnit (本次播放创建的 SoundUnit 实例)

在 SoundService 上以二维方式播放指定音效。参数依次为 soundId（音效标识字符串）、volume（音量大小）、speed（播放速率）、playerOrCampRoleId、campRoleId（两个额外属性参数，均填 False）、duration（持续时间），调用后返回本次播放对应的 SoundUnit 音效组件。

参数	类型	说明
soundId	String	声音ID
volume	Float	音量
speed	Float	速率
playerOrCampRoleId	Bool	额外播放范围开关，常规 2D 播放传 false；不要传 Player 对象。
campRoleId	Bool	额外阵营范围开关，常规 2D 播放传 false；不要传阵营 ID 数字。
duration	Float	播放时长

返回值 SoundUnit (本次播放创建的 SoundUnit 实例)

示例代码

播放 2D 音效并取得实例

-- @runtime client
local soundService = game:GetService('SoundService')
local soundUnit = soundService:Play2D('official://audio/10001', 80, 1.0, false, false, 3)
soundUnit.Volume = 60
print('2D 音效实例:', soundUnit)

Play3D

签名：Play3D(soundId: String, position: Vector3, duration: Float, volume: Float, speed: Float, player: Bool) -> SoundUnit (本次播放创建的 SoundUnit 实例)

Play3D 是 SoundService 提供的 3D 音效播放接口：在传入的世界坐标位置播放由 soundId 指定的音效，同时指定该次播放的持续时间、音量大小与播放速率，调用后返回对应的 SoundUnit 音效组件。

参数	类型	说明
soundId	String	声音 ID
position	Vector3	声音位置（Vector3 或同结构）
duration	Float	播放时长
volume	Float	音量 0~100
speed	Float	速率 0~1
player	Bool	额外播放范围开关，常规 3D 播放传 false；不要传 Player 对象。

返回值 SoundUnit (本次播放创建的 SoundUnit 实例)

示例代码

在世界位置播放 3D 音效

-- @runtime client
local soundService = game:GetService('SoundService')
local position = Vector3.New(0, 10, 0)
local soundUnit = soundService:Play3D('official://audio/10001', position, 5, 80, 1.0, false)
soundUnit.Playing = true
print('3D 音效实例:', soundUnit)

PlayLocalSound

签名：PlayLocalSound(soundId: String, volume: Float, speed: Float) -> void

在本地客户端一次性播放 2D 音效，不创建 SoundUnit 实例，性能开销最小。

参数	类型	说明
soundId	String	声音资源 URI（official://audio/{id} 或 custom://{asset_id}）
volume	Float	音量 0~100
speed	Float	速率 0~1

返回值 void

示例代码

在本地播放一次性 2D 音效

-- @runtime client
local soundService = game:GetService('SoundService')
local soundId = 'official://audio/10001'
local volume = 80
local speed = 1.0
soundService:PlayLocalSound(soundId, volume, speed)

SetGroupVolume

签名：SetGroupVolume(name: String, volume: Float) -> void

设置指定音组的音量。

参数	类型	说明
name	String	音组名称
volume	Float	音量（0~100）

返回值 void

示例代码

设置音组音量

-- @runtime client
-- 获取 SoundService 服务实例
local soundService = game:GetService("SoundService")

-- 设置名为 "BGM" 的音组音量为 50
soundService:SetGroupVolume("BGM", 50)

-- 验证音量是否设置成功
local currentVolume = soundService:GetGroupVolume("BGM")
print("BGM 音组当前音量: " .. currentVolume)

GetGroupVolume

签名：GetGroupVolume(name: String) -> Float (音量（0~100），音组不存在返回 100)

获取指定音组的当前音量。

参数	类型	说明
name	String	音组名称

返回值 Float (音量（0~100），音组不存在返回 100)

示例代码

获取音组音量

-- @runtime client
-- 获取 SoundService 服务实例
local soundService = game:GetService("SoundService")

-- 获取名为 "SFX" 的音组音量
local volume = soundService:GetGroupVolume("SFX")

-- 输出获取到的音量值
print("SFX 音组音量: " .. volume)