Label audio engine update methods

9 files changed, 62 insertions, 50 deletions

diff --git a/engine/pinball_game.asm b/engine/pinball_game.asm
index 3adce56..9c1c847 100644
--- a/engine/pinball_game.asm
+++ b/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]

diff --git a/engine/pinball_game/object_collision/blue_stage_resolve_collision.asm b/engine/pinball_game/object_collision/blue_stage_resolve_collision.asm
index 8cc2636..c9ac09d 100644
--- a/engine/pinball_game/object_collision/blue_stage_resolve_collision.asm
+++ b/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

diff --git a/engine/pinball_game/object_collision/red_stage_resolve_collision.asm b/engine/pinball_game/object_collision/red_stage_resolve_collision.asm
index 3e534b4..dcd080b 100644
--- a/engine/pinball_game/object_collision/red_stage_resolve_collision.asm
+++ b/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

diff --git a/engine/pinball_game/save_game.asm b/engine/pinball_game/save_game.asm
index 624a1a9..c1d65a8 100644
--- a/engine/pinball_game/save_game.asm
+++ b/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]

diff --git a/engine/pinball_game/slot.asm b/engine/pinball_game/slot.asm
index 3331fae..01e3bef 100644
--- a/engine/pinball_game/slot.asm
+++ b/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

diff --git a/engine/pinball_game/vertical_screen_transition.asm b/engine/pinball_game/vertical_screen_transition.asm
index 57ae6bb..59deb90 100644
--- a/engine/pinball_game/vertical_screen_transition.asm
+++ b/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

diff --git a/home.asm b/home.asm
index 29ca3d8..29c1420 100644
--- a/home.asm
+++ b/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
diff --git a/pokemon-reverse-engineering-tools b/pokemon-reverse-engineering-tools
-Subproject 27b200e0e13cf3264c1b124bad73f3f998e21ed
+Subproject 979c98a7c0f67ad6b9685b2d532c66a1f76ffb2
diff --git a/wram.asm b/wram.asm
index 18e4e59..64aa4f5 100644
--- a/wram.asm
+++ b/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