SoundUnit

SoundUnit 是场景中的音频播放单位，用 SoundId 指向音频资源，并通过 Volume、Speed、Looped、Playing 等属性决定播放的音量、速率与循环方式。它既能按 2D 方式独立播放，也能借助 SetPositio...

概览

SoundUnit 是场景中的音频播放单位，用 SoundId 指向音频资源，并通过 Volume、Speed、Looped、Playing 等属性决定播放的音量、速率与循环方式。它既能按 2D 方式独立播放，也能借助 SetPosition 与 FadeDistance 表现为随距离衰减的空间音效；同时提供 Play、Stop、SetVolumeSpeed 等方法和 Played、Stopped、Ended 事件，便于跟踪播放的起止状态。

继承自 Unit；可通过 World:CreateUnit("SoundUnit", ...) 创建；返回单个单位

函数

SetVolumeSpeed

签名：SetVolumeSpeed(Volume: Int, Speed: Float)

设置 SoundUnit 的音量和播放速率。

参数	类型	说明
Volume	Int	音量
Speed	Float	速率

调整音量与播放速率

-- @runtime client
local sound = game:GetService('World'):CreateUnit('SoundUnit', { SoundId = 'official://audio/5147' })
if sound == nil then return end
sound:SetVolumeSpeed(50, 1.2)
sound:Play()
sound:Stop()
sound:Destroy()

SetSpeed

签名：SetSpeed(Speed: Float)

设置当前 SoundUnit 实例的播放速率。

参数	类型	说明
Speed	Float	速率

创建 SoundUnit 并调整播放速率

-- @runtime client
-- 通过 game:CreateUnit 创建 SoundUnit 实例（不传具体音频，稍后设置 SoundId）
local sound = game:CreateUnit("SoundUnit", {})
-- 创建后指定音频资源，缺少 SoundId 时播放会失败
sound.SoundId = "official://audio/10001"
-- 调用 SetSpeed 把播放速率调快到 1.5 倍（音调随之升高）
sound:SetSpeed(1.5)
-- 读取 Speed 属性确认速率已写入
print("当前播放速率:", sound.Speed)
-- 在设定的速率下开始播放
sound:Play()
print("是否正在播放:", sound.Playing)

循环背景音中动态变速

-- @runtime client
-- 创建实例后设置循环播放的音频资源，用于持续背景音
local bgm = game:CreateUnit("SoundUnit", {})
bgm.SoundId = "official://audio/10001"
bgm.Looped = true
-- 先用较慢的速率播放，营造舒缓氛围
bgm:SetSpeed(0.8)
bgm:Play()
print("舒缓模式播放中:", bgm.Playing)
-- 节奏变化时直接提速，无需重新创建实例
bgm:SetSpeed(1.6)
print("提速后的播放速率:", bgm.Speed)
-- 场景结束时停止该音频
bgm:Stop()
print("停止后是否播放:", bgm.Playing)

SetVolume

签名：SetVolume(Volume: Int)

设置 SoundUnit 实例的播放音量。

参数	类型	说明
Volume	Int	音量

调整音量

-- @runtime client
local sound = game:GetService('World'):CreateUnit('SoundUnit', { SoundId = 'official://audio/5147' })
if sound == nil then return end
sound:SetVolume(50)
sound:Destroy()

SetFadeDistance

签名：SetFadeDistance(FadeDistance: Float)

设置 3D 声音的衰减距离，距离越远声音衰减越明显。

参数	类型	说明
FadeDistance	Float	速率

设置 3D 音效衰减距离

-- @runtime client
local World = game:GetService('World')
local soundUnit = World:CreateUnit('SoundUnit', {
    SoundId = 'official://audio/5147',
    SoundType = '3D',
})
soundUnit:SetFadeDistance(50.0)
soundUnit:SetPosition(Vector3.New(0, 0, 0))
soundUnit:Play()

SetDuration

签名：SetDuration(duration: Float)

SetDuration 是 SoundUnit 的方法，用于设置音效的存活时长，单位为秒。它接收一个必填的 Float 类型参数 duration，没有返回值。

参数	类型	说明
duration	Float	存活时长（秒，-1 永久）

设置音效播放时长

-- @runtime client
local sound = game:GetService('World'):CreateUnit('SoundUnit', { SoundId = 'official://audio/5147' })
if sound == nil then return end
sound:SetDuration(3.0)
sound:Play()

SetPosition

签名：SetPosition(position: Vector3)

设置 3D 音效在世界空间中的播放位置。

参数	类型	说明
position	Vector3	位置

设置 3D 音效位置

-- @runtime client
local World = game:GetService('World')
local soundUnit = World:CreateUnit('SoundUnit', {
    SoundId = 'official://audio/5147',
    SoundType = '3D',
})
soundUnit:SetPosition(Vector3.New(10, 5, 0))
soundUnit:Play()

Stop

签名：Stop()

停止当前正在播放的音效。

创建 SoundUnit 播放后调用 Stop 停止

-- @runtime client
-- 创建 SoundUnit，并指定官方内置音频资源作为音源
local sound = game:CreateUnit("SoundUnit", {
    SoundId = "official://audio/10001",
    Looped = true,
    Volume = 1,
})
-- 先启动播放，确认播放状态后再停止
sound:Play()
print("播放状态 Playing =", sound.Playing)
-- 调用 Stop 停止该 SoundUnit 当前播放的音效
sound:Stop()
print("停止后 Playing =", sound.Playing)

订阅 Stopped 事件后再调用 Stop

-- @runtime client
-- 创建一个循环播放的音效实例
local bgm = game:CreateUnit("SoundUnit", {
    SoundId = "official://audio/10001",
    Looped = true,
    Volume = 1,
})
-- 先订阅 Stopped 事件，确保停止动作发生时能观察到
bgm.Stopped:Once(function()
    print("Stopped 事件已触发")
end)
-- 先播放再调用 Stop，形成完整的开始与停止流程
bgm:Play()
print("播放中 Playing =", bgm.Playing)
bgm:Stop()
print("调用 Stop 后 Playing =", bgm.Playing)

Play

签名：Play()

开始播放 SoundUnit 关联的音效。

播放已配置音源

-- @runtime client
local sound = game:GetService('World'):CreateUnit('SoundUnit', { SoundId = 'official://audio/5147' })
if sound == nil then return end
sound:Play()
sound:Stop()
sound:Destroy()

属性

名称	类型	默认值	说明
SoundId	String	-	音效资源的 URI。
SoundType	String	3D	音效类型，如 2D 或 3D。
Speed	Float	1.0	音效的播放速率。
Volume	Float	100	音效的音量大小。
Duration	Float	-1	Duration 是 SoundUnit 的属性，表示音效的存活时长，单位为秒。其类型为 Float，默认值为 -1，可读可写，且允许编辑。
CampRoleId	Int	-1	音效所属的阵营 ID。
FadeDistance	Float	-1	3D 音效的衰减距离。
Playing	Bool	false	是否在创建后自动开始播放。
Looped	Bool	false	是否循环播放音效。

事件

Played

签名：Played()

播放开始时触发

Stopped

签名：Stopped()

播放停止时触发

Ended

签名：Ended()

播放结束时触发