🔊 Sound
Class for playing in-game 2D and 3D sounds
info
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
| Type | Name | Default | Description |
|---|---|---|---|
| Vector | location | Vector(0, 0, 0) | 3D only |
| Sound Asset or Special Path | asset | `` | The Sound Asset or Special Path |
| boolean | is_2D_sound | false | |
| boolean | auto_destroy | true | If to destroy after finished playing |
| SoundType | sound_type | SoundType.SFX | Used to apply user's volume settings |
| number | volume | 1 | |
| number | pitch | 1 | |
| number | inner_radius | 400 | 3D only |
| number | falloff_distance | 3600 | 3D only |
| AttenuationFunction | attenuation_function | Linear | 3D only |
| boolean | keep_playing_when_silent | false | 3D only - Whether to keep playing this sound when it's not audible - Use with caution, it may cause performance issues! |
| SoundLoopMode | loop_mode | Default | Loop Mode (if should force sound to loop) |
Functions
Inherited Actor Functions
| Returns | Name | Description | |
|---|---|---|---|
 | AddImpulse | Applies a Force in world space to this Actor | |
| AttachTo | Attaches this Actor to another Actor | |
| Destroy | Destroys this Actor | |
| Detach | Detaches this Actor if attached | |
| SetCollision | Sets this Actor's collision type | |
| SetForce | Adds a permanent force to this Actor | |
| SetGravityEnabled | Sets whether gravity is enabled on this Actor | |
 | SetVisibility | Sets the Actor visibility | |
 | SetHighlightEnabled | Sets whether the highlight is enabled on this Actor, and which highlight index to use | |
| SetOutlineEnabled | Sets whether the outline is enabled on this Actor, and which outline index to use | |
| SetLifeSpan | Sets the time (in seconds) before this Actor is destroyed | |
| SetLocation | Sets this Actor's location in the game world | |
 | SetNetworkAuthority | Sets the Player this Actor will have its physics calculated on Network Authority | |
| SetRelativeLocation | Sets this Actor's relative location in local space | |
| SetRelativeRotation | Sets this Actor's relative rotation in local space | |
| SetRotation | Sets this Actor's rotation in the game world | |
| SetScale | Sets this Actor's scale | |
| SetValue | Sets a value in this Actor, which can be accessed by any package | |
| TranslateTo | Smoothly moves this Actor to the specified location | |
| RotateTo | Smoothly rotates this Actor to the specified angle | |
| boolean | HasNetworkAuthority | Gets if the LocalPlayer is currently the Network Authority of this Actor |
| boolean | HasAuthority | Gets if this Actor was spawned by the client side |
| boolean | IsBeingDestroyed | Gets if this Actor is being destroyed |
| boolean | IsGravityEnabled | Gets whether gravity is enabled on this Actor |
| boolean | IsVisible | Gets whether this actor is Visible or not |
| boolean | IsInWater | Gets if this Actor is in water |
| boolean | IsNetworkDistributed | Gets if this Actor is currently Network Distributed |
| boolean | IsValid | Returns if this Actor is valid (i.e. not destroyed) |
| table | GetAttachedEntities | Gets all Actors attached to this Actor |
| any | GetAttachedTo | Gets the Actor this Actor is attached to |
| table | GetBounds | Gets this Actor's bounds |
| number | GetCollision | Gets this Actor's collision type |
| number | GetID | Gets the universal network ID of this Actor |
| Vector | GetLocation | Gets this Actor's location in the game world |
| Rotator | GetRotation | Gets this Actor's angle in the game world |
| Vector | GetForce | Gets this Actor's scale |
| Vector | GetScale | Gets this Actor's scale |
| string | GetType | Gets the type of this Actor |
| any | GetValue | Gets a value stored on this Actor at the given key |
| Vector | GetVelocity | Returns this Actor's current velocity |
| string | AddActorTag | Adds an Unreal Actor Tag to this Actor |
| string | RemoveActorTag` | Remove an Unreal Actor Tag from this Actor |
| table | GetActorTags | Gets all Unreal Actor Tags from this Actor |
| function | Subscribe | Subscribes to an Event |
| Unsubscribe | Unsubscribes from an Event |
| Returns | Name | Description |
|---|---|---|
FadeIn | Plays the sound with a fade effect | |
FadeOut | Stops the sound with a fade effect | |
Play | Starts the sound | |
SetFalloffDistance | If a 3D Sound, sets the distance which the sound is inaudible | |
SetInnerRadius | If a 3D Sound, sets the distance within the volume is 100% | |
SetLowPassFilter | Sets lowpass filter frequency. Sets 0 to disable it. | |
SetPaused | Pauses the sound | |
SetPitch | Sets the Sound's pitch | |
SetVolume | Sets the Sound's volume (0 - 1) | |
Stop | Stops the sound | |
StopDelayed | Stops the sound after the provided delay | |
| boolean | Is2D | Returns if the sound is 2D |
| boolean | IsPlaying | Returns if the sound is playing |
| number | GetDuration | Returns the duration of sound |
| number | GetPitch | Returns the pitch |
| number | GetVolume | Returns the volume |
| number | GetLowPassFilter | Returns the Low Pass Filter Frequency |
| number | GetInnerRadius | Returns the Attenuation Inner Radius |
| number | GetFalloffDistance | Returns the Attenuation Falloff Distance |
| SoundType | GetSoundType | Returns the Sound Type |
Events
Inherited Actor Events
| Name | Description | |
|---|---|---|
Destroy | Triggered when an Actor is destroyed | |
Spawn | Triggered when an Actor is spawned/created | |
ValueChange | Triggered when an Actor has a value changed with :SetValue() |
FadeIn
Plays the sound with a fade effect
my_sound:FadeIn(fade_in_duration, fade_volume_level, start_time)
| Type | Parameter | Default Value | Description |
|---|---|---|---|
| number | fade_in_duration | ||
| number | fade_volume_level | 1 | |
| number | start_time | 0 |
FadeOut
Stops the sound with a fade effect
my_sound:FadeOut(fade_out_duration, fade_volume_level, destroy_after_fadeout)
| Type | Parameter | Default Value | Description |
|---|---|---|---|
| number | fade_out_duration | ||
| number | fade_volume_level | 0 | |
| boolean | destroy_after_fadeout | false |
Play
Starts the sound
my_sound:Play(start_time)
| Type | Parameter | Default Value | Description |
|---|---|---|---|
| number | start_time | 0 |
SetFalloffDistance
If a 3D Sound, sets the distance which the sound is inaudible
my_sound:SetFalloffDistance(falloff_distance)
| Type | Parameter | Description |
|---|---|---|
| number | falloff_distance |
SetInnerRadius
If a 3D Sound, sets the distance within the volume is 100%
my_sound:SetInnerRadius(inner_radius)
| Type | Parameter | Description |
|---|---|---|
| number | inner_radius |
SetLowPassFilter
Sets lowpass filter frequency. Sets 0 to disable it.
my_sound:SetLowPassFilter(frequency)
| Type | Parameter | Description |
|---|---|---|
| number | frequency |
SetPaused
Pauses the sound
my_sound:SetPaused(pause)
| Type | Parameter | Default Value | Description |
|---|---|---|---|
| boolean | pause | true |
SetPitch
Sets the Sound's pitch
my_sound:SetPitch(new_pitch)
| Type | Parameter | Description |
|---|---|---|
| number | new_pitch |
SetVolume
Sets the Sound's volume (0 - 1)
my_sound:SetVolume(new_volume)
| Type | Parameter | Description |
|---|---|---|
| number | new_volume |
Stop
Stops the sound
my_sound:Stop()
StopDelayed
Stops the sound after the provided delay
my_sound:StopDelayed(delay)
| Type | Parameter | Description |
|---|---|---|
| number | delay |
Is2D
Gets if the sound is 2D
Returns boolean
my_sound:Is2D()
IsPlaying
Gets if the sound is playing
Returns boolean
my_sound:IsPlaying()
GetDuration
Gets the duration of the Sound.
Returns number
my_sound:GetDuration()
GetPitch
Returns number
my_sound:GetPitch()
GetVolume
Returns number
my_sound:GetVolume()
GetLowPassFilter
Returns number
my_sound:GetLowPassFilter()
GetInnerRadius
Returns number
my_sound:GetInnerRadius()
GetFalloffDistance
Returns number
my_sound:GetFalloffDistance()
GetSoundType
Returns number
my_sound:GetSoundType()
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.