Label audio engine update methods

engine/pinball_game.asm

@@ -14,7 +14,7 @@ GameScreenFunction_LoadGFX: ; 0xd861
 	callba InitializeCurrentStage
 	call FillBottomMessageBufferWithBlackTile
 	ld a, $1
-	ld [wd85d], a
+	ld [wAudioEngineEnabled], a
 	ld [wDrawBottomMessageBox], a
 	ld hl, wScreenState
 	inc [hl]
@@ -52,9 +52,9 @@ GameScreenFunction_StartBall: ; 0xd87f
 	callba Func_ed5e
 	call ClearOAMBuffer
 	callba DrawSpritesForStage
-	ld a, [wd849]
+	ld a, [wUpdateAudioEngineUsingTimerInterrupt]
 	and a
-	call nz, Func_e5d
+	call nz, ToggleAudioEngineUpdateMethod
 	ld a, $1
 	ld [wDrawBottomMessageBox], a
 	xor a
@@ -231,9 +231,9 @@ GameScreenFunction_EndBall: ; 0xdab2
 	and a
 	jr nz, .asm_db28
 	call FadeOut
-	ld a, [wd849]
+	ld a, [wUpdateAudioEngineUsingTimerInterrupt]
 	and a
-	call z, Func_e5d
+	call z, ToggleAudioEngineUpdateMethod
 	call DisableLCD
 	ld hl, hSTAT
 	res 6, [hl]
@@ -249,9 +249,9 @@ GameScreenFunction_EndBall: ; 0xdab2
 	ld bc, $0004
 	call AdvanceFrames
 	call FadeOut
-	ld a, [wd849]
+	ld a, [wUpdateAudioEngineUsingTimerInterrupt]
 	and a
-	call nz, Func_e5d
+	call nz, ToggleAudioEngineUpdateMethod
 	call DisableLCD
 	ld hl, hSTAT
 	res 6, [hl]
@@ -276,9 +276,9 @@ GameScreenFunction_EndBall: ; 0xdab2
 	ld bc, $0004
 	call AdvanceFrames
 	call FadeOut
-	ld a, [wd849]
+	ld a, [wUpdateAudioEngineUsingTimerInterrupt]
 	and a
-	call nz, Func_e5d
+	call nz, ToggleAudioEngineUpdateMethod
 	call DisableLCD
 	ld hl, hSTAT
 	res 6, [hl]

engine/pinball_game/object_collision/blue_stage_resolve_collision.asm

@@ -810,13 +810,13 @@ UpdatePikachuSaverAnimation_BlueField: ; 0x1d133
 	cp $1
 	jr nz, .asm_1d18c
 	xor a
-	ld [wd85d], a
+	ld [wAudioEngineEnabled], a
 	call Func_310a
 	rst AdvanceFrame
 	ld a, $1
 	callba PlayPikachuSoundClip
 	ld a, $1
-	ld [wd85d], a
+	ld [wAudioEngineEnabled], a
 	ld a, $ff
 	ld [wRumblePattern], a
 	ld a, $60

engine/pinball_game/object_collision/red_stage_resolve_collision.asm

@@ -2392,13 +2392,13 @@ UpdatePikachuSaverAnimation_RedField: ; 0x1669e
 	cp $1
 	jr nz, .asm_166f7
 	xor a
-	ld [wd85d], a
+	ld [wAudioEngineEnabled], a
 	call Func_310a
 	rst AdvanceFrame
 	ld a, $1
 	callba PlayPikachuSoundClip
 	ld a, $1
-	ld [wd85d], a
+	ld [wAudioEngineEnabled], a
 	ld a, $ff
 	ld [wRumblePattern], a
 	ld a, $60

engine/pinball_game/save_game.asm

@@ -4,9 +4,9 @@ SaveGame: ; 0xda05
 	ld bc, $0004
 	call AdvanceFrames
 	call FadeOut
-	ld a, [wd849]
+	ld a, [wUpdateAudioEngineUsingTimerInterrupt]
 	and a
-	call nz, Func_e5d
+	call nz, ToggleAudioEngineUpdateMethod
 	call DisableLCD
 	ld hl, hSTAT
 	res 6, [hl]

engine/pinball_game/slot.asm

@@ -254,13 +254,13 @@ SlotRewardPikachuSaver: ; 0xef83
 	ld a, MAX_PIKACHU_SAVER_CHARGE
 	ld [wPikachuSaverCharge], a
 	xor a
-	ld [wd85d], a
+	ld [wAudioEngineEnabled], a
 	call Func_310a
 	rst AdvanceFrame
 	ld a, $0
 	callba PlayPikachuSoundClip
 	ld a, $1
-	ld [wd85d], a
+	ld [wAudioEngineEnabled], a
 	ret
 
 SlotRewardBonusMultiplier: ; 0xefa7

engine/pinball_game/vertical_screen_transition.asm

@@ -16,13 +16,13 @@ FieldVerticalTransition: ; 0xe674
 	ld [hOBP0], a
 	ld [hOBP1], a
 	rst AdvanceFrame
-	call Func_e5d
+	call ToggleAudioEngineUpdateMethod
 	call DisableLCD
 	call ClearOAMBuffer
 	call Func_1129
 	call LoadStageCollisionAttributes
 	call LoadStageData
-	call Func_e5d
+	call ToggleAudioEngineUpdateMethod
 	call EnableLCD
 	ld a, $e4
 	ld [hBGP], a

home.asm

@@ -124,8 +124,8 @@ Start: ; 0x150
 	ld a, $a6
 	ld [hli], a
 	ld a, $0
-	ld [wd849], a
-	ld [wd84a], a
+	ld [wUpdateAudioEngineUsingTimerInterrupt], a
+	ld [wToggleAudioEngineUpdateMethod], a
 	ld a, Bank(PlaySong_BankF)
 	call SetSongBank
 	call Func_23b
@@ -222,8 +222,8 @@ SoftReset:
 	ld a, $a6
 	ld [hli], a
 	ld a, $0
-	ld [wd849], a
-	ld [wd84a], a
+	ld [wUpdateAudioEngineUsingTimerInterrupt], a
+	ld [wToggleAudioEngineUpdateMethod], a
 	ld a, BANK(Func_3c000)
 	call SetSongBank
 	ld a, [hSGBFlag]
@@ -329,29 +329,30 @@ VBlank: ; 0x2f2
 	ld a, [wd8e1]
 	and a
 	call nz, Func_167b
-	ld a, [wd849]
+	ld a, [wUpdateAudioEngineUsingTimerInterrupt]
 	and a
-	jr nz, .asm_37d
-	ld a, [wd85d]
+	jr nz, .skipAudioEngineUpdate
+	ld a, [wAudioEngineEnabled]
 	and a
 	call nz, UpdateSFX
-.asm_37d
-	ld a, [wd84a]
+.skipAudioEngineUpdate
+	ld a, [wToggleAudioEngineUpdateMethod]
 	and a
-	jr z, .asm_39d
+	jr z, .skipTimerToggle
+	; Enable timer interrupts for audio engine updating.
 	xor a
-	ld [wd84a], a
+	ld [wToggleAudioEngineUpdateMethod], a
 	ld a, $1
-	ld [wd849], a
-	ld a, $bc
+	ld [wUpdateAudioEngineUsingTimerInterrupt], a
+	ld a, -68
 	ld [rTMA], a
 	ld a, $0
 	ld [rTAC], a
 	ld hl, rIE
 	set 2, [hl]
 	ld a, $4
-	ld [rTAC], a
-.asm_39d
+	ld [rTAC], a ; Timer interrupt will fire ~60 times per second
+.skipTimerToggle
 	ld hl, MBC5SRamBank
 	ld a, [wd917]
 	and a
@@ -439,24 +440,25 @@ Timer: ; 0x418
 	push bc
 	push de
 	push hl
-	ld a, [wd849]
+	ld a, [wUpdateAudioEngineUsingTimerInterrupt]
 	and a
 	jr z, .asm_42a
-	ld a, [wd85d]
+	ld a, [wAudioEngineEnabled]
 	and a
 	call nz, UpdateSFX
 .asm_42a
-	ld a, [wd84a]
+	ld a, [wToggleAudioEngineUpdateMethod]
 	and a
-	jr z, .asm_440
+	jr z, .skipTimer
 	xor a
-	ld [wd84a], a
-	ld [wd849], a
+	ld [wToggleAudioEngineUpdateMethod], a
+	ld [wUpdateAudioEngineUsingTimerInterrupt], a
+	; disable timer
 	ld a, $0
 	ld [rTAC], a
 	ld hl, rIE
 	res 2, [hl]
-.asm_440
+.skipTimer
 	pop hl
 	pop de
 	pop bc
@@ -1391,13 +1393,18 @@ Modulo_C: ; 0xe55
 	and a
 	ret
 
-Func_e5d: ; 0xe5d
+ToggleAudioEngineUpdateMethod: ; 0xe5d
+; The audio engine is normally updated once every V-Blank interrupt. However, during pinball gameplay,
+; the LCD is disabled (no V-Blanks) when the pinball is transitioning between the Top- and Bottom-halfs of 
+; the Red and Blue Fields. Therefore, the audio engine wouldn't get updated for a fraction of a second, which
+; would has a noticeable pause in the music. To solve this, the Timer interrupt is enabled while the V-Blank is
+; disabled, and the audio engine gets updated during the Timer interrupt.
 	ld a, $1
-	ld [wd84a], a
-.asm_e62
-	ld a, [wd84a]
+	ld [wToggleAudioEngineUpdateMethod], a
+.wait
+	ld a, [wToggleAudioEngineUpdateMethod]
 	and a
-	jr nz, .asm_e62
+	jr nz, .wait
 	ret
 
 DrawBottomMessageBox: ; 0xe69
@@ -2552,7 +2559,7 @@ Func_1ffc: ; 0x1ffc
 	ld [wd807], a
 	callba Func_3c000
 	ld a, $1
-	ld [wd85d], a
+	ld [wAudioEngineEnabled], a
 	ld a, $37 ; space character for player high scores name
 	ld [wPlayerName], a
 	ld [wPlayerName + 1], a

pokemon-reverse-engineering-tools

@@ -1 +1 @@
-Subproject commit 27b200e0e13cf3264c1b124bad73f3f998e21ed2
+Subproject commit 979c98a7c0f67ad6b9685b2d532c66a1f76ffb22

wram.asm

@@ -1906,10 +1906,13 @@ wd812:: ; 0xd812
 wd848:: ; 0xd848
 	ds $1
 
-wd849:: ; 0xd849
+wUpdateAudioEngineUsingTimerInterrupt:: ; 0xd849
+; See ToggleAudioEngineUpdateMethod function for more in-depth explanation.
 	ds $1
 
-wd84a:: ; 0xd84a
+wToggleAudioEngineUpdateMethod:: ; 0xd84a
+; When this byte is set to 1, it toggles between the audio engine being updated by V-Blank vs. Timer Interrupt.
+; See ToggleAudioEngineUpdateMethod function for more in-depth explanation.
 	ds $1
 
 wd84b:: ; 0xd84b
@@ -1921,7 +1924,9 @@ wd84f:: ; 0xd84f
 wCurrentSongBank:: ; 0xd85b
 	ds $2
 
-wd85d:: ; 0xd85d
+wAudioEngineEnabled:: ; 0xd85d
+; 1 = normal audio (music/sfx) engine is enabled
+; 0 = disabled
 	ds $1
 
 wd85e:: ; 0xd85e