Sfx

From Pico-8 Wiki
Jump to navigation Jump to search
sfx( n, [channel,] [offset,] [length] )
Plays a sound effect.
n
The number of the sound effect to play (0-63), -1 to stop playing sound on the given channel, or -2 to release the sound of the given channel from looping.

channel
The channel to use for the sound effect (0-3). The default is -1, which chooses an available channel automatically. Can be -2 to stop playing the given sound effect on any channels it plays on.

offset
The note position in the sound effect to start playing (0-31). The default is 0 (the beginning).

length
The number of notes in the sound effect to play (0-31). The default is to play the entire sound effect.

A sound effect is a sequence of tones or notes. You can design sounds in the sound effect editor. A cartridge can have up to 64 sounds, numbered 0-63. A sound effect can represent a single effect played by a call to the sfx() function, or can be a series of notes played in a single channel of a music pattern.

The sfx() function plays a sound on one of PICO-8's four sound channels. If an explicit channel number is not specified, PICO-8 will attempt to select a channel automatically, giving priority to an unused channel so that two concurrent sounds may overlap.

If music is currently playing, the sound effect will attempt to honor the channel mask set by the call to the music() function to avoid channels that are important to the music. If you specify an explicit channel to sfx(), the music's channel mask is ignored.

It's possible to detect the current sfx being played for each channel, along with the index of the current note of each sfx. See stat(16..23) for details.

Examples

-- play sound 3 on any available channel
sfx(3)

-- play sound 3 starting from note position 21 on any available channel
sfx(3, -1, 21)

-- stop playing sound on channel 2
sfx(-1, 2)

-- release a looping sound on channel 2
sfx(-2, 2)

See also