Add a new music song

This tutorial is for how to add a new music song. As an example, we'll add the Route 47 theme demixed from HGSS by Mmmmmm.

Contents

1. Define a MUSIC_* constant
2. Create a file for the song
3. Update the music pointers
4. Include the new file in the ROM

1. Define a MUSIC_* constant

Edit constants/music_constants.asm:

 ; song ids
 ; Music indexes (see audio/music_pointers.asm)
 	const_def
 
 	const MUSIC_NONE                         ; 00
 	...
 	const MUSIC_MOBILE_CENTER                ; 66
+	const MUSIC_ROUTE_47                     ; 67

2. Create a file for the song

Writing your own music is beyond the scope of this tutorial. If you're interested in doing that, start by reading docs/music_commands.md and the source code of existing music. However, there's already a lot of new music available, demixed and remixed from other games by composers like FroggestSpirit, Mmmmmm, ShantyTown, and Pum.

For now, download the source code for Mmmmmm's Route 47 theme and save it as audio/music/route47.asm:

Music_Route47:
	musicheader 4, 1, Music_Route47_Ch1
	musicheader 1, 2, Music_Route47_Ch2
	musicheader 1, 3, Music_Route47_Ch3
	musicheader 1, 4, Music_Route47_Ch4

Music_Route47_Ch1:
	...

Music_Route47_Ch2:
	...

Music_Route47_Ch3:
	...

Music_Route47_Ch4:
	...

Notice the label Music_Route47 before the headers. That's used in the table of music pointers to identify the whole song.

3. Update the music pointers

Edit audio/music_pointers.asm:

 ; See song sections in audio.asm.
 
 Music: ; e906e
 ; entries correspond to MUSIC_* constants
 
 	dba Music_Nothing ; 0xe91a3
 	...
 	dba Music_PostCredits ; 0xcfd9e
 
 ; Crystal adds the following songs:
 
 	dba Music_Clair ; 0x1fa8d
 	...
 	dba Music_MobileCenter ; 0x17961d
 ; e91a3
+	dba Music_Route47

4. Include the new file in the ROM

Edit audio.asm:

+SECTION "New Songs", ROMX
+
+INCLUDE "audio/music/route47.asm"

That's it! Now you can use MUSIC_ROUTE_47 like any other music constant—try assigning it to a map in data/maps/maps.asm.

There is one thing to be aware of if you plan to add a lot of new songs. Crystal's music IDs go from $00, MUSIC_NONE, to $66, MUSIC_MOBILE_CENTER. If the IDs reach $80 or above they have their high bit set and start getting interpreted differently by GetMapMusic. There's a full explanation and fix at the hard-coded logic page.