hakowork/rojo
3
0
Fork 0
mirror of https://github.com/rojo-rbx/rojo.git synced 2026-10-25 04:54:07 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

update rules

Browse source
This commit is contained in:
Joe 2026-02-02 14:05:11 -06:00
parent 4c390fdd37
commit d5522b2fef
8549 changed files with 11783 additions and 1888 deletions
Download patch file Download diff file Expand all files Collapse all files

218
.cursor/rules/roblox/en-us/sound/dynamic-effects.md Normal file
View file

@ -0,0 +1,218 @@
---
title: Dynamic effects
description: Legacy effects that modify or enhance Sound objects in your experiences.
---
<Alert severity = 'warning'>
There is a newer set of audio effects that offer more control and address robust use cases. For more information, see [Audio effects](../audio/effects.md).
</Alert>
Dynamic effects modify or enhance the audio of individual `Class.Sound` objects or an entire `Class.SoundGroup`. You can apply these effects to make your audio more immersive within your experience, such as using `Class.ReverbSoundEffect` in large rooms to make them feel massive.
## Apply dynamic effects
Each dynamic effect you apply has additional properties you can adjust until you achieve the type of sound you desire. For more information on these properties, see each dynamic effect's API page.
To apply a dynamic effect:
1. In the **Explorer** window, insert a new dynamic effect into a `Class.Sound` or `Class.SoundGroup` object.
1. Hover over the object and click the ⊕ button. A contextual menu displays.
2. From the menu, insert a **dynamic effect**.
<img src="../assets/studio/explorer/SoundService-SoundGroup-ReverbSoundEffect.png" width="320" />
2. **(Optional)** In the **Properties** window, select the new dynamic effect and adjust its properties.
<img src="../assets/audio/sound-groups/Dynamic-Effect-Properties.png" width="320" />
## Types
### Equalizer
The `Class.EqualizerSoundEffect` allows for control of the volume of various frequency ranges. This dynamic effect is useful to highlight or minimize particular elements of audio, such as muffling all audio in your experience when a user goes underwater.
<table>
<tbody>
<tr>
<td><audio controls>
<source src="../assets/audio/dynamic-effects/no-effect.mp3" type="audio/mpeg"></source>
</audio></td>
<td><audio controls>
<source src="../assets/audio/dynamic-effects/equalizer.mp3" type="audio/mpeg"></source>
</audio></td>
</tr>
<tr>
<td>Audio without effect</td>
<td>Audio with equalizer</td>
</tr>
</tbody>
</table>
### Compressor
The `Class.CompressorSoundEffect` reduces the dynamic range of audio by lowering the volume of the highest parts of a source while at the same time raising the overall volume. This dynamic effect is useful to set a consistent volume for users to hear even if you record audio while whispering or speaking loudly. You can also use this dynamic effect to prioritize sounds from one `Class.SoundGroup` over another through the process of ducking. For more information, see [Ducking](../sound/groups.md#ducking).
<table>
<tbody>
<tr>
<td><audio controls>
<source src="../assets/audio/dynamic-effects/no-effect.mp3" type="audio/mpeg"></source>
</audio></td>
<td><audio controls>
<source src="../assets/audio/dynamic-effects/compressor.mp3" type="audio/mpeg"></source>
</audio></td>
</tr>
<tr>
<td>Audio without effect</td>
<td>Audio with compressor</td>
</tr>
</tbody>
</table>
### Reverb
The `Class.ReverbSoundEffect` simulates the effect of sounds bouncing off of several surfaces. This dynamic effect is useful to simulate more realistic reflections of sounds in interior spaces, such as bouncing a basketball inside a gymnasium, or playing rock music in a stadium.
<table>
<tbody>
<tr>
<td><audio controls>
<source src="../assets/audio/dynamic-effects/no-effect.mp3" type="audio/mpeg"></source>
</audio></td>
<td><audio controls>
<source src="../assets/audio/dynamic-effects/reverb.mp3" type="audio/mpeg"></source>
</audio></td>
</tr>
<tr>
<td>Audio without effect</td>
<td>Audio with reverb</td>
</tr>
</tbody>
</table>
### Chorus
The `Class.ChorusSoundEffect` simulates the effect of multiple vocals or instruments playing simultaneously by taking the original sound and overlaying copies, each with slight variations in pitch. This dynamic effect is useful for simulating a robotic or futuristic quality to your audio.
<table>
<tbody>
<tr>
<td><audio controls>
<source src="../assets/audio/dynamic-effects/no-effect.mp3" type="audio/mpeg"></source>
</audio></td>
<td><audio controls>
<source src="../assets/audio/dynamic-effects/chorus.mp3" type="audio/mpeg"></source>
</audio></td>
</tr>
<tr>
<td>Audio without effect</td>
<td>Audio with chorus</td>
</tr>
</tbody>
</table>
### Distortion
The `Class.DistortionSoundEffect` simulates the effect that would occur when overdriving older style audio equipment. This dynamic effect causes clipping in the sound and adds a general "fuzziness", which is useful for either adding intensity and character to musical instruments.
<table>
<tbody>
<tr>
<td><audio controls>
<source src="../assets/audio/dynamic-effects/no-effect.mp3" type="audio/mpeg"></source>
</audio></td>
<td><audio controls>
<source src="../assets/audio/dynamic-effects/distortion.mp3" type="audio/mpeg"></source>
</audio></td>
</tr>
<tr>
<td>Audio without effect</td>
<td>Audio with distortion</td>
</tr>
</tbody>
</table>
### Echo
The `Class.EchoSoundEffect` causes a sound to repeat on a delay with diminishing volume, simulating the real effect of an echo that bounces off of hard surfaces, such as walls and caves.
<table>
<tbody>
<tr>
<td><audio controls>
<source src="../assets/audio/dynamic-effects/no-effect.mp3" type="audio/mpeg"></source>
</audio></td>
<td><audio controls>
<source src="../assets/audio/dynamic-effects/echo.mp3" type="audio/mpeg"></source>
</audio></td>
</tr>
<tr>
<td>Audio without effect</td>
<td>Audio with echo</td>
</tr>
</tbody>
</table>
### Flange
The `Class.FlangeSoundEffect` creates a sweeping or whooshing effect by copying the original audio signal and playing it slightly offset and modulated on top of the original. This dynamic effect is useful for adding strange, otherworldly digital quality to your audio. For example, you can use it on an air conditioner recording to make a sci-fi spaceship engine rumble.
<table>
<tbody>
<tr>
<td><audio controls>
<source src="../assets/audio/dynamic-effects/no-effect.mp3" type="audio/mpeg"></source>
</audio></td>
<td><audio controls>
<source src="../assets/audio/dynamic-effects/flange.mp3" type="audio/mpeg"></source>
</audio></td>
</tr>
<tr>
<td>Audio without effect</td>
<td>Audio with flange</td>
</tr>
</tbody>
</table>
### Pitch Shift
The `Class.PitchShiftSoundEffect` raises or lowers pitch without changing the playback speed. This dynamic effect is useful for changing the scale of your sounds. You can use it to make small sounds feel huge by pitching them down or conversely pitch sounds up to make an explosion sound more like a balloon pop.
<table>
<tbody>
<tr>
<td><audio controls>
<source src="../assets/audio/dynamic-effects/no-effect.mp3" type="audio/mpeg"></source>
</audio></td>
<td><audio controls>
<source src="../assets/audio/dynamic-effects/pitch-shift.mp3" type="audio/mpeg"></source>
</audio></td>
</tr>
<tr>
<td>Audio without effect</td>
<td>Audio with pitch shift</td>
</tr>
</tbody>
</table>
### Tremolo
The `Class.TremoloSoundEffect` creates a trembling effect on a sound by varying its volume up and down. This dynamic effect is useful to transform instrument sounds into a wavy, dreamlike quality, or to create swells and dips in weather-related audio.
<table>
<tbody>
<tr>
<td><audio controls>
<source src="../assets/audio/dynamic-effects/no-effect.mp3" type="audio/mpeg"></source>
</audio></td>
<td><audio controls>
<source src="../assets/audio/dynamic-effects/tremolo.mp3" type="audio/mpeg"></source>
</audio></td>
</tr>
<tr>
<td>Audio without effect</td>
<td>Audio with tremolo</td>
</tr>
</tbody>
</table>

112
.cursor/rules/roblox/en-us/sound/groups.md Normal file
View file

@ -0,0 +1,112 @@
---
title: Sound groups
description: Legacy audio mixers that group multiple Sound objects so you can control the properties of multiple audio signals at once.
---
<Alert severity = 'warning'>
`Class.SoundGroup` objects are now discouraged in favor of the more robust functionality of audio objects. For more information, see [Audio objects](../audio/objects.md).
</Alert>
A `Class.SoundGroup` is an **audio mixer** that groups multiple audio objects, such as `Class.Sound` objects or additional `Class.SoundGroup|SoundGroups`, allowing you to control the volume and dynamic effects properties of multiple audio signals at once. Useful applications include:
- [Assigning audio](#assign-audio-objects-to-sound-groups) to **SoundEffects** and **BackgroundMusic** sound groups so that you can adjust each group's master volume for optimal audio balancing.
- [Nesting sound groups](#nest-sound-groups) into meaningful categories under a mix tree.
- Grouping all sounds that need a specific [dynamic effect](../sound/dynamic-effects.md). For example, you can group all sounds inside a cave to a **Cave** sound group, then apply a `Class.ReverbSoundEffect` to simulate the sounds reflecting off of the cave's environment.
When creating `Class.SoundGroup|SoundGroups`, it's best to keep them all in a single location for organizational purposes as you continue to add and edit audio within your experience. The following example stores the new `Class.SoundGroup` under `Class.SoundService`, as this service determines how `Class.Sound` objects play in experiences.
## Create sound groups
To create a `Class.SoundGroup`:
1. In the **Explorer** window, hover over `Class.SoundService` and click the ⊕ button. A contextual menu displays.
2. From the menu, insert a `Class.SoundGroup`.
<img src="../assets/studio/explorer/SoundService-SoundGroup.png" width="320" />
3. Triple-click the new sound group and rename it according to its purpose, such as **SoundEffects** or **BackgroundMusic**.
## Assign audio objects to sound groups
`Class.SoundGroup|SoundGroups` don't have the typical parent-child behavior of other forms of object grouping like `Class.Model|Models` and `Class.Folder|Folders`. Instead, you must **assign** each `Class.Sound` object to its applicable `Class.SoundGroup` object, regardless of either object's location in the workspace hierarchy, because where you place the `Class.Sound` object changes where audio emits from, not the `Class.SoundGroup` object itself. For more information, see [sound objects](../sound/objects.md).
To assign a `Class.Sound` object to a `Class.SoundGroup`:
1. In the **Explorer** window, select a sound object.
2. In the **Properties** window, click the **SoundGroup** property field. Your cursor changes.
3. In the **Explorer** window, click on the sound group object you want to assign your sound object to. The sound object's **SoundGroup** property updates accordingly.
<img src="../assets/studio/properties/Sound-SoundGroup.png" width="320" />
## Nest sound groups
You can nest `Class.SoundGroup|SoundGroups` together into meaningful categories under a mix tree for organization and scripting purposes. When you're planning the parent-child relationships in your mix, consider the different sound categories in your experience, and how important they should be for the listener. For example, player ability sounds are likely much more important to gameplay than environmental sounds. If you group them into separate parent `Class.SoundGroup|SoundGroups`, you can easily access and [adjust their volume levels](#adjust-volume) as you add more `Class.Sound` objects to your experience.
To nest `Class.SoundGroup|SoundGroups`:
1. In the **Explorer** window, click-and-drag a sound group over the sound group you want to nest it under. The sound group name becomes translucent, and your cursor changes to a plus icon.
2. Drop the sound group. It displays as a child of the sound group you nested it under.
## Adjust volume
There are two main ways to think about a sound's volume: how loud the sound is by itself, and how loud it is in relation to other sounds. For example, a waterfall sounds loud when you play it by itself, but when you compare it to other sound effects like tires screeching, it likely sounds much quieter. To ensure that each sound plays at the correct volume for your experience, you can either [add multipliers](#add-multipliers) to `Class.SoundGroup|SoundGroups`, or prioritize audio from one `Class.SoundGroup` over another through the process of [ducking](#ducking).
### Add multipliers
The `Class.SoundGroup.Volume|Volume` property of a `Class.SoundGroup` lets you apply a **volume multiplier** between `0` and `10` to each of its child audio objects while they retain their relative volumes. This means that if a `Class.Sound` object has a volume of `0.5` and you child it to a `Class.SoundGroup` that has a volume multiplier of `0.5`, the effective volume of the `Class.Sound` object is `0.25`.
This property is useful when you want to test volume changes to different `Class.SoundGroup|SoundGroups` without having to manually change the volume of each `Class.Sound` object. For example, if you want to check what it'd sound like to increase the volume of all of your experience's music, you can create a **Music** `Class.SoundGroup` for every musical `Class.Sound` object or `Class.SoundGroup`, then apply a volume multiplier of `2`.
### Ducking
You can prioritize audio from one `Class.SoundGroup` over another through the `Class.CompressorSoundEffect`. This dynamic effect allows you to **duck**, or reduce in volume, `Class.Sound` objects in low-priority `Class.SoundGroup|SoundGroups` whenever `Class.Sound` objects in high-priority `Class.SoundGroup|SoundGroups` start to play. This allows the listener to concentrate on the specific audio that you want them to pay attention to while not suddenly cutting the audio from low-priority sounds completely. When the high-priority audio finishes playing, low-priority audio returns to its original volume, keeping the listener immersed in your experience.
The sounds that you choose to duck depend on the needs of your specific experience. For example, one experience might benefit from reducing the volume of background music whenever a GUI notification plays, while others might benefit from reducing the volume of GUI notifications whenever dialogue plays. The following reference mix tree prioritizes `Class.Sound` objects in the high-priority **GUI Notifications** and **Weapons** `Class.SoundGroup|SoundGroups` while de-prioritizing `Class.Sound` objects in low-priority **3D** and **2D Ambience** `Class.SoundGroup|SoundGroups`.
<img src="../assets/audio/sound-groups/Mix-Tree.png" width="182" />
The `Class.CompressorSoundEffect` has four main properties you must set in order to duck audio whenever your high priority audio plays:
<table>
<thead>
<tr>
<th>Property</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>`Class.CompressorSoundEffect.Threshold|Threshold`</td>
<td>The threshold decibel level that Studio applies ducking. You can set this property to any value between `-80` (full compression) and `0` (full volume).</td>
</tr>
<tr>
<td>`Class.CompressorSoundEffect.Attack|Attack`</td>
<td>The rate you want audio to duck. You can set this property to any value between `0.001` and `1` second.</td>
</tr>
<tr>
<td>`Class.CompressorSoundEffect.Release|Release`</td>
<td>The rate you want the audio to stop ducking. You can set this property to any value between `0.001` and `1` second.</td>
</tr>
<tr>
<td>`Class.CompressorSoundEffect.Ratio|Ratio`</td>
<td>The ratio of how much ducking you want to occur between the audio object that Studio prioritizes and the audio object that ducks. You can set this property to any value between `1` (no compression) and `50` (fifty times the compression).</td>
</tr>
</tbody>
</table>
The values of each of these properties are highly dependent on your specific audio. Each source audio has a different volume, and you might only need to duck by a minimal amount in order for your high priority audio to have emphasis in your experience.
To prioritize `Class.SoundGroup|SoundGroups` through the `Class.CompressorSoundEffect`:
1. In the **Explorer** window, navigate to the SoundGroup you want to duck and insert a CompressorSoundEffect.
1. Hover over the **SoundGroup** and click the ⊕ button. A contextual menu displays.
1. From the menu, insert a **CompressorSoundEffect**.
2. Select the **CompressorSoundEffect**, then navigate to the **Properties** window.
3. Select the **SideChain** property. Your cursor changes.
4. Select the **Sound** or **SoundGroup** object that you want to prioritize when the compressor applies. The **SideChain** property updates accordingly.
5. In the **Threshold property** field, input the decibel level in which you want the ducking to start.
6. In the **Attack** property field, input how quickly you want audio to duck.
7. In the **Release** property field, input how quickly you want the audio to stop ducking.
8. In the **Ratio** property field, input the ratio of how much compression you want to occur between the audio object that ducks and the audio object that Studio prioritizes.
9. **(Optional)** Play test your experience to see if the audio sounds correct. If not, adjust the **CompressorSoundEffect** properties accordingly.

24
.cursor/rules/roblox/en-us/sound/index.md Normal file
View file

@ -0,0 +1,24 @@
---
title: Sound
description: An overview of legacy Sound objects and effects.
---
<Alert severity = 'warning'>
There is a newer set of [audio objects](../audio/objects.md) and [effects](../audio/effects.md) that offer more control and address robust use cases. For more information, see [Audio](../audio/index.md).
</Alert>
Sound effects and music enhance your experiences and make them more immersive. You can import your own [audio assets](../audio/assets.md) or search for free-to-use audio in the [Creator Store](../production/creator-store.md), play audio through `Class.Sound` or objects, and enhance audio playback through [dynamic effects](#dynamic-effects).
## Sound objects
A [sound object](../sound/objects.md) emits audio within an experience. Roblox assigns each [audio asset](../audio/assets.md) a unique ID that you can assign to `Class.Sound` objects to play a specific sound effect or music track. You can either set this audio to play automatically at runtime, or trigger it to play from scripts.
The location of where you place a `Class.Sound` object in the [Explorer](../studio/explorer.md) hierarchy affects how users hear audio. If you want users to only hear audio near a specific position, you must parent the `Class.Sound` object to a 3D object or `Class.Attachment` to behave as positional audio. If you want users to hear audio regardless of their position, you must insert the `Class.Sound` object directly into `Class.Workspace` or `Class.SoundService` to behave as background audio.
## Sound groups
A [sound group](../sound/groups.md) acts as an audio mixer for multiple audio objects, such as `Class.Sound` objects or additional `Class.SoundGroup|SoundGroups`, allowing you to control the volume and dynamic effects properties of multiple audio signals at once.
## Dynamic effects
[Dynamic effects](../sound/dynamic-effects.md) modify or enhance the audio of individual `Class.Sound` objects or an entire `Class.SoundGroup`. You can apply these effects to make audio more immersive within the experience, such as using `Class.EqualizerSoundEffect` to make rain sound muffled, `Class.CompressorSoundEffect` to control a sound's maximum volume, or `Class.ReverbSoundEffect` to add more realistic reflections of sound in interior spaces.

295
.cursor/rules/roblox/en-us/sound/objects.md Normal file
View file

@ -0,0 +1,295 @@
---
title: Sound objects
description: Sound objects are legacy instances that emit sound within an experience.
---
<Alert severity = 'warning'>
There is a newer set of [audio objects](../audio/objects.md) that offer more control and address robust use cases. For more information, see [Audio](../audio/index.md).
</Alert>
Audio playback occurs through `Class.Sound` objects which emit audio within an experience. Roblox assigns each [audio asset](../audio/assets.md) a unique ID that you can assign to `Class.Sound` objects to play a specific sound effect or music track. You can either set this audio to play automatically at runtime, or trigger it to [play from scripts](#script-sound-objects).
To modify playback of multiple `Class.Sound` objects, you can assign them to a [sound group](../sound/groups.md) and control the entire group's volume, as well as apply [dynamic effects](../sound/dynamic-effects.md).
## Create sound objects
There are three locations you can create a `Class.Sound` object, and each location determines how audio emits and volume changes in relation to the user's position within the experience.
<table>
<thead>
<tr>
<th>Location</th>
<th>How audio emits</th>
<th>How volume changes</th>
</tr>
</thead>
<tbody>
<tr>
<td>Child of a block, sphere, or cylinder `Class.BasePart`.</td>
<td>Audio emits outward from the entire surface of the part.</td>
<td>Volume changes depending on the distance between the user's sound listener and the position of the part, as well as its size.</td>
</tr>
<tr>
<td>Child of an `Class.Attachment`, `Class.MeshPart`, `Class.TrussPart`, `Class.WedgePart`, or `Class.CornerWedgePart`.</td>
<td>Audio emits outward from the single attachment point or part center.</td>
<td>Volume changes depending on the distance between the user's sound listener and the attachment/part position.</td>
</tr>
<tr>
<td>Within `Class.SoundService` or `Class.Workspace`.</td>
<td>Audio emits throughout the experience.</td>
<td>Volume and pan position remain the same regardless of the user's sound listener position or rotation.</td>
</tr>
</tbody>
</table>
### Positional audio
Positional audio is audio that users can only hear near a specific position within the experience. There are two types of positional audio you can utilize: volumetric and point source.
#### Volumetric
Volumetric audio is the most realistic audio option, as it dynamically changes depending on the user's position to the audio source. For example, if the user is within a `Class.BasePart` with a child `Class.Sound` object, audio plays all around the user, similar to music in headphones playing at the same volume in each speaker. When the user exits the part, audio gradually decreases in volume and becomes more directional per speaker, moving around the user's head when their listener rotates. For information on the properties that control how loud your audio is at different distances from the part, see [RollOffMinDistance and RollOffMaxDistance](#rolloffmindistance-and-rolloffmaxdistance).
The size of the `Class.BasePart` also affects the audio's volume, as larger `Class.BasePart|BaseParts` produce a wider area in which users can hear the audio and when a user navigates away from a large `Class.BasePart`, volume decreases slower. The following example displays a `Class.BasePart` that is the size of a city with a `Class.Sound` object playing ambient audio. Users A and B experience the audio differently: user B is closer to the large `Class.BasePart`, and they mostly hear the audio around the same loudness in both speakers. Conversely, user A is further away from the city, so the audio they hear is quieter and more directional than user B, playing at differing loudness in each of their speakers.
<img src="../assets/audio/sound-objects/Volumetric-Sound-Diagram.jpg" width="80%" />
Volumetric audio is useful for any audio that needs to be immersive around a user and change dynamically depending on the user's position, such as a concert stage or ambience zones like rainfall. When you experiment with placing a `Class.Sound` object on `Class.BasePart|BaseParts` of different sizes and positions from users, you can hear how immersive volumetric audio can be.
<video src="../assets/audio/sound-objects/Volumetric-Demo.mp4" controls width="80%"></video>
To create a `Class.Sound` object for volumetric audio:
1. In the **Explorer** window, select **SoundService**.
2. In the **Properties** window, navigate to the **VolumetricAudio** property, then set it to **Enabled**.
3. In the **Explorer** window, hover over a `Class.BasePart`, then click the ⊕ button. A contextual menu displays.
4. From the menu, insert a **Sound**.
5. In the **Properties** window, navigate to the **SoundId** property and input a valid [audio asset ID](../audio/assets.md).
<img src="../assets/studio/properties/Sound-SoundId.png" width="320" />
6. **(Optional)** If you want the audio to start playing when the experience begins, enable the **Playing** property.
#### Point source
Contrary to volumetric audio, point source audio only emits from a single point source. This type of audio is useful for explosions, impact noises, electronic devices, and dialogue.
<video src="../assets/audio/sound-objects/Sound-Point-Source.mp4" controls width="80%"></video>
To create a `Class.Sound` object for point source audio:
1. In the **Explorer** window, hover over an attachment, truss, wedge, or corner wedge, then click the ⊕ button. A contextual menu displays.
2. From the menu, insert a **Sound**.
3. In the **Properties** window, navigate to the **SoundId** property and input a valid [audio asset ID](../audio/assets.md).
4. **(Optional)** If you want the audio to start playing when the experience begins, enable the **Playing** property.
### Background audio
Background audio plays at the same volume no matter where the user travels within your experience. This type of audio is useful for music that you want to play for users, especially when you want to create a soundtrack of multiple audio files.
It's best to keep all `Class.Sound` objects for background audio in a single location of the Workspace for organization purposes as you continue to add and edit audio within your experience. The following example stores the new `Class.Sound` object under the `Class.SoundService` container, as this service determines how `Class.Sound` objects play in experiences.
To create a `Class.Sound` object for background audio:
1. In the **Explorer** window, hover over **SoundService**, then click the ⊕ button. A contextual menu displays.
2. From the menu, insert a **Sound**.
3. In the **Properties** window, navigate to the **SoundId** property and input a valid [audio asset ID](../audio/assets.md).
4. **(Optional)** If you want the audio to start playing when the experience begins, enable the **Playing** property.
5. **(Optional)** If this `Class.Sound` object is the only track you want to play in the place, enable its **Looped** property.
## Customize sound objects
`Class.Sound` object properties work together to influence how users experience your audio, such as:
- How loud they hear specific audio individually and in relation to one another ([Volume](#volume)).
- How they perceive volume when they move away from the audio source ([RollOffMinDistance](#rolloffmindistance-and-rolloffmaxdistance), [RollOffMaxDistance](#rolloffmindistance-and-rolloffmaxdistance), and [RollOffMode](#rolloffmode))
- What part of the audio they can listen to ([TimePosition](#timeposition)).
- How fast and at what pitch they hear it ([PlaybackSpeed](#playbackspeed)).
- If the audio automatically replays upon completion ([Looped](#looped)).
### Volume
The `Class.Sound.Volume|Volume` property allows you to set the volume of your audio anywhere from `0` (silence) to `10` (booming). If you want to change the volume of multiple `Class.Sound` objects at once, parent them under a [sound group](../sound/groups.md).
<Alert severity="warning">
If your source audio is sufficiently loud, you likely don't need to increase the volume to more than `2`, as this property is multiplicative. For example: a `Class.Sound.Volume|Volume` value of `4` is four times as loud than a `Class.Sound.Volume|Volume` value of `1`, so if your source audio was already loud, the audio might become overwhelming to users.
</Alert>
### RollOffMinDistance and RollOffMaxDistance
`Class.Sound.RollOffMinDistance|RollOffMinDistance` and `Class.Sound.RollOffMaxDistance|RollOffMaxDistance` determine the range of how a user perceives volume from positional audio. For volumetric audio, `Class.Sound.RollOffMinDistance|RollOffMinDistance` is the minimum distance in studs that audio begins to decrease in volume when the client's listener **moves away** from the parent `Class.BasePart`, and `Class.Sound.RollOffMaxDistance|RollOffMaxDistance` property is the maximum distance in studs that a client's listener can hear audio from the surface of the object.
<img src="../assets/audio/sound-objects/Sound-Volumetric-RollOff.jpg" width="800" />
For point source audio, `Class.Sound.RollOffMinDistance|RollOffMinDistance` and `Class.Sound.RollOffMaxDistance|RollOffMaxDistance` work similarly to volumetric audio, but the roll off distance these properties control doesn't surround the object, it only influences the distance outward from the point source.
<img src="../assets/audio/sound-objects/Sound-Point-RollOff.jpg" width="800" />
### RollOffMode
The `Class.Sound.RollOffMode|RollOffMode` property allows you to decide how audio fades as the distance between the user's listener and the `Class.Sound` object's parent increases. You can set this property to one of four values of the `Enum.RollOffMode` enum.
<img src="../assets/audio/sound-objects/RollOffMode-Chart.png" width="80%" />
<table>
<thead>
<tr>
<th>RollOffMode</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>`Inverse` (default)</td>
<td>Volume initially fades abruptly from `Class.Sound.RollOffMinDistance|RollOffMinDistance`, but volume fading becomes more gradual the closer a user is to reaching the `Class.Sound.RollOffMaxDistance|RollOffMaxDistance`. Once they reach the `Class.Sound.RollOffMaxDistance|RollOffMaxDistance`, the audio falls silent.</td>
</tr>
<tr>
<td>`Linear`</td>
<td>Volume fades linearly between `Class.Sound.RollOffMinDistance|RollOffMinDistance` and `Class.Sound.RollOffMaxDistance|RollOffMaxDistance`. Once a user reaches the `Class.Sound.RollOffMaxDistance|RollOffMaxDistance`, the audio falls silent.</td>
</tr>
<tr>
<td>`InverseTapered`</td>
<td>Volume follows the inverse model when close to `Class.Sound.RollOffMinDistance|RollOffMinDistance` and the linear square model when a user is close to `Class.Sound.RollOffMaxDistance|RollOffMaxDistance`. Audio approaches silence at the maximum distance point.</td>
</tr>
<tr>
<td>`LinearSquare`</td>
<td>Volume fades between `Class.Sound.RollOffMinDistance|RollOffMinDistance` and `Class.Sound.RollOffMaxDistance|RollOffMaxDistance` with a linear squared relationship. Audio approaches silence at the maximum distance point.</td>
</tr>
</tbody>
</table>
<Alert severity="warning">
For most `Inverse` and `Linear` `Class.Sound.RollOffMode|RollOffMode` types, low `Class.Sound.RollOffMaxDistance|RollOffMaxDistance` values cause audio to abruptly cut off when the listener reaches the `Class.Sound.RollOffMaxDistance|RollOffMaxDistance`. If you want your audio to gradually decrease in volume, set a higher `Class.Sound.RollOffMaxDistance|RollOffMaxDistance` value.
</Alert>
### PlaybackSpeed
The `Class.Sound.PlaybackSpeed|PlaybackSpeed` property allows you to determine the speed your audio plays. For example, if you set the `Class.Sound.PlaybackSpeed|PlaybackSpeed` to a value of **2**, your audio plays twice as fast and one octave higher in pitch. Similarly, if you set it to a value of **0.5**, your audio plays twice as slow and one octave lower in pitch.
<table>
<tbody>
<tr>
<td><audio controls>
<source src="../assets/audio/sound-objects/CarHorn_HalfSpeed.mp3" type="audio/mpeg"></source>
</audio></td>
<td><audio controls>
<source src="../assets/audio/sound-objects/CarHorn_NormalSpeed.mp3" type="audio/mpeg"></source></audio></td>
<td><audio controls>
<source src="../assets/audio/sound-objects/CarHorn_DoubleSpeed.mp3" type="audio/mpeg"></source>
</audio></td>
</tr>
<tr>
<td>`Class.Sound.PlaybackSpeed|PlaybackSpeed` = 0.5</td>
<td>`Class.Sound.PlaybackSpeed|PlaybackSpeed` = 1.0</td>
<td>`Class.Sound.PlaybackSpeed|PlaybackSpeed` = 2.0</td>
</tr>
</tbody>
</table>
### TimePosition
The `Class.Sound.TimePosition|TimePosition` property displays, in seconds, what position within the audio sample a user is currently hearing. This property is useful for either only playing a section of the audio sample, or triggering an event to occur once audio reaches a specific position. For example, the following code sample causes a particle emitter to emit a white ring particle above a part within a limited time range of an audio track.
```lua
local RunService = game:GetService("RunService")
local Workspace = game:GetService("Workspace")
-- Create a new part
local part = Instance.new("Part")
part.Anchored = true
part.Color = Color3.new(0.75, 0.2, 0.5)
part.Size = Vector3.new(2, 1, 2)
part.Material = Enum.Material.Neon
part.Position = Vector3.new(0, 4, 0)
part.Parent = Workspace
-- Create an attachment on the part
local attachment = Instance.new("Attachment")
attachment.Position = Vector3.new(0, 0.5, 0)
attachment.Parent = part
-- Create a particle emitter on the attachment
local emitter = Instance.new("ParticleEmitter")
emitter.Rate = 5
emitter.Lifetime = NumberRange.new(1.5, 1.5)
emitter.Texture = "rbxassetid://1266170131"
emitter.Speed = NumberRange.new(1, 1)
emitter.Size = NumberSequence.new{NumberSequenceKeypoint.new(0, 1), NumberSequenceKeypoint.new(1, 6)}
emitter.Transparency = NumberSequence.new{NumberSequenceKeypoint.new(0, 1), NumberSequenceKeypoint.new(0.25, 0), NumberSequenceKeypoint.new(1, 1)}
emitter.Orientation = Enum.ParticleOrientation.VelocityPerpendicular
emitter.Parent = attachment
-- Create a sound on the attachment
local sound = Instance.new("Sound")
sound.SoundId = "rbxassetid://1835405646"
sound.Parent = attachment
-- Play the sound
sound:Play()
-- Start checking if emitter should be enabled
RunService.Heartbeat:Connect(function()
-- Enable the emitter within a time range of the audio; otherwise disable it
emitter.Enabled = sound.TimePosition >= 5 and sound.TimePosition < 20
end)
```
### Looped
The `Class.Sound.Looped|Looped` property allows you to repeat audio after it has finished playing. When set to `true`, the `Class.Sound` object's audio plays again. This is useful to apply to [background audio](#background-audio) to ensure your experience never has abrupt silence.
## Script sound objects
### Play audio contextually
Aside from auto-playing audio through the `Class.Sound` object's `Class.Sound.Playing|Playing` property, you can play audio contextually from a `Class.LocalScript` by calling `Class.Sound:Play()|Play()` on the corresponding `Class.Sound` object. For example:
```lua
local Workspace = game:GetService("Workspace")
local sound = Instance.new("Sound")
sound.SoundId = "rbxassetid://9120386436"
sound.Looped = true
sound.Parent = Workspace
sound:Play()
```
Alternatively, if the place will feature multiple tracks, you can play a specific track from a `Class.LocalScript`:
```lua
local SoundService = game:GetService("SoundService")
local musicTrack = SoundService:FindFirstChild("LucidDream")
if musicTrack not musicTrack.IsPlaying then
musicTrack:Play()
end
```
### Play interface audio
You can play interface audio for `Class.GuiObject|GuiObjects` such as [buttons](../ui/buttons.md) by hooking up a `Class.Sound` object to the `Class.GuiButton.Activated|Activated` event listener. This lets you provide auditory feedback to users, such as when they hover over or press it.
To play a `Class.Sound` object's audio when a user activates a `Class.TextButton` or `Class.ImageButton`:
1. In the [Explorer](../studio/explorer.md) window, hover over the `Class.TextButton` or `Class.ImageButton`, then click the ⊕ button. A contextual menu displays.
2. From the menu, insert either a `Class.LocalScript` or a `Class.Script` with `Class.BaseScript.RunContext|RunContext` set to `Enum.RunContext.Client`.
3. Paste the following code into the script, then replace `SOUND_NAME` with the name of a `Class.Sound` object located inside the `Class.SoundService` container.
```lua
local SoundService = game:GetService("SoundService")
local button = script.Parent
local sound = SoundService:FindFirstChild("SOUND_NAME")
if not sound.isLoaded then
sound.Loaded:Wait()
end
local function onButtonActivated()
if sound and not sound.IsPlaying then
sound:Play()
end
end
button.Activated:Connect(onButtonActivated)
```