版本：最新版 - a1.156.0 ⚖️

🔊 Sound

用于播放游戏内 2D 和 3D 声音的类。

Client Only🔁Not Distributable🧑‍💻API Source

👪Inheritance

This class shares methods and events from Base Entity, Base Actor.

提示

你还可以直接从磁盘加载原始的 .ogg 文件！请查阅 SpecialPath。

🎒 示例

Client/Index.lua
local my_sound = Sound(
    Vector(-510, 145, 63), -- 位置（如果是 3D 音效）
    "nanos-world::A_VR_Confirm", -- 资产路径
    false, -- 是否为 2D 音效
    true, -- 自动销毁（播放完毕后是否销毁）
    SoundType.SFX,
    1, -- 音量
    1 -- 音调
)

Client/Index.lua
-- 生成位于包中的 ogg 音效
local ogg_sound = Sound(Vector(), "package://my-package/Client/awesome_beep.ogg", true)

🛠 构造函数

Default Constructor

No description provided

local my_sound = Sound(location, asset, is_2d_sound?, auto_destroy?, sound_type?, volume?, pitch?, inner_radius?, falloff_distance?, attenuation_function?, keep_playing_when_silent?, loop_mode?, auto_play?)

Parameters

Type	Name	Default	Description
Vector	`location`	Required parameter	仅在 3D 声音时使用
Sound Reference	`asset`	Required parameter	要加载的声音资产
boolean	`is_2d_sound`	`false`	是否生成为 2D 或 3D 声音
boolean	`auto_destroy`	`true`	播放完成后是否销毁
SoundType	`sound_type`	`SoundType.SFX`	用于应用用户的音量设置
float	`volume`	`1`	音量倍率
float	`pitch`	`1`	音高倍率
float	`inner_radius`	`400`	仅在 3D 声音时使用
float	`falloff_distance`	`3600`	仅在 3D 声音时使用
AttenuationFunction	`attenuation_function`	`AttenuationFunction.Linear`	仅在 3D 声音时使用
boolean	`keep_playing_when_silent`	`false`	仅在 3D 声音时使用 - 请谨慎使用，这可能会导致性能问题！
SoundLoopMode	`loop_mode`	`SoundLoopMode.Default`	是否应强制声音循环播放
boolean	`auto_play`	`true`	加载后是否立即播放

备注

auto_destroy 意味着实体在生成后会立即被销毁，失去对游戏内生成的 Sound 的引用。因此，如果 Sound 本身无限循环，它将持续播放直到玩家重新连接。

🗿 静态函数

Inherited Entity Static Functions

Sound inherits from Base Entity Class, sharing it's methods and functions:
Base Entityscripting-reference/classes/base-classes/entity

Returns	Name	Description
table of Base Entity	`GetAll`	返回一个包含调用此方法的类中所有实体的表
Base Entity	`GetByIndex`	返回该类中指定索引处的特定实体
integer	`GetCount`	返回该类当前存在的实体数量
table of table	`GetInheritedClasses`	获取使用继承系统创建的、直接继承自该类的所有子类列表
iterator	`GetPairs`	返回一个包含该类所有实体的迭代器，用于 `pairs()` 循环
table or nil	`GetParentClass`	如果该类是使用继承系统创建的，则获取其父类
table	`Inherit`	使用继承系统继承此类
boolean	`IsChildOf`	如果该类是使用继承系统创建的，检查此类是否为另一个类的子类
function	`Subscribe`	为该类的所有实体订阅一个事件
function	`SubscribeRemote`	订阅从服务器调用的自定义远程事件
	`Unsubscribe`	退订此包内该类中此事件的所有回调，或者仅取消传入的特定回调

This class doesn't have own static functions.

🦠 函数

Inherited Entity Functions

Sound inherits from Base Entity Class, sharing it's methods and functions:
Base Entityscripting-reference/classes/base-classes/entity

Returns	Name	Description
	`BroadcastRemoteEvent`	直接在此实体上向所有玩家调用自定义远程事件
	`BroadcastRemoteInRadiusEvent`	直接针对此实体调用自定义远程事件，并将该事件传递给半径范围内的所有玩家
	`CallRemoteEvent`	直接在此实体上向特定玩家调用自定义远程事件
	`CallRemoteEvent`	直接在此实体上调用自定义远程事件
	`CallRemotePlayersEvent`	直接在此实体上调用自定义远程事件，并将事件传递给玩家列表
	`Destroy`	销毁该实体
	`FinishSpawn`	如果此实体是以延迟 `spawn_mode` 生成的，则完成生成过程并将该实体发送至客户端
table of string	`GetAllValuesKeys`	获取所有存储值的键名列表
table	`GetClass`	获取该实体的类
integer	`GetID`	获取该实体的全网通用网络 ID（在客户端和服务器上相同）
any	`GetValue`	获取此实体上存储在给定键处的值
boolean	`HasAuthority`	获取本地上下文是否对此实体拥有主控（如果由客户端生成则为 true，由服务器生成则为 false）
boolean	`IsA`	递归检查此实体是否继承自某个类
boolean	`IsBeingDestroyed`	如果该实体正在被销毁，则返回 true
boolean	`IsSpawned`	获取此实体是否已完成生成
boolean	`IsValid`	如果该实体有效（即未被销毁且指向一个有效的实体），则返回 true
	`SetSpawnMode`	从继承类的构造函数中覆盖此实体完成生成的时间点
	`SetValue`	在此实体中设置一个值
function	`Subscribe`	在这个特定实体上订阅一个事件
function	`SubscribeRemote`	在这个特定实体上订阅一个从服务器调用的自定义远程事件
	`Unsubscribe`	退订此包内该实体中此事件的所有回调，或者仅取消传入的特定回调

Inherited Actor Functions

Sound inherits from Base Actor Class, sharing it's methods and functions:
Base Actorscripting-reference/classes/base-classes/actor

Returns	Name	Description
	`AddActorTag`	向该 Actor 添加一个虚幻 Actor 标签
	`AddAngularImpulse`	向该 Actor 添加角冲量。适用于单次瞬间爆发
	`AddImpulse`	向该 Actor 添加冲量。适用于单次瞬间爆发
boolean	`AttachTo`	将该 Actor 附加到任何其他 Actor 上，可选择附加在特定骨骼处
	`Detach`	将该 Actor 从其附加的 Actor 上分离
table of string	`GetActorTags`	获取该 Actor 上的所有虚幻 Actor 标签
Vector	`GetAngularForce`	获取该 Actor 的角外力（由 `SetAngularForce()` 设置）
float	`GetAngularVelocity`	返回此 Actor 的角速度
table of Base Actor	`GetAttachedEntities`	获取附加到该 Actor 的所有 Actor
Base Actor or nil	`GetAttachedTo`	获取该 Actor 所附加到的父级 Actor
string	`GetAttachedToSocket`	获取此 Actor 所附加到的骨骼或插槽名称
table	`GetBounds`	获取此 Actor 的包围盒，便于计算其在世界中的尺寸
CollisionType	`GetCollision`	获取该 Actor 的碰撞类型
integer	`GetDimension`	获取该 Actor 的维度
float	`GetDistanceFromCamera`	获取该 Actor 距离相机的距离
Vector	`GetForce`	获取该 Actor 的持续外力（由 `SetForce()` 设置）
float	`GetLifeSpan`	获取此 Actor 被销毁前剩余的时间（秒）
Vector	`GetLocation`	获取该 Actor 在游戏世界中的位置
float	`GetMass`	返回此 Actor 的质量
Player or nil	`GetNetworkAuthority`	获取该 Actor 的网络主控玩家
Vector	`GetRelativeLocation`	如果该 Actor 已附加，获取其相对位置
Rotator	`GetRelativeRotation`	如果该 Actor 已附加，获取其相对旋转
Rotator	`GetRotation`	获取该 Actor 在游戏世界中的角度值
Vector	`GetScale`	获取该 Actor 的缩放比例
float	`GetScreenPercentage`	获取该 Actor 在屏幕中所占尺寸的百分比
table	`GetSocketTransform`	在给定骨骼或插槽名称的情况下，获取世界空间中的插槽变换
Vector	`GetVelocity`	获取该 Actor 当前的速度
boolean	`HasNetworkAuthority`	如果本地玩家当前是该 Actor 的网络主控（Network Authority），则返回 true
boolean	`IsGravityEnabled`	如果该 Actor 启用了重力，则返回 true
boolean	`IsInWater`	如果该 Actor 处于水中，则返回 true
boolean	`IsNetworkDistributed`	如果该 Actor 当前处于网络分配状态，则返回 true
boolean	`IsVisible`	如果该 Actor 可见，则返回 true
	`RemoveActorTag`	从该 Actor 中移除一个虚幻 Actor 标签
	`RotateTo`	在一定时间内平滑旋转该 Actor 到指定角度
	`SetAngularForce`	向该 Actor 添加一个永久的角外力，设为 Vector(0, 0, 0) 可以取消
	`SetCastShadow`	设置该 Actor 是否投射阴影
	`SetCollision`	设置该 Actor 的碰撞类型
	`SetDimension`	设置此 Actor 的维度。Actor 仅能看见并与处于同一维度中的实体进行交互
	`SetDistanceOptimizationMultiplier`	设置此 Actor 的距离优化系数
	`SetForce`	向该 Actor 添加一个永久的外力，设为 Vector(0, 0, 0) 可以取消
	`SetGravityEnabled`	设置该 Actor 是否启用重力
	`SetHighlightEnabled`	设置该 Actor 是否启用高亮显示，以及使用哪个高亮索引值
	`SetLifeSpan`	设置该 Actor 被销毁前的生存时间（秒）。经过这段时间后，Actor 将被自动销毁。
	`SetLocation`	设置该 Actor 在游戏世界中的位置
	`SetNetworkAuthority`	设置某个玩家拥有此 Actor 的网络主控
	`SetNetworkAuthorityAutoDistributed`	设置该 Actor 是否在玩家之间自动分配网络主控
	`SetOutlineEnabled`	设置该 Actor 是否启用描边，以及使用哪个描边索引值
	`SetRelativeLocation`	在局部空间中设置该 Actor 的相对位置（仅在此 Actor 已附加时生效）
	`SetRelativeRotation`	在局部空间中设置该 Actor 的相对旋转（仅在此 Actor 已附加时生效）
	`SetRenderCullDistance`	设置该 Actor 的渲染剔除距离
	`SetRotation`	设置该 Actor 在游戏世界中的旋转
	`SetScale`	设置该 Actor 的缩放比例
	`SetVisibility`	设置该 Actor 是否可见
	`TranslateTo`	在一定时间内平滑地将该 Actor 移动到某个位置
boolean	`WasRecentlyRendered`	获取该 Actor 最近是否在屏幕上被渲染过

Returns	Name	Description
	`FadeIn`	使用淡入效果播放声音
	`FadeOut`	使用淡出效果停止声音
float	`GetDuration`	获取声音的时长
float	`GetFalloffDistance`	获取声音衰减至完全听不见的距离
float	`GetInnerRadius`	获取音量维持 100% 的内半径
float	`GetLowPassFilter`	获取低通滤波器频率
string	`GetPath`	获取此声音的资产路径
float	`GetPitch`	获取音高倍率
SoundType	`GetSoundType`	获取声音类型，用于应用用户的音量设置
float	`GetVolume`	获取音量倍率
boolean	`Is2D`	获取声音是否为 2D 声音
boolean	`IsPlaying`	获取声音是否正在播放
	`Play`	开始播放声音
	`SetFalloffDistance`	如果是 3D 声音，设置声音变得听不到的距离
	`SetInnerRadius`	如果是 3D 音效，设置音量维持 100% 的内半径
	`SetLowPassFilter`	设置低通滤波器频率。设为 0 以禁用它。
	`SetPaused`	暂停或恢复播放声音
	`SetPitch`	设置声音的音调
	`SetVolume`	设置声音的音量
	`Stop`	停止声音
	`StopDelayed`	在指定的延迟时间后停止声音

Optimal

`FadeIn`

使用淡入效果播放声音

my_sound:FadeIn(fade_in_duration, fade_volume_level?, start_time?)

Parameters

Type	Parameter	Default	Description
float	`fade_in_duration`	Required parameter	淡入所需的秒数
float	`fade_volume_level?`	`1.0`	淡入目标音量倍率
float	`start_time?`	`0.0`	从声音的第几秒开始播放

Optimal

`FadeOut`

使用淡出效果停止声音

my_sound:FadeOut(fade_out_duration, fade_volume_level?, destroy_after_fadeout?)

Parameters

Type	Parameter	Default	Description
float	`fade_out_duration`	Required parameter	淡出所需的秒数
float	`fade_volume_level?`	`0.0`	淡入目标音量倍率
boolean	`destroy_after_fadeout?`	`false`	淡出结束后是否销毁 Sound

Optimal

`GetDuration`

获取声音的时长

local duration = my_sound:GetDuration()

Returns

Type	Description
float	声音的持续时长

Optimal

`GetFalloffDistance`

获取声音衰减至完全听不见的距离

local falloff_distance = my_sound:GetFalloffDistance()

Returns

Type	Description
float	衰减距离

`GetInnerRadius`

获取音量维持 100% 的内半径

local inner_radius = my_sound:GetInnerRadius()

Returns

Type	Description
float	内半径

`GetLowPassFilter`

获取低通滤波器频率

local frequency = my_sound:GetLowPassFilter()

Returns

Type	Description
float	低通滤波器频率

`GetPath`

获取此声音的资产路径

local path = my_sound:GetPath()

Returns

Type	Description
string	资产路径

Optimal

`GetPitch`

获取音高倍率

local pitch = my_sound:GetPitch()

Returns

Type	Description
float	音高倍率

`GetSoundType`

获取声音类型，用于应用用户的音量设置

local sound_type = my_sound:GetSoundType()

Returns

Type	Description
SoundType	声音类型

Optimal

`GetVolume`

获取音量倍率

local volume = my_sound:GetVolume()

Returns

Type	Description
float	音量倍率

`Is2D`

获取声音是否为 2D 声音

local is_2d_sound = my_sound:Is2D()

Returns

Type	Description
boolean	该声音是否为 2D 音效

Optimal

`IsPlaying`

获取声音是否正在播放

local is_playing = my_sound:IsPlaying()

Returns

Type	Description
boolean	声音是否正在播放

Optimal

`Play`

开始播放声音

my_sound:Play(start_time?)

Parameters

Type	Parameter	Default	Description
float	`start_time?`	`0.0`	从声音的第几秒开始播放

Optimal

`SetFalloffDistance`

如果是 3D 声音，设置声音变得听不到的距离

my_sound:SetFalloffDistance(falloff_distance)

Parameters

Type	Parameter	Default	Description
float	`falloff_distance`	Required parameter	从内半径起算，声音衰减至完全听不见的距离

`SetInnerRadius`

如果是 3D 音效，设置音量维持 100% 的内半径

my_sound:SetInnerRadius(inner_radius)

Parameters

Type	Parameter	Default	Description
float	`inner_radius`	Required parameter	音量维持 100% 的半径

`SetLowPassFilter`

设置低通滤波器频率。设为 0 以禁用它。

my_sound:SetLowPassFilter(frequency)

Parameters

Type	Parameter	Default	Description
float	`frequency`	Required parameter	新的低通滤波器频率。设为 0 可禁用

`SetPaused`

暂停或恢复播放声音

my_sound:SetPaused(pause?)

Parameters

Type	Parameter	Default	Description
boolean	`pause?`	`true`	是暂停 (true) 还是恢复 (false)

Optimal

`SetPitch`

设置声音的音调

my_sound:SetPitch(new_pitch)

Parameters

Type	Parameter	Default	Description
float	`new_pitch`	Required parameter	声音的新音高

`SetVolume`

设置声音的音量

my_sound:SetVolume(new_volume)

Parameters

Type	Parameter	Default	Description
float	`new_volume`	Required parameter	音量倍率，1 为原始音量

`Stop`

停止声音

my_sound:Stop()

Optimal

`StopDelayed`

在指定的延迟时间后停止声音

my_sound:StopDelayed(delay)

Parameters

Type	Parameter	Default	Description
float	`delay`	Required parameter	停止前等待的秒数

🚀 事件

Inherited Entity Events

Sound inherits from Base Entity Class, sharing it's events:
Base Entityscripting-reference/classes/base-classes/entity

	Name	Description
	`ClassRegister`	当使用继承系统注册一个新类时触发
	`Destroy`	当实体被销毁时触发
	`Spawn`	当实体被生成/创建时触发
	`ValueChange`	当实体通过 `:SetValue()` 改变了值时触发

Inherited Actor Events

Sound inherits from Base Actor Class, sharing it's events:
Base Actorscripting-reference/classes/base-classes/actor

	Name	Description
	`DimensionChange`	当 Actor 改变其维度时触发
	`EnterWater`	当 Actor 进入水体时触发
	`LeaveWater`	当 Actor 离开水体时触发
	`NetworkAuthorityChange`	当 Actor 更改其网络主控玩家时触发
	`NetworkAuthorityChange`	当本地玩家获得或失去对此 Actor 的网络主控时触发

This class doesn't have own events.

🔊 Sound Attenuation（声音衰减）

该属性定义了决定声音随距离衰减速率的函数。有多种不同的函数可供选择：

🔈 Linear（线性）

这是默认函数。使用此函数时，音量将线性衰减，因此当听者靠近或远离声源时，音量的变化是恒定的。该函数适用于大型背景类声音之间的交叉淡入淡出，不需要高度聚焦的 3D 空间衰减设置。

🔈 Logarithmic（对数）

使用此函数时，声音衰减表现为，在近距离时音量变化较大，而在远距离时变化较小。该函数适用于需要良好 3D 定位感的点声源，同时在合理距离内仍清晰听见。

🔈 Inverse（反转）

使用此函数时，音量的变化类似于对数曲线，但更加夸张。该函数适用于只需要在远距离勉强听见，但当听者非常靠近声源时音量会显著增大的声音。

🔈 Log Reverse（反向对数）

使用此函数时，近距离时的音量变化较小，而在远距离时变化更加剧烈。该函数适用于需要在较大距离范围内保持高音量的声音。

🔈 Natural Sound（自然声音）

该函数尝试模拟更“自然”的衰减行为，以产生更符合现实情况的效果。该函数介于对数（Logarithmic）与反比（Inverse）函数之间。

🎒 示例​

🛠 构造函数​

Default Constructor​

Parameters

🗿 静态函数​

🦠 函数​

FadeIn​

Parameters

FadeOut​

Parameters

GetDuration​

Returns

GetFalloffDistance​

Returns

GetInnerRadius​

Returns

GetLowPassFilter​

Returns

GetPath​

Returns

GetPitch​

Returns

GetSoundType​

Returns

GetVolume​

Returns

Is2D​

Returns

IsPlaying​

Returns

Play​

Parameters

SetFalloffDistance​

Parameters

SetInnerRadius​

Parameters

SetLowPassFilter​

Parameters

SetPaused​

Parameters

SetPitch​

Parameters

SetVolume​

Parameters

Stop​

StopDelayed​

Parameters

🚀 事件​

🔊 Sound Attenuation（声音衰减）​

🔈 Linear（线性）​

🔈 Logarithmic（对数）​

🔈 Inverse（反转）​

🔈 Log Reverse（反向对数）​

🔈 Natural Sound（自然声音）​

🎒 示例

🛠 构造函数

Default Constructor

🗿 静态函数

🦠 函数

`FadeIn`

`FadeOut`

`GetDuration`

`GetFalloffDistance`

`GetInnerRadius`

`GetLowPassFilter`

`GetPath`

`GetPitch`

`GetSoundType`

`GetVolume`

`Is2D`

`IsPlaying`

`Play`

`SetFalloffDistance`

`SetInnerRadius`

`SetLowPassFilter`

`SetPaused`

`SetPitch`

`SetVolume`

`Stop`

`StopDelayed`

🚀 事件

🔊 Sound Attenuation（声音衰减）

🔈 Linear（线性）

🔈 Logarithmic（对数）

🔈 Inverse（反转）

🔈 Log Reverse（反向对数）

🔈 Natural Sound（自然声音）