Document main menu and game event functions

7 files changed, 104 insertions, 84 deletions

diff --git a/src/constants/misc_constants.asm b/src/constants/misc_constants.asm
index 1cfffb4..c1e3bf1 100644
--- a/src/constants/misc_constants.asm
+++ b/src/constants/misc_constants.asm
@@ -24,3 +24,14 @@ D_DOWN     EQU 1 << D_DOWN_F   ; $80
 
 BUTTONS    EQU A_BUTTON | B_BUTTON | SELECT | START  ; $0f
 D_PAD      EQU D_RIGHT  | D_LEFT   | D_UP   | D_DOWN ; $f0
+
+; Game event constants (wGameEventIndex)
+	const_def
+	const GAME_EVENT_CONTINUE_FROM_DIARY_OR_NEW_GAME ; $0
+	const GAME_EVENT_DUEL                            ; $1
+	const GAME_EVENT_BATTLE_CENTER                   ; $2
+	const GAME_EVENT_GIFT_CENTER                     ; $3
+	const GAME_EVENT_CREDITS                         ; $4
+	const GAME_EVENT_CONTINUE_DUEL                   ; $5
+	const GAME_EVENT_CHALLENGE_MACHINE               ; $6
+NUM_GAME_EVENTS EQU const_value
diff --git a/src/engine/bank1.asm b/src/engine/bank1.asm
index ab84ad8..8852914 100644
--- a/src/engine/bank1.asm
+++ b/src/engine/bank1.asm
@@ -1,5 +1,6 @@
 ; continuation of Bank0 Start
-Start_Cont: ; 4000 (1:4000)
+; supposed to be the main loop, but the game never returns from _GameLoop anyway
+GameLoop: ; 4000 (1:4000)
 	di
 	ld sp, $e000
 	call ResetSerial
@@ -18,8 +19,8 @@ Start_Cont: ; 4000 (1:4000)
 	ldh a, [hButtonsHeld]
 	cp A_BUTTON | B_BUTTON
 	jr z, .ask_erase_backup_ram
-	farcall Func_126d1
-	jr Start_Cont
+	farcall _GameLoop
+	jr GameLoop
 .ask_erase_backup_ram
 	call Func_405a
 	call EmptyScreen
@@ -55,14 +56,15 @@ CommentedOut_406e: ; 406e (1:406e)
 	ret
 ; 0x406f
 
-Func_406f: ; 406f (1:406f)
+; try to resume a saved duel from the main menu
+TryContinueDuel: ; 406f (1:406f)
 	call Func_420b
 	call $66e9
 	ldtx hl, BackUpIsBrokenText
-	jr c, Func_4097
+	jr c, FailedToContinueDuel
 ;	fallthrough
 
-Func_407a: ; 407a (1:407a)
+ContinueDuel: ; 407a (1:407a)
 	ld hl, sp+$00
 	ld a, l
 	ld [wcbe5], a
@@ -77,7 +79,7 @@ Func_407a: ; 407a (1:407a)
 	jp StartDuel.asm_40fb
 ; 0x4097
 
-Func_4097: ; 4097 (1:4097)
+FailedToContinueDuel: ; 4097 (1:4097)
 	call DrawWideTextBox_WaitForInput
 	call ResetSerial
 	scf
diff --git a/src/engine/bank3.asm b/src/engine/bank3.asm
index 717ff69..3612854 100644
--- a/src/engine/bank3.asm
+++ b/src/engine/bank3.asm
@@ -3,8 +3,8 @@ LoadMap: ; c000 (3:4000)
 	call EnableSRAM
 	bank1call Func_6785
 	call DisableSRAM
-	ld a, $0
-	ld [wd0b5], a
+	ld a, GAME_EVENT_CONTINUE_FROM_DIARY_OR_NEW_GAME
+	ld [wGameEventIndex], a
 	xor a
 	ld [wd10f], a
 	ld [wd110], a
@@ -1765,8 +1765,8 @@ asm_cd2f
 	ld [wd0c5], a
 	pop af
 	farcall Func_118a7
-	ld a, $1
-	ld [wd0b5], a
+	ld a, GAME_EVENT_DUEL
+	ld [wGameEventIndex], a
 	ld hl, wd0b4
 	set 6, [hl]
 	jp IncreaseOWScriptPointerBy4
@@ -1794,8 +1794,8 @@ Func_cd66: ; cd66 (3:4d66)
 	ret
 
 Func_cd76: ; cd76 (3:4d76)
-	ld a, $2
-	ld [wd0b5], a
+	ld a, GAME_EVENT_BATTLE_CENTER
+	ld [wGameEventIndex], a
 	ld hl, wd0b4
 	set 6, [hl]
 	jp IncreaseOWScriptPointerBy1
@@ -2707,8 +2707,8 @@ Func_d39d: ; d39d (3:539d)
 	jr .asm_d3b6
 
 .asm_d3ac
-	ld a, $3
-	ld [wd0b5], a
+	ld a, GAME_EVENT_GIFT_CENTER
+	ld [wGameEventIndex], a
 	ld hl, wd0b4
 	set 6, [hl]
 
@@ -2717,8 +2717,8 @@ Func_d39d: ; d39d (3:539d)
 
 Func_d3b9: ; d3b9 (3:53b9)
 	call Func_3917
-	ld a, $4
-	ld [wd0b5], a
+	ld a, GAME_EVENT_CREDITS
+	ld [wGameEventIndex], a
 	ld hl, wd0b4
 	set 6, [hl]
 	jp IncreaseOWScriptPointerBy1
@@ -2794,8 +2794,8 @@ Func_d435: ; d435 (3:5435)
 	jp IncreaseOWScriptPointerBy2
 
 Func_d43d: ; d43d (3:543d)
-	ld a, $6
-	ld [wd0b5], a
+	ld a, GAME_EVENT_CHALLENGE_MACHINE
+	ld [wGameEventIndex], a
 	ld hl, wd0b4
 	set 6, [hl]
 	jp IncreaseOWScriptPointerBy1
diff --git a/src/engine/bank4.asm b/src/engine/bank4.asm
index 1b16106..35dee45 100644
--- a/src/engine/bank4.asm
+++ b/src/engine/bank4.asm
@@ -1077,34 +1077,38 @@ OverworldScriptTable: ; 1217b (4:617b)
 Unknown_1229f: ; 1229f (4:629f)
 	INCROM $1229f, $126d1
 
-Func_126d1: ; 126d1 (4:66d1)
+; usually, the game doesn't loop here at all, since as soon as a main menu option
+; is selected, there is no need to come back to the menu.
+; the only exception is after returning from Card Pop!
+_GameLoop: ; 126d1 (4:66d1)
 	call InitSpritePositions
 	ld hl, wVBlankOAMCopyToggle
 	inc [hl]
 	farcall Func_70018
 	ld a, $ff
 	ld [wd627], a
-.asm_126e1
+.main_menu_loop
 	ld a, PLAYER_TURN
 	ldh [hWhoseTurn], a
 	farcall Func_c1f8
 	farcall Func_1d078
 	ld a, [wd628]
-	ld hl, PointerTable_126fc
+	ld hl, MainMenuFunctionTable
 	call JumpToFunctionInTable
-	jr c, .asm_126e1
-	jr Func_126d1
+	jr c, .main_menu_loop ; return to main menu
+	jr _GameLoop ; virtually restart game
 
+; this is never reached
 	scf
 	ret
 
-PointerTable_126fc:
-	dw CardPop_12768
-	dw Func_12741
-	dw Func_12704
-	dw Func_1277e
+MainMenuFunctionTable:
+	dw MainMenu_CardPop
+	dw MainMenu_ContinueFromDiary
+	dw MainMenu_NewGame
+	dw MainMenu_ContinueDuel
 
-Func_12704: ; 12704 (4:6704)
+MainMenu_NewGame: ; 12704 (4:6704)
 	farcall Func_c1b1
 	call Func_128a9
 	farcall Func_1996e
@@ -1121,30 +1125,30 @@ Func_12704: ; 12704 (4:6704)
 	ld [wd111], a
 	call Func_39fc
 	farcall Func_1d306
-	ld a, $0
-	ld [wd0b5], a
-	farcall $03, Func_383d
+	ld a, GAME_EVENT_CONTINUE_FROM_DIARY_OR_NEW_GAME
+	ld [wGameEventIndex], a
+	farcall $03, ExecuteGameEvent
 	or a
 	ret
 
-Func_12741: ; 12741 (4:6741)
+MainMenu_ContinueFromDiary: ; 12741 (4:6741)
 	ld a, MUSIC_STOP
 	call PlaySong
 	call Func_11320
-	jr nc, Func_12704
+	jr nc, MainMenu_NewGame
 	farcall Func_c1ed
 	farcall Func_70000
 	call EnableSRAM
 	xor a
 	ld [$ba44], a
 	call DisableSRAM
-	ld a, $0
-	ld [wd0b5], a
-	farcall $03, Func_383d
+	ld a, GAME_EVENT_CONTINUE_FROM_DIARY_OR_NEW_GAME
+	ld [wGameEventIndex], a
+	farcall $03, ExecuteGameEvent
 	or a
 	ret
 
-CardPop_12768: ; 12768 (4:6768)
+MainMenu_CardPop: ; 12768 (4:6768)
 	ld a, MUSIC_CARD_POP
 	call PlaySong
 	bank1call Func_7571
@@ -1155,15 +1159,15 @@ CardPop_12768: ; 12768 (4:6768)
 	scf
 	ret
 
-Func_1277e: ; 1277e (4:677e)
+MainMenu_ContinueDuel: ; 1277e (4:677e)
 	ld a, MUSIC_STOP
 	call PlaySong
 	farcall Func_c9cb
 	farcall $04, Func_3a40
 	farcall Func_70000
-	ld a, $5
-	ld [wd0b5], a
-	farcall $03, Func_383d
+	ld a, GAME_EVENT_CONTINUE_DUEL
+	ld [wGameEventIndex], a
+	farcall $03, ExecuteGameEvent
 	or a
 	ret
 ; 0x1279a
diff --git a/src/engine/booster_packs.asm b/src/engine/booster_packs.asm
index 99dde3f..98692d8 100644
--- a/src/engine/booster_packs.asm
+++ b/src/engine/booster_packs.asm
@@ -4,7 +4,7 @@ GenerateBoosterPack: ; 1e1c4 (7:61c4)
 	push hl
 	push bc
 	push de
-	ld [wBoosterIndex], a
+	ld [wBoosterPackID], a
 .no_cards_found_loop
 	call InitBoosterData
 	call GenerateBoosterEnergies
@@ -524,10 +524,10 @@ InitBoosterData: ; 1e430 (7:6430)
 	ld [wBoosterAveragedTypeChances], a
 	ret
 
-; get the pointer to the data of the booster pack at [wBoosterIndex]
+; get the pointer to the data of the booster pack at [wBoosterPackID]
 FindBoosterDataPointer: ; 1e46f (7:646f)
 	push bc
-	ld a, [wBoosterIndex]
+	ld a, [wBoosterPackID]
 	add a
 	ld c, a
 	ld b, $0
diff --git a/src/engine/home.asm b/src/engine/home.asm
index 05da41c..cbe87bb 100644
--- a/src/engine/home.asm
+++ b/src/engine/home.asm
@@ -61,10 +61,10 @@ Start: ; 0150 (0:0150)
 	call ResetSerial
 	call CopyDMAFunction
 	call SetupExtRAM
-	ld a, BANK(Start_Cont)
+	ld a, BANK(GameLoop)
 	call BankswitchHome
 	ld sp, $e000
-	jp Start_Cont
+	jp GameLoop
 
 VBlankHandler: ; 019b (0:019b)
 	push af
@@ -6879,9 +6879,9 @@ PrintYesOrNoItems: ; 2b66 (0:2b66)
 ; 0x2b70
 
 Func_2b70: ; 2b70 (0:2b70)
-	ld a, BANK(Func_407a)
+	ld a, BANK(ContinueDuel)
 	call BankswitchHome
-	jp Func_407a
+	jp ContinueDuel
 ; 0x2b78
 
 ; loads opponent deck to wOpponentDeck
@@ -9067,45 +9067,48 @@ Func_380e: ; 380e (0:380e)
 	call BankswitchHome
 	ret
 
-Func_383d: ; 383d (0:383d)
+; enable the play time counter and execute the game event at [wGameEventIndex],
+; then return to the overworld or restart the game.
+ExecuteGameEvent: ; 383d (0:383d)
 	ld a, $1
 	ld [wPlayTimeCounterEnable], a
 	ldh a, [hBankROM]
 	push af
-.asm_3845
-	call Func_3855
-	jr nc, .asm_3850
+.loop
+	call _ExecuteGameEvent
+	jr nc, .restart
 	farcall LoadMap
-	jr .asm_3845
-.asm_3850
+	jr .loop
+.restart
 	pop af
 	call BankswitchHome
 	ret
 
-Func_3855: ; 3855 (0:3855)
-	ld a, [wd0b5]
-	cp $7
-	jr c, .asm_385e
-	ld a, $6
-.asm_385e
-	ld hl, PointerTable_3864
+; execute a game event at [wGameEventIndex] from GameEventPointerTable
+_ExecuteGameEvent: ; 3855 (0:3855)
+	ld a, [wGameEventIndex]
+	cp NUM_GAME_EVENTS
+	jr c, .got_game_event
+	ld a, GAME_EVENT_CHALLENGE_MACHINE
+.got_game_event
+	ld hl, GameEventPointerTable
 	jp JumpToFunctionInTable
 
-PointerTable_3864: ; 3864 (0:3864)
-	dw Func_3874
-	dw Func_38c0
-	dw Func_38a3
-	dw Func_3876
-	dw Credits_3911
-	dw Func_38fb
-	dw Func_38db
-	dw Func_3874
-
-Func_3874: ; 3874 (0:3874)
+GameEventPointerTable: ; 3864 (0:3864)
+	dw GameEvent_ContinueFromDiaryOrNewGame
+	dw GameEvent_PracticeDuel
+	dw GameEvent_BattleCenter
+	dw GameEvent_GiftCenter
+	dw GameEvent_Credits
+	dw GameEvent_ContinueDuel
+	dw GameEvent_ChallengeMachine
+	dw GameEvent_ContinueFromDiaryOrNewGame
+
+GameEvent_ContinueFromDiaryOrNewGame: ; 3874 (0:3874)
 	scf
 	ret
 
-Func_3876: ; 3876 (0:3876)
+GameEvent_GiftCenter: ; 3876 (0:3876)
 	ldh a, [hBankROM]
 	push af
 	call PauseSong
@@ -9126,7 +9129,7 @@ Func_3876: ; 3876 (0:3876)
 	scf
 	ret
 
-Func_38a3: ; 38a3 (0:38a3)
+GameEvent_BattleCenter: ; 38a3 (0:38a3)
 	ld a, $2
 	ld [wd0c2], a
 	xor a
@@ -9141,7 +9144,7 @@ Func_38a3: ; 38a3 (0:38a3)
 	scf
 	ret
 
-Func_38c0: ; 38c0 (0:38c0)
+GameEvent_PracticeDuel: ; 38c0 (0:38c0)
 	ld a, $1
 	ld [wd0c2], a
 	xor a
@@ -9155,7 +9158,7 @@ Func_38c0: ; 38c0 (0:38c0)
 	scf
 	ret
 
-Func_38db: ; 38db (0:38db)
+GameEvent_ChallengeMachine: ; 38db (0:38db)
 	ld a, $6
 	ld [wd111], a
 	call Func_39fc
@@ -9171,19 +9174,19 @@ Func_38db: ; 38db (0:38db)
 	scf
 	ret
 
-Func_38fb: ; 38fb (0:38fb)
+GameEvent_ContinueDuel: ; 38fb (0:38fb)
 	xor a
 	ld [wd112], a
-	bank1call Func_406f
+	bank1call TryContinueDuel
 	call EnableSRAM
 	ld a, [$ba44]
 	call DisableSRAM
 	cp $ff
-	jr z, Func_38db.asm_38ed
+	jr z, GameEvent_ChallengeMachine.asm_38ed
 	scf
 	ret
 
-Credits_3911: ; 3911 (0:3911)
+GameEvent_Credits: ; 3911 (0:3911)
 	farcall Credits_1d6ad
 	or a
 	ret
diff --git a/src/wram.asm b/src/wram.asm
index 3802967..6af5cb8 100644
--- a/src/wram.asm
+++ b/src/wram.asm
@@ -1154,7 +1154,7 @@ wd0aa:: ; d0aa
 wd0b4:: ; d0b4
 	ds $1
 
-wd0b5:: ; d0b5
+wGameEventIndex:: ; d0b5
 	ds $1
 
 wSCX:: ; d0b6
@@ -1688,7 +1688,7 @@ wd636:: ; d635
 	ds $32
 
 ; which BoosterPack_* corresponds to the booster pack that the player is opening
-wBoosterIndex:: ; d669
+wBoosterPackID:: ; d669
 	ds $1
 
 ; card being currently processed by the booster pack engine functions