Clarify the relation between hMusicTrack, hNextMusicTrack and wActiveMusicTrack

[kemenaran]

There are several variables controlling the music track playback:

• hMusicTrack,
• hNextMusicTrack,
• wActiveMusicTrack

These variables are often used together, but seem to have subtle differences (like one of these seems to have immediate effect, and another to store the track to be played after a transition).

We should understand better what these variables do (and maybe rename some of them accordingly).

[Vextrove]

wActiveMusicTrack ($D368) - setting this begins playing a new track and then resets itself to 00

hMusicTrack ($FFB0) - is the track of the current area, e.g. overworld, village, mysterious forest, etc.
is set when entering an area as soon as the previous area's music has fully faded out.

hNextMusicTrack ($FFB1) - is set when entering a new area and the previous track begins fading out. When the music from the previous area has finished fading out, hNextMusicTrack is set to 00.

hNextWorldMusicTrack ($FFBF) - Same as_ hMusicTrack_, but set immediately when entering a new area, rather than when the previous track has fully faded out.

[Vextrove]

When $D369 is set to 00, music stops playing.
$FFBC sometimes stores the currently audible (what you actually hear) trackID.
$FFBD seems to store trackIDs, but only updates in special cases.

For music that plays after a previous track has faded out first:
At $D369 is the ID of the music that is audible.
At $D3CA is also the ID of the music that is audible.
At $D3CB is the ID of the track that was previously playing. The value gets set to the ID of the track when it has finished fading out, which is copied from $D3CA.

For music that plays immediately without fading out the previous track first:
$D3CB seems to hold the ID of the currently playing track.
$D369 and $D3CA have the trackID but with a value subtracted. (See next comments)

[Vextrove]

When manually setting the music using wActiveMusicTrack using a debugger, $D369 holds the ID of the currently audible track, but but with a value subtracted. (See next comment)

[Vextrove]

wMusicMode ($D3CE) - For some tracks this is set to 01. For others, it is set to 00.

When writing $00 to $10 to wActiveMusicTrack, $D369 matches the trackID written to wActiveMusicTrack. wMusicMode set to 01
trackIDs from $11 to $30: $10 gets subtracted from the trackID. wMusicMode set to 00
trackIDs from $31 to $60: $20 gets subtracted from the trackID. wMusicMode set to 00
trackIDs from $61 to $6F: $40 gets subtracted from the trackID. wMusicMode set to 01
trackIDs from $70 to $FE: matches trackID written in wActiveMusicTrack. wMusicMode set to 00
trackIDs $FF: sets $D369 to $00. wMusicMode is not set.

EDIT: Whether wMusicMode is set to 01 or not seems to depend on whether MusicDataPointerTable_1E (music_2.asm) is used or not, rather than MusicDataPointerTable_1B (music_1.asm)

[Vextrove]

I propose wActiveMusicTrack be renamed to wMusicTrackToPlay,
and hMusicTrack to hCurrentScreenTrack.

hNextMusicTrack to hNextScreenTrackToFadeInto, but I am not sure about this one. I will have to do some more debugging on this.

hNextWorldMusicTrack to hNextScreenTrack - for consistency with hCurrentScreenTrack, but 'World' instead of 'Area' is fine.

[kemenaran]

Nice findings 👍

So, apparently, music tracks all have a global ID, which is a unique number identifying a track (that would match the MUSIC_ constants in constants/sfx.asm)

But tracks can be stored in two different pointers tables (in music_1 and music_2). So tracks IDs have an associated table, index tuple, which tells where to find the address for the track.

So we can make clear in the naming or the variables whether we are speaking about the index of a music track (i.e. the substracted value that is used to look up addresses in the pointers table) or the id of a music track (i.e. the value equal to the MUSIC_ constants), presumed by default.

So I would suggest:

• wActiveMusicTrack -> wMusicTrackToPlay (because it matches its purpose better, indeed)
• wMusicMode -> wActiveMusicTable (0 or 1, for "use table in music 1 or in music2")
• $D369 -> wActiveMusicIndex (index in the music table)
• hMusicTrack -> hActiveMusicTrack (I feel like 'active' is the same than 'current screen', but shorter)
• hNextMusicTrack -> hNextMusicTrackToFadeInto 👍
• hNextWorldMusicTrack -> I would keep it as this for now

What do you think?

[Vextrove]

I'm glad you figured all that index stuff out! wActiveMusicIndex and wActiveMusicTable sound great.

hMusicTrack is not the active music track. It is the default track of the current area, or more specifically screen. When things like item fanfares finish playing or your powerup expires, it will return to the default track.
'ActiveMusicTrack' sounds like it is the track is actually currently playing, which is not always the case. More importantly, it does not convey that it is the default track of the area. This is how this memory address is used in the code; to set a track to play after a special track that is temporarily playing, e.g. cutscene music, item jingles, etc. After noticing this in the code, I think hDefaultMusicTrack is better than my previously proposed hCurrentScreenTrack.

hMusicTrack and hNextWorldMusicTrack are related. I would name hNextWorldMusicTrack the same as whatever hMusicTrack becomes but with 'Next' inserted in front of it. (hNextDefaultMusicTrack)

[Vextrove]

I will change these variables and submit a PR tomorrow.

EDIT: done.