Pulp Audio Runtime

Building a Playdate game in Lua and want to take advantage of Pulp’s audio authoring tools? The Pulp audio runtime is a small Lua library that lets you do just that.

One-time setup

Download the audio runtime bundle from the Assets pane of Game mode in the Pulp editor. Unzip and copy the Lua file and two json files into the root of your project’s Lua source folder.

Add import 'pulp-audio' to your main.lua and call pulp.audio.init() once. Then call pulp.audio.update() once per frame inside playdate.update().

Updating song and sound data

Export the updated data from the individual Song or Sound modes in the Pulp editor (or download the bundle again from the Game mode) and replace the existing json files in your project with updated versions. Rebuild your game.

API

pulp.audio.init(songsPath, soundsPath)

The songsPath and soundsPath arguments are both optional. Paths are relative to the root of your Lua source folder. Their respective default values are pulp-songs.json and pulp-sounds.json.

pulp.audio.update()

Call once per frame to keep the audio data flowing.

pulp.audio.playSound(soundName)

Play a sound effect by name.

pulp.audio.playSong(songName, playOnce, onCompleteCallback)

Play a song by name. By default it will loop indefinitely. To play a song once and stop, pass pulp.audio.kPlayOnce (or true) as the optional second argument. When playing once, pass a function as the optional third argument, and it will be called when the song stops. If the song is already playing it will continue to play uninterrupted.

pulp.audio.stopSong()

Stops the currently playing song.

pulp.audio.setBpm(newBpm)

Change the bpm of the currently playing song. When starting a new song, the bpm reverts to the authored bpm of the new song.

Example main.lua

This example features two songs named “intro” and “loop”, and one sound named “confirm”. It imports and initializes the Pulp audio runtime, then plays “intro” once then loops “loop”. Inside the Playdate update callback it updates the runtime, and plays the “confirm” sound when A is pressed and restarts our “intro” into “loop” song combo when B is pressed. (Note that individual Pulp songs can have a loop point after a short intro. This is a contrived example to surface more of the API.)

import 'pulp-audio'

pulp.audio.init()

local once = pulp.audio.kPlayOnce

pulp.audio.playSong('intro', once, function()
    pulp.audio.playSong('loop')
end)

function playdate.update()
    pulp.audio.update()

    if playdate.buttonJustPressed('a') then
        pulp.audio.playSound('confirm')
    end

    if playdate.buttonJustPressed('b') then
        pulp.audio.playSong('intro', once, function()
            pulp.audio.playSong('loop')
        end)
    end
end