BindingForce Wiki - User contributions [en]

Music Engine Description

2022-04-08T20:29:07Z

DontBaguMe: /* Title Music Engine */

There are two separate music engines in Zelda 2. Both are in bank 6 (along
with the song data). The music engine for the title screen resides at
<code>$8000</code> and the engine for the rest of the game is at
<code>$9000</code>. Each of these engines is called once per frame during the
appropriate part of the game.

Changes to the music engine should be very easy to make, as there is an
abundance of free space in bank 6.

== Title Music Engine ==

'''TODO''' properly format the following by bgt (original at https://eab.xyz/W2zplGD) and dontbagume (on discord).

# Title Music Engine

The title music engine is different from the engine that plays music
during the rest of the game. In particular, it has a wider range of
notes that can be represented. If you want to look into the actual
code, the title screen music engine main loop is at `$8000` (vesus
`$9000` for the game music loop).

The metadata for the songs is all the same as in the other areas,
although the title music is actually broken up into several songs
itself. These song boundaries control the timing of the title scroll.

The following songs exist in the title song table:

1. Intro
2. Start
3. Build up
4. Main
5. Breakdown

The start of song 2 triggers the title to scroll into view. The start
of song 4 triggers a countdown until the story scroll begins. After
song 5 finishes, the engine loops back to song 2.

Within the note data, a special format is used. Rather than encoding
the duration and pitch together in a single byte, the title music has
"pitch" bytes and "duration" bytes. Any byte with the highest bit set
(i.e. anything >= `$80`) is interpreted as a duration change, which
sets the duration of all future notes. Anything else is a pitch value
which indicates a note of the current duration should be played. The
low nibble of duration values keys into a lookup table at bank 6 `$8084`
and store the duration byte at $07FF. Value durations are as follows:

* `$80` - 8 ticks (sixteenth note)
* `$81` - 24 ticks (dotted eighth note)
* `$82` - 16 ticks (eighth note)
* `$83` - 32 ticks (quarter note)
* `$84` - 48 ticks (dotted quarter note)
* `$85` - 64 ticks (half note)
* `$86` - 96 ticks (dotted half note)
* `$87` - 128 ticks (whole note)
* `$88` - 11 ticks (eighth note triplet)
* `$89` - 10 ticks (???)
* `$8A` - 80 ticks (half note + eighth note)
* `$8B` - 256 ticks (two whole notes)
* `$8F` - 6 ticks (dotted 32nd note)

Note: $8C, $8D and $8E are duplicates, so these could be used for
custom durations if desired.

The pitch values are much more straightforward. As far as I can tell,
`$4C` is A4 and every semitone away from that adds or subtracts 2 from
the value. Thus, C5 (three semitones above A4) is `$52`. The value
`$02` represents a rest.

-2- -3- -4- -5- -6- -7-
A : $12 $2A $42 $5A $72
Bb : $14 $2C $44 $5C $74
B : $16 $2E $46 $5E $76
C : $18 $30 $48 $60 $78
C# : $1A $32 $4A $62 $7A
D : $04 $1C $34 $4C $64
Eb : $06 $1E $36 $4E $66
E : $08 $20 $38 $50 $68
F : $0A $22 $3A $52 $6A
F# : $0C $24 $3C $54 $6C
G : $0E $26 $3E $56 $6E
G# : $10 $28 $40 $58 $70

By way of an example, let's look at the main section of the vanilla
title music. The title metadata starts at bank 6 `$84DA`:

08 11 14 16 19 1E 1E 1E
^ Main section

The main section is the fourth song, starting at `$84DA + $16 = $84F0`:

3F 3F 00

This means there is a single phrase for the main section, which is
repeated twice. The phrase data is at `$84DA + $3F = $8519`.

00 3D 86 3A 1A 5F

From this, we see the melody note data is located at `$863D`:

83 Quarter notes
02 Rest
48 Ab4
82 Eighth note
46 G4
83 Quarter notes
3E Eb4
34 Bb3
84 Dotted quarter notes
2E G3
83 Quarter notes
30 Ab3
34 Bb3
3A Db4
38 C4
34 Bb3
30 Ab3
82 Eighth notes
34 Bb3
83 Quarter notes
30 Ab3
85 Half notes
2E G3
82 Quarter notes
02 Rest
00 End of Data

== Main Music Engine ==

=== Data Tables ===

There are several data tables used by the music engine.

==== Pulse Envelope ====

This table is used to set the volume of the pulse channels over time. The index
used starts at a certain value and decrements, so the table is in reverse order.
The index is halved before use, so each value lasts two frames.

{| class="wikitable"
|+ Pulse Envelope <code>$9135</code>
|90||91||91||91||92||92||92||92
|-
|93||93||94||94||94||95||95||95
|-
|96||96||96||97||97||97||98||98
|}

==== Duration LUT ====

This table is used to determine the duration of a note. The note data is stored
with 5 bits of pitch information and 3 bits of duration, as such:

D1 D0 P4 P3 P2 P1 P0 D2

The Get Note Duration routine shifts things around to get the D bits into the
three least significant bits and masks it before use. This value is then added
to the tempo value in <code>$E5</code> which is always a multiple of 8 to index
into the following table:

{| class="wikitable"
|+Duration LUT <code>$914D</code>
|'''00'''||04||0C||08||10||18||20||05||06
|-
|'''08'''||04||0F||09||12||1B||24||06||06
|-
|'''10'''||05||0F||0A||14||1E||28||07||06
|-
|'''18'''||06||12||0C||18||24||30||08||10
|-
|'''20'''||07||15||0E||1C||2A||38||13||12
|-
|'''28'''||07||15||0E||1C||2A||38||XX||XX
|}

The last two values in each row seem a bit strange, as they are not nice
multiples of the first entry which is usually thought of as the length of an
eighth note. The last row has garbage values in those positions as that is the
start of another data table, so they are not even listed here.

'''TODO''' Check what values are used in vanilla.

==== Pitch LUT ====

This table is used to detemine the pitch of a note. The note data is stored as
described above, and the fact that the least significant bit is masked out is
advantageous since the pulse channels can use 11 bits of timer data, so each
entry in this table is actually two bytes wide.

Rather than show the raw bytes here, it's more useful to show the rough note
that those values represent. If the raw values are interesting to you, check
the ROM for them. It's worth noting that some of the higher notes are several
cents off from the listed note.

{| class="wikitable"
|+Pitch LUT <code>$918F</code>
| || 00|| 02|| 04|| 06|| 08|| 0a|| 0c|| 0e
|-
|00|| C3||---|| E3|| G3||G#3|| A3||A#3|| B3
|-
|10|| C4||C#4|| D4||D#4|| E4|| F4||F#4|| G4
|-
|20||G#4|| A4||A#4|| B4|| C5||C#5|| D5||D#5
|-
|30|| E5|| F5||F#5|| G5|| A5||A#5|| B5||C#3
|-
|40|| D3||D#3|| F3||F#3||G#5|| C6||C#6|| D6
|-
|50||D#6|| E6|| F6||F#6|| G6||G#6|| A6||A#6
|-
|60|| B6|| C7||C#7|| D7||D#7|| E7|| F7||F#7
|-
|70|| G7||G#7|| A7||A#7|| B7|| C8
|}

Value <code>$02</code> represents a rest.

Note that although the table goes through <code>$7A</code> values above
<code>$3E</code> aren't usable due to the 5 bit limit for pitch data in
the song data. However, the sound effects routines make use of these
extra notes. For example, the sword beam effect alternates between
playing C7 and F6.

==== Noise Samples ====

Several sound effects use the same routine to load "samples" for the noise
channel to play. These values have the noise volume in the high nybble and the
noise period in the low nybble.

$90E8 - Sword slash
$9123 - Enemy hurt
$912C - Crumble block

=== Variables ===

This is just a dump of RAM addresses used by the music engine and a short
description of what they are.

$00E0 - Current phrase note data address (low byte)
$00E1 - Current phrase note data address (high byte)
$00E2 - Song offset, converted from song id to be an index instead of a bit field
$00E3 - Current phrase index
$00E4 - Drums loop start
$00E5 - Tempo
$00E6 - Pulse 1 low bits (used for vibrato effect)
$00E7 - Pulse 2 low bits (used for vibrato effect)
$00E8 - Pitch storage, temporary
$00E9 - Play sound effect
$00EA - Disable music
$00EB - Request new song
$00EC - Play sound effect
$00ED - Play sound effect
$00EE - Play sound effect
$00EF - Play sound effect

$0707 - Current world
$075F - Queued song, loaded after screen transitions
$07DA - Ganon Laugh sample
$07DB - Song to resume after fanfare
$07DF - ??? Likely sound effect flag for pulse 1 channel override

$07E0 - ??? Likely sound effect flag for noise channel
$07E2 - Pulse 2 envelope index
$07E3 - Pulse 1 envelope index
$07E4 - Drums current note duration
$07E5 - Bass current note duration
$07E6 - Harmony current note duration
$07E7 - Melody current note duration
$07E8 - Drums next note index
$07E9 - Bass next note index
$07EA - Harmony next note index
$07EB - Melody next note index

$07EC - Ganon Laugh counter
$07ED - Sound FX counter (E9)
$07EE - Sound FX counter (E9)
$07F5 - Sound FX counter (ED)

$07FA - Current SFX (E9)
$07FB - Current song
$07FD - Current SFX (ED)
$07FE - ??? Likely sound effect flag for pulse 2 channel override
$07FF - Current SFX (EF)

=== Routines ===

This is a non-exhaustive list of the routines in bank 6 involving the playing of
music and sound effects. Each routine also lists its address so you can search
in a disassembly for the actual code for that routine if these descriptions
aren't clear.

==== Main Music Loop <code>$9000</code> ====

Checks that the music disable flag is off, then runs several SFX routines.
After the SFX routines, the main music routine runs. After all this, various
music related memory locations are cleared.

==== Configure Pulse1 Channel <code>$9031</code> ====

Takes registers x and y and configures the APU registers <code>$4000</code> and <code>$4001</code>
respectively.

==== Configure Pulse2 Channel <code>$9038</code> ====

Takes registers x and y and configures the APU registers <code>$4004</code> and <code>$4005</code>
respectively.

==== Play Note Pulse1 <code>$9042</code> ====

Takes a pitch index in register a and plays the note on the pulse 1 channel.

==== Play Note <code>$9044</code> ====

Called by the various play note routines. Takes a pitch index in register a and
uses register x as a channel selector. For the pulse channels, this routine
also saves the lower 8 bits of the APU timer register to <code>$E6</code> or <code>$E7</code> which
are used for a vibrato effect.

==== Play Note Pulse2 <code>$9067</code> ====

Takes a pitch index in register a and plays the note on the pulse 2 channel.

==== Play Note Triangle <code>$906B</code> ====

Takes a pitch index in register a and plays the note on the triangle channel.

==== Get Note Duration <code>$906F</code> ====

Takes note data in register a and looks up the duration. The original note
data is saved in register x and the result of the duration lookup is put in
register a. The duration lookup is offset by the tempo stored in <code>$E5</code>.

==== Vibrato Pulse1 <code>$9089</code> ====

Applies a vibrato effect on the pulse 1 channel. Takes the duration of the note
left in register a and the APU timer low bits in register y.

==== Vibrato Pulse2 <code>$9097</code> ====

Applies a vibrato effect on the pulse 2 channel. Takes the duration of the note
left in register a and the APU timer low bits in register y.

==== Vibrato <code>$909E</code> ====

Takes the duration of the note remaining in register a, the low bits of the APU
timer in register y, and the channel to use in register x. This is called by
the other vibrato routines after setting x appropriately.

Uses the <code>$04</code> bit of the duration to either add or subtract 2 from the low
timer bits. Only the low bits are used because writing to the high bits resets
the phase of the channel which can cause clicks. None of the notes from the
pitch LUT are close enough to the boundary for the change to require the high
bits to change anyway, so this works out fine.

==== Play E9 SFX <code>$920B</code> ====

Plays the sound effect requested in <code>$E9</code>.

'''TODO''' document further.

==== Play EF SFX <code>$92F4</code> ====

Plays the sound effect requested in <code>$EF</code>.

'''TODO''' document further.

==== Play EE SFX <code>$9408</code> ====

Plays the sound effect requested in <code>$EE</code>.

'''TODO''' document further.

==== Play Noise <code>$959D</code> ====

Configures the APU noise registers to make a noise burst. Takes configuration
for registers <code>$400F</code>, <code>$400E</code>, and <code>$400C</code> in registers y, x, and a.

==== Crumble Bridge SFX <code>$956C</code> ====

Starts playing the sound effect for a crumble bridge crumbling. This uses both
the noise and the triangle channels so it sets flags to disable the music on
those channels. Continues with SFX Noise Decay.

==== SFX Noise Decay <code>$9587</code> ====

Counts down the timer in <code>$07F5</code> and turns off the noise when it reaches 0.
Also clears the flag for the ED sound effect in <code>$07FD</code>.

==== Play ED SFX <code>$95A7</code> ====

Plays the sound effect request in <code>$ED</code> or continues the sound effect saved in
<code>$07FD</code>. Existing sound effects which are higher than the current sound effect
will be ignored. If the same sound effect is requested that is already playing,
it will restart the sound effect except for <code>$80</code> which gives priority to
continuing. When the sound is continued instead of newly played, the decay
routine will be called instead.

; <code>$02</code>
: Crumble Bridge
; <code>$04</code> and <code>$10</code>
: Crumble Block / Enemy Hurt
; <code>$20</code> and <code>$80</code>
: Sword Strike
; <code>$40</code>
: Very short noise burst, probably unused. Doesn't store the effect, and doesn't have an associated decay.

==== Crumble Block / Enemy Hurt SFX <code>$95E6</code> ====

Starts playing the sound of a block breaking or an enemy getting hurt.

==== Crumble Block / Enemy Hurt SFX Decay <code>$95EE</code> ====

Looks up noise register values based on the timer and the sound effect value.
Crumble Block samples are at <code>$912C</code> while Enemy Hurt is at <code>$9123</code>. Continues
on to Play Noise Samples.

==== Play Noise Samples <code>$9612</code> ====

Takes a sample value in register a. The low four bits of this are used to set
the noise period via APU register <code>$400E</code>. The high four bits are used to set
the noise volume via APU register <code>$400C</code>.

Continues on the SFX Noise Decay process.

==== Sword Strike SFX <code>$9604</code> ====

Starts playing the sound of swinging your sword. This looks up samples based on
the duration left at <code>$90E8</code> and plays them via Play Noise Samples.

==== Play EC SFX <code>$990B</code> ====

Plays the sound effect requested in <code>$EC</code>.

'''TODO''' document further.

==== Play Music <code>$9B18</code> ====

Plays the music for the game.

Runs Load Song if a new song is requested in <code>$EB</code>. Otherwise, runs Play Notes
if the current song is set in <code>$07FB</code>. If neither of these is true, do nothing.

==== Next Song <code>$9B24</code> ====

Checks if the previous song should loop. If not, calls Mute All and returns.

If the previous song was <code>$01</code> (the "intro" to the main theme), sets the next
song to <code>$02</code> (the main theme loop).

If the previous song was <code>$10</code> (the item get / level up fanfare), sets the
current song from <code>$07DB</code>. Otherwise, leaves the current song the same as the
previous song.

Proceeds to Load Song.

==== Mute All <code>$9B3B</code> ====

Clears the current song at <code>$07FB</code> and sets the APU registers to mute the volume
on both pulse channels, the triangle channel, and the noise channel.

==== Load Song <code>$9B61</code> ====

Takes a song id in register a and preps some variables for that song.

If the song is <code>$10</code> (item get / level up fanfare) then it first saves the
previous song to <code>$07FB</code> if it is less than <code>$10</code> so that the previous music
will resume after the fanfare.

Sets the phrase counter at <code>$E3</code> to 0 and the song offset at <code>$E2</code> based on the
song id. Song ids are a bit field, and the song offset is the position of the
lowest bit in the song id for indexing into the song table.

Proceeds to Load Song Data.

==== Load Song Data <code>$9B80</code> ====

Loads the music variables based on the current world and current song offset.

There are four blocks of code that are basically the same, for each of the four
different music tables. Each one just uses a different position for the tables
to load.

Based on the current world in <code>$0707</code> it loads data from these offsets:

<code>$00</code>
: Overworld music - <code>$9B87</code>
<code>$01</code> or <code>$02</code>
: Town music - <code>$9BC6</code>
<code>$03</code> or <code>$04</code>
: Palace music - <code>$9C05</code>
<code>$05</code> or higher
: Great Palace music - <code>$9C42</code>

First, uses the song offset in <code>$E2</code> to index into the song table at the base
offset given above.

The phrase counter at <code>$E3</code> is added to that and used as in index again to
retrieve the current phrase offset. If the current phrase offset is <code>$00</code> that
means the song is over and the process goes back to the Next Song routine.

Otherwise, the following structure is read at the base offset above + phrase
offset just calculated.

* <code>$E5</code> Tempo
* <code>$E0</code> Note Data Low
* <code>$E1</code> Note Data High
* <code>$07E9</code> Bass Note Pointer
* <code>$07EA</code> Harmony Note Pointer
* <code>$07E8</code> Drum Note Pointer

After this, the drum loop start point at <code>$E4</code> is also set to the same value as
the drum note pointer. The melody note pointer at <code>$07EB</code> is set to <code>$00</code>, and
all the durations (melody at <code>$07E7</code>, harmony at <code>$07E6</code>, bass at <code>$07E5</code>, and
drums at <code>$07E4</code>) are set to <code>$01</code>.

Proceeds to Play Notes.

==== Play Notes ====

This routine is broken into four major and similar sections: one each for
melody, harmony, bass, and drums. The general process is as follows:

decrement duration
if duration == 0 {
load next note
increment note pointer
set duration for note
if no overriding sound effect {
play note on appropriate channel
}
}

Some channels have unique processing at different points in this. For example,
the melody note data is null terminated, so if the loaded note in <code>$00</code> then the
routine will jump to Load Song Data instead to go to the next phrase. If the
drums channel gets a <code>$00</code> note it will reset the drums note pointer to the
drums loop start and repeat the phrase. The bass and harmony channels don't
have this looping behavior. This means that if the bass or harmony channels
aren't long enough, the engine will happily just play whatever data comes next
in the ROM.

The melody is played on pulse 2 channel, the harmony on pulse 1 (which gets
subverted by sound effects that need just one pulse channel), the bass on the
triangle channel, and the drums on the noise channel.

For the pulse channels, after the note is played, the envelope counter for that
channel (<code>$07E2</code> for pulse 1, <code>$07E3</code> for pulse 2) is set. Normally the
envelope is set to <code>$2F</code> but song <code>$40</code> (crystal fanfare and final boss music)
sets it to <code>$18</code> instead. The envelope is not set if no note was played because
the pitch index was <code>$02</code> which indicates a rest.

Also for the pulse channels, after the above pseudocode, the vibrato and
enveloping happens as long as there is no overriding sound effect. The envelope
works by checking the envelope counter set previously and decrementing it. The
counter value is halved and used to look up the envelope value in the LUT at
<code>$9135</code>. These values are written directly to APU register <code>$4000</code> or <code>$4004</code>
depending on the channel.

The bass channel has one special handling as well. The APU register <code>$4008</code> is
set differently based on the current song id. For song <code>$10</code> (item get / level
up fanfare) the register is set to <code>$60</code> but all other songs use <code>$1f</code>.

The noise channel is not affect at all by the pitch. Any pitch value that is
non zero will play a burst of noise.

Music Engine Description

2022-03-30T10:58:05Z

DontBaguMe: /* Title Music Engine */

There are two separate music engines in Zelda 2. Both are in bank 6 (along
with the song data). The music engine for the title screen resides at
<code>$8000</code> and the engine for the rest of the game is at
<code>$9000</code>. Each of these engines is called once per frame during the
appropriate part of the game.

Changes to the music engine should be very easy to make, as there is an
abundance of free space in bank 6.

== Title Music Engine ==

'''TODO''' properly format the following by bgt (original at https://eab.xyz/W2zplGD) and dontbagume (on discord).

# Title Music Engine

The title music engine is different from the engine that plays music
during the rest of the game. In particular, it has a wider range of
notes that can be represented. If you want to look into the actual
code, the title screen music engine main loop is at `$8000` (vesus
`$9000` for the game music loop).

The metadata for the songs is all the same as in the other areas,
although the title music is actually broken up into several songs
itself. These song boundaries control the timing of the title scroll.

The following songs exist in the title song table:

1. Intro
2. Start
3. Build up
4. Main
5. Breakdown

The start of song 2 triggers the title to scroll into view. The start
of song 4 triggers a countdown until the story scroll begins. After
song 5 finishes, the engine loops back to song 2.

Within the note data, a special format is used. Rather than encoding
the duration and pitch together in a single byte, the title music has
"pitch" bytes and "duration" bytes. Any byte with the highest bit set
(i.e. anything >= `$80`) is interpreted as a duration change, which
sets the duration of all future notes. Anything else is a pitch value
which indicates a note of the current duration should be played. The
low nibble of duration values keys into a lookup table at bank 6 `$8084`
and store the duration byte at $07FF. Value durations are as follows:

* `$80` - 8 ticks (sixteenth note)
* `$81` - 24 ticks (dotted eighth note)
* `$82` - 16 ticks (eighth note)
* `$83` - 32 ticks (quarter note)
* `$84` - 48 ticks (dotted quarter note)
* `$85` - 64 ticks (half note)
* `$86` - 96 ticks (dotted half note)
* `$87` - 128 ticks (whole note)
* `$88` - 11 ticks (eighth note triplet)
* `$89` - 10 ticks (???)
* `$8A` - 80 ticks (half note + eighth note)
* `$8B` - 256 ticks (two whole notes)
* `$8F` - 6 ticks (dotted 32nd note)

Note: $8C, $8D and $8E are duplicates, so these could be used for
custom durations if desired.

The pitch values are much more straightforward. As far as I can tell,
`$4C` is A4 and every semitone away from that adds or subtracts 2 from
the value. Thus, C5 (three semitones above A4) is `$52`. The value
`$02` represents a rest.

-2- -3- -4- -5- -6- -7-
A : $12 $2A $42 $5A $72
Bb : $14 $2C $44 $5C $74
B : $16 $2E $46 $5E $76
C : $18 $30 $48 $60 $78
C# : $1A $32 $4A $62 $7A
D : $04 $1C $34 $4C $64
Eb : $06 $1E $36 $4E $66
E : $08 $20 $38 $50 $68
F : $0A $22 $3A $52 $6A
F# : $0C $24 $3C $54 $6C
G : $0E $26 $3E $56 $6E
G# : $10 $28 $40 $58 $70

By way of an example, let's look at the main section of the vanilla
title music. The title metadata starts at bank 6 `$84DA`:

08 11 14 16 19 1E 1E 1E
^ Main section

The main section is the fourth song, starting at `$84DA + $16 = $84F0`:

3F 3F 00

This means there is a single phrase for the main section, which is
repeated twice. The phrase data is at `$84DA + $3F = $8519`.

00 3D 86 3A 1A 5F

From this, we see the melody note data is located at `$863D`:

83 Quarter notes
02 Rest
48 Ab4
82 Eighth note
46 G4
83 Quarter notes
3E Eb4
34 Bb3
84 Dotted quarter notes
2E G3
83 Quarter notes
30 Ab3
34 Bb3
3A Db4
38 C4
34 Bb3
30 Ab3
82 Eighth notes
34 Bb3
83 Quarter notes
30 Ab3
85 Half notes
2E G3
82 Quarter notes
02 Rest
00 End of Data

dontbagume additions:

DURATION
* `$80` - 6 ticks sixteenth note
* `$81` - 9 ticks dotted eighth note
* `$82` - 12 ticks eighth note
* `$83` - 24 ticks quarter note
* `$84` - 36 ticks dotted quarter note
* `$85` - 48 ticks half note
* `$86` - 72 ticks dotted half note
* `$87` - 96 ticks whole note
* `$88` - 8 ticks eighth triplets
* `$89` - 7 ticks poor man's swung 16th (long)
* `$8A` - 60 ticks half + eighth
* `$8B` - 192 ticks two whole notes
* `$8F` - 5 ticks poor man's swung 16th (short)

PITCH
-1- -2- -3- -4- -5-
A : $04 $1C $34 $4C $64
Bb : $06 $1E $36 $4E $66
B : $08 $20 $38 $50 $68
C : $0A $22 $3A $52 $6A
C# : $0C $24 $3C $54 $6C
D : $0E $26 $3E $56 $6E
Eb : $10 $28 $40 $58 $70
E : $12 $2A $42 $5A $72
F : $14 $2C $44 $5C $74
F# : $16 $2E $46 $5E $76
G : $18 $30 $48 $60 $78
G# : $1A $32 $4A $62 $7A

== Main Music Engine ==

=== Data Tables ===

There are several data tables used by the music engine.

==== Pulse Envelope ====

This table is used to set the volume of the pulse channels over time. The index
used starts at a certain value and decrements, so the table is in reverse order.
The index is halved before use, so each value lasts two frames.

{| class="wikitable"
|+ Pulse Envelope <code>$9135</code>
|90||91||91||91||92||92||92||92
|-
|93||93||94||94||94||95||95||95
|-
|96||96||96||97||97||97||98||98
|}

==== Duration LUT ====

This table is used to determine the duration of a note. The note data is stored
with 5 bits of pitch information and 3 bits of duration, as such:

D1 D0 P4 P3 P2 P1 P0 D2

The Get Note Duration routine shifts things around to get the D bits into the
three least significant bits and masks it before use. This value is then added
to the tempo value in <code>$E5</code> which is always a multiple of 8 to index
into the following table:

{| class="wikitable"
|+Duration LUT <code>$914D</code>
|'''00'''||04||0C||08||10||18||20||05||06
|-
|'''08'''||04||0F||09||12||1B||24||06||06
|-
|'''10'''||05||0F||0A||14||1E||28||07||06
|-
|'''18'''||06||12||0C||18||24||30||08||10
|-
|'''20'''||07||15||0E||1C||2A||38||13||12
|-
|'''28'''||07||15||0E||1C||2A||38||XX||XX
|}

The last two values in each row seem a bit strange, as they are not nice
multiples of the first entry which is usually thought of as the length of an
eighth note. The last row has garbage values in those positions as that is the
start of another data table, so they are not even listed here.

'''TODO''' Check what values are used in vanilla.

==== Pitch LUT ====

This table is used to detemine the pitch of a note. The note data is stored as
described above, and the fact that the least significant bit is masked out is
advantageous since the pulse channels can use 11 bits of timer data, so each
entry in this table is actually two bytes wide.

Rather than show the raw bytes here, it's more useful to show the rough note
that those values represent. If the raw values are interesting to you, check
the ROM for them. It's worth noting that some of the higher notes are several
cents off from the listed note.

{| class="wikitable"
|+Pitch LUT <code>$918F</code>
| || 00|| 02|| 04|| 06|| 08|| 0a|| 0c|| 0e
|-
|00|| C3||---|| E3|| G3||G#3|| A3||A#3|| B3
|-
|10|| C4||C#4|| D4||D#4|| E4|| F4||F#4|| G4
|-
|20||G#4|| A4||A#4|| B4|| C5||C#5|| D5||D#5
|-
|30|| E5|| F5||F#5|| G5|| A5||A#5|| B5||C#3
|-
|40|| D3||D#3|| F3||F#3||G#5|| C6||C#6|| D6
|-
|50||D#6|| E6|| F6||F#6|| G6||G#6|| A6||A#6
|-
|60|| B6|| C7||C#7|| D7||D#7|| E7|| F7||F#7
|-
|70|| G7||G#7|| A7||A#7|| B7|| C8
|}

Value <code>$02</code> represents a rest.

Note that although the table goes through <code>$7A</code> values above
<code>$3E</code> aren't usable due to the 5 bit limit for pitch data in
the song data. However, the sound effects routines make use of these
extra notes. For example, the sword beam effect alternates between
playing C7 and F6.

==== Noise Samples ====

Several sound effects use the same routine to load "samples" for the noise
channel to play. These values have the noise volume in the high nybble and the
noise period in the low nybble.

$90E8 - Sword slash
$9123 - Enemy hurt
$912C - Crumble block

=== Variables ===

This is just a dump of RAM addresses used by the music engine and a short
description of what they are.

$00E0 - Current phrase note data address (low byte)
$00E1 - Current phrase note data address (high byte)
$00E2 - Song offset, converted from song id to be an index instead of a bit field
$00E3 - Current phrase index
$00E4 - Drums loop start
$00E5 - Tempo
$00E6 - Pulse 1 low bits (used for vibrato effect)
$00E7 - Pulse 2 low bits (used for vibrato effect)
$00E8 - Pitch storage, temporary
$00E9 - Play sound effect
$00EA - Disable music
$00EB - Request new song
$00EC - Play sound effect
$00ED - Play sound effect
$00EE - Play sound effect
$00EF - Play sound effect

$0707 - Current world
$075F - Queued song, loaded after screen transitions
$07DA - Ganon Laugh sample
$07DB - Song to resume after fanfare
$07DF - ??? Likely sound effect flag for pulse 1 channel override

$07E0 - ??? Likely sound effect flag for noise channel
$07E2 - Pulse 2 envelope index
$07E3 - Pulse 1 envelope index
$07E4 - Drums current note duration
$07E5 - Bass current note duration
$07E6 - Harmony current note duration
$07E7 - Melody current note duration
$07E8 - Drums next note index
$07E9 - Bass next note index
$07EA - Harmony next note index
$07EB - Melody next note index

$07EC - Ganon Laugh counter
$07ED - Sound FX counter (E9)
$07EE - Sound FX counter (E9)
$07F5 - Sound FX counter (ED)

$07FA - Current SFX (E9)
$07FB - Current song
$07FD - Current SFX (ED)
$07FE - ??? Likely sound effect flag for pulse 2 channel override
$07FF - Current SFX (EF)

=== Routines ===

This is a non-exhaustive list of the routines in bank 6 involving the playing of
music and sound effects. Each routine also lists its address so you can search
in a disassembly for the actual code for that routine if these descriptions
aren't clear.

==== Main Music Loop <code>$9000</code> ====

Checks that the music disable flag is off, then runs several SFX routines.
After the SFX routines, the main music routine runs. After all this, various
music related memory locations are cleared.

==== Configure Pulse1 Channel <code>$9031</code> ====

Takes registers x and y and configures the APU registers <code>$4000</code> and <code>$4001</code>
respectively.

==== Configure Pulse2 Channel <code>$9038</code> ====

Takes registers x and y and configures the APU registers <code>$4004</code> and <code>$4005</code>
respectively.

==== Play Note Pulse1 <code>$9042</code> ====

Takes a pitch index in register a and plays the note on the pulse 1 channel.

==== Play Note <code>$9044</code> ====

Called by the various play note routines. Takes a pitch index in register a and
uses register x as a channel selector. For the pulse channels, this routine
also saves the lower 8 bits of the APU timer register to <code>$E6</code> or <code>$E7</code> which
are used for a vibrato effect.

==== Play Note Pulse2 <code>$9067</code> ====

Takes a pitch index in register a and plays the note on the pulse 2 channel.

==== Play Note Triangle <code>$906B</code> ====

Takes a pitch index in register a and plays the note on the triangle channel.

==== Get Note Duration <code>$906F</code> ====

Takes note data in register a and looks up the duration. The original note
data is saved in register x and the result of the duration lookup is put in
register a. The duration lookup is offset by the tempo stored in <code>$E5</code>.

==== Vibrato Pulse1 <code>$9089</code> ====

Applies a vibrato effect on the pulse 1 channel. Takes the duration of the note
left in register a and the APU timer low bits in register y.

==== Vibrato Pulse2 <code>$9097</code> ====

Applies a vibrato effect on the pulse 2 channel. Takes the duration of the note
left in register a and the APU timer low bits in register y.

==== Vibrato <code>$909E</code> ====

Takes the duration of the note remaining in register a, the low bits of the APU
timer in register y, and the channel to use in register x. This is called by
the other vibrato routines after setting x appropriately.

Uses the <code>$04</code> bit of the duration to either add or subtract 2 from the low
timer bits. Only the low bits are used because writing to the high bits resets
the phase of the channel which can cause clicks. None of the notes from the
pitch LUT are close enough to the boundary for the change to require the high
bits to change anyway, so this works out fine.

==== Play E9 SFX <code>$920B</code> ====

Plays the sound effect requested in <code>$E9</code>.

'''TODO''' document further.

==== Play EF SFX <code>$92F4</code> ====

Plays the sound effect requested in <code>$EF</code>.

'''TODO''' document further.

==== Play EE SFX <code>$9408</code> ====

Plays the sound effect requested in <code>$EE</code>.

'''TODO''' document further.

==== Play Noise <code>$959D</code> ====

Configures the APU noise registers to make a noise burst. Takes configuration
for registers <code>$400F</code>, <code>$400E</code>, and <code>$400C</code> in registers y, x, and a.

==== Crumble Bridge SFX <code>$956C</code> ====

Starts playing the sound effect for a crumble bridge crumbling. This uses both
the noise and the triangle channels so it sets flags to disable the music on
those channels. Continues with SFX Noise Decay.

==== SFX Noise Decay <code>$9587</code> ====

Counts down the timer in <code>$07F5</code> and turns off the noise when it reaches 0.
Also clears the flag for the ED sound effect in <code>$07FD</code>.

==== Play ED SFX <code>$95A7</code> ====

Plays the sound effect request in <code>$ED</code> or continues the sound effect saved in
<code>$07FD</code>. Existing sound effects which are higher than the current sound effect
will be ignored. If the same sound effect is requested that is already playing,
it will restart the sound effect except for <code>$80</code> which gives priority to
continuing. When the sound is continued instead of newly played, the decay
routine will be called instead.

; <code>$02</code>
: Crumble Bridge
; <code>$04</code> and <code>$10</code>
: Crumble Block / Enemy Hurt
; <code>$20</code> and <code>$80</code>
: Sword Strike
; <code>$40</code>
: Very short noise burst, probably unused. Doesn't store the effect, and doesn't have an associated decay.

==== Crumble Block / Enemy Hurt SFX <code>$95E6</code> ====

Starts playing the sound of a block breaking or an enemy getting hurt.

==== Crumble Block / Enemy Hurt SFX Decay <code>$95EE</code> ====

Looks up noise register values based on the timer and the sound effect value.
Crumble Block samples are at <code>$912C</code> while Enemy Hurt is at <code>$9123</code>. Continues
on to Play Noise Samples.

==== Play Noise Samples <code>$9612</code> ====

Takes a sample value in register a. The low four bits of this are used to set
the noise period via APU register <code>$400E</code>. The high four bits are used to set
the noise volume via APU register <code>$400C</code>.

Continues on the SFX Noise Decay process.

==== Sword Strike SFX <code>$9604</code> ====

Starts playing the sound of swinging your sword. This looks up samples based on
the duration left at <code>$90E8</code> and plays them via Play Noise Samples.

==== Play EC SFX <code>$990B</code> ====

Plays the sound effect requested in <code>$EC</code>.

'''TODO''' document further.

==== Play Music <code>$9B18</code> ====

Plays the music for the game.

Runs Load Song if a new song is requested in <code>$EB</code>. Otherwise, runs Play Notes
if the current song is set in <code>$07FB</code>. If neither of these is true, do nothing.

==== Next Song <code>$9B24</code> ====

Checks if the previous song should loop. If not, calls Mute All and returns.

If the previous song was <code>$01</code> (the "intro" to the main theme), sets the next
song to <code>$02</code> (the main theme loop).

If the previous song was <code>$10</code> (the item get / level up fanfare), sets the
current song from <code>$07DB</code>. Otherwise, leaves the current song the same as the
previous song.

Proceeds to Load Song.

==== Mute All <code>$9B3B</code> ====

Clears the current song at <code>$07FB</code> and sets the APU registers to mute the volume
on both pulse channels, the triangle channel, and the noise channel.

==== Load Song <code>$9B61</code> ====

Takes a song id in register a and preps some variables for that song.

If the song is <code>$10</code> (item get / level up fanfare) then it first saves the
previous song to <code>$07FB</code> if it is less than <code>$10</code> so that the previous music
will resume after the fanfare.

Sets the phrase counter at <code>$E3</code> to 0 and the song offset at <code>$E2</code> based on the
song id. Song ids are a bit field, and the song offset is the position of the
lowest bit in the song id for indexing into the song table.

Proceeds to Load Song Data.

==== Load Song Data <code>$9B80</code> ====

Loads the music variables based on the current world and current song offset.

There are four blocks of code that are basically the same, for each of the four
different music tables. Each one just uses a different position for the tables
to load.

Based on the current world in <code>$0707</code> it loads data from these offsets:

<code>$00</code>
: Overworld music - <code>$9B87</code>
<code>$01</code> or <code>$02</code>
: Town music - <code>$9BC6</code>
<code>$03</code> or <code>$04</code>
: Palace music - <code>$9C05</code>
<code>$05</code> or higher
: Great Palace music - <code>$9C42</code>

First, uses the song offset in <code>$E2</code> to index into the song table at the base
offset given above.

The phrase counter at <code>$E3</code> is added to that and used as in index again to
retrieve the current phrase offset. If the current phrase offset is <code>$00</code> that
means the song is over and the process goes back to the Next Song routine.

Otherwise, the following structure is read at the base offset above + phrase
offset just calculated.

* <code>$E5</code> Tempo
* <code>$E0</code> Note Data Low
* <code>$E1</code> Note Data High
* <code>$07E9</code> Bass Note Pointer
* <code>$07EA</code> Harmony Note Pointer
* <code>$07E8</code> Drum Note Pointer

After this, the drum loop start point at <code>$E4</code> is also set to the same value as
the drum note pointer. The melody note pointer at <code>$07EB</code> is set to <code>$00</code>, and
all the durations (melody at <code>$07E7</code>, harmony at <code>$07E6</code>, bass at <code>$07E5</code>, and
drums at <code>$07E4</code>) are set to <code>$01</code>.

Proceeds to Play Notes.

==== Play Notes ====

This routine is broken into four major and similar sections: one each for
melody, harmony, bass, and drums. The general process is as follows:

decrement duration
if duration == 0 {
load next note
increment note pointer
set duration for note
if no overriding sound effect {
play note on appropriate channel
}
}

Some channels have unique processing at different points in this. For example,
the melody note data is null terminated, so if the loaded note in <code>$00</code> then the
routine will jump to Load Song Data instead to go to the next phrase. If the
drums channel gets a <code>$00</code> note it will reset the drums note pointer to the
drums loop start and repeat the phrase. The bass and harmony channels don't
have this looping behavior. This means that if the bass or harmony channels
aren't long enough, the engine will happily just play whatever data comes next
in the ROM.

The melody is played on pulse 2 channel, the harmony on pulse 1 (which gets
subverted by sound effects that need just one pulse channel), the bass on the
triangle channel, and the drums on the noise channel.

For the pulse channels, after the note is played, the envelope counter for that
channel (<code>$07E2</code> for pulse 1, <code>$07E3</code> for pulse 2) is set. Normally the
envelope is set to <code>$2F</code> but song <code>$40</code> (crystal fanfare and final boss music)
sets it to <code>$18</code> instead. The envelope is not set if no note was played because
the pitch index was <code>$02</code> which indicates a rest.

Also for the pulse channels, after the above pseudocode, the vibrato and
enveloping happens as long as there is no overriding sound effect. The envelope
works by checking the envelope counter set previously and decrementing it. The
counter value is halved and used to look up the envelope value in the LUT at
<code>$9135</code>. These values are written directly to APU register <code>$4000</code> or <code>$4004</code>
depending on the channel.

The bass channel has one special handling as well. The APU register <code>$4008</code> is
set differently based on the current song id. For song <code>$10</code> (item get / level
up fanfare) the register is set to <code>$60</code> but all other songs use <code>$1f</code>.

The noise channel is not affect at all by the pitch. Any pitch value that is
non zero will play a burst of noise.

Music Engine Description

2022-03-30T04:47:01Z

DontBaguMe: /* Title Music Engine */

There are two separate music engines in Zelda 2. Both are in bank 6 (along
with the song data). The music engine for the title screen resides at
<code>$8000</code> and the engine for the rest of the game is at
<code>$9000</code>. Each of these engines is called once per frame during the
appropriate part of the game.

Changes to the music engine should be very easy to make, as there is an
abundance of free space in bank 6.

== Title Music Engine ==

'''TODO''' properly format the following by bgt (original at https://eab.xyz/W2zplGD) and dontbagume (on discord).

# Title Music Engine

The title music engine is different from the engine that plays music
during the rest of the game. In particular, it has a wider range of
notes that can be represented. If you want to look into the actual
code, the title screen music engine main loop is at `$8000` (vesus
`$9000` for the game music loop).

The metadata for the songs is all the same as in the other areas,
although the title music is actually broken up into several songs
itself. These song boundaries control the timing of the title scroll.

The following songs exist in the title song table:

1. Intro
2. Start
3. Build up
4. Main
5. Breakdown

The start of song 2 triggers the title to scroll into view. The start
of song 4 triggers a countdown until the story scroll begins. After
song 5 finishes, the engine loops back to song 2.

Within the note data, a special format is used. Rather than encoding
the duration and pitch together in a single byte, the title music has
"pitch" bytes and "duration" bytes. Any byte with the highest bit set
(i.e. anything >= `$80`) is interpreted as a duration change, which
sets the duration of all future notes. Anything else is a pitch value
which indicates a note of the current duration should be played. The
low nibble of duration values keys into a lookup table at bank 6 `$8084`
and store the duration byte at $07FF. Value durations are as follows:

* `$80` - 8 ticks (sixteenth note)
* `$81` - 24 ticks (dotted eighth note)
* `$82` - 16 ticks (eighth note)
* `$83` - 32 ticks (quarter note)
* `$84` - 48 ticks (dotted quarter note)
* `$85` - 64 ticks (half note)
* `$86` - 96 ticks (dotted half note)
* `$87` - 128 ticks (whole note)
* `$88` - 11 ticks (eighth note triplet)
* `$89` - 10 ticks (???)
* `$8A` - 80 ticks (half note + eighth note)
* `$8B` - 256 ticks (two whole notes)
* `$8F` - 6 ticks (dotted 32nd note)

Note: $8C, $8D and $8E are duplicates, so these could be used for
custom durations if desired.

The pitch values are much more straightforward. As far as I can tell,
`$4C` is A4 and every semitone away from that adds or subtracts 2 from
the value. Thus, C5 (three semitones above A4) is `$52`. The value
`$02` represents a rest.

-1- -2- -3- -4- -5-
A : $04 $1C $34 $4C $64
Bb : $06 $1E $36 $4E $66
B : $08 $20 $38 $50 $68
C : $0A $22 $3A $52 $6A
C# : $0C $24 $3C $54 $6C
D : $0E $26 $3E $56 $6E
Eb : $10 $28 $40 $58 $70
E : $12 $2A $42 $5A $72
F : $14 $2C $44 $5C $74
F# : $16 $2E $46 $5E $76
G : $18 $30 $48 $60 $78
G# : $1A $32 $4A $62 $7A

By way of an example, let's look at the main section of the vanilla
title music. The title metadata starts at bank 6 `$84DA`:

08 11 14 16 19 1E 1E 1E
^ Main section

The main section is the fourth song, starting at `$84DA + $16 = $84F0`:

3F 3F 00

This means there is a single phrase for the main section, which is
repeated twice. The phrase data is at `$84DA + $3F = $8519`.

00 3D 86 3A 1A 5F

From this, we see the melody note data is located at `$863D`:

83 Quarter notes
02 Rest
48 Ab4
82 Eighth note
46 G4
83 Quarter notes
3E Eb4
34 Bb3
84 Dotted quarter notes
2E G3
83 Quarter notes
30 Ab3
34 Bb3
3A Db4
38 C4
34 Bb3
30 Ab3
82 Eighth notes
34 Bb3
83 Quarter notes
30 Ab3
85 Half notes
2E G3
82 Quarter notes
02 Rest
00 End of Data

dontbagume additions:

DURATION
* `$80` - 6 ticks sixteenth note
* `$81` - 9 ticks dotted eighth note
* `$82` - 12 ticks eighth note
* `$83` - 24 ticks quarter note
* `$84` - 36 ticks dotted quarter note
* `$85` - 48 ticks half note
* `$86` - 72 ticks dotted half note
* `$87` - 96 ticks whole note
* `$88` - 8 ticks eighth triplets
* `$89` - 7 ticks poor man's swung 16th (long)
* `$8A` - 60 ticks half + eighth
* `$8B` - 192 ticks two whole notes
* `$8F` - 5 ticks poor man's swung 16th (short)

PITCH
-1- -2- -3- -4- -5-
A : $04 $1C $34 $4C $64
Bb : $06 $1E $36 $4E $66
B : $08 $20 $38 $50 $68
C : $0A $22 $3A $52 $6A
C# : $0C $24 $3C $54 $6C
D : $0E $26 $3E $56 $6E
Eb : $10 $28 $40 $58 $70
E : $12 $2A $42 $5A $72
F : $14 $2C $44 $5C $74
F# : $16 $2E $46 $5E $76
G : $18 $30 $48 $60 $78
G# : $1A $32 $4A $62 $7A

== Main Music Engine ==

=== Data Tables ===

There are several data tables used by the music engine.

==== Pulse Envelope ====

This table is used to set the volume of the pulse channels over time. The index
used starts at a certain value and decrements, so the table is in reverse order.
The index is halved before use, so each value lasts two frames.

{| class="wikitable"
|+ Pulse Envelope <code>$9135</code>
|90||91||91||91||92||92||92||92
|-
|93||93||94||94||94||95||95||95
|-
|96||96||96||97||97||97||98||98
|}

==== Duration LUT ====

This table is used to determine the duration of a note. The note data is stored
with 5 bits of pitch information and 3 bits of duration, as such:

D1 D0 P4 P3 P2 P1 P0 D2

The Get Note Duration routine shifts things around to get the D bits into the
three least significant bits and masks it before use. This value is then added
to the tempo value in <code>$E5</code> which is always a multiple of 8 to index
into the following table:

{| class="wikitable"
|+Duration LUT <code>$914D</code>
|'''00'''||04||0C||08||10||18||20||05||06
|-
|'''08'''||04||0F||09||12||1B||24||06||06
|-
|'''10'''||05||0F||0A||14||1E||28||07||06
|-
|'''18'''||06||12||0C||18||24||30||08||10
|-
|'''20'''||07||15||0E||1C||2A||38||13||12
|-
|'''28'''||07||15||0E||1C||2A||38||XX||XX
|}

The last two values in each row seem a bit strange, as they are not nice
multiples of the first entry which is usually thought of as the length of an
eighth note. The last row has garbage values in those positions as that is the
start of another data table, so they are not even listed here.

'''TODO''' Check what values are used in vanilla.

==== Pitch LUT ====

This table is used to detemine the pitch of a note. The note data is stored as
described above, and the fact that the least significant bit is masked out is
advantageous since the pulse channels can use 11 bits of timer data, so each
entry in this table is actually two bytes wide.

Rather than show the raw bytes here, it's more useful to show the rough note
that those values represent. If the raw values are interesting to you, check
the ROM for them. It's worth noting that some of the higher notes are several
cents off from the listed note.

{| class="wikitable"
|+Pitch LUT <code>$918F</code>
| || 00|| 02|| 04|| 06|| 08|| 0a|| 0c|| 0e
|-
|00|| C3||---|| E3|| G3||G#3|| A3||A#3|| B3
|-
|10|| C4||C#4|| D4||D#4|| E4|| F4||F#4|| G4
|-
|20||G#4|| A4||A#4|| B4|| C5||C#5|| D5||D#5
|-
|30|| E5|| F5||F#5|| G5|| A5||A#5|| B5||C#3
|-
|40|| D3||D#3|| F3||F#3||G#5|| C6||C#6|| D6
|-
|50||D#6|| E6|| F6||F#6|| G6||G#6|| A6||A#6
|-
|60|| B6|| C7||C#7|| D7||D#7|| E7|| F7||F#7
|-
|70|| G7||G#7|| A7||A#7|| B7|| C8
|}

Value <code>$02</code> represents a rest.

Note that although the table goes through <code>$7A</code> values above
<code>$3E</code> aren't usable due to the 5 bit limit for pitch data in
the song data. However, the sound effects routines make use of these
extra notes. For example, the sword beam effect alternates between
playing C7 and F6.

==== Noise Samples ====

Several sound effects use the same routine to load "samples" for the noise
channel to play. These values have the noise volume in the high nybble and the
noise period in the low nybble.

$90E8 - Sword slash
$9123 - Enemy hurt
$912C - Crumble block

=== Variables ===

This is just a dump of RAM addresses used by the music engine and a short
description of what they are.

$00E0 - Current phrase note data address (low byte)
$00E1 - Current phrase note data address (high byte)
$00E2 - Song offset, converted from song id to be an index instead of a bit field
$00E3 - Current phrase index
$00E4 - Drums loop start
$00E5 - Tempo
$00E6 - Pulse 1 low bits (used for vibrato effect)
$00E7 - Pulse 2 low bits (used for vibrato effect)
$00E8 - Pitch storage, temporary
$00E9 - Play sound effect
$00EA - Disable music
$00EB - Request new song
$00EC - Play sound effect
$00ED - Play sound effect
$00EE - Play sound effect
$00EF - Play sound effect

$0707 - Current world
$075F - Queued song, loaded after screen transitions
$07DA - Ganon Laugh sample
$07DB - Song to resume after fanfare
$07DF - ??? Likely sound effect flag for pulse 1 channel override

$07E0 - ??? Likely sound effect flag for noise channel
$07E2 - Pulse 2 envelope index
$07E3 - Pulse 1 envelope index
$07E4 - Drums current note duration
$07E5 - Bass current note duration
$07E6 - Harmony current note duration
$07E7 - Melody current note duration
$07E8 - Drums next note index
$07E9 - Bass next note index
$07EA - Harmony next note index
$07EB - Melody next note index

$07EC - Ganon Laugh counter
$07ED - Sound FX counter (E9)
$07EE - Sound FX counter (E9)
$07F5 - Sound FX counter (ED)

$07FA - Current SFX (E9)
$07FB - Current song
$07FD - Current SFX (ED)
$07FE - ??? Likely sound effect flag for pulse 2 channel override
$07FF - Current SFX (EF)

=== Routines ===

This is a non-exhaustive list of the routines in bank 6 involving the playing of
music and sound effects. Each routine also lists its address so you can search
in a disassembly for the actual code for that routine if these descriptions
aren't clear.

==== Main Music Loop <code>$9000</code> ====

Checks that the music disable flag is off, then runs several SFX routines.
After the SFX routines, the main music routine runs. After all this, various
music related memory locations are cleared.

==== Configure Pulse1 Channel <code>$9031</code> ====

Takes registers x and y and configures the APU registers <code>$4000</code> and <code>$4001</code>
respectively.

==== Configure Pulse2 Channel <code>$9038</code> ====

Takes registers x and y and configures the APU registers <code>$4004</code> and <code>$4005</code>
respectively.

==== Play Note Pulse1 <code>$9042</code> ====

Takes a pitch index in register a and plays the note on the pulse 1 channel.

==== Play Note <code>$9044</code> ====

Called by the various play note routines. Takes a pitch index in register a and
uses register x as a channel selector. For the pulse channels, this routine
also saves the lower 8 bits of the APU timer register to <code>$E6</code> or <code>$E7</code> which
are used for a vibrato effect.

==== Play Note Pulse2 <code>$9067</code> ====

Takes a pitch index in register a and plays the note on the pulse 2 channel.

==== Play Note Triangle <code>$906B</code> ====

Takes a pitch index in register a and plays the note on the triangle channel.

==== Get Note Duration <code>$906F</code> ====

Takes note data in register a and looks up the duration. The original note
data is saved in register x and the result of the duration lookup is put in
register a. The duration lookup is offset by the tempo stored in <code>$E5</code>.

==== Vibrato Pulse1 <code>$9089</code> ====

Applies a vibrato effect on the pulse 1 channel. Takes the duration of the note
left in register a and the APU timer low bits in register y.

==== Vibrato Pulse2 <code>$9097</code> ====

Applies a vibrato effect on the pulse 2 channel. Takes the duration of the note
left in register a and the APU timer low bits in register y.

==== Vibrato <code>$909E</code> ====

Takes the duration of the note remaining in register a, the low bits of the APU
timer in register y, and the channel to use in register x. This is called by
the other vibrato routines after setting x appropriately.

Uses the <code>$04</code> bit of the duration to either add or subtract 2 from the low
timer bits. Only the low bits are used because writing to the high bits resets
the phase of the channel which can cause clicks. None of the notes from the
pitch LUT are close enough to the boundary for the change to require the high
bits to change anyway, so this works out fine.

==== Play E9 SFX <code>$920B</code> ====

Plays the sound effect requested in <code>$E9</code>.

'''TODO''' document further.

==== Play EF SFX <code>$92F4</code> ====

Plays the sound effect requested in <code>$EF</code>.

'''TODO''' document further.

==== Play EE SFX <code>$9408</code> ====

Plays the sound effect requested in <code>$EE</code>.

'''TODO''' document further.

==== Play Noise <code>$959D</code> ====

Configures the APU noise registers to make a noise burst. Takes configuration
for registers <code>$400F</code>, <code>$400E</code>, and <code>$400C</code> in registers y, x, and a.

==== Crumble Bridge SFX <code>$956C</code> ====

Starts playing the sound effect for a crumble bridge crumbling. This uses both
the noise and the triangle channels so it sets flags to disable the music on
those channels. Continues with SFX Noise Decay.

==== SFX Noise Decay <code>$9587</code> ====

Counts down the timer in <code>$07F5</code> and turns off the noise when it reaches 0.
Also clears the flag for the ED sound effect in <code>$07FD</code>.

==== Play ED SFX <code>$95A7</code> ====

Plays the sound effect request in <code>$ED</code> or continues the sound effect saved in
<code>$07FD</code>. Existing sound effects which are higher than the current sound effect
will be ignored. If the same sound effect is requested that is already playing,
it will restart the sound effect except for <code>$80</code> which gives priority to
continuing. When the sound is continued instead of newly played, the decay
routine will be called instead.

; <code>$02</code>
: Crumble Bridge
; <code>$04</code> and <code>$10</code>
: Crumble Block / Enemy Hurt
; <code>$20</code> and <code>$80</code>
: Sword Strike
; <code>$40</code>
: Very short noise burst, probably unused. Doesn't store the effect, and doesn't have an associated decay.

==== Crumble Block / Enemy Hurt SFX <code>$95E6</code> ====

Starts playing the sound of a block breaking or an enemy getting hurt.

==== Crumble Block / Enemy Hurt SFX Decay <code>$95EE</code> ====

Looks up noise register values based on the timer and the sound effect value.
Crumble Block samples are at <code>$912C</code> while Enemy Hurt is at <code>$9123</code>. Continues
on to Play Noise Samples.

==== Play Noise Samples <code>$9612</code> ====

Takes a sample value in register a. The low four bits of this are used to set
the noise period via APU register <code>$400E</code>. The high four bits are used to set
the noise volume via APU register <code>$400C</code>.

Continues on the SFX Noise Decay process.

==== Sword Strike SFX <code>$9604</code> ====

Starts playing the sound of swinging your sword. This looks up samples based on
the duration left at <code>$90E8</code> and plays them via Play Noise Samples.

==== Play EC SFX <code>$990B</code> ====

Plays the sound effect requested in <code>$EC</code>.

'''TODO''' document further.

==== Play Music <code>$9B18</code> ====

Plays the music for the game.

Runs Load Song if a new song is requested in <code>$EB</code>. Otherwise, runs Play Notes
if the current song is set in <code>$07FB</code>. If neither of these is true, do nothing.

==== Next Song <code>$9B24</code> ====

Checks if the previous song should loop. If not, calls Mute All and returns.

If the previous song was <code>$01</code> (the "intro" to the main theme), sets the next
song to <code>$02</code> (the main theme loop).

If the previous song was <code>$10</code> (the item get / level up fanfare), sets the
current song from <code>$07DB</code>. Otherwise, leaves the current song the same as the
previous song.

Proceeds to Load Song.

==== Mute All <code>$9B3B</code> ====

Clears the current song at <code>$07FB</code> and sets the APU registers to mute the volume
on both pulse channels, the triangle channel, and the noise channel.

==== Load Song <code>$9B61</code> ====

Takes a song id in register a and preps some variables for that song.

If the song is <code>$10</code> (item get / level up fanfare) then it first saves the
previous song to <code>$07FB</code> if it is less than <code>$10</code> so that the previous music
will resume after the fanfare.

Sets the phrase counter at <code>$E3</code> to 0 and the song offset at <code>$E2</code> based on the
song id. Song ids are a bit field, and the song offset is the position of the
lowest bit in the song id for indexing into the song table.

Proceeds to Load Song Data.

==== Load Song Data <code>$9B80</code> ====

Loads the music variables based on the current world and current song offset.

There are four blocks of code that are basically the same, for each of the four
different music tables. Each one just uses a different position for the tables
to load.

Based on the current world in <code>$0707</code> it loads data from these offsets:

<code>$00</code>
: Overworld music - <code>$9B87</code>
<code>$01</code> or <code>$02</code>
: Town music - <code>$9BC6</code>
<code>$03</code> or <code>$04</code>
: Palace music - <code>$9C05</code>
<code>$05</code> or higher
: Great Palace music - <code>$9C42</code>

First, uses the song offset in <code>$E2</code> to index into the song table at the base
offset given above.

The phrase counter at <code>$E3</code> is added to that and used as in index again to
retrieve the current phrase offset. If the current phrase offset is <code>$00</code> that
means the song is over and the process goes back to the Next Song routine.

Otherwise, the following structure is read at the base offset above + phrase
offset just calculated.

* <code>$E5</code> Tempo
* <code>$E0</code> Note Data Low
* <code>$E1</code> Note Data High
* <code>$07E9</code> Bass Note Pointer
* <code>$07EA</code> Harmony Note Pointer
* <code>$07E8</code> Drum Note Pointer

After this, the drum loop start point at <code>$E4</code> is also set to the same value as
the drum note pointer. The melody note pointer at <code>$07EB</code> is set to <code>$00</code>, and
all the durations (melody at <code>$07E7</code>, harmony at <code>$07E6</code>, bass at <code>$07E5</code>, and
drums at <code>$07E4</code>) are set to <code>$01</code>.

Proceeds to Play Notes.

==== Play Notes ====

This routine is broken into four major and similar sections: one each for
melody, harmony, bass, and drums. The general process is as follows:

decrement duration
if duration == 0 {
load next note
increment note pointer
set duration for note
if no overriding sound effect {
play note on appropriate channel
}
}

Some channels have unique processing at different points in this. For example,
the melody note data is null terminated, so if the loaded note in <code>$00</code> then the
routine will jump to Load Song Data instead to go to the next phrase. If the
drums channel gets a <code>$00</code> note it will reset the drums note pointer to the
drums loop start and repeat the phrase. The bass and harmony channels don't
have this looping behavior. This means that if the bass or harmony channels
aren't long enough, the engine will happily just play whatever data comes next
in the ROM.

The melody is played on pulse 2 channel, the harmony on pulse 1 (which gets
subverted by sound effects that need just one pulse channel), the bass on the
triangle channel, and the drums on the noise channel.

For the pulse channels, after the note is played, the envelope counter for that
channel (<code>$07E2</code> for pulse 1, <code>$07E3</code> for pulse 2) is set. Normally the
envelope is set to <code>$2F</code> but song <code>$40</code> (crystal fanfare and final boss music)
sets it to <code>$18</code> instead. The envelope is not set if no note was played because
the pitch index was <code>$02</code> which indicates a rest.

Also for the pulse channels, after the above pseudocode, the vibrato and
enveloping happens as long as there is no overriding sound effect. The envelope
works by checking the envelope counter set previously and decrementing it. The
counter value is halved and used to look up the envelope value in the LUT at
<code>$9135</code>. These values are written directly to APU register <code>$4000</code> or <code>$4004</code>
depending on the channel.

The bass channel has one special handling as well. The APU register <code>$4008</code> is
set differently based on the current song id. For song <code>$10</code> (item get / level
up fanfare) the register is set to <code>$60</code> but all other songs use <code>$1f</code>.

The noise channel is not affect at all by the pitch. Any pitch value that is
non zero will play a burst of noise.

Music Engine Description

2022-03-30T04:44:59Z

DontBaguMe: /* Title Music Engine */

There are two separate music engines in Zelda 2. Both are in bank 6 (along
with the song data). The music engine for the title screen resides at
<code>$8000</code> and the engine for the rest of the game is at
<code>$9000</code>. Each of these engines is called once per frame during the
appropriate part of the game.

Changes to the music engine should be very easy to make, as there is an
abundance of free space in bank 6.

== Title Music Engine ==

'''TODO''' properly format the following by bgt (original at https://eab.xyz/W2zplGD) and dontbagume (on discord).

# Title Music Engine

The title music engine is different from the engine that plays music
during the rest of the game. In particular, it has a wider range of
notes that can be represented. If you want to look into the actual
code, the title screen music engine main loop is at `$8000` (vesus
`$9000` for the game music loop).

The metadata for the songs is all the same as in the other areas,
although the title music is actually broken up into several songs
itself. These song boundaries control the timing of the title scroll.

The following songs exist in the title song table:

1. Intro
2. Start
3. Build up
4. Main
5. Breakdown

The start of song 2 triggers the title to scroll into view. The start
of song 4 triggers a countdown until the story scroll begins. After
song 5 finishes, the engine loops back to song 2.

Within the note data, a special format is used. Rather than encoding
the duration and pitch together in a single byte, the title music has
"pitch" bytes and "duration" bytes. Any byte with the highest bit set
(i.e. anything >= `$80`) is interpreted as a duration change, which
sets the duration of all future notes. Anything else is a pitch value
which indicates a note of the current duration should be played. The
low nibble of duration values keys into a lookup table at bank 6 `$8084`
and store the duration byte at $07FF. Value durations are as follows:

* `$80` - 8 ticks (sixteenth note)
* `$81` - 24 ticks (dotted eighth note)
* `$82` - 16 ticks (eighth note)
* `$83` - 32 ticks (quarter note)
* `$84` - 48 ticks (dotted quarter note)
* `$85` - 64 ticks (half note)
* `$86` - 96 ticks (dotted half note)
* `$87` - 128 ticks (whole note)
* `$88` - 11 ticks (eighth note triplet)
* `$89` - 10 ticks (???)
* `$8A` - 80 ticks (half note + eighth note)
* `$8B` - 256 ticks (two whole notes)
* `$8F` - 6 ticks (dotted 32nd note)

The pitch values are much more straightforward. As far as I can tell,
`$4C` is A4 and every semitone away from that adds or subtracts 2 from
the value. Thus, C5 (three semitones above A4) is `$52`. The value
`$02` represents a rest.

-1- -2- -3- -4- -5-
A : $04 $1C $34 $4C $64
Bb : $06 $1E $36 $4E $66
B : $08 $20 $38 $50 $68
C : $0A $22 $3A $52 $6A
C# : $0C $24 $3C $54 $6C
D : $0E $26 $3E $56 $6E
Eb : $10 $28 $40 $58 $70
E : $12 $2A $42 $5A $72
F : $14 $2C $44 $5C $74
F# : $16 $2E $46 $5E $76
G : $18 $30 $48 $60 $78
G# : $1A $32 $4A $62 $7A

By way of an example, let's look at the main section of the vanilla
title music. The title metadata starts at bank 6 `$84DA`:

08 11 14 16 19 1E 1E 1E
^ Main section

The main section is the fourth song, starting at `$84DA + $16 = $84F0`:

3F 3F 00

This means there is a single phrase for the main section, which is
repeated twice. The phrase data is at `$84DA + $3F = $8519`.

00 3D 86 3A 1A 5F

From this, we see the melody note data is located at `$863D`:

83 Quarter notes
02 Rest
48 Ab4
82 Eighth note
46 G4
83 Quarter notes
3E Eb4
34 Bb3
84 Dotted quarter notes
2E G3
83 Quarter notes
30 Ab3
34 Bb3
3A Db4
38 C4
34 Bb3
30 Ab3
82 Eighth notes
34 Bb3
83 Quarter notes
30 Ab3
85 Half notes
2E G3
82 Quarter notes
02 Rest
00 End of Data

dontbagume additions:

DURATION
* `$80` - 6 ticks sixteenth note
* `$81` - 9 ticks dotted eighth note
* `$82` - 12 ticks eighth note
* `$83` - 24 ticks quarter note
* `$84` - 36 ticks dotted quarter note
* `$85` - 48 ticks half note
* `$86` - 72 ticks dotted half note
* `$87` - 96 ticks whole note
* `$88` - 8 ticks eighth triplets
* `$89` - 7 ticks poor man's swung 16th (long)
* `$8A` - 60 ticks half + eighth
* `$8B` - 192 ticks two whole notes
* `$8F` - 5 ticks poor man's swung 16th (short)

PITCH
-1- -2- -3- -4- -5-
A : $04 $1C $34 $4C $64
Bb : $06 $1E $36 $4E $66
B : $08 $20 $38 $50 $68
C : $0A $22 $3A $52 $6A
C# : $0C $24 $3C $54 $6C
D : $0E $26 $3E $56 $6E
Eb : $10 $28 $40 $58 $70
E : $12 $2A $42 $5A $72
F : $14 $2C $44 $5C $74
F# : $16 $2E $46 $5E $76
G : $18 $30 $48 $60 $78
G# : $1A $32 $4A $62 $7A

== Main Music Engine ==

=== Data Tables ===

There are several data tables used by the music engine.

==== Pulse Envelope ====

This table is used to set the volume of the pulse channels over time. The index
used starts at a certain value and decrements, so the table is in reverse order.
The index is halved before use, so each value lasts two frames.

{| class="wikitable"
|+ Pulse Envelope <code>$9135</code>
|90||91||91||91||92||92||92||92
|-
|93||93||94||94||94||95||95||95
|-
|96||96||96||97||97||97||98||98
|}

==== Duration LUT ====

This table is used to determine the duration of a note. The note data is stored
with 5 bits of pitch information and 3 bits of duration, as such:

D1 D0 P4 P3 P2 P1 P0 D2

The Get Note Duration routine shifts things around to get the D bits into the
three least significant bits and masks it before use. This value is then added
to the tempo value in <code>$E5</code> which is always a multiple of 8 to index
into the following table:

{| class="wikitable"
|+Duration LUT <code>$914D</code>
|'''00'''||04||0C||08||10||18||20||05||06
|-
|'''08'''||04||0F||09||12||1B||24||06||06
|-
|'''10'''||05||0F||0A||14||1E||28||07||06
|-
|'''18'''||06||12||0C||18||24||30||08||10
|-
|'''20'''||07||15||0E||1C||2A||38||13||12
|-
|'''28'''||07||15||0E||1C||2A||38||XX||XX
|}

The last two values in each row seem a bit strange, as they are not nice
multiples of the first entry which is usually thought of as the length of an
eighth note. The last row has garbage values in those positions as that is the
start of another data table, so they are not even listed here.

'''TODO''' Check what values are used in vanilla.

==== Pitch LUT ====

This table is used to detemine the pitch of a note. The note data is stored as
described above, and the fact that the least significant bit is masked out is
advantageous since the pulse channels can use 11 bits of timer data, so each
entry in this table is actually two bytes wide.

Rather than show the raw bytes here, it's more useful to show the rough note
that those values represent. If the raw values are interesting to you, check
the ROM for them. It's worth noting that some of the higher notes are several
cents off from the listed note.

{| class="wikitable"
|+Pitch LUT <code>$918F</code>
| || 00|| 02|| 04|| 06|| 08|| 0a|| 0c|| 0e
|-
|00|| C3||---|| E3|| G3||G#3|| A3||A#3|| B3
|-
|10|| C4||C#4|| D4||D#4|| E4|| F4||F#4|| G4
|-
|20||G#4|| A4||A#4|| B4|| C5||C#5|| D5||D#5
|-
|30|| E5|| F5||F#5|| G5|| A5||A#5|| B5||C#3
|-
|40|| D3||D#3|| F3||F#3||G#5|| C6||C#6|| D6
|-
|50||D#6|| E6|| F6||F#6|| G6||G#6|| A6||A#6
|-
|60|| B6|| C7||C#7|| D7||D#7|| E7|| F7||F#7
|-
|70|| G7||G#7|| A7||A#7|| B7|| C8
|}

Value <code>$02</code> represents a rest.

Note that although the table goes through <code>$7A</code> values above
<code>$3E</code> aren't usable due to the 5 bit limit for pitch data in
the song data. However, the sound effects routines make use of these
extra notes. For example, the sword beam effect alternates between
playing C7 and F6.

==== Noise Samples ====

Several sound effects use the same routine to load "samples" for the noise
channel to play. These values have the noise volume in the high nybble and the
noise period in the low nybble.

$90E8 - Sword slash
$9123 - Enemy hurt
$912C - Crumble block

=== Variables ===

This is just a dump of RAM addresses used by the music engine and a short
description of what they are.

$00E0 - Current phrase note data address (low byte)
$00E1 - Current phrase note data address (high byte)
$00E2 - Song offset, converted from song id to be an index instead of a bit field
$00E3 - Current phrase index
$00E4 - Drums loop start
$00E5 - Tempo
$00E6 - Pulse 1 low bits (used for vibrato effect)
$00E7 - Pulse 2 low bits (used for vibrato effect)
$00E8 - Pitch storage, temporary
$00E9 - Play sound effect
$00EA - Disable music
$00EB - Request new song
$00EC - Play sound effect
$00ED - Play sound effect
$00EE - Play sound effect
$00EF - Play sound effect

$0707 - Current world
$075F - Queued song, loaded after screen transitions
$07DA - Ganon Laugh sample
$07DB - Song to resume after fanfare
$07DF - ??? Likely sound effect flag for pulse 1 channel override

$07E0 - ??? Likely sound effect flag for noise channel
$07E2 - Pulse 2 envelope index
$07E3 - Pulse 1 envelope index
$07E4 - Drums current note duration
$07E5 - Bass current note duration
$07E6 - Harmony current note duration
$07E7 - Melody current note duration
$07E8 - Drums next note index
$07E9 - Bass next note index
$07EA - Harmony next note index
$07EB - Melody next note index

$07EC - Ganon Laugh counter
$07ED - Sound FX counter (E9)
$07EE - Sound FX counter (E9)
$07F5 - Sound FX counter (ED)

$07FA - Current SFX (E9)
$07FB - Current song
$07FD - Current SFX (ED)
$07FE - ??? Likely sound effect flag for pulse 2 channel override
$07FF - Current SFX (EF)

=== Routines ===

This is a non-exhaustive list of the routines in bank 6 involving the playing of
music and sound effects. Each routine also lists its address so you can search
in a disassembly for the actual code for that routine if these descriptions
aren't clear.

==== Main Music Loop <code>$9000</code> ====

Checks that the music disable flag is off, then runs several SFX routines.
After the SFX routines, the main music routine runs. After all this, various
music related memory locations are cleared.

==== Configure Pulse1 Channel <code>$9031</code> ====

Takes registers x and y and configures the APU registers <code>$4000</code> and <code>$4001</code>
respectively.

==== Configure Pulse2 Channel <code>$9038</code> ====

Takes registers x and y and configures the APU registers <code>$4004</code> and <code>$4005</code>
respectively.

==== Play Note Pulse1 <code>$9042</code> ====

Takes a pitch index in register a and plays the note on the pulse 1 channel.

==== Play Note <code>$9044</code> ====

Called by the various play note routines. Takes a pitch index in register a and
uses register x as a channel selector. For the pulse channels, this routine
also saves the lower 8 bits of the APU timer register to <code>$E6</code> or <code>$E7</code> which
are used for a vibrato effect.

==== Play Note Pulse2 <code>$9067</code> ====

Takes a pitch index in register a and plays the note on the pulse 2 channel.

==== Play Note Triangle <code>$906B</code> ====

Takes a pitch index in register a and plays the note on the triangle channel.

==== Get Note Duration <code>$906F</code> ====

Takes note data in register a and looks up the duration. The original note
data is saved in register x and the result of the duration lookup is put in
register a. The duration lookup is offset by the tempo stored in <code>$E5</code>.

==== Vibrato Pulse1 <code>$9089</code> ====

Applies a vibrato effect on the pulse 1 channel. Takes the duration of the note
left in register a and the APU timer low bits in register y.

==== Vibrato Pulse2 <code>$9097</code> ====

Applies a vibrato effect on the pulse 2 channel. Takes the duration of the note
left in register a and the APU timer low bits in register y.

==== Vibrato <code>$909E</code> ====

Takes the duration of the note remaining in register a, the low bits of the APU
timer in register y, and the channel to use in register x. This is called by
the other vibrato routines after setting x appropriately.

Uses the <code>$04</code> bit of the duration to either add or subtract 2 from the low
timer bits. Only the low bits are used because writing to the high bits resets
the phase of the channel which can cause clicks. None of the notes from the
pitch LUT are close enough to the boundary for the change to require the high
bits to change anyway, so this works out fine.

==== Play E9 SFX <code>$920B</code> ====

Plays the sound effect requested in <code>$E9</code>.

'''TODO''' document further.

==== Play EF SFX <code>$92F4</code> ====

Plays the sound effect requested in <code>$EF</code>.

'''TODO''' document further.

==== Play EE SFX <code>$9408</code> ====

Plays the sound effect requested in <code>$EE</code>.

'''TODO''' document further.

==== Play Noise <code>$959D</code> ====

Configures the APU noise registers to make a noise burst. Takes configuration
for registers <code>$400F</code>, <code>$400E</code>, and <code>$400C</code> in registers y, x, and a.

==== Crumble Bridge SFX <code>$956C</code> ====

Starts playing the sound effect for a crumble bridge crumbling. This uses both
the noise and the triangle channels so it sets flags to disable the music on
those channels. Continues with SFX Noise Decay.

==== SFX Noise Decay <code>$9587</code> ====

Counts down the timer in <code>$07F5</code> and turns off the noise when it reaches 0.
Also clears the flag for the ED sound effect in <code>$07FD</code>.

==== Play ED SFX <code>$95A7</code> ====

Plays the sound effect request in <code>$ED</code> or continues the sound effect saved in
<code>$07FD</code>. Existing sound effects which are higher than the current sound effect
will be ignored. If the same sound effect is requested that is already playing,
it will restart the sound effect except for <code>$80</code> which gives priority to
continuing. When the sound is continued instead of newly played, the decay
routine will be called instead.

; <code>$02</code>
: Crumble Bridge
; <code>$04</code> and <code>$10</code>
: Crumble Block / Enemy Hurt
; <code>$20</code> and <code>$80</code>
: Sword Strike
; <code>$40</code>
: Very short noise burst, probably unused. Doesn't store the effect, and doesn't have an associated decay.

==== Crumble Block / Enemy Hurt SFX <code>$95E6</code> ====

Starts playing the sound of a block breaking or an enemy getting hurt.

==== Crumble Block / Enemy Hurt SFX Decay <code>$95EE</code> ====

Looks up noise register values based on the timer and the sound effect value.
Crumble Block samples are at <code>$912C</code> while Enemy Hurt is at <code>$9123</code>. Continues
on to Play Noise Samples.

==== Play Noise Samples <code>$9612</code> ====

Takes a sample value in register a. The low four bits of this are used to set
the noise period via APU register <code>$400E</code>. The high four bits are used to set
the noise volume via APU register <code>$400C</code>.

Continues on the SFX Noise Decay process.

==== Sword Strike SFX <code>$9604</code> ====

Starts playing the sound of swinging your sword. This looks up samples based on
the duration left at <code>$90E8</code> and plays them via Play Noise Samples.

==== Play EC SFX <code>$990B</code> ====

Plays the sound effect requested in <code>$EC</code>.

'''TODO''' document further.

==== Play Music <code>$9B18</code> ====

Plays the music for the game.

Runs Load Song if a new song is requested in <code>$EB</code>. Otherwise, runs Play Notes
if the current song is set in <code>$07FB</code>. If neither of these is true, do nothing.

==== Next Song <code>$9B24</code> ====

Checks if the previous song should loop. If not, calls Mute All and returns.

If the previous song was <code>$01</code> (the "intro" to the main theme), sets the next
song to <code>$02</code> (the main theme loop).

If the previous song was <code>$10</code> (the item get / level up fanfare), sets the
current song from <code>$07DB</code>. Otherwise, leaves the current song the same as the
previous song.

Proceeds to Load Song.

==== Mute All <code>$9B3B</code> ====

Clears the current song at <code>$07FB</code> and sets the APU registers to mute the volume
on both pulse channels, the triangle channel, and the noise channel.

==== Load Song <code>$9B61</code> ====

Takes a song id in register a and preps some variables for that song.

If the song is <code>$10</code> (item get / level up fanfare) then it first saves the
previous song to <code>$07FB</code> if it is less than <code>$10</code> so that the previous music
will resume after the fanfare.

Sets the phrase counter at <code>$E3</code> to 0 and the song offset at <code>$E2</code> based on the
song id. Song ids are a bit field, and the song offset is the position of the
lowest bit in the song id for indexing into the song table.

Proceeds to Load Song Data.

==== Load Song Data <code>$9B80</code> ====

Loads the music variables based on the current world and current song offset.

There are four blocks of code that are basically the same, for each of the four
different music tables. Each one just uses a different position for the tables
to load.

Based on the current world in <code>$0707</code> it loads data from these offsets:

<code>$00</code>
: Overworld music - <code>$9B87</code>
<code>$01</code> or <code>$02</code>
: Town music - <code>$9BC6</code>
<code>$03</code> or <code>$04</code>
: Palace music - <code>$9C05</code>
<code>$05</code> or higher
: Great Palace music - <code>$9C42</code>

First, uses the song offset in <code>$E2</code> to index into the song table at the base
offset given above.

The phrase counter at <code>$E3</code> is added to that and used as in index again to
retrieve the current phrase offset. If the current phrase offset is <code>$00</code> that
means the song is over and the process goes back to the Next Song routine.

Otherwise, the following structure is read at the base offset above + phrase
offset just calculated.

* <code>$E5</code> Tempo
* <code>$E0</code> Note Data Low
* <code>$E1</code> Note Data High
* <code>$07E9</code> Bass Note Pointer
* <code>$07EA</code> Harmony Note Pointer
* <code>$07E8</code> Drum Note Pointer

After this, the drum loop start point at <code>$E4</code> is also set to the same value as
the drum note pointer. The melody note pointer at <code>$07EB</code> is set to <code>$00</code>, and
all the durations (melody at <code>$07E7</code>, harmony at <code>$07E6</code>, bass at <code>$07E5</code>, and
drums at <code>$07E4</code>) are set to <code>$01</code>.

Proceeds to Play Notes.

==== Play Notes ====

This routine is broken into four major and similar sections: one each for
melody, harmony, bass, and drums. The general process is as follows:

decrement duration
if duration == 0 {
load next note
increment note pointer
set duration for note
if no overriding sound effect {
play note on appropriate channel
}
}

Some channels have unique processing at different points in this. For example,
the melody note data is null terminated, so if the loaded note in <code>$00</code> then the
routine will jump to Load Song Data instead to go to the next phrase. If the
drums channel gets a <code>$00</code> note it will reset the drums note pointer to the
drums loop start and repeat the phrase. The bass and harmony channels don't
have this looping behavior. This means that if the bass or harmony channels
aren't long enough, the engine will happily just play whatever data comes next
in the ROM.

The melody is played on pulse 2 channel, the harmony on pulse 1 (which gets
subverted by sound effects that need just one pulse channel), the bass on the
triangle channel, and the drums on the noise channel.

For the pulse channels, after the note is played, the envelope counter for that
channel (<code>$07E2</code> for pulse 1, <code>$07E3</code> for pulse 2) is set. Normally the
envelope is set to <code>$2F</code> but song <code>$40</code> (crystal fanfare and final boss music)
sets it to <code>$18</code> instead. The envelope is not set if no note was played because
the pitch index was <code>$02</code> which indicates a rest.

Also for the pulse channels, after the above pseudocode, the vibrato and
enveloping happens as long as there is no overriding sound effect. The envelope
works by checking the envelope counter set previously and decrementing it. The
counter value is halved and used to look up the envelope value in the LUT at
<code>$9135</code>. These values are written directly to APU register <code>$4000</code> or <code>$4004</code>
depending on the channel.

The bass channel has one special handling as well. The APU register <code>$4008</code> is
set differently based on the current song id. For song <code>$10</code> (item get / level
up fanfare) the register is set to <code>$60</code> but all other songs use <code>$1f</code>.

The noise channel is not affect at all by the pitch. Any pitch value that is
non zero will play a burst of noise.

Music Engine Description

2022-03-30T04:19:44Z

DontBaguMe: /* Title Music Engine */

There are two separate music engines in Zelda 2. Both are in bank 6 (along
with the song data). The music engine for the title screen resides at
<code>$8000</code> and the engine for the rest of the game is at
<code>$9000</code>. Each of these engines is called once per frame during the
appropriate part of the game.

Changes to the music engine should be very easy to make, as there is an
abundance of free space in bank 6.

== Title Music Engine ==

'''TODO''' properly format the following by bgt (original at https://eab.xyz/W2zplGD) and dontbagume (on discord).

# Title Music Engine

The title music engine is different from the engine that plays music
during the rest of the game. In particular, it has a wider range of
notes that can be represented. If you want to look into the actual
code, the title screen music engine main loop is at `$8000` (vesus
`$9000` for the game music loop).

The metadata for the songs is all the same as in the other areas,
although the title music is actually broken up into several songs
itself. These song boundaries control the timing of the title scroll.

The following songs exist in the title song table:

1. Intro
2. Start
3. Build up
4. Main
5. Breakdown

The start of song 2 triggers the title to scroll into view. The start
of song 4 triggers a countdown until the story scroll begins. After
song 5 finishes, the engine loops back to song 2.

Within the note data, a special format is used. Rather than encoding
the duration and pitch together in a single byte, the title music has
"pitch" bytes and "duration" bytes. Any byte with the highest bit set
(i.e. anything >= `$80`) is interpreted as a duration change, which
sets the duration of all future notes. Anything else is a pitch value
which indicates a note of the current duration should be played. The
low nibble of duration values keys into a lookup table at bank 6 `$8084`
and store the duration byte at $07FF. Value durations are as follows:

* `$80` - 8 ticks (sixteenth note)
* `$81` - 24 ticks (dotted eighth note)
* `$82` - 16 ticks (eighth note)
* `$83` - 32 ticks (quarter note)
* `$84` - 48 ticks (dotted quarter note)
* `$85` - 64 ticks (half note)
* `$86` - 96 ticks (dotted half note)
* `$87` - 128 ticks (whole note)
* `$88` - 11 ticks (eighth note triplet)
* `$89` - 10 ticks (???)
* `$8A` - 256 ticks (two whole notes)
* `$8F` - 6 ticks (dotted 32nd note)

The pitch values are much more straightforward. As far as I can tell,
`$4C` is A4 and every semitone away from that adds or subtracts 2 from
the value. Thus, C5 (three semitones above A4) is `$52`. The value
`$02` represents a rest.

-1- -2- -3- -4- -5-
A : $04 $1C $34 $4C $64
Bb : $06 $1E $36 $4E $66
B : $08 $20 $38 $50 $68
C : $0A $22 $3A $52 $6A
C# : $0C $24 $3C $54 $6C
D : $0E $26 $3E $56 $6E
Eb : $10 $28 $40 $58 $70
E : $12 $2A $42 $5A $72
F : $14 $2C $44 $5C $74
F# : $16 $2E $46 $5E $76
G : $18 $30 $48 $60 $78
G# : $1A $32 $4A $62 $7A

By way of an example, let's look at the main section of the vanilla
title music. The title metadata starts at bank 6 `$84DA`:

08 11 14 16 19 1E 1E 1E
^ Main section

The main section is the fourth song, starting at `$84DA + $16 = $84F0`:

3F 3F 00

This means there is a single phrase for the main section, which is
repeated twice. The phrase data is at `$84DA + $3F = $8519`.

00 3D 86 3A 1A 5F

From this, we see the melody note data is located at `$863D`:

83 Quarter notes
02 Rest
48 Ab4
82 Eighth note
46 G4
83 Quarter notes
3E Eb4
34 Bb3
84 Dotted quarter notes
2E G3
83 Quarter notes
30 Ab3
34 Bb3
3A Db4
38 C4
34 Bb3
30 Ab3
82 Eighth notes
34 Bb3
83 Quarter notes
30 Ab3
85 Half notes
2E G3
82 Quarter notes
02 Rest
00 End of Data

dontbagume additions:

DURATION
* `$80` - 6 ticks sixteenth note
* `$81` - 9 ticks dotted eighth note
* `$82` - 12 ticks eighth note
* `$83` - 24 ticks quarter note
* `$84` - 36 ticks dotted quarter note
* `$85` - 48 ticks half note
* `$86` - 72 ticks dotted half note
* `$87` - 96 ticks whole note
* `$88` - 8 ticks eighth triplets
* `$89` - 7 ticks poor man's swung 16th (long)
* `$8A` - 60 ticks half + eighth
* `$8B` - 192 ticks two whole notes
* `$8F` - 5 ticks poor man's swung 16th (short)

PITCH
-1- -2- -3- -4- -5-
A : $04 $1C $34 $4C $64
Bb : $06 $1E $36 $4E $66
B : $08 $20 $38 $50 $68
C : $0A $22 $3A $52 $6A
C# : $0C $24 $3C $54 $6C
D : $0E $26 $3E $56 $6E
Eb : $10 $28 $40 $58 $70
E : $12 $2A $42 $5A $72
F : $14 $2C $44 $5C $74
F# : $16 $2E $46 $5E $76
G : $18 $30 $48 $60 $78
G# : $1A $32 $4A $62 $7A

== Main Music Engine ==

=== Data Tables ===

There are several data tables used by the music engine.

==== Pulse Envelope ====

This table is used to set the volume of the pulse channels over time. The index
used starts at a certain value and decrements, so the table is in reverse order.
The index is halved before use, so each value lasts two frames.

{| class="wikitable"
|+ Pulse Envelope <code>$9135</code>
|90||91||91||91||92||92||92||92
|-
|93||93||94||94||94||95||95||95
|-
|96||96||96||97||97||97||98||98
|}

==== Duration LUT ====

This table is used to determine the duration of a note. The note data is stored
with 5 bits of pitch information and 3 bits of duration, as such:

D1 D0 P4 P3 P2 P1 P0 D2

The Get Note Duration routine shifts things around to get the D bits into the
three least significant bits and masks it before use. This value is then added
to the tempo value in <code>$E5</code> which is always a multiple of 8 to index
into the following table:

{| class="wikitable"
|+Duration LUT <code>$914D</code>
|'''00'''||04||0C||08||10||18||20||05||06
|-
|'''08'''||04||0F||09||12||1B||24||06||06
|-
|'''10'''||05||0F||0A||14||1E||28||07||06
|-
|'''18'''||06||12||0C||18||24||30||08||10
|-
|'''20'''||07||15||0E||1C||2A||38||13||12
|-
|'''28'''||07||15||0E||1C||2A||38||XX||XX
|}

The last two values in each row seem a bit strange, as they are not nice
multiples of the first entry which is usually thought of as the length of an
eighth note. The last row has garbage values in those positions as that is the
start of another data table, so they are not even listed here.

'''TODO''' Check what values are used in vanilla.

==== Pitch LUT ====

This table is used to detemine the pitch of a note. The note data is stored as
described above, and the fact that the least significant bit is masked out is
advantageous since the pulse channels can use 11 bits of timer data, so each
entry in this table is actually two bytes wide.

Rather than show the raw bytes here, it's more useful to show the rough note
that those values represent. If the raw values are interesting to you, check
the ROM for them. It's worth noting that some of the higher notes are several
cents off from the listed note.

{| class="wikitable"
|+Pitch LUT <code>$918F</code>
| || 00|| 02|| 04|| 06|| 08|| 0a|| 0c|| 0e
|-
|00|| C3||---|| E3|| G3||G#3|| A3||A#3|| B3
|-
|10|| C4||C#4|| D4||D#4|| E4|| F4||F#4|| G4
|-
|20||G#4|| A4||A#4|| B4|| C5||C#5|| D5||D#5
|-
|30|| E5|| F5||F#5|| G5|| A5||A#5|| B5||C#3
|-
|40|| D3||D#3|| F3||F#3||G#5|| C6||C#6|| D6
|-
|50||D#6|| E6|| F6||F#6|| G6||G#6|| A6||A#6
|-
|60|| B6|| C7||C#7|| D7||D#7|| E7|| F7||F#7
|-
|70|| G7||G#7|| A7||A#7|| B7|| C8
|}

Value <code>$02</code> represents a rest.

Note that although the table goes through <code>$7A</code> values above
<code>$3E</code> aren't usable due to the 5 bit limit for pitch data in
the song data. However, the sound effects routines make use of these
extra notes. For example, the sword beam effect alternates between
playing C7 and F6.

==== Noise Samples ====

Several sound effects use the same routine to load "samples" for the noise
channel to play. These values have the noise volume in the high nybble and the
noise period in the low nybble.

$90E8 - Sword slash
$9123 - Enemy hurt
$912C - Crumble block

=== Variables ===

This is just a dump of RAM addresses used by the music engine and a short
description of what they are.

$00E0 - Current phrase note data address (low byte)
$00E1 - Current phrase note data address (high byte)
$00E2 - Song offset, converted from song id to be an index instead of a bit field
$00E3 - Current phrase index
$00E4 - Drums loop start
$00E5 - Tempo
$00E6 - Pulse 1 low bits (used for vibrato effect)
$00E7 - Pulse 2 low bits (used for vibrato effect)
$00E8 - Pitch storage, temporary
$00E9 - Play sound effect
$00EA - Disable music
$00EB - Request new song
$00EC - Play sound effect
$00ED - Play sound effect
$00EE - Play sound effect
$00EF - Play sound effect

$0707 - Current world
$075F - Queued song, loaded after screen transitions
$07DA - Ganon Laugh sample
$07DB - Song to resume after fanfare
$07DF - ??? Likely sound effect flag for pulse 1 channel override

$07E0 - ??? Likely sound effect flag for noise channel
$07E2 - Pulse 2 envelope index
$07E3 - Pulse 1 envelope index
$07E4 - Drums current note duration
$07E5 - Bass current note duration
$07E6 - Harmony current note duration
$07E7 - Melody current note duration
$07E8 - Drums next note index
$07E9 - Bass next note index
$07EA - Harmony next note index
$07EB - Melody next note index

$07EC - Ganon Laugh counter
$07ED - Sound FX counter (E9)
$07EE - Sound FX counter (E9)
$07F5 - Sound FX counter (ED)

$07FA - Current SFX (E9)
$07FB - Current song
$07FD - Current SFX (ED)
$07FE - ??? Likely sound effect flag for pulse 2 channel override
$07FF - Current SFX (EF)

=== Routines ===

This is a non-exhaustive list of the routines in bank 6 involving the playing of
music and sound effects. Each routine also lists its address so you can search
in a disassembly for the actual code for that routine if these descriptions
aren't clear.

==== Main Music Loop <code>$9000</code> ====

Checks that the music disable flag is off, then runs several SFX routines.
After the SFX routines, the main music routine runs. After all this, various
music related memory locations are cleared.

==== Configure Pulse1 Channel <code>$9031</code> ====

Takes registers x and y and configures the APU registers <code>$4000</code> and <code>$4001</code>
respectively.

==== Configure Pulse2 Channel <code>$9038</code> ====

Takes registers x and y and configures the APU registers <code>$4004</code> and <code>$4005</code>
respectively.

==== Play Note Pulse1 <code>$9042</code> ====

Takes a pitch index in register a and plays the note on the pulse 1 channel.

==== Play Note <code>$9044</code> ====

Called by the various play note routines. Takes a pitch index in register a and
uses register x as a channel selector. For the pulse channels, this routine
also saves the lower 8 bits of the APU timer register to <code>$E6</code> or <code>$E7</code> which
are used for a vibrato effect.

==== Play Note Pulse2 <code>$9067</code> ====

Takes a pitch index in register a and plays the note on the pulse 2 channel.

==== Play Note Triangle <code>$906B</code> ====

Takes a pitch index in register a and plays the note on the triangle channel.

==== Get Note Duration <code>$906F</code> ====

Takes note data in register a and looks up the duration. The original note
data is saved in register x and the result of the duration lookup is put in
register a. The duration lookup is offset by the tempo stored in <code>$E5</code>.

==== Vibrato Pulse1 <code>$9089</code> ====

Applies a vibrato effect on the pulse 1 channel. Takes the duration of the note
left in register a and the APU timer low bits in register y.

==== Vibrato Pulse2 <code>$9097</code> ====

Applies a vibrato effect on the pulse 2 channel. Takes the duration of the note
left in register a and the APU timer low bits in register y.

==== Vibrato <code>$909E</code> ====

Takes the duration of the note remaining in register a, the low bits of the APU
timer in register y, and the channel to use in register x. This is called by
the other vibrato routines after setting x appropriately.

Uses the <code>$04</code> bit of the duration to either add or subtract 2 from the low
timer bits. Only the low bits are used because writing to the high bits resets
the phase of the channel which can cause clicks. None of the notes from the
pitch LUT are close enough to the boundary for the change to require the high
bits to change anyway, so this works out fine.

==== Play E9 SFX <code>$920B</code> ====

Plays the sound effect requested in <code>$E9</code>.

'''TODO''' document further.

==== Play EF SFX <code>$92F4</code> ====

Plays the sound effect requested in <code>$EF</code>.

'''TODO''' document further.

==== Play EE SFX <code>$9408</code> ====

Plays the sound effect requested in <code>$EE</code>.

'''TODO''' document further.

==== Play Noise <code>$959D</code> ====

Configures the APU noise registers to make a noise burst. Takes configuration
for registers <code>$400F</code>, <code>$400E</code>, and <code>$400C</code> in registers y, x, and a.

==== Crumble Bridge SFX <code>$956C</code> ====

Starts playing the sound effect for a crumble bridge crumbling. This uses both
the noise and the triangle channels so it sets flags to disable the music on
those channels. Continues with SFX Noise Decay.

==== SFX Noise Decay <code>$9587</code> ====

Counts down the timer in <code>$07F5</code> and turns off the noise when it reaches 0.
Also clears the flag for the ED sound effect in <code>$07FD</code>.

==== Play ED SFX <code>$95A7</code> ====

Plays the sound effect request in <code>$ED</code> or continues the sound effect saved in
<code>$07FD</code>. Existing sound effects which are higher than the current sound effect
will be ignored. If the same sound effect is requested that is already playing,
it will restart the sound effect except for <code>$80</code> which gives priority to
continuing. When the sound is continued instead of newly played, the decay
routine will be called instead.

; <code>$02</code>
: Crumble Bridge
; <code>$04</code> and <code>$10</code>
: Crumble Block / Enemy Hurt
; <code>$20</code> and <code>$80</code>
: Sword Strike
; <code>$40</code>
: Very short noise burst, probably unused. Doesn't store the effect, and doesn't have an associated decay.

==== Crumble Block / Enemy Hurt SFX <code>$95E6</code> ====

Starts playing the sound of a block breaking or an enemy getting hurt.

==== Crumble Block / Enemy Hurt SFX Decay <code>$95EE</code> ====

Looks up noise register values based on the timer and the sound effect value.
Crumble Block samples are at <code>$912C</code> while Enemy Hurt is at <code>$9123</code>. Continues
on to Play Noise Samples.

==== Play Noise Samples <code>$9612</code> ====

Takes a sample value in register a. The low four bits of this are used to set
the noise period via APU register <code>$400E</code>. The high four bits are used to set
the noise volume via APU register <code>$400C</code>.

Continues on the SFX Noise Decay process.

==== Sword Strike SFX <code>$9604</code> ====

Starts playing the sound of swinging your sword. This looks up samples based on
the duration left at <code>$90E8</code> and plays them via Play Noise Samples.

==== Play EC SFX <code>$990B</code> ====

Plays the sound effect requested in <code>$EC</code>.

'''TODO''' document further.

==== Play Music <code>$9B18</code> ====

Plays the music for the game.

Runs Load Song if a new song is requested in <code>$EB</code>. Otherwise, runs Play Notes
if the current song is set in <code>$07FB</code>. If neither of these is true, do nothing.

==== Next Song <code>$9B24</code> ====

Checks if the previous song should loop. If not, calls Mute All and returns.

If the previous song was <code>$01</code> (the "intro" to the main theme), sets the next
song to <code>$02</code> (the main theme loop).

If the previous song was <code>$10</code> (the item get / level up fanfare), sets the
current song from <code>$07DB</code>. Otherwise, leaves the current song the same as the
previous song.

Proceeds to Load Song.

==== Mute All <code>$9B3B</code> ====

Clears the current song at <code>$07FB</code> and sets the APU registers to mute the volume
on both pulse channels, the triangle channel, and the noise channel.

==== Load Song <code>$9B61</code> ====

Takes a song id in register a and preps some variables for that song.

If the song is <code>$10</code> (item get / level up fanfare) then it first saves the
previous song to <code>$07FB</code> if it is less than <code>$10</code> so that the previous music
will resume after the fanfare.

Sets the phrase counter at <code>$E3</code> to 0 and the song offset at <code>$E2</code> based on the
song id. Song ids are a bit field, and the song offset is the position of the
lowest bit in the song id for indexing into the song table.

Proceeds to Load Song Data.

==== Load Song Data <code>$9B80</code> ====

Loads the music variables based on the current world and current song offset.

There are four blocks of code that are basically the same, for each of the four
different music tables. Each one just uses a different position for the tables
to load.

Based on the current world in <code>$0707</code> it loads data from these offsets:

<code>$00</code>
: Overworld music - <code>$9B87</code>
<code>$01</code> or <code>$02</code>
: Town music - <code>$9BC6</code>
<code>$03</code> or <code>$04</code>
: Palace music - <code>$9C05</code>
<code>$05</code> or higher
: Great Palace music - <code>$9C42</code>

First, uses the song offset in <code>$E2</code> to index into the song table at the base
offset given above.

The phrase counter at <code>$E3</code> is added to that and used as in index again to
retrieve the current phrase offset. If the current phrase offset is <code>$00</code> that
means the song is over and the process goes back to the Next Song routine.

Otherwise, the following structure is read at the base offset above + phrase
offset just calculated.

* <code>$E5</code> Tempo
* <code>$E0</code> Note Data Low
* <code>$E1</code> Note Data High
* <code>$07E9</code> Bass Note Pointer
* <code>$07EA</code> Harmony Note Pointer
* <code>$07E8</code> Drum Note Pointer

After this, the drum loop start point at <code>$E4</code> is also set to the same value as
the drum note pointer. The melody note pointer at <code>$07EB</code> is set to <code>$00</code>, and
all the durations (melody at <code>$07E7</code>, harmony at <code>$07E6</code>, bass at <code>$07E5</code>, and
drums at <code>$07E4</code>) are set to <code>$01</code>.

Proceeds to Play Notes.

==== Play Notes ====

This routine is broken into four major and similar sections: one each for
melody, harmony, bass, and drums. The general process is as follows:

decrement duration
if duration == 0 {
load next note
increment note pointer
set duration for note
if no overriding sound effect {
play note on appropriate channel
}
}

Some channels have unique processing at different points in this. For example,
the melody note data is null terminated, so if the loaded note in <code>$00</code> then the
routine will jump to Load Song Data instead to go to the next phrase. If the
drums channel gets a <code>$00</code> note it will reset the drums note pointer to the
drums loop start and repeat the phrase. The bass and harmony channels don't
have this looping behavior. This means that if the bass or harmony channels
aren't long enough, the engine will happily just play whatever data comes next
in the ROM.

The melody is played on pulse 2 channel, the harmony on pulse 1 (which gets
subverted by sound effects that need just one pulse channel), the bass on the
triangle channel, and the drums on the noise channel.

For the pulse channels, after the note is played, the envelope counter for that
channel (<code>$07E2</code> for pulse 1, <code>$07E3</code> for pulse 2) is set. Normally the
envelope is set to <code>$2F</code> but song <code>$40</code> (crystal fanfare and final boss music)
sets it to <code>$18</code> instead. The envelope is not set if no note was played because
the pitch index was <code>$02</code> which indicates a rest.

Also for the pulse channels, after the above pseudocode, the vibrato and
enveloping happens as long as there is no overriding sound effect. The envelope
works by checking the envelope counter set previously and decrementing it. The
counter value is halved and used to look up the envelope value in the LUT at
<code>$9135</code>. These values are written directly to APU register <code>$4000</code> or <code>$4004</code>
depending on the channel.

The bass channel has one special handling as well. The APU register <code>$4008</code> is
set differently based on the current song id. For song <code>$10</code> (item get / level
up fanfare) the register is set to <code>$60</code> but all other songs use <code>$1f</code>.

The noise channel is not affect at all by the pitch. Any pitch value that is
non zero will play a burst of noise.