10 KiB
Music Commands
Defined in macros/scripts/audio.asm and audio/engine.asm:MusicCommands.
Note: Commands that are intended for the song channels (1-4) can be used by the sound effect channels (5-8) if the sound effect channel exits sound effect mode with the toggle_sfx command.
channel_count n
Used at the start of each sound header to specify how many channels are used in the sound.
n: Number of channels [1, 4]
channel index, address
Used for each channel in a sound header.
index: Channel number [1, 8]
address: Pointer to the sound data
note pitch, length
Play a basic note. Used by channels 1-3.
pitch: Pitch of note (see constants/audio_constants.asm)
length: Length of note in "ticks" [1, 16]. The exact duration of a tick is dependant on the current "speed" (see note_type and drum_speed) and the current "tempo" (see tempo).
drum_note instrument, length
Play a predefined drum note. Used by channel 4.
instrument: Instrument ID [1, 12] (see toggle_noise)
length: Length of note [1, 16]
rest length
Basic rest. Used by channels 1-4.
length: Length of rest [1, 16]
square_note length, volume, fade, frequency
Sound effect square note. Used by channels 5-7.
length: Length of note [0, 255]
volume: Initial volume [0, 15]
fade: Volume fade [-7, 7]
frequency: Note frequency [0, 65535]
noise_note length, volume, fade, frequency
Sound effect noise note. Used by channel 8.
length: Length of note [0, 255]
volume: Initial volume [0, 15]
fade: Volume fade [-7, 7]
frequency: Note frequency [0, 255]
$D0−$D7: octave n
Set the octave for the notes played on the current channel. Used by channels 1-3.
n: New octave [1, 8]
$D8: note_type length, volume, fade/wave_instrument
Set persistent note properties. Used by channels 1-3.
length: Base note length [1, 15] (12 is often used for 4/4 common time because 12 is factorable by both 3 and 4. Therefore it works very well for quarter notes, eighth notes, sixteenth notes, and triplets.)
volume: Initial volume [0, 15] for channels 1-2, [0, 3] for channel 3 (see volume_envelope)
fade: Volume fade [-7, 7] (applies to channels 1-2)
wave_instrument: Wave instrument ID (applies to channel 3) (see audio/wave_samples.asm)
$D8: drum_speed length
Set persistent note properties. Used by channel 4.
length: Base note length [1, 15] (use 12 for common time)
$D9: transpose num_octaves, num_pitches
Transpose all notes played on the current channel. Used by channels 1-3.
num_octaves: Number of octaves to subtract from each note
num_pitches: Number of pitches to add to each note
$DA: tempo tempo
Set the tempo for all playing channels. This should only be used by channel 1.
The formula to convert from this tempo to BPM is: BPM = 19200 / tempo
This formula also works backwards to convert BPM to tempo: tempo = 19200 / BPM
Only set or change this value when all playing channels are triggering a note or rest at the same time, otherwise desyncs may happen.
$DB: duty_cycle duty_cycle
Set the square duty (sound) for the current channel. Used by channels 1-2.
The only accepted values are 0-3.
- 0 = 12.5% waveform:
_______¯ - 1 = 25% waveform:
______¯¯ - 2 = 50% waveform:
____¯¯¯¯ - 3 = 75% waveform:
__¯¯¯¯¯¯(sounds the same as 25%)
To change the sound for channel 3, use note_type or volume_envelope.
$DC: volume_envelope volume, fade/wave_instrument
Set the volume envelope for the current channel. Used by channels 1-3.
volume: Initial volume [0, 15] for channels 1-2, [0, 3] for channel 3
fade: Volume fade [-7, 7] (applies to channels 1-2)
wave_instrument: Wave instrument ID (applies to channel 3) (see audio/wave_samples.asm)
For channel 3, the only acceped volume values are 0-3.
- 0 = Mute
- 1 = 100% volume
- 2 = 50% volume
- 3 = 25% volume
Note about fade: A positive value means a decrease in volume; a negative value means an increase in volume. A small magnitude means a quick change; a large magnitude means a slow change. It is stored in signed magnitude representation, so a value of 8 is the same as (negative) 0.
$DD: pitch_sweep length, pitch_change
Set pitch sweep properties. Used by channel 5.
length: Duration of effect [0, 15]
pitch_change: Extent of effect [-7, 8] Note: 8 is used in place of 0
$DE: duty_cycle_pattern a, b, c, d
Set duty cycle pattern (ie, pulse width modulation). Used by channels 5-6.
This cycles the channel through 4 duty cycles, one per frame.
Each argument defines a duty cycle, same as the duty_cycle command.
$DF: toggle_sfx
Toggle between pitch-based songs and frequency-based sound effects. Can be used by any channel.
Note: Similar to the pokered command execute_music, however execute_music can only be used on channels 5-8 and can not be disabled for the duration of the sound once it is enabled.
$E0: pitch_slide duration, octave, pitch
Bend the pitch of the next note played, and only that note. Used by channel 1.
duration: Duration of the target note after slide effect
octave: Target octave
pitch: Target pitch (see constants/audio_constants.asm)
$E1: vibrato delay, extent, rate
Apply vibrato to current channel. Used by channels 1-3.
delay: Delay until vibrato effect begins for each note [0, 255]
extent: Amplitude of vibrato [0, 15]
rate: Frequency of vibrato [0, 15]
$E2: unknownmusic0xe2 unknown
$E3: toggle_noise id
Set the "drum kit" to be used if it is currently unset. Mute the channel otherwise. Used by channel 4.
id: Drum kit ID [0, 5] (see audio/drumkits.asm)
Note: The drum kit ID is initially unset at the start of a song. When muting the channel, the id argument must not be present.
$E4: force_stereo_panning left_enable, right_enable
Set left/right stereo output for the current channel, regardless of user's stereo setting. Used by channels 1-4.
left_enable: TRUE/FALSE
right_enable: TRUE/FALSE
$E5: volume left_volume, right_volume
Set master volume for left/right speakers. Typically only used by channel 1.
left_volume: Left speaker volume [0, 7]
right_volume: Right speaker volume [0, 7]
Note: Minimum volume, 0, is not muted.
$E6: pitch_offset pitch_offset
Adjust the pitch of all notes on the current channel. Used by channels 1-3.
pitch_offset: Frequency adjustment of each pitch
Note: Similar to the pokered command toggle_perfect_pitch. toggle_perfect_pitch can be replaced with a combination of pitch_offset 1 and pitch_offset 0.
$E7: unknownmusic0xe7 unknown
$E8: unknownmusic0xe8 unknown
$E9: tempo_relative value
$EA: restart_channel address
$EB: new_song id
$EC: sfx_priority_on
$ED: sfx_priority_off
$EE: unknownmusic0xee address
$EF: stereo_panning left_enable, right_enable
Set left/right stereo output for the current channel, if the user has stereo mode enabled. Used by channels 1-4.
left_enable: TRUE/FALSE
right_enable: TRUE/FALSE
$F0: sfx_toggle_noise id
Set the "drum kit" to be used if it is currently unset. Mute the channel otherwise. Used by channel 8.
id: Drum kit ID [0, 5] (see audio/drumkits.asm)
Note: The drum kit ID is initially unset at the start of a song. When muting the channel, the id argument must not be present.
$F1: music0xf1
$F2: music0xf2
$F3: music0xf3
$F4: music0xf4
$F5: music0xf5
$F6: music0xf6
$F7: music0xf7
$F8: music0xf8
$F9: unknownmusic0xf9
$FA: set_condition condition
$FB: sound_jump_if condition, address
$FC: sound_jump address
$FD: sound_loop count, address
Execute a branch of sound commands a total of count times.
count: Number of times to execute the loop (including the first execution) (use 0 for an infinite loop)
address: Pointer to the start of the loop of sound commands
$FE: sound_call address
Execute a branch of sound commands, returning to the call point once a sound_ret command is reached.
address: Pointer to the branch of sound commands to call
$FF: sound_ret
Return to the caller (ie, sound_call) if in a sub branch. End the sound otherwise.