Sounds

    Sound is a great way to provide feedback to player actions and events, background sounds can also give your scene more context and improve the player’s immersion into it.

    Note: Keep in mind that sounds are only heard by players who are standing within the parcels that make up the scene where the sound was generated, even if they would otherwise be in hearing range. Players can also turn off sounds on their settings.

    Supported sound formats vary depending on the browser, but it’s recommended to use .mp3.

    .wav files are also supported but not generally recommended as they are significantly larger.

    Play sounds

    To play a sound, you need the following:

    • An Entity to use for the sound location.
    • An AudioSource component, added to that entity.
    • An AudioClip object, referenced by that component.
    // Create entity
const cube = new Entity()

// Create AudioClip object, holding audio file
const clip = new AudioClip("sounds/carnivalrides.mp3")

// Create AudioSource component, referencing `clip`
const source = new AudioSource(clip)

// Add AudioSource component to entity
cube.addComponent(source)

// Play sound
source.playing = true

    When creating an AudioClip object, you need to provide the path to the location of the sound file.

    The sound file must be inside the project folder. In the example above, the audio file is located in a sounds folder, which is located at root level of the scene project folder.

    Tip: We recommend keeping your sound files separate in a /sounds folder inside your scene.

    Each entity can only have a single AudioSource component, that can only have a single AudioClip. This limitation can be easily overcome by including multiple invisible entities, each with their own sound.

    If you set the playing property of an AudioSource component to false, the file is stopped. This means that if you later set playing to true again, the sound file will begin from the start again.

    Looping

    To keep a sound playing in a continuous loop, set the loop field of the AudioSource component to true before you start playing it.

    source.loop = true
source.playing = true

    Looping sounds is especially useful for adding background music or other background sounds.

    You can use the playOnce() function to play a sound once from start to finish.

    source.playOnce()

    Set volume

    You can set the volume property of the AudioSource component to change the volume of a sound.

    The volume can be a number from 0 to 1.

    source.volume = 0.5

    Note: Of course, the volume of a sound is also affected by the distance from the audio source.

    Reuse sound objects

    A great way to save processing power is to use a same AudioClip object on many AudioSource components.

    Suppose you have a large amount of balls bouncing around in your scene, and you want to hear a thump sound every time two of them collide. You can add an AudioSource component to each ball, and use a single AudioClip object on all of these.

    Streaming sound

    You can stream audio from a URL. This is useful to play music directly from an internet radio, or stream a conference into your scene.

    The audio in the source must be in one of the following formats: .mp3, ogg, or aac. The source must also be an https URL (http URLs aren’t supported), and the source should have CORS policies (Cross Origin Resource Sharing) that permit externally accessing it. If this is not the case, you might need to set up a server to act as a proxy and expose the stream in a valid way.

    To add sound into your scene, simply add an entity with an AudioStream component:

    const streamSource = new Entity()
streamSource.addComponent(
  new AudioStream(
    "https://icecast.ravepartyradio.org/ravepartyradio-192.mp3"
  )
)
engine.addEntity(streamSource)

streamSource.getComponent(AudioStream).playing = true

    Note: The streamed sound isn’t positional, it will be heard at a consistent volume throughout your entire scene. If a player steps out of the scene, they will not hear the streaming at all.

    Set the volume of the AudioStream component by changing its volume property.

    Switch the AudioStream component on or off by setting its playing property to true or false.