Audio
Plays WAV files from the project. Play returns a handle you use to control that sound while it is playing. Without an audio device every call is a safe no-op (0 or false). Handles are only valid while the sound plays: after it ends, the slot may be reused by another sound.
Namespace: caffeine.audio · Dryad prefix: caffeine_audio_
isAvailable#
Lua: caffeine.audio.isAvailable · Dryad: caffeine_audio_available
isAvailable() -> boolean
Tells whether sound can be played.
Returns: boolean. true when a playback device is open.
Example
if not caffeine.audio.isAvailable() then caffeine.debug.warn("no sound") end
play#
Lua: caffeine.audio.play · Dryad: caffeine_audio_play
play(path[, volume[, pan[, loop]]]) -> number
Plays a sound. The file is decoded once and cached.
| Parameters | Type | Description |
|---|---|---|
path | string | WAV file, relative to the project root. |
volume | number | 0 to 1, default 1. |
pan | number | -1 left to 1 right, default 0. |
loop | boolean | Repeat until stopped, default false. |
Returns: number. A handle greater than 0, or 0 when the sound could not play (no device, missing file, all 32 channels busy).
Example
local h = caffeine.audio.play("audio/jump.wav", 0.8)
playAt#
Lua: caffeine.audio.playAt · Dryad: caffeine_audio_play_at
playAt(path, x, y[, maxDistance[, volume]]) -> number
Plays a sound whose volume and left/right pan follow its distance to the listener (see setListener).
| Parameters | Type | Description |
|---|---|---|
path | string | WAV file, relative to the project root. |
x, y | number | Sound position in the 2D world. |
maxDistance | number | Distance at which the sound is silent, default 500. |
volume | number | Extra gain, default 1. |
Returns: number. A handle, or 0 when it could not play.
Example
caffeine.audio.playAt("audio/boom.wav", 120, 40, 300)
stop#
Lua: caffeine.audio.stop · Dryad: caffeine_audio_stop
stop(handle) -> boolean
Stops a sound.
| Parameters | Type | Description |
|---|---|---|
handle | number | Handle returned by play or playAt. |
Returns: boolean. false when the handle is unknown or the sound has already ended.
Example
caffeine.audio.stop(h)
pause#
Lua: caffeine.audio.pause · Dryad: caffeine_audio_pause
pause(handle) -> boolean
Pauses a sound; resume continues it.
| Parameters | Type | Description |
|---|---|---|
handle | number | Handle returned by play or playAt. |
Returns: boolean. false when the handle is unknown or the sound has already ended.
Example
caffeine.audio.pause(h)
resume#
Lua: caffeine.audio.resume · Dryad: caffeine_audio_resume
resume(handle) -> boolean
Resumes a paused sound.
| Parameters | Type | Description |
|---|---|---|
handle | number | Handle returned by play or playAt. |
Returns: boolean. false when the handle is unknown or the sound has already ended.
Example
caffeine.audio.resume(h)
setVolume#
Lua: caffeine.audio.setVolume · Dryad: caffeine_audio_set_volume
setVolume(handle, volume) -> boolean
Changes the volume of a playing sound.
| Parameters | Type | Description |
|---|---|---|
handle | number | Handle returned by play or playAt. |
volume | number | 0 to 1. |
Returns: boolean. false when the handle is unknown or the sound has already ended.
Example
caffeine.audio.setVolume(h, 0.3)
setLoop#
Lua: caffeine.audio.setLoop · Dryad: caffeine_audio_set_loop
setLoop(handle, loop) -> boolean
Turns looping on or off for a playing sound.
| Parameters | Type | Description |
|---|---|---|
handle | number | Handle returned by play or playAt. |
loop | boolean | true to repeat. |
Returns: boolean. false when the handle is unknown or the sound has already ended.
Example
caffeine.audio.setLoop(h, false)
isPlaying#
Lua: caffeine.audio.isPlaying · Dryad: caffeine_audio_is_playing
isPlaying(handle) -> boolean
Tells whether a sound is still playing.
| Parameters | Type | Description |
|---|---|---|
handle | number | Handle returned by play or playAt. |
Returns: boolean. true while the sound plays (not paused, not ended).
Example
if not caffeine.audio.isPlaying(h) then h = caffeine.audio.play("audio/loop.wav") end
stopAll#
Lua: caffeine.audio.stopAll · Dryad: caffeine_audio_stop_all
stopAll()
Stops every sound. Scene changes do this automatically.
Returns: none
Example
caffeine.audio.stopAll()
setMasterVolume#
Lua: caffeine.audio.setMasterVolume · Dryad: caffeine_audio_set_master_volume
setMasterVolume(volume)
Sets the volume applied to sounds started afterwards.
| Parameters | Type | Description |
|---|---|---|
volume | number | 0 to 1. |
Returns: none
Example
caffeine.audio.setMasterVolume(0.5)
masterVolume#
Lua: caffeine.audio.masterVolume · Dryad: caffeine_audio_master_volume
masterVolume() -> number
Reads the master volume.
Returns: number. The master volume, 0 to 1 (0 without audio).
Example
local v = caffeine.audio.masterVolume()
setListener#
Lua: caffeine.audio.setListener · Dryad: caffeine_audio_set_listener
setListener(x, y)
Sets where playAt measures distance from, usually the player or camera.
| Parameters | Type | Description |
|---|---|---|
x, y | number | Listener position in the 2D world. |
Returns: none
Example
caffeine.audio.setListener(player_x, player_y)