audio
sfx
sfx( #, [channel], [offset], [length] )
# | the SFX number of the sound you want to play (#0-63) |
channel | (optional) a number specifying which of the 4 channels (#0-3) to play on. |
offset | (optional) a number of notes (#0-31) into a sound for when to start playing the sound. |
length | (optional) a number of notes (#0-31) into a sound for when to stop playing the sound. |
sfx( 1 )
- play all of SFX #1, on an unoccupied channel
sfx( 3, 0 )
- play all of SFX #3, on channel #0
sfx( 4, 2, 6 )
- play part of SFX #4, in channel #2, starting 6 notes in
sfx( 4, 2, 6, 20 )
- play part of SFX #4, in channel #2, starting 6 notes in, ending at note 20
Extra Options using Negative Numbers:
SFX # | |
---|---|
-1 | Stop the current sound on this channel. |
-2 | Stop looping the current sound on this channel, but let it finish. |
Channel # | |
---|---|
-1 | (default) Play the sound on a channel that is not in use. |
-2 | Stop the sound from playing on any channel. |
sfx( -1 , 3 )
- stop playing any sounds on channel #3
sfx( -2 , 3 )
- stop looping any sounds on channel #3
sfx( -1 )
- stop playing all sounds on all channels
sfx( -2 )
- stop looping all sounds on all channels but allow them to finish
2704
20 Oct 2023
music
music( #, [fade-length], [channel-mask] )
# = the number of the song in the music editor.
fade-length = (optional) a number, in milliseconds (default 0), to fade-in the music - increase the volume over this amount of time.
channel-mask = (optional) reserves channels for music (#0-15).
Note: SFX can still play on reserved channels but only if specifically designating the channel number with sfx(#, channel)
music( 1 )
- play music pattern #1, on an unoccupied channel
music( 3, 1000 )
- play music pattern #3, and fade-in for 1 second
music( 4, 3000, 1 )
- play music pattern #4, fade-in for 3 seconds, and reserve channel #0 for music
Important to know:
- A music pattern is simply one or more SFX patterns set to play in specific channels at the same time.
- There are only 4 channels and each channel can play only 1 SFX pattern at a time.
- You can only play 1 music pattern at a time (using up to 4 channels).
- The channels that the music pattern will use are set in the music editor.
- Playing an SFX will use the lowest available channel, unless the channel is specified.
- Using the channel-mask argument to reserve a channel for music does not affect which channels music plays on but does affect which channels are available for SFX to play on.
Extra Option using a Negative Number:
Music # | |
---|---|
-1 | Stop the current music. |
music( -1 )
- stop the currently playing music pattern
Reserving multiple channels:
The channel-mask option does not take channel numbers like sfx()
does. Instead, the channel-mask is a value that represents one or more channel numbers.
Channel # | Mask Value # |
---|---|
0 | 1 |
1 | 2 |
2 | 4 |
3 | 8 |
The default channel-mask value is 0, no channels reserved for music.
To reserve multiple channels, you simply add the mask values together. For example, if we want to reserve channels 2 and 3 for music, then we take channel #2's value of 4 and channel #3's value of 8. Then we add them together: 4 + 8 = 12. So music( 0, 0, 12 )
will play pattern 0 and reserve channels 2 and 3 for music.
Let's flip the above table and list all the channel-mask values in order and see which channels each value will reserve:
Value # | Channel #s |
---|---|
0 | none |
1 | 0 |
2 | 1 |
3 | 0 , 1 |
4 | 2 |
5 | 0 , 2 |
6 | 1 , 2 |
7 | 0 , 1 , 2 |
8 | 3 |
9 | 0 , 3 |
10 | 1 , 3 |
11 | 0 , 1 , 3 |
12 | 2 , 3 |
13 | 0 , 2 , 3 |
14 | 1 , 2 , 3 |
15 | 0, 1, 2, 3 |
Example:
music( 1, 0, 6)
- play music pattern #1, without fade-in, and reserve channels 1 and 2 for music.
2094
18 May 2023