commented audio code

audio.asm

@@ -364,10 +364,10 @@ SECTION "Audio Engine 1", ROMX, BANK[AUDIO_1]
 
 PlayBattleMusic:: ; 0x90c6
 	xor a
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
 	ld [wLowHealthAlarm], a
 	dec a
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound ; stop music
 	call DelayFrame
 	ld c, BANK(Music_GymLeaderBattle)
@@ -406,7 +406,7 @@ Music_RivalAlternateStart:: ; 0x9b47
 	ld c, BANK(Music_MeetRival)
 	ld a, MUSIC_MEET_RIVAL
 	call PlayMusic
-	ld hl, wc006
+	ld hl, wChannelCommandPointers
 	ld de, Music_MeetRival_branch_b1a2
 	call Audio1_OverwriteChannelPointer
 	ld de, Music_MeetRival_branch_b21d
@@ -425,30 +425,30 @@ Music_RivalAlternateTempo:: ; 0x9b65
 	ld c, BANK(Music_MeetRival)
 	ld a, MUSIC_MEET_RIVAL
 	call PlayMusic
-	ld hl, wc006
+	ld hl, wChannelCommandPointers
 	ld de, Music_MeetRival_branch_b119
 	jp Audio1_OverwriteChannelPointer
 
 ; applies both the alternate start and alternate tempo
 Music_RivalAlternateStartAndTempo:: ; 0x9b75
 	call Music_RivalAlternateStart
-	ld hl, wc006
+	ld hl, wChannelCommandPointers
 	ld de, Music_MeetRival_branch_b19b
 	jp Audio1_OverwriteChannelPointer
 
 ; an alternate tempo for Cities1 which is used for the Hall of Fame room
 Music_Cities1AlternateTempo:: ; 0x9b81
-	ld a, $a
-	ld [wcfc8], a
-	ld [wcfc9], a
-	ld a, $ff
-	ld [wMusicHeaderPointer], a
+	ld a, 10
+	ld [wAudioFadeOutCounterReloadValue], a
+	ld [wAudioFadeOutCounter], a
+	ld a, $ff ; stop playing music after the fade-out is finished
+	ld [wAudioFadeOutControl], a
 	ld c, 100
-	call DelayFrames
+	call DelayFrames ; wait for the fade-out to finish
 	ld c, BANK(Music_Cities1)
 	ld a, MUSIC_CITIES1
 	call PlayMusic
-	ld hl, wc006
+	ld hl, wChannelCommandPointers
 	ld de, Music_Cities1_branch_aa6f
 	jp Audio1_OverwriteChannelPointer
 
@@ -477,7 +477,7 @@ Music_DoLowHealthAlarm:: ; 2136e (8:536e)
 
 .asm_2138a
 	ld a, $86
-	ld [wc02a], a ;disable sound channel?
+	ld [wChannelSoundIDs + CH4], a ;disable sound channel?
 	ld a, [wLowHealthAlarm]
 	and $7f ;decrement alarm timer.
 	dec a
@@ -491,7 +491,7 @@ Music_DoLowHealthAlarm:: ; 2136e (8:536e)
 .disableAlarm
 	xor a
 	ld [wLowHealthAlarm], a  ;disable alarm
-	ld [wc02a], a  ;re-enable sound channel?
+	ld [wChannelSoundIDs + CH4], a  ;re-enable sound channel?
 	ld de, .toneDataSilence
 	jr .playTone
 
@@ -542,7 +542,7 @@ Music_PokeFluteInBattle:: ; 22306 (8:6306)
 	ld a, SFX_CAUGHT_MON
 	call PlaySoundWaitForCurrent
 	; then immediately overwrtie the channel pointers
-	ld hl, wc00e
+	ld hl, wChannelCommandPointers + CH4 * 2
 	ld de, SFX_08_PokeFlute_Ch1
 	call Audio2_OverwriteChannelPointer
 	ld de, SFX_08_PokeFlute_Ch2
@@ -572,7 +572,7 @@ PlayPokedexRatingSfx:: ; 7d13b (1f:513b)
 .gotSfxPointer
 	push bc
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySoundWaitForCurrent
 	pop bc
 	ld b, $0

constants/hardware_constants.asm

@@ -107,4 +107,3 @@ rUNKNOWN5   EQU $ff75 ; (8Fh) - Bit 4-6 (Read/Write)
 rUNKNOWN6   EQU $ff76 ; (00h) - Always 00h (Read Only)
 rUNKNOWN7   EQU $ff77 ; (00h) - Always 00h (Read Only)
 rIE         EQU $ffff ; Interrupt Enable (R/W)
-

constants/music_constants.asm

@@ -1,3 +1,42 @@
+; HW sound channel register base addresses
+HW_CH1_BASE EQU (rNR10 % $100)
+HW_CH2_BASE EQU ((rNR21 % $100) - 1)
+HW_CH3_BASE EQU (rNR30 % $100)
+HW_CH4_BASE EQU ((rNR41 % $100) - 1)
+
+; HW sound channel enable bit masks
+HW_CH1_ENABLE_MASK EQU %00010001
+HW_CH2_ENABLE_MASK EQU %00100010
+HW_CH3_ENABLE_MASK EQU %01000100
+HW_CH4_ENABLE_MASK EQU %10001000
+
+; HW sound channel disable bit masks
+HW_CH1_DISABLE_MASK EQU (~HW_CH1_ENABLE_MASK & $ff)
+HW_CH2_DISABLE_MASK EQU (~HW_CH2_ENABLE_MASK & $ff)
+HW_CH3_DISABLE_MASK EQU (~HW_CH3_ENABLE_MASK & $ff)
+HW_CH4_DISABLE_MASK EQU (~HW_CH4_ENABLE_MASK & $ff)
+
+REG_DUTY_SOUND_LEN  EQU 1
+REG_VOLUME_ENVELOPE EQU 2
+REG_FREQUENCY_LO    EQU 3
+
+MAX_SFX_ID EQU $B9
+
+CRY_SFX_START EQU $14
+CRY_SFX_END   EQU $86
+
+; wChannelFlags1 constants
+BIT_PERFECT_PITCH         EQU 0 ; controlled by toggleperfectpitch command
+BIT_CHANNEL_CALL          EQU 1 ; if in channel call
+BIT_NOISE_OR_SFX          EQU 2 ; if channel is the music noise channel or an SFX channel
+BIT_VIBRATO_DIRECTION     EQU 3 ; if the pitch is above or below normal (cycles)
+BIT_PITCH_BEND_ON         EQU 4 ; if pitch bend is active
+BIT_PITCH_BEND_DECREASING EQU 5 ; if the pitch bend frequency is decreasing (instead of increasing)
+BIT_ROTATE_DUTY           EQU 6 ; if rotating duty
+
+; wChannelFlags2 constant (only has one flag)
+BIT_EXECUTE_MUSIC EQU 0 ; if in execute music
+
 ; Song ids are calculated by address to save space.
 
 music_const: MACRO

engine/battle/animations.asm

@@ -772,7 +772,7 @@ DoBallTossSpecialEffects: ; 78f3e (1e:4f3e)
 	dec b
 	jr nz,.loop
 	ld a,%00001000
-	ld [$ff10],a ; Channel 1 sweep register
+	ld [rNR10],a ; Channel 1 sweep register
 	ret
 .isTrainerBattle ; if it's a trainer battle, shorten the animation by one frame
 	ld a,[W_SUBANIMCOUNTER]
@@ -2335,19 +2335,19 @@ GetMoveSound: ; 7986f (1e:586f)
 	call GetCryData
 	ld b,a
 	pop hl
-	ld a,[wc0f1]
+	ld a,[wFrequencyModifier]
 	add [hl]
-	ld [wc0f1],a
+	ld [wFrequencyModifier],a
 	inc hl
-	ld a,[wc0f2]
+	ld a,[wTempoModifier]
 	add [hl]
-	ld [wc0f2],a
+	ld [wTempoModifier],a
 	jr .done
 .NotCryMove
 	ld a,[hli]
-	ld [wc0f1],a
+	ld [wFrequencyModifier],a
 	ld a,[hli]
-	ld [wc0f2],a
+	ld [wTempoModifier],a
 .done
 	ld a,b
 	ret
@@ -3029,8 +3029,8 @@ PlayApplyingAttackSound: ; 79e6a (1e:5e6a)
 	ld b, $1
 	ld c, SFX_NOT_VERY_EFFECTIVE
 .playSound
-	ld [wc0f1], a
+	ld [wFrequencyModifier], a
 	ld a, b
-	ld [wc0f2], a
+	ld [wTempoModifier], a
 	ld a, c
 	jp PlaySound

engine/battle/common_text.asm

@@ -61,9 +61,9 @@ PrintBeginningBattleText: ; 58d99 (16:4d99)
 
 .playSFX
 	xor a
-	ld [wc0f1], a
+	ld [wFrequencyModifier], a
 	ld a, $80
-	ld [wc0f2], a
+	ld [wTempoModifier], a
 	ld a, SFX_SILPH_SCOPE
 	call PlaySound
 	jp WaitForSoundToFinish

engine/battle/core.asm

@@ -867,12 +867,12 @@ FaintEnemyPokemon: ; 0x3c567
 	dec a
 	jr z, .wild_win
 	xor a
-	ld [wc0f1], a
-	ld [wc0f2], a
+	ld [wFrequencyModifier], a
+	ld [wTempoModifier], a
 	ld a, SFX_FAINT_FALL
 	call PlaySoundWaitForCurrent
 .sfxwait
-	ld a, [wc02a]
+	ld a, [wChannelSoundIDs + CH4]
 	cp SFX_FAINT_FALL
 	jr z, .sfxwait
 	ld a, SFX_FAINT_THUD
@@ -952,7 +952,7 @@ EnemyMonFaintedText: ; 0x3c63e
 EndLowHealthAlarm: ; 3c643 (f:4643)
 	xor a
 	ld [wLowHealthAlarm], a ;disable low health alarm
-	ld [wc02a], a
+	ld [wChannelSoundIDs + CH4], a
 	inc a
 	ld [wccf6], a
 	ret
@@ -1045,7 +1045,7 @@ TrainerDefeatedText: ; 3c6e9 (f:46e9)
 PlayBattleVictoryMusic: ; 3c6ee (f:46ee)
 	push af
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySoundWaitForCurrent
 	ld c, BANK(Music_DefeatedTrainer)
 	pop af
@@ -1944,7 +1944,7 @@ DrawPlayerHUDAndHPBar: ; 3cd60 (f:4d60)
 	ld [hl], $0
 	ret z
 	xor a
-	ld [wc02a], a
+	ld [wChannelSoundIDs + CH4], a
 	ret
 .asm_3cde6
 	ld hl, wLowHealthAlarm
@@ -6993,8 +6993,8 @@ _LoadTrainerPic: ; 3f04b (f:704b)
 ; unreferenced
 ResetCryModifiers: ; 3f069 (f:7069)
 	xor a
-	ld [wc0f1], a
-	ld [wc0f2], a
+	ld [wFrequencyModifier], a
+	ld [wTempoModifier], a
 	jp PlaySound
 
 ; animates the mon "growing" out of the pokeball

engine/battle/end_of_battle.asm

@@ -46,7 +46,7 @@ EndOfBattle: ; 137aa (4:77aa)
 .resetVariables
 	xor a
 	ld [wLowHealthAlarm], a ;disable low health alarm
-	ld [wc02a], a
+	ld [wChannelSoundIDs + CH4], a
 	ld [W_ISINBATTLE], a
 	ld [W_BATTLETYPE], a
 	ld [W_MOVEMISSED], a

engine/cable_club.asm

@@ -824,12 +824,12 @@ TradeCenter_Trade:
 	add hl, bc
 	ld a, [hl]
 	ld [wTradedEnemyMonSpecies], a
-	ld a, $a
-	ld [wMusicHeaderPointer], a
+	ld a, 10
+	ld [wAudioFadeOutControl], a
 	ld a, $2
-	ld [wc0f0], a
+	ld [wAudioSavedROMBank], a
 	ld a, MUSIC_SAFARI_ZONE
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld c, 100
 	call DelayFrames
@@ -915,12 +915,12 @@ CableClub_Run: ; 5a5f (1:5a5f)
 	inc a ; LINK_STATE_IN_CABLE_CLUB
 	ld [wLinkState], a
 	ld [$ffb5], a
-	ld a, $a
-	ld [wMusicHeaderPointer], a
+	ld a, 10
+	ld [wAudioFadeOutControl], a
 	ld a, BANK(Music_Celadon)
-	ld [wc0f0], a
+	ld [wAudioSavedROMBank], a
 	ld a, MUSIC_CELADON
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	jp PlaySound
 
 EmptyFunc3: ; 5aaf (1:5aaf)

engine/evolution.asm

@@ -8,9 +8,9 @@ EvolveMon: ; 7bde9 (1e:7de9)
 	push af
 	xor a
 	ld [wLowHealthAlarm], a
-	ld [wc02a], a
+	ld [wChannelSoundIDs + CH4], a
 	dec a
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld a, $1
 	ld [H_AUTOBGTRANSFERENABLED], a
@@ -68,7 +68,7 @@ EvolveMon: ; 7bde9 (1e:7de9)
 .done
 	ld [wcf1d], a
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld a, [wcf1d]
 	call PlayCry

engine/hall_of_fame.asm

@@ -280,9 +280,9 @@ HoFRecordMonInfo: ; 70404 (1c:4404)
 	jp CopyData
 
 HoFFadeOutScreenAndMusic: ; 70423 (1c:4423)
-	ld a, $a
-	ld [wcfc8], a
-	ld [wcfc9], a
+	ld a, 10
+	ld [wAudioFadeOutCounterReloadValue], a
+	ld [wAudioFadeOutCounter], a
 	ld a, $ff
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
 	jp GBFadeOutToWhite

engine/hidden_object_functions7.asm

@@ -63,14 +63,14 @@ SafariZoneGameStillGoing: ; 1e9ab (7:69ab)
 SafariZoneGameOver: ; 1e9b0 (7:69b0)
 	call EnableAutoTextBoxDrawing
 	xor a
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
 	dec a
 	call PlaySound
 	ld c, BANK(SFX_Safari_Zone_PA)
 	ld a, SFX_SAFARI_ZONE_PA
 	call PlayMusic
 .asm_1e9c2
-	ld a, [wc02a]
+	ld a, [wChannelSoundIDs + CH4]
 	cp $b9
 	jr nz, .asm_1e9c2
 	ld a, TEXT_SAFARI_GAME_OVER
@@ -374,7 +374,7 @@ BillsHouseInitiatedText: ; 1ebe2 (7:6be2)
 	db $06
 	TX_ASM
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld c, 16
 	call DelayFrames

engine/intro.asm

@@ -325,10 +325,10 @@ PlayShootingStar: ; 4188a (10:588a)
 	call DelayFrames
 .next
 	ld a, BANK(Music_IntroBattle)
-	ld [wc0ef], a
-	ld [wc0f0], a
+	ld [wAudioROMBank], a
+	ld [wAudioSavedROMBank], a
 	ld a, MUSIC_INTRO_BATTLE
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	call IntroClearMiddleOfScreen
 	call ClearSprites

engine/items/items.asm

@@ -856,7 +856,7 @@ ItemUseMedicine: ; dabb (3:5abb)
 .notFullHP ; if the pokemon's current HP doesn't equal its max HP
 	xor a
 	ld [wLowHealthAlarm],a ;disable low health alarm
-	ld [wc02a],a
+	ld [wChannelSoundIDs + CH4],a
 	push hl
 	push de
 	ld bc,32
@@ -1643,7 +1643,7 @@ ItemUsePokeflute: ; e140 (3:6140)
 	call WaitForSoundToFinish ; wait for sound to end
 	callba Music_PokeFluteInBattle ; play in-battle pokeflute music
 .musicWaitLoop ; wait for music to finish playing
-	ld a,[wc02c]
+	ld a,[wChannelSoundIDs + CH6]
 	and a ; music off?
 	jr nz,.musicWaitLoop
 .skipMusic
@@ -1716,8 +1716,8 @@ PlayedFluteHadEffectText: ; e215 (3:6215)
 	ld c, BANK(SFX_Pokeflute)
 	call PlayMusic
 .musicWaitLoop ; wait for music to finish playing
-	ld a,[wc028]
-	cp a,$b8
+	ld a,[wChannelSoundIDs + CH2]
+	cp a, SFX_POKEFLUE
 	jr z,.musicWaitLoop
 	call PlayDefaultMusic ; start playing normal music again
 .done

engine/menu/pokedex.asm

@@ -397,7 +397,7 @@ ShowPokedexDataInternal: ; 402e2 (10:42e2)
 	ld hl,wd72c
 	set 1,[hl]
 	ld a,$33 ; 3/7 volume
-	ld [$ff24],a
+	ld [rNR50],a
 	call GBPalWhiteOut ; zero all palettes
 	call ClearScreen
 	ld a,[wd11e] ; pokemon ID
@@ -566,7 +566,7 @@ ShowPokedexDataInternal: ; 402e2 (10:42e2)
 	ld hl,wd72c
 	res 1,[hl]
 	ld a,$77 ; max volume
-	ld [$ff24],a
+	ld [rNR50],a
 	ret
 
 HeightWeightText: ; 40448 (10:4448)

engine/menu/status_screen.asm

@@ -80,7 +80,7 @@ StatusScreen: ; 12953 (4:6953)
 	ld hl, wd72c
 	set 1, [hl]
 	ld a, $33
-	ld [$ff24], a ; Reduce the volume
+	ld [rNR50], a ; Reduce the volume
 	call GBPalWhiteOutWithDelay3
 	call ClearScreen
 	call UpdateSprites
@@ -430,7 +430,7 @@ StatusScreen2: ; 12b57 (4:6b57)
 	ld hl, wd72c
 	res 1, [hl]
 	ld a, $77
-	ld [$ff24], a
+	ld [rNR50], a
 	call GBPalWhiteOut
 	jp ClearScreen
 

engine/oak_speech.asm

@@ -129,12 +129,12 @@ OakSpeech: ; 6115 (1:6115)
 	ld a,[H_LOADEDROMBANK]
 	push af
 	ld a, BANK(Music_PalletTown)
-	ld [wc0ef],a
-	ld [wc0f0],a
-	ld a,$A
-	ld [wMusicHeaderPointer],a
+	ld [wAudioROMBank],a
+	ld [wAudioSavedROMBank],a
+	ld a, 10
+	ld [wAudioFadeOutControl],a
 	ld a,$FF
-	ld [wc0ee],a
+	ld [wNewSoundID],a
 	call PlaySound ; stop music
 	pop af
 	ld [H_LOADEDROMBANK],a

engine/overworld/elevator.asm

@@ -33,7 +33,7 @@ ShakeElevator: ; 7bf15 (1e:7f15)
 	ld a, SFX_SAFARI_ZONE_PA
 	call PlayMusic
 .musicLoop
-	ld a, [wc02a]
+	ld a, [wChannelSoundIDs + CH4]
 	cp $b9
 	jr z, .musicLoop
 	call UpdateSprites

engine/overworld/healing_machine.asm

@@ -15,44 +15,44 @@ AnimateHealingMachine: ; 70433 (1c:4433)
 	ld hl, wOAMBuffer + $84
 	ld de, PokeCenterOAMData
 	call CopyHealingMachineOAM
-	ld a, $4
-	ld [wMusicHeaderPointer], a
+	ld a, 4
+	ld [wAudioFadeOutControl], a
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
-.asm_70464
-	ld a, [wMusicHeaderPointer]
-	and a
-	jr nz, .asm_70464
+.waitLoop
+	ld a, [wAudioFadeOutControl]
+	and a ; is fade-out finished?
+	jr nz, .waitLoop ; if not, check again
 	ld a, [wPartyCount]
 	ld b, a
-.asm_7046e
+.partyLoop
 	call CopyHealingMachineOAM
 	ld a, SFX_HEALING_MACHINE
 	call PlaySound
 	ld c, 30
 	call DelayFrames
 	dec b
-	jr nz, .asm_7046e
-	ld a, [wc0ef]
+	jr nz, .partyLoop
+	ld a, [wAudioROMBank]
 	cp BANK(Audio3_UpdateMusic)
-	ld [wc0f0], a
-	jr nz, .asm_70495
+	ld [wAudioSavedROMBank], a
+	jr nz, .next
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld a, BANK(Music_PkmnHealed)
-	ld [wc0ef], a
-.asm_70495
+	ld [wAudioROMBank], a
+.next
 	ld a, MUSIC_PKMN_HEALED
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld d, $28
 	call FlashSprite8Times
-.asm_704a2
-	ld a, [wc026]
-	cp MUSIC_PKMN_HEALED
-	jr z, .asm_704a2
+.waitLoop2
+	ld a, [wChannelSoundIDs]
+	cp MUSIC_PKMN_HEALED ; is the healed music still playing?
+	jr z, .waitLoop2 ; if so, check gain
 	ld c, 32
 	call DelayFrames
 	pop af

engine/overworld/npc_movement.asm

@@ -163,10 +163,10 @@ PewterMuseumGuyMovementScriptPointerTable: ; 1a510 (6:6510)
 
 PewterMovementScript_WalkToMuseum: ; 1a514 (6:6514)
 	ld a, BANK(Music_MuseumGuy)
-	ld [wc0ef], a
-	ld [wc0f0], a
+	ld [wAudioROMBank], a
+	ld [wAudioSavedROMBank], a
 	ld a, MUSIC_MUSEUM_GUY
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld a, [wSpriteIndex]
 	swap a
@@ -219,10 +219,10 @@ PewterGymGuyMovementScriptPointerTable: ; 1a57d (6:657d)
 
 PewterMovementScript_WalkToGym: ; 1a581 (6:6581)
 	ld a, BANK(Music_MuseumGuy)
-	ld [wc0ef], a
-	ld [wc0f0], a
+	ld [wAudioROMBank], a
+	ld [wAudioSavedROMBank], a
 	ld a, MUSIC_MUSEUM_GUY
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld a, [wSpriteIndex]
 	swap a

engine/overworld/pokecenter.asm

@@ -24,12 +24,12 @@ DisplayPokemonCenterDialogue_: ; 6fe6 (1:6fe6)
 	predef HealParty
 	callba AnimateHealingMachine ; do the healing machine animation
 	xor a
-	ld [wMusicHeaderPointer], a
-	ld a, [wc0f0]
-	ld [wc0ef], a
-	ld a, [wd35b]
-	ld [wcfca], a
-	ld [wc0ee], a
+	ld [wAudioFadeOutControl], a
+	ld a, [wAudioSavedROMBank]
+	ld [wAudioROMBank], a
+	ld a, [wMapMusicSoundID]
+	ld [wLastMusicSoundID], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld hl, PokemonFightingFitText
 	call PrintText

engine/slot_machine.asm

@@ -411,7 +411,7 @@ SlotMachine_CheckForMatches: ; 37588 (d:7588)
 	call PrintText
 .done
 	xor a
-	ld [wc002], a
+	ld [wMuteAudioAndPauseMusic], a
 	ret
 .rollWheel3DownByOneSymbol
 	call SlotMachine_AnimWheel3
@@ -654,7 +654,7 @@ SlotMachine_PrintPayoutCoins: ; 3775f (d:775f)
 
 SlotMachine_PayCoinsToPlayer: ; 3776b (d:776b)
 	ld a, $1
-	ld [wc002], a
+	ld [wMuteAudioAndPauseMusic], a
 	call WaitForSoundToFinish
 
 ; Put 1 in the temp coins variable. This value is added to the player's coins

engine/titlescreen.asm

@@ -18,8 +18,8 @@ SetDefaultNamesBeforeTitlescreen: ; 42b7 (1:42b7)
 	ld [hli], a
 	ld [hl], a
 	ld a, BANK(Music_TitleScreen)
-	ld [wc0ef], a
-	ld [wc0f0], a
+	ld [wAudioROMBank], a
+	ld [wAudioSavedROMBank], a
 
 DisplayTitleScreen: ; 42dd (1:42dd)
 	call GBPalWhiteOut
@@ -219,7 +219,7 @@ ENDC
 	call Delay3
 	call WaitForSoundToFinish
 	ld a, MUSIC_TITLE_SCREEN
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	xor a
 	ld [wcc5b], a

home.asm

@@ -332,9 +332,9 @@ GetCryData:: ; 13d9 (0:13d9)
 	ld a, [hli]
 	ld b, a ; cry id
 	ld a, [hli]
-	ld [wc0f1], a
+	ld [wFrequencyModifier], a
 	ld a, [hl]
-	ld [wc0f2], a
+	ld [wTempoModifier], a
 	call BankswitchBack
 
 	; Cry headers have 3 channels,
@@ -998,27 +998,27 @@ ResetPlayerSpriteData_ClearSpriteData:: ; 28c4 (0:28c4)
 	xor a
 	jp FillMemory
 
-Func_28cb:: ; 28cb (0:28cb)
-	ld a, [wMusicHeaderPointer]
+FadeOutAudio:: ; 28cb (0:28cb)
+	ld a, [wAudioFadeOutControl]
 	and a
 	jr nz, .asm_28dc
 	ld a, [wd72c]
 	bit 1, a
 	ret nz
 	ld a, $77
-	ld [$ff24], a
+	ld [rNR50], a
 	ret
 .asm_28dc
-	ld a, [wcfc9]
+	ld a, [wAudioFadeOutCounter]
 	and a
-	jr z, .asm_28e7
+	jr z, .counterReachedZero
 	dec a
-	ld [wcfc9], a
+	ld [wAudioFadeOutCounter], a
 	ret
-.asm_28e7
-	ld a, [wcfc8]
-	ld [wcfc9], a
-	ld a, [$ff24]
+.counterReachedZero
+	ld a, [wAudioFadeOutCounterReloadValue]
+	ld [wAudioFadeOutCounter], a
+	ld a, [rNR50]
 	and a
 	jr z, .asm_2903
 	ld b, a
@@ -1031,20 +1031,20 @@ Func_28cb:: ; 28cb (0:28cb)
 	dec a
 	swap a
 	or c
-	ld [$ff24], a
+	ld [rNR50], a
 	ret
 .asm_2903
-	ld a, [wMusicHeaderPointer]
+	ld a, [wAudioFadeOutControl]
 	ld b, a
 	xor a
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
-	ld a, [wc0f0]
-	ld [wc0ef], a
+	ld a, [wAudioSavedROMBank]
+	ld [wAudioROMBank], a
 	ld a, b
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	jp PlaySound
 
 ; this function is used to display sign messages, sprite dialog, etc.
@@ -2604,12 +2604,12 @@ PlayTrainerMusic:: ; 33e8 (0:33e8)
 	and a
 	ret nz
 	xor a
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
 	ld a, $ff
 	call PlaySound
 	ld a, BANK(Music_MeetEvilTrainer)
-	ld [wc0ef], a
-	ld [wc0f0], a
+	ld [wAudioROMBank], a
+	ld [wAudioSavedROMBank], a
 	ld a, [wEngagedTrainerClass]
 	ld b, a
 	ld hl, EvilTrainerList
@@ -2634,7 +2634,7 @@ PlayTrainerMusic:: ; 33e8 (0:33e8)
 .maleTrainer
 	ld a, MUSIC_MEET_MALE_TRAINER
 .PlaySound
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	jp PlaySound
 
 INCLUDE "data/trainer_types.asm"
@@ -3217,8 +3217,8 @@ WaitForSoundToFinish:: ; 3748 (0:3748)
 	and $80
 	ret nz
 	push hl
-.asm_374f
-	ld hl, wc02a
+.waitLoop
+	ld hl, wChannelSoundIDs + CH4
 	xor a
 	or [hl]
 	inc hl
@@ -3226,7 +3226,7 @@ WaitForSoundToFinish:: ; 3748 (0:3748)
 	inc hl
 	inc hl
 	or [hl]
-	jr nz, .asm_374f
+	jr nz, .waitLoop
 	pop hl
 	ret
 

home/audio.asm

@@ -3,112 +3,139 @@ PlayDefaultMusic:: ; 2307 (0:2307)
 	xor a
 	ld c, a
 	ld d, a
-	ld [wcfca], a
-	jr Func_2324
+	ld [wLastMusicSoundID], a
+	jr PlayDefaultMusicCommon
 
-Func_2312:: ; 2312 (0:2312)
-	ld c, $a
-	ld d, $0
+PlayDefaultMusicFadeOutCurrent:: ; 2312 (0:2312)
+; Fade out the current music and then play the default music.
+	ld c, 10
+	ld d, 0
 	ld a, [wd72e]
-	bit 5, a
-	jr z, Func_2324
+	bit 5, a ; has a battle just ended?
+	jr z, PlayDefaultMusicCommon
 	xor a
-	ld [wcfca], a
-	ld c, $8
+	ld [wLastMusicSoundID], a
+	ld c, 8
 	ld d, c
-Func_2324:: ; 2324 (0:2324)
+
+PlayDefaultMusicCommon:: ; 2324 (0:2324)
 	ld a, [wWalkBikeSurfState]
 	and a
-	jr z, .asm_2343
+	jr z, .walking
 	cp $2
-	jr z, .asm_2332
+	jr z, .surfing
 	ld a, MUSIC_BIKE_RIDING
-	jr .asm_2334
-.asm_2332
+	jr .next
+
+.surfing
 	ld a, MUSIC_SURFING
-.asm_2334
+
+.next
 	ld b, a
 	ld a, d
-	and a
+	and a ; should current music be faded out first?
 	ld a, BANK(Music_BikeRiding)
-	jr nz, .asm_233e
-	ld [wc0ef], a
-.asm_233e
-	ld [wc0f0], a
-	jr .asm_234c
-.asm_2343
-	ld a, [wd35b]
+	jr nz, .next2
+
+; Only change the audio ROM bank if the current music isn't going to be faded
+; out before the default music begins.
+	ld [wAudioROMBank], a
+
+.next2
+; [wAudioSavedROMBank] will be copied to [wAudioROMBank] after fading out the
+; current music (if the current music is faded out).
+	ld [wAudioSavedROMBank], a
+	jr .next3
+
+.walking
+	ld a, [wMapMusicSoundID]
 	ld b, a
-	call Func_2385
-	jr c, .asm_2351
-.asm_234c
-	ld a, [wcfca]
-	cp b
-	ret z
-.asm_2351
+	call CompareMapMusicBankWithCurrentBank
+	jr c, .next4
+
+.next3
+	ld a, [wLastMusicSoundID]
+	cp b ; is the default music already playing?
+	ret z ; if so, do nothing
+
+.next4
 	ld a, c
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
 	ld a, b
-	ld [wcfca], a
-	ld [wc0ee], a
+	ld [wLastMusicSoundID], a
+	ld [wNewSoundID], a
 	jp PlaySound
 
-Func_235f:: ; 235f (0:235f)
-	ld a, [wc0ef]
+UpdateMusic6Times:: ; 235f (0:235f)
+; This is called when entering a map, before fading out the current music and
+; playing the default music (i.e. the map's music or biking/surfing music).
+	ld a, [wAudioROMBank]
 	ld b, a
 	cp BANK(Audio1_UpdateMusic)
 	jr nz, .checkForAudio2
-.audio1
+
+; audio 1
 	ld hl, Audio1_UpdateMusic
-	jr .asm_2378
+	jr .next
+
 .checkForAudio2
 	cp BANK(Audio2_UpdateMusic)
 	jr nz, .audio3
-.audio2
+
+; audio 2
 	ld hl, Audio2_UpdateMusic
-	jr .asm_2378
+	jr .next
+
 .audio3
 	ld hl, Audio3_UpdateMusic
-.asm_2378
-	ld c, $6
-.asm_237a
+
+.next
+	ld c, 6
+.loop
 	push bc
 	push hl
 	call Bankswitch
 	pop hl
 	pop bc
 	dec c
-	jr nz, .asm_237a
+	jr nz, .loop
 	ret
 
-Func_2385:: ; 2385 (0:2385)
-	ld a, [wd35c]
+CompareMapMusicBankWithCurrentBank:: ; 2385 (0:2385)
+; Compares the map music's audio ROM bank with the current audio ROM bank
+; and updates the audio ROM bank variables.
+; Returns whether the banks are different in carry.
+	ld a, [wMapMusicROMBank]
 	ld e, a
-	ld a, [wc0ef]
+	ld a, [wAudioROMBank]
 	cp e
-	jr nz, .asm_2394
-	ld [wc0f0], a
+	jr nz, .differentBanks
+	ld [wAudioSavedROMBank], a
 	and a
 	ret
-.asm_2394
-	ld a, c
+.differentBanks
+	ld a, c ; this is a fade-out counter value and it's always non-zero
 	and a
 	ld a, e
-	jr nz, .asm_239c
-	ld [wc0ef], a
-.asm_239c
-	ld [wc0f0], a
+	jr nz, .next
+; If the fade-counter is non-zero, we don't change the audio ROM bank because
+; it's needed to keep playing the music as it fades out. The FadeOutAudio
+; routine will take care of copying [wAudioSavedROMBank] to [wAudioROMBank]
+; when the music has faded out.
+	ld [wAudioROMBank], a
+.next
+	ld [wAudioSavedROMBank], a
 	scf
 	ret
 
 PlayMusic:: ; 23a1 (0:23a1)
 	ld b, a
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	xor a
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
 	ld a, c
-	ld [wc0ef], a
-	ld [wc0f0], a
+	ld [wAudioROMBank], a
+	ld [wAudioSavedROMBank], a
 	ld a, b
 
 ; plays music specified by a. If value is $ff, music is stopped
@@ -117,66 +144,74 @@ PlaySound:: ; 23b1 (0:23b1)
 	push de
 	push bc
 	ld b, a
-	ld a, [wc0ee]
+	ld a, [wNewSoundID]
 	and a
-	jr z, .asm_23c8
+	jr z, .next
 	xor a
-	ld [wc02a], a
-	ld [wc02b], a
-	ld [wc02c], a
-	ld [wc02d], a
-.asm_23c8
-	ld a, [wMusicHeaderPointer]
-	and a
-	jr z, .asm_23e3
-	ld a, [wc0ee]
-	and a
-	jr z, .asm_2425
+	ld [wChannelSoundIDs + CH4], a
+	ld [wChannelSoundIDs + CH5], a
+	ld [wChannelSoundIDs + CH6], a
+	ld [wChannelSoundIDs + CH7], a
+.next
+	ld a, [wAudioFadeOutControl]
+	and a ; has a fade-out length been specified?
+	jr z, .noFadeOut
+	ld a, [wNewSoundID]
+	and a ; is the new sound ID 0?
+	jr z, .done ; if so, do nothing
 	xor a
-	ld [wc0ee], a
-	ld a, [wcfca]
-	cp $ff
-	jr nz, .asm_2414
+	ld [wNewSoundID], a
+	ld a, [wLastMusicSoundID]
+	cp $ff ; has the music been stopped?
+	jr nz, .fadeOut ; if not, fade out the current music
+; If it has been stopped, start playing the new music immediately.
 	xor a
-	ld [wMusicHeaderPointer], a
-.asm_23e3
+	ld [wAudioFadeOutControl], a
+.noFadeOut
 	xor a
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	ld a, [H_LOADEDROMBANK]
-	ld [$ffb9], a
-	ld a, [wc0ef]
+	ld [hSavedROMBank], a
+	ld a, [wAudioROMBank]
 	ld [H_LOADEDROMBANK], a
 	ld [MBC1RomBank], a
-	cp BANK(Audio1_9876)
+	cp BANK(Audio1_PlaySound)
 	jr nz, .checkForAudio2
-.audio1
+
+; audio 1
 	ld a, b
-	call Audio1_9876
-	jr .asm_240b
+	call Audio1_PlaySound
+	jr .next2
+
 .checkForAudio2
-	cp BANK(Audio2_22035)
+	cp BANK(Audio2_PlaySound)
 	jr nz, .audio3
-.audio2
+
+; audio 2
 	ld a, b
-	call Audio2_22035
-	jr .asm_240b
+	call Audio2_PlaySound
+	jr .next2
+
 .audio3
 	ld a, b
-	call Audio3_7d8ea
-.asm_240b
-	ld a, [$ffb9]
+	call Audio3_PlaySound
+
+.next2
+	ld a, [hSavedROMBank]
 	ld [H_LOADEDROMBANK], a
 	ld [MBC1RomBank], a
-	jr .asm_2425
-.asm_2414
+	jr .done
+
+.fadeOut
 	ld a, b
-	ld [wcfca], a
-	ld a, [wMusicHeaderPointer]
-	ld [wcfc8], a
-	ld [wcfc9], a
+	ld [wLastMusicSoundID], a
+	ld a, [wAudioFadeOutControl]
+	ld [wAudioFadeOutCounterReloadValue], a
+	ld [wAudioFadeOutCounter], a
 	ld a, b
-	ld [wMusicHeaderPointer], a
-.asm_2425
+	ld [wAudioFadeOutControl], a
+
+.done
 	pop bc
 	pop de
 	pop hl

home/init.asm

@@ -98,8 +98,8 @@ rLCDC_DEFAULT EQU %11100011
 	predef LoadSGB
 
 	ld a, BANK(SFX_Shooting_Star)
-	ld [wc0ef], a
-	ld [wc0f0], a
+	ld [wAudioROMBank], a
+	ld [wAudioSavedROMBank], a
 	ld a, $9c
 	ld [H_AUTOBGTRANSFERDEST + 1], a
 	xor a
@@ -127,11 +127,11 @@ ClearVram:
 
 StopAllSounds::
 	ld a, BANK(Audio1_UpdateMusic)
-	ld [wc0ef], a
-	ld [wc0f0], a
+	ld [wAudioROMBank], a
+	ld [wAudioSavedROMBank], a
 	xor a
-	ld [wMusicHeaderPointer], a
-	ld [wc0ee], a
-	ld [wcfca], a
+	ld [wAudioFadeOutControl], a
+	ld [wNewSoundID], a
+	ld [wLastMusicSoundID], a
 	dec a
 	jp PlaySound

home/overworld.asm

@@ -658,7 +658,7 @@ CheckMapConnections:: ; 07ba (0:07ba)
 	ld [wCurrentTileBlockMapViewPointer + 1],a
 .loadNewMap ; load the connected map that was entered
 	call LoadMapHeader
-	call Func_2312 ; music
+	call PlayDefaultMusicFadeOutCurrent
 	ld b,$09
 	call GoPAL_SET
 ; Since the sprite set shouldn't change, this will just update VRAM slots at
@@ -750,16 +750,16 @@ HandleBlackOut::
 	ld [MBC1RomBank], a
 	call ResetStatusAndHalveMoneyOnBlackout
 	call SpecialWarpIn
-	call Func_2312
+	call PlayDefaultMusicFadeOutCurrent
 	jp SpecialEnterMap
 
 StopMusic::
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 .wait
-	ld a, [wMusicHeaderPointer]
+	ld a, [wAudioFadeOutControl]
 	and a
 	jr nz, .wait
 	jp StopAllSounds
@@ -1224,7 +1224,7 @@ CollisionCheckOnLand:: ; 0bd1 (0:0bd1)
 	call CheckTilePassable
 	jr nc,.noCollision
 .collision
-	ld a,[wc02a]
+	ld a,[wChannelSoundIDs + CH4]
 	cp a,SFX_COLLISION ; check if collision sound is already playing
 	jr z,.setCarry
 	ld a,SFX_COLLISION
@@ -1927,7 +1927,7 @@ CollisionCheckOnWater:: ; 0fb7 (0:0fb7)
 	jr z,.stopSurfing ; stop surfing if the tile is passable
 	jr .loop
 .collision
-	ld a,[wc02a]
+	ld a,[wChannelSoundIDs + CH4]
 	cp a,SFX_COLLISION ; check if collision sound is already playing
 	jr z,.setCarry
 	ld a,SFX_COLLISION
@@ -2279,9 +2279,9 @@ LoadMapHeader:: ; 107c (0:107c)
 	add hl,bc
 	add hl,bc
 	ld a,[hli]
-	ld [wd35b],a ; music 1
+	ld [wMapMusicSoundID],a ; music 1
 	ld a,[hl]
-	ld [wd35c],a ; music 2
+	ld [wMapMusicROMBank],a ; music 2
 	pop af
 	ld [H_LOADEDROMBANK],a
 	ld [MBC1RomBank],a
@@ -2352,8 +2352,8 @@ LoadMapData:: ; 1241 (0:1241)
 	ld a,[W_FLAGS_D733]
 	bit 1,a
 	jr nz,.restoreRomBank
-	call Func_235f ; music related
-	call Func_2312 ; music related
+	call UpdateMusic6Times
+	call PlayDefaultMusicFadeOutCurrent
 .restoreRomBank
 	pop af
 	ld [H_LOADEDROMBANK],a

home/vblank.asm

@@ -38,21 +38,21 @@ VBlank::
 
 	ld a, [H_VBLANKOCCURRED]
 	and a
-	jr z, .vblanked
+	jr z, .skipZeroing
 	xor a
 	ld [H_VBLANKOCCURRED], a
-.vblanked
 
+.skipZeroing
 	ld a, [H_FRAMECOUNTER]
 	and a
-	jr z, .decced
+	jr z, .skipDec
 	dec a
 	ld [H_FRAMECOUNTER], a
-.decced
 
-	call Func_28cb
+.skipDec
+	call FadeOutAudio
 
-	ld a, [wc0ef] ; music ROM bank
+	ld a, [wAudioROMBank] ; music ROM bank
 	ld [H_LOADEDROMBANK], a
 	ld [MBC1RomBank], a
 

hram.asm

@@ -182,7 +182,9 @@ hJoy5        EQU $FFB5
 hJoy6        EQU $FFB6
 hJoy7        EQU $FFB7
 
-H_LOADEDROMBANK     EQU $FFB8
+H_LOADEDROMBANK EQU $FFB8
+
+hSavedROMBank EQU $FFB9
 
 ; is automatic background transfer during V-blank enabled?
 ; if nonzero, yes

scripts/ceruleancity.asm

@@ -65,7 +65,7 @@ CeruleanCityScript0: ; 194c8 (6:54c8)
 	and a
 	jr z, .asm_19512
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 .asm_19512
 	ld c, BANK(Music_MeetRival)
@@ -172,7 +172,7 @@ CeruleanCityScript2: ; 195b1 (6:55b1)
 	ld [hSpriteIndexOrTextID], a
 	call DisplayTextID
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	callba Music_RivalAlternateStart
 	ld a, $1

scripts/oakslab.asm

@@ -511,7 +511,7 @@ OaksLabScript15: ; 1ceb0 (7:4eb0)
 	ld [hJoyHeld], a
 	call EnableAutoTextBoxDrawing
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	callba Music_RivalAlternateStart
 	ld a, $15
@@ -612,7 +612,7 @@ OaksLabScript16: ; 1cf12 (7:4f12)
 	call FillMemory
 	ld [hl], $ff
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	callba Music_RivalAlternateStart
 	ld a, $1

scripts/pewterpokecenter.asm

@@ -59,9 +59,9 @@ PewterPokecenterText3: ; 5c59b (17:459b)
 	ld c, 24
 	call DelayFrames
 
-	ld a, [wc026]
+	ld a, [wChannelSoundIDs]
 	ld b, a
-	ld a, [wc027]
+	ld a, [wChannelSoundIDs + CH1]
 	or b
 	jr nz, .loop
 

scripts/pokemontower2.asm

@@ -23,7 +23,7 @@ PokemonTower2Script0: ; 6050f (18:450f)
 	call ArePlayerCoordsInArray
 	ret nc
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld c, BANK(Music_MeetRival)
 	ld a, MUSIC_MEET_RIVAL
@@ -77,7 +77,7 @@ PokemonTower2Script1: ; 60563 (18:4563)
 	ld [H_SPRITEINDEX], a
 	call MoveSprite
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	callba Music_RivalAlternateStart
 	ld a, $2

scripts/redshouse1f.asm

@@ -29,14 +29,14 @@ MomHealPokemon: ; 4818a (12:418a)
 	call ReloadMapData
 	predef HealParty
 	ld a, MUSIC_PKMN_HEALED
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 .next
-	ld a, [wc026]
+	ld a, [wChannelSoundIDs]
 	cp MUSIC_PKMN_HEALED
 	jr z, .next
-	ld a, [wd35b]
-	ld [wc0ee], a
+	ld a, [wMapMusicSoundID]
+	ld [wNewSoundID], a
 	call PlaySound
 	call GBFadeInFromWhite
 	ld hl, MomHealText2

scripts/route22.asm

@@ -89,7 +89,7 @@ Route22Script0: ; 50f00 (14:4f00)
 	and a
 	jr z, .asm_50f4e
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 .asm_50f4e
 	ld c, BANK(Music_MeetRival)
@@ -168,7 +168,7 @@ Route22Script2: ; 50fb5 (14:4fb5)
 	ld [hSpriteIndexOrTextID], a
 	call DisplayTextID
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	callba Music_RivalAlternateStart
 	ld a, [wcf0d]
@@ -242,11 +242,11 @@ Route22Script_5104e: ; 5104e (14:504e)
 	and a
 	jr z, .skipYVisibilityTesta
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 .skipYVisibilityTesta
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	callba Music_RivalAlternateTempo
 	ld a, $2
@@ -327,7 +327,7 @@ Route22Script5: ; 510df (14:50df)
 	ld [hSpriteIndexOrTextID], a
 	call DisplayTextID
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	callba Music_RivalAlternateStartAndTempo
 	ld a, [wcf0d]

scripts/silphco7.asm

@@ -131,7 +131,7 @@ SilphCo7Script0: ; 51c23 (14:5c23)
 	ld a, PLAYER_DIR_DOWN
 	ld [wPlayerMovingDirection], a
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld c, BANK(Music_MeetRival)
 	ld a, MUSIC_MEET_RIVAL
@@ -220,7 +220,7 @@ SilphCo7Script4: ; 51cc8 (14:5cc8)
 	ld [hSpriteIndexOrTextID], a
 	call DisplayTextID
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	callba Music_RivalAlternateStart
 	ld de, MovementData_51d1d

scripts/ssanne2.asm

@@ -25,7 +25,7 @@ SSAnne2Script0: ; 613be (18:53be)
 	call ArePlayerCoordsInArray
 	ret nc
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld c, BANK(Music_MeetRival)
 	ld a, MUSIC_MEET_RIVAL
@@ -146,7 +146,7 @@ SSAnne2Script2: ; 6146d (18:546d)
 	ld [H_SPRITEINDEX], a
 	call MoveSprite
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	callba Music_RivalAlternateStart
 	ld a, $3

scripts/ssanne7.asm

@@ -44,21 +44,21 @@ SSAnne7Text1: ; 618ad (18:58ad)
 SSAnne7RubText: ; 618ec (18:58ec)
 	TX_FAR _SSAnne7RubText
 	TX_ASM
-	ld a, [wc0ef]
+	ld a, [wAudioROMBank]
 	cp BANK(Audio3_UpdateMusic)
-	ld [wc0f0], a
+	ld [wAudioSavedROMBank], a
 	jr nz, .asm_61908
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld a, Bank(Music_PkmnHealed)
-	ld [wc0ef], a
+	ld [wAudioROMBank], a
 .asm_61908
 	ld a, MUSIC_PKMN_HEALED
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 .asm_61910
-	ld a, [wc026]
+	ld a, [wChannelSoundIDs]
 	cp MUSIC_PKMN_HEALED
 	jr z, .asm_61910
 	call PlayDefaultMusic

scripts/vermiliondock.asm

@@ -40,7 +40,7 @@ VermilionDock_1db9b: ; 1db9b (7:5b9b)
 	SetEventForceReuseHL EVENT_SS_ANNE_LEFT
 	ld a, $ff
 	ld [wJoyIgnore], a
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld c, BANK(Music_Surfing)
 	ld a, MUSIC_SURFING

wram.asm

@@ -61,66 +61,146 @@ ENDM
 
 SECTION "WRAM Bank 0", WRAM0
 
-wc000:: ds 1
-wc001:: ds 1
-wc002:: ds 1
-wc003:: ds 1
-wc004:: ds 1
-wc005:: ds 1
-wc006:: ds 8
-wc00e:: ds 4
-wc012:: ds 4
-wc016:: ds 16
-wc026:: ds 1
-wc027:: ds 1
-wc028:: ds 2
-wc02a:: ds 1
-wc02b:: ds 1
-wc02c:: ds 1
-wc02d:: ds 1
-wc02e:: ds 8
-wc036:: ds 8
-wc03e:: ds 8
-wc046:: ds 8
-wc04e:: ds 8
-wc056:: ds 8
-wc05e:: ds 8
-wc066:: ds 8
-wc06e:: ds 8
-wc076:: ds 8
-wc07e:: ds 8
-wc086:: ds 8
-wc08e:: ds 8
-wc096:: ds 8
-wc09e:: ds 8
-wc0a6:: ds 8
-wc0ae:: ds 8
-wc0b6:: ds 8
-wc0be:: ds 8
-wc0c6:: ds 8
-wc0ce:: ds 1
-wc0cf:: ds 1
-wc0d0:: ds 1
-wc0d1:: ds 1
-wc0d2:: ds 1
-wc0d3:: ds 1
-wc0d4:: ds 1
-wc0d5:: ds 1
-wc0d6:: ds 8
-wc0de:: ds 8
-wc0e6:: ds 1
-wc0e7:: ds 1
-wc0e8:: ds 1
-wc0e9:: ds 1
-wc0ea:: ds 1
-wc0eb:: ds 1
-wc0ec:: ds 1
-wc0ed:: ds 1
-wc0ee:: ds 1
-wc0ef:: ds 1
-wc0f0:: ds 1
-wc0f1:: ds 1
-wc0f2:: ds 14
+wUnusedC000:: ; c000
+	ds 1
+
+wSoundID:: ; c001
+	ds 1
+
+wMuteAudioAndPauseMusic:: ; c002
+; bit 7: whether sound has been muted
+; all bits: whether the effective is active
+; Store 1 to activate effect (any value in the range [1, 127] works).
+; All audio is muted and music is paused. Sfx continues playing until it
+; ends normally.
+; Store 0 to resume music.
+	ds 1
+
+wDisableChannelOutputWhenSfxEnds:: ; c003
+	ds 1
+
+wStereoPanning:: ; c004
+	ds 1
+
+wSavedVolume:: ; c005
+	ds 1
+
+wChannelCommandPointers:: ; c006
+	ds 16
+
+wChannelReturnAddresses:: ; c016
+	ds 16
+
+wChannelSoundIDs:: ; c026
+	ds 8
+
+wChannelFlags1:: ; c02e
+	ds 8
+
+wChannelFlags2:: ; c036
+	ds 8
+
+wChannelDuties:: ; c03e
+	ds 8
+
+wChannelDutyCycles:: ; c046
+	ds 8
+
+wChannelVibratoDelayCounters:: ; c04e
+; reloaded at the beginning of a note. counts down until the vibrato begins.
+	ds 8
+
+wChannelVibratoExtents:: ; c056
+	ds 8
+
+wChannelVibratoRates:: ; c05e
+; high nybble is rate (counter reload value) and low nybble is counter.
+; time between applications of vibrato.
+	ds 8
+
+wChannelFrequencyLowBytes:: ; c066
+	ds 8
+
+wChannelVibratoDelayCounterReloadValues:: ; c06e
+; delay of the beginning of the vibrato from the start of the note
+	ds 8
+
+wChannelPitchBendLengthModifiers:: ; c076
+	ds 8
+
+wChannelPitchBendFrequencySteps:: ; c07e
+	ds 8
+
+wChannelPitchBendFrequencyStepsFractionalPart:: ; c086
+	ds 8
+
+wChannelPitchBendCurrentFrequencyFractionalPart:: ; c08e
+	ds 8
+
+wChannelPitchBendCurrentFrequencyHighBytes:: ; c096
+	ds 8
+
+wChannelPitchBendCurrentFrequencyLowBytes:: ; c09e
+	ds 8
+
+wChannelPitchBendTargetFrequencyHighBytes:: ; c0a6
+	ds 8
+
+wChannelPitchBendTargetFrequencyLowBytes:: ; c0ae
+	ds 8
+
+wChannelNoteDelayCounters:: ; c0b6
+; Note delays are stored as 16-bit fixed-point numbers where the integer part
+; is 8 bits and the fractional part is 8 bits.
+	ds 8
+
+wChannelLoopCounters:: ; c0be
+	ds 8
+
+wChannelNoteSpeeds:: ; c0c6
+	ds 8
+
+wChannelNoteDelayCountersFractionalPart:: ; c0ce
+	ds 8
+
+wChannelOctaves:: ; c0d6
+	ds 8
+
+wChannelVolumes:: ; c0de
+; also includes fade for hardware channels that support it
+	ds 8
+
+wMusicWaveInstrument::
+	ds 1
+
+wSfxWaveInstrument::
+	ds 1
+
+wMusicTempo:: ; c0e8
+	ds 2
+
+wSfxTempo:: ; c0ea
+	ds 2
+
+wSfxHeaderPointer:: ; c0ec
+	ds 2
+
+wNewSoundID:: ; c0ee
+	ds 1
+
+wAudioROMBank:: ; c0ef
+	ds 1
+
+wAudioSavedROMBank:: ; c0f0
+	ds 1
+
+wFrequencyModifier:: ; c0f1
+	ds 1
+
+wTempoModifier:: ; c0f2
+	ds 1
+
+	ds 13
 
 
 SECTION "Sprite State Data", WRAM0[$c100]
@@ -1289,13 +1369,35 @@ wTileInFrontOfPlayer:: ; cfc6
 ; background tile number in front of the player (either 1 or 2 steps ahead)
 	ds 1
 
-wMusicHeaderPointer:: ; cfc7
-; (the current music channel address - $4000) / 3
+wAudioFadeOutControl:: ; cfc7
+; The desired fade counter reload value is stored here prior to calling
+; PlaySound in order to cause the current music to fade out before the new
+; music begins playing. Storing 0 causes no fade out to occur and the new music
+; to begin immediately.
+; This variable has another use related to fade-out, as well. PlaySound stores
+; the sound ID of the music that should be played after the fade-out is finished
+; in this variable. FadeOutAudio checks if it's non-zero every V-Blank and
+; fades out the current audio if it is. Once it has finished fading out the
+; audio, it zeroes this variable and starts playing the sound ID stored in it.
 	ds 1
 
-wcfc8:: ds 1 ; used with audio
-wcfc9:: ds 1 ; also used with audio
-wcfca:: ds 1 ; also used with audio too
+wAudioFadeOutCounterReloadValue:: ; cfc8
+	ds 1
+
+wAudioFadeOutCounter:: ; cfc9
+	ds 1
+
+wLastMusicSoundID:: ; cfca
+; This is used to determine whether the default music is already playing when
+; attempting to play the default music (in order to avoid restarting the same
+; music) and whether the music has already been stopped when attempting to
+; fade out the current music (so that the new music can be begin immediately
+; instead of waiting).
+; It sometimes contains the sound ID of the last music played, but it may also
+; contain $ff (if the music has been stopped) or 0 (because some routines zero
+; it in order to prevent assumptions from being made about the current state of
+; the music).
+	ds 1
 
 wUpdateSpritesEnabled:: ; cfcb
 ; $00 = causes sprites to be hidden and the value to change to $ff
@@ -2126,8 +2228,11 @@ wLetterPrintingDelayFlags:: ; d358
 wPlayerID:: ; d359
 	ds 2
 
-wd35b:: ds 1 ; used with audio stuff
-wd35c:: ds 1 ; storage for audio bank for current map?
+wMapMusicSoundID:: ; d35b
+	ds 1
+
+wMapMusicROMBank:: ; d35c
+	ds 1
 
 wMapPalOffset:: ; d35d
 ; offset subtracted from FadePal4 to get the background and object palettes for the current map