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)

Examples: 
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.

Official Manual - Music

Images in this Guide by NerdyTeachers is licensed under CC BY-SA 4.0

2211

18 May 2023

Font