🔊 声音

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

---

💂Authority

This class can only be spawned on 🟧 Client side.

🔁Network Authority Distribution

This class can't be Network Authority distributed.

👪Inheritance

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

🧑‍💻API Source

This page is auto-generated! The Functions, Properties and Events described here are defined in our GitHub's API Repository! Feel free to commit suggestions and changes to the source .json API files!

---

提示

You can also load raw .ogg files from disk! Please check SpecialPath.

🎒 示例

local my_sound = Sound(
    Vector(-510, 145, 63), -- Location (if a 3D sound)
    "nanos-world::A_VR_Confirm", -- Asset Path
    false, -- Is 2D Sound
    true, -- Auto Destroy (if to destroy after finished playing)
    SoundType.SFX,
    1, -- Volume
    1 -- Pitch
)

-- Spawning a ogg sound located in a Package
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	No description provided
float	pitch	1	No description provided
float	inner_radius	400	仅在 3D 声音时使用
float	falloff_distance	3600	仅在 3D 声音时使用
AttenuationFunction	attenuation_function	Linear	仅在 3D 声音时使用
boolean	keep_playing_when_silent	false	仅在 3D 声音时使用 - 请谨慎使用，这可能会导致性能问题！
SoundLoopMode	loop_mode	Default	是否应强制声音循环播放
boolean	auto_play	true	加载后是否应立即播放

备注

auto_destroy means the Entity will be immediately destroyed after spawned, losing references to the Sound spawned in-game. So if the Sound itself loops indefinitely, it will keep playing until the Player reconnects.

🗿 静态函数

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	完成生成过程，如果实体是通过 defer_spawn 生成的，则将实体发送给客户端
	table of string	GetAllValuesKeys	获取所有值键的列表
	table	GetClass	获取该实体的类
	integer	GetID	获取该实体的全网通用网络 ID（在客户端和服务器上相同）
	any	GetValue	获取此实体上存储在给定键处的 值
	boolean	HasAuthority	获取本地上下文是否对此实体拥有主控（如果由客户端生成则为 true，由服务器生成则为 false）
	boolean	IsA	递归检查此实体是否继承自某个类
	boolean	IsBeingDestroyed	如果该实体正在被销毁，则返回 true
	boolean	IsValid	如果该实体有效（即未被销毁且指向一个有效的实体），则返回 true
		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() 设置）
	table of Base Actor	GetAttachedEntities	获取附加到该 Actor 的所有 Actor
	Base Actor or nil	GetAttachedTo	获取该 Actor 所附加到的父级 Actor
	table	GetBounds	获取该 Actor 的边界范围
	CollisionType	GetCollision	获取该 Actor 的碰撞类型
	integer	GetDimension	获取该 Actor 的维度
	float	GetDistanceFromCamera	获取该 Actor 距离相机的距离
	Vector	GetForce	获取该 Actor 的持续外力（由 SetForce() 设置）
	Vector	GetLocation	获取该 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 的维度
		SetDistanceOptimizationMultiplier	设置此 Actor 的距离优化系数
		SetForce	Adds a permanent force to this Actor, set to Vector(0, 0, 0) to cancel
		SetGravityEnabled	Sets whether gravity is enabled on this Actor
		SetHighlightEnabled	Sets whether the highlight is enabled on this Actor, and which highlight index to use
		SetLifeSpan	Sets the time (in seconds) before this Actor is destroyed. After this time has passed, the actor will be automatically destroyed.
		SetLocation	Sets this Actor's location in the game world
		SetNetworkAuthority	Sets the Player to have network authority over this Actor
		SetNetworkAuthorityAutoDistributed	Sets if this Actor will auto distribute the network authority between players
		SetOutlineEnabled	Sets whether the outline is enabled on this Actor, and which outline index to use
		SetRelativeLocation	Sets this Actor's relative location in local space (only if this actor is attached)
		SetRelativeRotation	Sets this Actor's relative rotation in local space (only if this actor is attached)
		SetRenderCullDistance	Sets this Actor's render cull distance
		SetRotation	Sets this Actor's rotation in the game world
		SetScale	Sets this Actor's scale
		SetVisibility	Sets whether the actor is visible or not
		TranslateTo	Smoothly moves this actor to a location over a certain time
	boolean	WasRecentlyRendered	Gets if this Actor was recently rendered on screen

	Returns	Name	Description
		FadeIn	使用淡入效果播放声音
		FadeOut	使用淡出效果停止声音
	float	GetDuration	获取声音的时长
	float	GetFalloffDistance	No description provided
	float	GetInnerRadius	No description provided
	float	GetLowPassFilter	No description provided
	string	GetPath	No description provided
	float	GetPitch	No description provided
	SoundType	GetSoundType	No description provided
	float	GetVolume	No description provided
	boolean	Is2D	获取声音是否为 2D 声音
	boolean	IsPlaying	获取声音是否正在播放
		Play	开始播放声音
		SetFalloffDistance	如果是 3D 声音，设置声音变得听不到的距离
		SetInnerRadius	如果是 3D 声音，设置音量保持在 100% 以内的距离
		SetLowPassFilter	设置低通滤波器频率。设为 0 以禁用它。
		SetPaused	暂停声音
		SetPitch	设置声音的音调
		SetVolume	设置声音的音量
		Stop	停止声音
		StopDelayed	在指定的延迟时间后停止声音

---

FadeIn

使用淡入效果播放声音

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

Parameters

Type	Parameter	Default	Description
float	fade_in_duration	Required parameter	No description provided
float	fade_volume_level?	1.0	No description provided
float	start_time?	0.0	No description provided

---

FadeOut

使用淡出效果停止声音

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

Parameters

Type	Parameter	Default	Description
float	fade_out_duration	Required parameter	No description provided
float	fade_volume_level?	0.0	No description provided
boolean	destroy_after_fadeout?	false	No description provided

---

GetDuration

获取声音的时长

local duration = my_sound:GetDuration()

Returns

Type	Description
float	duration

---

GetFalloffDistance

local falloff_distance = my_sound:GetFalloffDistance()

Returns

Type	Description
float	falloff_distance

See also SetFalloffDistance.

---

GetInnerRadius

local inner_radius = my_sound:GetInnerRadius()

Returns

Type	Description
float	inner_radius

See also SetInnerRadius.

---

GetLowPassFilter

local frequency = my_sound:GetLowPassFilter()

Returns

Type	Description
float	frequency

See also SetLowPassFilter.

---

GetPath

local path = my_sound:GetPath()

Returns

Type	Description
string	path

---

GetPitch

local pitch = my_sound:GetPitch()

Returns

Type	Description
float	pitch

See also SetPitch.

---

GetSoundType

local sound_type = my_sound:GetSoundType()

Returns

Type	Description
SoundType	sound_type

---

GetVolume

local volume = my_sound:GetVolume()

Returns

Type	Description
float	volume

See also SetVolume.

---

Is2D

获取声音是否为 2D 声音

local is_2D_sound = my_sound:Is2D()

Returns

Type	Description
boolean	is_2D_sound

---

IsPlaying

获取声音是否正在播放

local is_playing = my_sound:IsPlaying()

Returns

Type	Description
boolean	is_playing

---

Play

开始播放声音

my_sound:Play(start_time?)

Parameters

Type	Parameter	Default	Description
float	start_time?	0.0	No description provided

---

SetFalloffDistance

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

my_sound:SetFalloffDistance(falloff_distance)

Parameters

Type	Parameter	Default	Description
float	falloff_distance	Required parameter	No description provided

See also GetFalloffDistance.

---

SetInnerRadius

如果是 3D 声音，设置音量保持在 100% 以内的距离

my_sound:SetInnerRadius(inner_radius)

Parameters

Type	Parameter	Default	Description
float	inner_radius	Required parameter	No description provided

See also GetInnerRadius.

---

SetLowPassFilter

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

my_sound:SetLowPassFilter(frequency)

Parameters

Type	Parameter	Default	Description
float	frequency	Required parameter	No description provided

See also GetLowPassFilter.

---

SetPaused

暂停声音

my_sound:SetPaused(pause?)

Parameters

Type	Parameter	Default	Description
boolean	pause?	true	No description provided

---

SetPitch

设置声音的音调

my_sound:SetPitch(new_pitch)

Parameters

Type	Parameter	Default	Description
float	new_pitch	Required parameter	No description provided

See also GetPitch.

---

SetVolume

设置声音的音量

my_sound:SetVolume(new_volume)

Parameters

Type	Parameter	Default	Description
float	new_volume	Required parameter	范围从 0.0 到 1.0

See also GetVolume.

---

Stop

停止声音

my_sound:Stop()

---

StopDelayed

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

my_sound:StopDelayed(delay)

Parameters

Type	Parameter	Default	Description
float	delay	Required parameter	No description provided

🚀 事件

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 改变其维度时触发

This class doesn't have own events.

🔊 Sound Attenuation

This property defines the function that determines the rate of attenuation over distance. There are a number of different functions to choose from:

🔈 Linear

This is the default function. When using this function the volume will attenuate linearly and so the changes in volume are constant as the listener moves towards and away from the source. This function is good for crossfading between large background-type sounds that don't need tightly focussed 3D spatial falloff settings.

🔈 Logarithmic

When using this function the volume attenuates such that the changes in volume are greater at close distances, and lesser at far distances. This function is good for spot sounds that need good 3D positioning, while still being audible at reasonable distances.

🔈 Inverse

When using this function, the changes in volume are similar to that of the logarithmic curve, but are more exaggerated. This function is good for sounds that only need to be just audible at far distances, but that gets significantly louder as the listener gets quite close to the source.

🔈 Log Reverse

When using this function, the changes in volume are lesser at close distances, with more dramatic differences at far distances. This function is good for sounds that need to be loud across larger distances.

🔈 Natural Sound

This function attempts to model a more 'naturalistic' falloff behavior to produce behaviors that closer match reality. This function is a kind of 'middle ground' between the Logarithmic and Inverse functions.