Editing Sfx

{{ApiReference
|name=sfx
|shortdesc=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|optional|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|optional|The note position in the sound effect to start playing (0-31). The default is 0 (the beginning).
|length|optional|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 <code>sfx()</code> function, or can be a series of notes played in a single channel of a [[Music|music]] pattern.

The <code>sfx()</code> 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|music()]] function to avoid channels that are important to the music. If you specify an explicit channel to <code>sfx()</code>, 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#.7B16.E2.80.A626.7D_Sound_and_music_status|<code>stat(16..23)</code>]] for details.

== Examples ==
<syntaxhighlight lang="lua">
-- 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)
</syntaxhighlight>

== See also ==

* [[Music|<code>music()</code>]]
* [[Stat#.7B16.E2.80.A626.7D_Sound_and_music_status|<code>stat(16..23)</code>]]
[[Category:Reference]]
[[Category:API]]