Commands & Exports

This section lists all available commands, exports, and events included in the script. You’ll find client-side, server-side, and shared functions designed to help developers integrate, extend, or interact with the system easily within their own scripts or frameworks.

Commands

This section lists all available commands included in the script. Each command is designed to simplify administration, player interaction, or debugging tasks. You’ll find detailed descriptions, usage examples, and permission requirements to help you manage and customize your server efficiently.

Command
Description

/bx-create

Create Boombox Command

/bx-pickup

Pickup Boombox Command

/bx-drop

Drop Boombox Command

/bx-destroy

Destroy Boombox Command

/bx

Access Boombox Command

Shared Exports

This section provides all available shared exports for the script. These functions allow developers to interact with the system from the server side, manage data, trigger actions, and integrate with other resources. Each export includes a clear description and a practical example to simplify its implementation.

createUniqueId

The createUniqueId export allows you to generate a unique soundId using qs-3dsound. This is useful when you want full control over sound identifiers before playing or managing sounds, ensuring there are no ID conflicts.

How to Use

To create a unique sound ID, use the following code:

local soundId = exports['qs-3dsound']:createUniqueId()
print("Generated soundId:", soundId)

This returns a unique string that can be reused later when playing or controlling sounds.

getInfoFromUrl

The getInfoFromUrl export allows you to retrieve basic information from a music URL using qs-3dsound. This is useful for displaying song data such as title, artist, and thumbnail before or during playback.

How to Use

To get information from a URL, use the following code:

local info = exports['qs-3dsound']:getInfoFromUrl(
    "https://example.com/music"
)

if info then
    print(info.title)
    print(info.artist)
    print(info.thumbnail)
else
    print("Failed to get song info")
end

On success, the export returns the song metadata. If it fails, it returns false.

searchTrack

The searchTrack export allows you to search for tracks by song name using qs-3dsound. It returns the same type of information as getInfoFromUrl, making it useful for music search systems, players, or UI selectors.

How to Use

To search for a track, use the following code:

If the search is successful, it returns track data such as artist, title, thumbnails, and IDs. If it fails, it returns an error with a message and code.

searchTracks

The searchTracks export allows you to search for albums or playlists using qs-3dsound. It returns the same information as searchTrack, but instead of a single result, it returns an array of tracks. This export does not support SoundCloud.

How to Use

To search for an album or playlist, use the following code:

This returns a list of tracks with the same data structure as searchTrack.

Client Exports

This section provides all available client exports for the script. These functions allow you to interact directly with the system from the client side, enabling custom features, UI interactions, and integrations with other resources. Each export includes a short description and usage example for easy implementation.

Play

The Play export allows you to play a sound using qs-3dsound, either as a global sound or as a 3D positional sound in the world. If coordinates are provided, the sound becomes distance-based. If no coordinates are set, the sound can be heard from anywhere on the map. This export is synchronous and returns a soundId if the sound is created successfully, or false if it fails.

How to Use

To play a sound, use the following code:

PlayAsync

The PlayAsync export allows you to play a sound using qs-3dsound in an asynchronous way. It works the same as the Play export, allowing global or 3D positional sounds, but it does not return any value. This is useful when you don’t need to track or control the sound after playing it.

How to Use

To play a sound asynchronously, use the following code:

The attachEntity export allows you to attach an existing sound to a networked entity so the sound follows it in real time. This is ideal for vehicles, players, or any moving entity that needs dynamic audio.

How to Use

To attach a sound to an entity, use the following code:

The detachEntity export allows you to detach a sound from an entity, stopping it from following the entity movement.

How to Use

To detach a sound from an entity, use the following code:

attachPlayer

The attachPlayer export allows you to attach a sound directly to a player using qs-3dsound. Unlike attaching to an entity, this method automatically detects when the player enters a vehicle and correctly filters the sound, ensuring proper audio behavior. This makes it the recommended option when working with player-based sounds.

How to Use

To attach a sound to a player, use the following code:

detachPlayer

The detachPlayer export allows you to detach a sound from a player using qs-3dsound. Once detached, the sound will stop following the player and will no longer adapt to player-related state changes, such as entering or exiting a vehicle.

How to Use

To detach a sound from a player, use the following code:

Stop

The Stop export allows you to completely stop and remove a sound using qs-3dsound. Unlike the Pause export, this method fully deletes the audio player from the DOM when using sources like Spotify or YouTube, which is important for performance and optimization. Once stopped, the sound cannot be resumed and must be played again from scratch.

How to Use

To stop a sound, use the following code:

Pause

The Pause export allows you to pause a sound using qs-3dsound. Unlike the Stop export, pausing a sound keeps the audio player loaded, allowing the sound to be resumed later from the same position.

How to Use

To pause a sound, use the following code:

Resume

The Resume export allows you to resume a paused sound using qs-3dsound. It continues playback from the exact point where the sound was paused, as long as the sound has not been stopped or removed.

How to Use

To resume a sound, use the following code:

This continues the sound playback from its paused state.

Destroy

The Destroy export allows you to fully remove a sound using qs-3dsound. This completely deletes the sound instance and frees all associated resources. Once destroyed, the sound no longer exists and cannot be resumed or controlled.

How to Use

To destroy a sound, use the following code:

destroyAllSounds

The destroyAllSounds export allows you to remove all active sounds at once using qs-3dsound. This instantly destroys every sound instance and frees all audio resources. It is useful for cleanups, resource restarts, or resetting the audio system.

How to Use

To destroy all sounds, use the following code:

This immediately removes every active sound.

repeatSound

The repeatSound export allows you to toggle repeat mode for a sound using qs-3dsound. When enabled, the sound will automatically replay from the beginning once it finishes.

How to Use

To enable repeat on a sound, use the following code:

This makes the sound loop continuously.

addFilter

The addFilter export allows you to apply an audio filter to an existing sound using qs-3dsound. This lets you modify how the sound is heard in real time, such as muffling, boosting, or shaping frequencies for immersive effects.

How to Use

To add a filter to a sound, use the following code:

removeFilter

The removeFilter export allows you to remove any active audio filter from a sound using qs-3dsound. Once removed, the sound will play with its original, unmodified audio.

How to Use

To remove a filter from a sound, use the following code:

Server Exports

This section provides all available server exports for the script. These functions allow developers to interact with the system from the server side, manage data, trigger actions, and integrate with other resources. Each export includes a clear description and a practical example to simplify its implementation.

Play

The Play export allows you to create and play a server-side sound using qs-3dsound. This export is synchronous, meaning it returns a soundId if the sound is created successfully, or false if it fails. Unlike the client version, coords are required on the server side. This is useful when you need proper sync, control, or data for all players.

How to Use

To play a server-side sound, use the following code:

If the sound cannot be created, the export will return false.

PlayAsync

The PlayAsync export allows you to create and play a server-side sound using qs-3dsound in an asynchronous way. Unlike the synchronous version, this export does not return a soundId, but it works faster and allows you to attach the sound to an entity or a player at creation time. This makes it ideal for asset sounds.

This export should only be used for asset sounds. Do not use it for YouTube, Spotify, or SoundCloud audio.

How to Use

To play a server-side sound asynchronously, use the following code:

Stop

The Stop export allows you to completely stop and remove a server-side sound using qs-3dsound. Unlike the Pause export, this method fully deletes the audio player from the DOM when using sources like YouTube or Spotify, which is important for optimization. Once stopped, the sound is fully removed and must be played again from scratch.

How to Use

To stop a server-side sound, use the following code:

This fully removes the sound and frees resources.

Pause

The Pause export allows you to pause a server-side sound using qs-3dsound. Unlike stopping, pausing keeps the audio player loaded, allowing the sound to be resumed later from the same position.

How to Use

To pause a server-side sound, use the following code:

This pauses the sound without removing the audio player.

Resume

The Resume export allows you to resume a server-side sound using qs-3dsound. It continues playback from the exact point where the sound was paused, as long as the sound has not been stopped or destroyed.

How to Use

To resume a server-side sound, use the following code:

This continues the sound playback for all synced players.

Destroy

The Destroy export allows you to fully remove a server-side sound using qs-3dsound. This completely deletes the sound instance and frees all associated resources. Once destroyed, the sound no longer exists and cannot be resumed or controlled.

How to Use

To destroy a server-side sound, use the following code:

This permanently removes the sound from the system.

destroyAllSounds

The destroyAllSounds export allows you to remove all active server-side sounds at once using qs-3dsound. This instantly destroys every sound instance and frees all audio resources. It is mainly used for cleanups, resets, or when restarting systems that rely on sounds.

How to Use

To destroy all server-side sounds, use the following code:

This immediately removes every active sound from the server.

attachEntity

The attachEntity export allows you to attach a server-side sound to a networked entity using qs-3dsound. Once attached, the sound will follow the entity in real time for all synced players. This is ideal for vehicles, objects, or any moving entities that need positional audio.

How to Use

To attach a server-side sound to an entity, use the following code:

This links the sound to the entity movement.

detachEntity

The detachEntity export allows you to detach a server-side sound from an entity using qs-3dsound. Once detached, the sound will stop following the entity and will no longer update its position based on entity movement.

How to Use

To detach a server-side sound from an entity, use the following code:

This removes the link between the sound and the entity.

attachPlayer

The attachPlayer export allows you to attach a server-side sound directly to a player using qs-3dsound. This method is recommended over attachEntity for players, because it automatically detects when the player enters a vehicle and correctly filters the sound, ensuring proper audio behavior for all synced players.

How to Use

To attach a server-side sound to a player, use the following code:

This ensures the sound follows the player and adapts correctly when entering or exiting vehicles.

detachPlayer

The detachPlayer export allows you to detach a server-side sound from a player using qs-3dsound. Once detached, the sound will stop following the player and will no longer adapt to player-related state changes, such as entering or exiting a vehicle.

How to Use

To detach a server-side sound from a player, use the following code:

This removes the sound link from the player.