ui/ambientSound - Ambient Sound Stream Player

Reference for extensions.ui.ambientSound, which plays randomized ambient sound streams from JSON configuration files.

Overview

Manages multiple ambient sound streams, each containing a pool of sound files. Randomly selects sounds from each stream, plays them with configurable delays, and cycles through the pool without repeating the same sound consecutively. Used for environmental ambiance (wind, birds, traffic, etc.).

Exports

Internals

• soundStreams: Array of stream objects, each containing:
  • sounds - Array of sound file paths
  • delay - {min, max} or {max} for random delay between sounds
  • volume, pitch, fadeInTime - Playback parameters
  • currentSoundData - Currently playing sound state
  • previousSound - Index of last played sound (to avoid repeats)
  • streamID - Unique integer identifier
• Playback: Uses Engine.Audio.playOnce('AudioGui', path, options) which returns {len = duration}
• Cycling: After currentTime > delay + length, selects next random sound

How It Works

-- Initialize an ambient sound stream from JSON
local streamId = extensions.ui_ambientSound.init('/ui/ambientSounds/forest.json')

-- Modify stream parameters
extensions.ui_ambientSound.setStreamState(streamId, 0.5, 1.0, 2.0)

-- Remove stream
extensions.ui_ambientSound.deleteSoundSFX(streamId)

JSON Config Format

{
  "data": {
    "sounds": [
      "art/sound/ambient/birds_01.ogg",
      "art/sound/ambient/birds_02.ogg",
      "art/sound/ambient/birds_03.ogg"
    ],
    "delay": [3, 10]
  }
}

Update Loop

-- Called each frame (typically from onUpdate hook)
extensions.ui_ambientSound.update(dt)

-- Internally:
-- 1. Check if current sound is playing
-- 2. If not, start playback via Engine.Audio.playOnce
-- 3. Track elapsed time
-- 4. When elapsed > delay + sound_length, pick next random sound

Notes

• Default volume is 0.29 (hardcoded in playOnce call)
• Sounds never repeat consecutively (random selection with previous exclusion)
• Delay can be a range [min, max] or single value [max] (min defaults to 1)
• Stream IDs are sequential integers starting from 1
• Files are validated with FS:fileExists() before playback

Additional Exports

The following exports are available but not yet documented in detail:

• M.deleteSoundSFX
• M.init
• M.setStreamState
• M.update