"Add a new music song" tutorial

7 files changed, 212 insertions, 2 deletions

diff --git a/Add-a-new-music-song.md b/Add-a-new-music-song.md
new file mode 100644
index 0000000..e23ab93
--- /dev/null
+++ b/Add-a-new-music-song.md
@@ -0,0 +1,93 @@
+This tutorial is for how to add a new music song. As an example, we'll add the [Route 47 theme](https://soundcloud.com/mmmmmmmmmmmmmmmmm-1/route-47-gbc-8-bit) demixed from HGSS by [Mmmmmm](https://soundcloud.com/mmmmmmmmmmmmmmmmm-1).
+
+
+## Contents
+
+1. [Define a `MUSIC_ROUTE_47` constant](#1-define-a-music-route-47-constant)
+2. [Create a file for the song](#2-create-a-file-for-the-song)
+3. [Update the music pointers](#3-update the music pointers)
+4. [Include the new file in the ROM](#4-include-the-new-file-in-the-rom)
+
+
+## 1. Define a `MUSIC_ROUTE_47` constant
+
+Edit [constants/music_constants.asm](../blob/master/constants/music_constants.asm):
+
+```diff
+ ; 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](../blob/master/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](https://soundcloud.com/froggestspirit), [Mmmmmm](https://soundcloud.com/mmmmmmmmmmmmmmmmm-1), [ShantyTown](https://soundcloud.com/huderlem), and [Pum](https://www.youtube.com/playlist?list=PLQHiVZUO5so0LHdQzx6iu4Ze0zCkbbm7N).
+
+For now, download the [source code](https://pastebin.com/raw/aSDuVfDW) 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](../blob/master/audio/music_pointers.asm):
+
+```diff
+ ; 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](../blob/master/audio.asm):
+
+```diff
+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](../blob/master/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](Hard-coded-logic#some-high-values-for-maps-music-ids-play-incorrectly) page.
diff --git a/Expand-tilesets-from-192-tiles-to-255.md b/Expand-tilesets-from-192-tiles-to-255.md
new file mode 100644
index 0000000..2c47641
--- /dev/null
+++ b/Expand-tilesets-from-192-tiles-to-255.md
@@ -0,0 +1,2 @@
+![Screenshot](screenshots/192-tiles-vram.png)
+![Screenshot](screenshots/johto-modern.png)
diff --git a/Hard-coded-logic.md b/Hard-coded-logic.md
index 9806570..22e3f4c 100644
--- a/Hard-coded-logic.md
+++ b/Hard-coded-logic.md
@@ -7,6 +7,7 @@ Much of the game logic can be changed via the files in [data/](../blob/master/da
 - [Maps that don't display a location sign](#maps-that-dont-display-a-location-sign)
 - [Outdoor maps within indoor maps don't confuse Dig or Escape Rope](#outdoor-maps-within-indoor-maps-dont-confuse-dig-or-escape-rope)
 - [Landmark limits when scrolling in the Town Map](#landmark-limits-when-scrolling-in-the-town-map)
+- [Some high values for maps' music IDs play incorrectly](#some-high-values-for-maps-music-ids-play-incorrectly)
 - [Trainer classes with different battle music](#trainer-classes-with-different-battle-music)
 - [`RIVAL1`'s first Pokémon has no held item](#rival1s-first-pokémon-has-no-held-item)
 - [`RIVAL1` and `RIVAL2` don't print their trainer class in battle](#rival1-and-rival2-dont-print-their-trainer-class-in-battle)
@@ -130,6 +131,119 @@ This is caused by `InitEnemyTrainer` in [engine/battle/core.asm](../blob/master/
 ```
 
 
+## Some high values for maps' music IDs play incorrectly
+
+If a map's music ID is $64 (the value of `MUSIC_MAHOGANY_MART` or `MUSIC_SUICUNE_BATTLE`) in [data/maps/maps.asm](../blob/master/data/maps/maps.asm) it will play either `MUSIC_ROCKET_HIDEOUT` or `MUSIC_CHERRYGROVE_CITY`. Moreover, if a map's music ID is $80 or above (the value of `RADIO_TOWER_MUSIC`) it might play `MUSIC_ROCKET_OVERTURE` or something else.
+
+This is caused by `GetMapMusic` in [home/map.asm](../blob/master/home/map.asm):
+
+```asm
+GetMapMusic:: ; 2cbd
+	push hl
+	push bc
+	ld de, MAP_MUSIC
+	call GetMapField
+	ld a, c
+	cp MUSIC_MAHOGANY_MART
+	jr z, .mahoganymart
+	bit RADIO_TOWER_MUSIC_F, c
+	jr nz, .radiotower
+	farcall Function8b342
+	ld e, c
+	ld d, 0
+.done
+	pop bc
+	pop hl
+	ret
+
+.radiotower
+	ld a, [wStatusFlags2]
+	bit STATUSFLAGS2_ROCKETS_IN_RADIO_TOWER_F, a
+	jr z, .clearedradiotower
+	ld de, MUSIC_ROCKET_OVERTURE
+	jr .done
+
+.clearedradiotower
+	; the rest of the byte
+	ld a, c
+	and RADIO_TOWER_MUSIC - 1
+	ld e, a
+	ld d, 0
+	jr .done
+
+.mahoganymart
+	ld a, [wStatusFlags2]
+	bit STATUSFLAGS2_ROCKETS_IN_MAHOGANY_F, a
+	jr z, .clearedmahogany
+	ld de, MUSIC_ROCKET_HIDEOUT
+	jr .done
+
+.clearedmahogany
+	ld de, MUSIC_CHERRYGROVE_CITY
+	jr .done
+; 2cff
+```
+
+This can cause problems if you add too many new music songs, or rearrange the existing ones. A solution would be to redefine the special music constants in [constants/music_constants.asm](../blob/master/constants/music_constants.asm):
+
+```asm
+; GetMapMusic picks music for these values (see home/map.asm)
+MUSIC_MAHOGANY_MART EQU $fc
+MUSIC_RADIO_TOWER   EQU $fd
+
+; ExitPokegearRadio_HandleMusic uses these values
+RESTART_MAP_MUSIC   EQU $fe
+ENTER_MAP_MUSIC     EQU $ff
+```
+
+And then edit `GetMapMusic`:
+
+```asm
+GetMapMusic:: ; 2cbd
+	push hl
+	push bc
+	ld de, MAP_MUSIC
+	call GetMapField
+	ld a, c
+	cp MUSIC_MAHOGANY_MART
+	jr z, .mahoganymart
+	cp MUSIC_RADIO_TOWER
+	jr z, .radiotower
+	farcall Function8b342
+	ld e, c
+	ld d, 0
+.done
+	pop bc
+	pop hl
+	ret
+
+.radiotower
+	ld a, [wStatusFlags2]
+	bit STATUSFLAGS2_ROCKETS_IN_RADIO_TOWER_F, a
+	jr z, .clearedradiotower
+	ld de, MUSIC_ROCKET_OVERTURE
+	jr .done
+
+.clearedradiotower
+	ld de, MUSIC_GOLDENROD_CITY
+	jr .done
+
+.mahoganymart
+	ld a, [wStatusFlags2]
+	bit STATUSFLAGS2_ROCKETS_IN_MAHOGANY_F, a
+	jr z, .clearedmahogany
+	ld de, MUSIC_ROCKET_HIDEOUT
+	jr .done
+
+.clearedmahogany
+	ld de, MUSIC_CHERRYGROVE_CITY
+	jr .done
+; 2cff
+```
+
+You'll also need to edit [data/maps/maps.asm](../blob/master/data/maps/maps.asm) so the Radio Tower maps use `MUSIC_RADIO_TOWER` instead of `RADIO_TOWER_MUSIC | MUSIC_GOLDENROD_CITY`.
+
+
 ## Trainer classes with different battle music
 
 This is caused by `PlayBattleMusic` in [engine/battle/start_battle.asm](../blob/master/engine/battle/start_battle.asm). The routine's logic is:
diff --git a/New-Moves.md b/New-Moves.md
deleted file mode 100644
index 3874643..0000000
--- a/New-Moves.md
+++ /dev/null
@@ -1 +0,0 @@
-New Moves
\ No newline at end of file
diff --git a/Tutorials.md b/Tutorials.md
index 95f5d88..ab81387 100644
--- a/Tutorials.md
+++ b/Tutorials.md
@@ -10,12 +10,14 @@ Tutorials may use diff syntax to show edits:
 **How to add a new…**
 
 - [Type (Fairy)](Add-a-new-Fairy-type)
+- [Music song](Add-a-new-music-song)
 
 **Upgrades to existing features:**
 
+- [Expand tilesets from 192 tiles to 255](Expand-tilesets-from-192-tiles-to-255)
+- [Allow map tiles to appear above sprites (so NPCs can walk behind tiles) with `PRIORITY` colors](Allow-map-tiles-to-appear-above-sprites-\(so-NPCs-can-walk-behind-tiles\)-with-PRIORITY-colors)
 - [Remove the 25% failure chance for AI status moves](Remove-the-25%25-failure-chance-for-AI-status-moves)
 - [Colored trainer card badges](Colored-trainer-card-badges)
-- [Allow map tiles to appear above sprites (so NPCs can walk behind tiles) with `PRIORITY` colors](Allow-map-tiles-to-appear-above-sprites-\(so-NPCs-can-walk-behind-tiles\)-with-PRIORITY-colors)
 
 **Features from later generations:**
 
diff --git a/screenshots/192-tiles-vram.png b/screenshots/192-tiles-vram.png
new file mode 100644
index 0000000..262b63f
--- /dev/null
+++ b/screenshots/192-tiles-vram.png
diff --git a/screenshots/johto_modern.png b/screenshots/johto_modern.png
new file mode 100644
index 0000000..1c080ff
--- /dev/null
+++ b/screenshots/johto_modern.png