Spatial and attached audio
Spatial audio has a position in the world. Its direction and attenuation follow
GTA’s audio engine. Supply pos when creating Audio or LocalAudio to enable
it. You can then move the sound through pos or attach it to an entity.
Attach a sound to a vehicle
Section titled “Attach a sound to a vehicle”Place music.ogg under audio/ in the client content root, as described in
Playing your first sound. This server example
creates a vehicle with a looping sound that follows it:
// @ts-check/// <reference types="@revomp/types-server" />import * as revo from 'revo-server';
const vehicle = new revo.Vehicle( 'sultan', { x: -1220, y: -1765, z: 3.9 }, Math.PI / 2,);
const sound = new revo.Audio('resources://audio/music.ogg', { pos: vehicle.pos, streamDistance: 60, volume: -12, loop: true,});
sound.attachTo(vehicle);sound.play();attachTo() follows the entity’s position automatically and preserves the
playback timeline. It returns whether the attachment succeeded. The sound must
have been created with pos, even when it will be attached immediately.
For a stationary emitter, set pos to its world coordinates and call play()
without attaching it. For playback heard only on the current client, create a
LocalAudio with the same spatial options. Local audio starts automatically.
Range and attenuation
Section titled “Range and attenuation”streamDistance sets the streaming radius in metres. It must be positive.
When omitted, server audio uses stream_distance from the server config.
In the example, the explicit value overrides that default, so listeners can
stream the sound within 60 metres of the vehicle. Attached audio also requires the entity
to be streamed in. A small margin around the boundary prevents repeated
streaming changes when a player moves near the edge.
GTA applies distance attenuation while the sound is streamed in. Increasing
streamDistance alone does not make it louder or change its attenuation curve.
Choose a radius that covers the area where the sound should be heard, and check
the level at several distances. Category volume and the player’s audio settings
also affect the result.
Stereo sources are mixed down to mono for the world emitter, so a mono file is sufficient for a sound heard from a single point.
Dimensions
Section titled “Dimensions”Unattached spatial audio starts in dimension 0. Set sound.dimension to place
it in another dimension, or use globalDimension to make it visible across
dimensions. The listener must still meet the distance and audience rules.
Attached audio inherits the entity’s dimension and follows subsequent changes. Detach it before assigning a separate dimension. See Dimensions for the shared visibility rules.
Streaming out and returning
Section titled “Streaming out and returning”Playback depends on how the sound was created:
| Source | When the listener returns |
|---|---|
Server Audio, recorded source |
Joins the current point on the shared timeline, including loop progress. |
LocalAudio, resource file |
Resumes from its saved position. |
LocalAudio, recorded HTTP(S) URL |
Reopens the source from the beginning. |
| Live HTTP(S) source | Reconnects to the current broadcast. |
An attached sound waits while its entity is unavailable on the client. Streaming back in can require loading or buffering before the sound becomes audible.
Detach and remove
Section titled “Detach and remove”sound.detach() leaves the sound playing at the last attachment position and
retains its dimension. Assigning pos also detaches it. Call detach() before
destroying an entity if the sound should continue at that location.
Destroying the attached entity stops its audio. The audio object remains valid,
so call sound.destroy() when it is no longer needed. Server audio can also be
repositioned or attached to another entity and started again with play().