Skip to main content
Version: latest - a1.0.0 ⚖️

🔊 Sound

Class for playing in-game 2D and 3D sounds

info

This is a Client only Class.

tip

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

Usage#

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)

Constructor Parameters#

TypeNameDefaultDescription
VectorlocationVector(0, 0, 0)3D only
SpecialPathasset
booleanis_2D_soundfalse
booleanauto_destroytrueIf to destroy after finished playing
SoundTypesound_typeSoundType.SFXUsed to apply user’s volume settings
numbervolume1
numberpitch1
numberinner_radius4003D only
numberfalloff_distance36003D only
AttenuationFunctionattenuation_functionLinear3D only
booleankeep_playing_when_silentfalse3D only - Whether to keep playing this sound when it’s not audible - Use with caution, it may cause performance issues!
SoundLoopModeloop_modeDefaultLoop Mode (if should force sound to loop)

Functions#

Inherited Actor Functions
Base Actorscripting-reference/classes/base-classes/actor
ReturnsNameDescription
AddImpulseApplies a Force in world coordinate on this Actor
AttachToAttaches this Actor to any other Actor
DestroyDestroys this Actor
DetachDetaches this Actor if attached
SetCollisionSets the actor’s collision type
SetForceAdds a permanent force to this actor
SetGravityEnabledSets the actor’s gravity enabled
SetHighlightEnabledEnables this Actor Highlighting at a specific Index color
SetLifeSpanSets the actor’s life span to be destroyed
SetLocationSets the actor’s location in the game world
SetNetworkAuthoritySets this actor’s new Player Network Authority
SetRelativeLocationSets the actor’s relative location in local space
SetRelativeRotationSets the actor’s relative rotation in local space
SetRotationSets the actor’s rotation in the game world
SetScaleSets the actor’s scale
SetValueSets a value in this entity, which can be accessed by any package
TranslateToSmoothly moves this actor to a Location
RotateToSmoothly rotates this actor to a Rotation
booleanIsGravityEnabledGets the actor’s gravity enabled
booleanIsInWaterGets if the actor is in Water
booleanIsNetworkDistributedGets if the actor is Network Distributed
booleanIsValidReturns if this entity is valid (i.e. not destroyed)
tableGetAttachedEntitiesGets all actors attached to this entity
anyGetAttachedToGets the actor this actor is attached to
tableGetBoundsGets the actor bounds size
numberGetCollisionGets the current actor’s collision
numberGetIDGets the universal network ID of this entity
VectorGetLocationGet the actor’s position in the game world
VectorGetInitialLocationGets the initial location
RotatorGetRotationGets the actor’s rotation in the game world
VectorGetScaleGets the actor’s scale
stringGetTypeReturns the type of this Actor
anyGetValueGets a value given a key
VectorGetVelocityReturns the current actor Velocity
SubscribeSubscribes for an Event
UnsubscribeUnsubscribes from Events
ReturnsNameDescription
FadeInPlays the sound with a fade effect
FadeOutStops the sound with a fade effect
PlayStarts the sound
SetFalloffDistanceIf a 3D Sound, sets the distance which the sound is inaudible
SetInnerRadiusIf a 3D Sound, sets the distance within the volume is 100%
SetLowPassFilterSets lowpass filter frequency. Sets 0 to disable it.
SetPausedPauses the sound
SetPitchSets the Sound’s pitch
SetVolumeSets the Sound’s volume (0 - 1)
StopStops the sound
StopDelayedStops the sound after the provided delay
booleanIsPlayingReturns if the sound is playing
numberGetDurationReturns the duration of sound

Events#

Inherited Actor Events
Base Actorscripting-reference/classes/base-classes/actor
NameDescription
DestroyTriggered when an Entity is Destroyed
SpawnTriggered when an Entity is Spawned/Created
ValueChangeTriggered when an Entity has it’s value changed

FadeIn#

Plays the sound with a fade effect

my_sound:FadeIn(fade_in_duration, fade_volume_level, start_time)
TypeParameterDefault ValueDescription
numberfade_in_duration
numberfade_volume_level1
numberstart_time0

FadeOut#

Stops the sound with a fade effect

my_sound:FadeOut(fade_out_duration, fade_volume_level, destroy_after_fadeout)
TypeParameterDefault ValueDescription
numberfade_out_duration
numberfade_volume_level0
booleandestroy_after_fadeoutfalse

Play#

Starts the sound

my_sound:Play(start_time)
TypeParameterDefault ValueDescription
numberstart_time0

SetFalloffDistance#

If a 3D Sound, sets the distance which the sound is inaudible

my_sound:SetFalloffDistance(falloff_distance)
TypeParameterDescription
numberfalloff_distance

SetInnerRadius#

If a 3D Sound, sets the distance within the volume is 100%

my_sound:SetInnerRadius(inner_radius)
TypeParameterDescription
numberinner_radius

SetLowPassFilter#

Sets lowpass filter frequency. Sets 0 to disable it.

my_sound:SetLowPassFilter(frequency)
TypeParameterDescription
numberfrequency

SetPaused#

Pauses the sound

my_sound:SetPaused(pause)
TypeParameterDefault ValueDescription
booleanpausetrue

SetPitch#

Sets the Sound's pitch

my_sound:SetPitch(new_pitch)
TypeParameterDescription
numbernew_pitch

SetVolume#

Sets the Sound's volume (0 - 1)

my_sound:SetVolume(new_volume)
TypeParameterDescription
numbernew_volume

Stop#

Stops the sound

my_sound:Stop()

StopDelayed#

Stops the sound after the provided delay

my_sound:StopDelayed(delay)
TypeParameterDescription
numberdelay

IsPlaying#

Gets if the sound is playing

Returns boolean

my_sound:IsPlaying()

GetDuration#

Gets the duration of the Sound.

Returns number

my_sound:GetDuration()

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.