SoundGroup

概览

字段	值
Kind	Unit · 单位 Unit
Realm	common

继承关系

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

继承成员

1 个来源 / 4 属性 / 25 函数 / 6 事件

• 来自 Unit（4 属性 / 25 函数 / 6 事件）
  • 属性：AssetId、Name、Desc、Parent
  • 函数：ClearAllChildren、GetChildren、GetDescendants、IsAncestorOf、IsDescendantOf、FindFirstAncestor、FindFirstAncestorWhichIsA、FindFirstAncestorOfClass、FindFirstChild、FindFirstChildWhichIsA、FindFirstChildOfClass、HasChildren、GetChildCount、GetChildAtIndex、SetAttribute、GetAttribute、GetAllProps、Clone、IsA、Destroy、GetPropertyChangedSignal、GetAttributeChangedSignal、FindFromPath、GetFullPath、GetDebugId
  • 事件：ChildAdded、ChildRemoved、DescendantAdded、DescendantRemoving、AncestryChanged、Destroying

SoundGroup 是音效分组容器，通过 Volume 统一控制挂在该组下的 SoundUnit 音量。

适用场景

用于把背景音乐、环境音或音效分组管理。将 SoundGroup 挂到 SoundService，再把 SoundUnit.Parent 设为该 SoundGroup，即可统一调节组内音量。

使用要点

通过 World:CreateUnit("SoundGroup", { Volume = 100 }) 创建音组并挂到 SoundService；Volume 使用 0-100 音量值。创建 SoundUnit 后设置 SoundId，再把 SoundUnit.Parent 设为音组并调用 Play()。

注意事项

SoundGroup 本身不播放声音，只影响作为子节点挂入的 SoundUnit。Volume 与 SoundUnit.Volume 统一使用 0-100 音量值；例如 50 表示把组音量调到一半。

代码示例

创建音组并播放组内音效

-- @runtime client
local World = game:GetService("World")
local SoundService = game:GetService("SoundService")

local soundGroup = World:CreateUnit("SoundGroup", {
    Volume = 100,
    Parent = SoundService,
})

local soundUnit = World:CreateUnit("SoundUnit", {
    SoundId = "official://audio/5147",
    Parent = soundGroup,
})
soundUnit:Play()

soundGroup.Volume = 50
print("音组音量:", soundGroup.Volume)

属性 (1)

Name	类型	默认值	说明
Volume	Float	100.0	音组的全局音量，影响该音组下所有 SoundUnit 的最终输出音量。

关联类型

• Unit