more duel engine labels and documentation

4 files changed, 59 insertions, 58 deletions

diff --git a/src/engine/bank1.asm b/src/engine/bank1.asm
index 65e06f8..1793403 100755
--- a/src/engine/bank1.asm
+++ b/src/engine/bank1.asm
@@ -85,45 +85,45 @@ StartDuel: ; 409f (1:409f)
 	ret c
 
 ; the loop returns here after every turn switch
-.mainDuelLoop
+.mainDuelLoop ; 40ee (1:40ee)
 	xor a
 	ld [wCurrentDuelMenuItem], a
 	call HandleSwordsDanceOrFocusEnergySubstatus
 	call $54c8
-	call Func_4225
+	call DrawCardFromDeck
 	call Func_0f58
 	ld a, [wDuelFinished]
 	or a
-	jr nz, .duelIsOver
+	jr nz, .duelFinished
 	call UpdateSubstatusConditions
 	call $6baf
 	call Func_3b31
 	call Func_0f58
 	ld a, [wDuelFinished]
 	or a
-	jr nz, .duelIsOver
+	jr nz, .duelFinished
 	ld hl, $cc06
 	inc [hl]
 	ld a, [$cc09]
 	cp $80
 	jr z, .asm_4126
 
-.asm_4121
+.nextTurn
 	call SwapTurn
 	jr .mainDuelLoop
 
 .asm_4126
 	ld a, [wIsPracticeDuel]
 	or a
-	jr z, .asm_4121
+	jr z, .nextTurn
 	ld a, [hl]
 	cp $f
-	jr c, .asm_4121
+	jr c, .nextTurn
 	xor a
 	ld [$d0c3], a
 	ret
 
-.duelIsOver
+.duelFinished
 	call $5990
 	call Func_04a2
 	ld a, $3
@@ -146,9 +146,9 @@ StartDuel: ; 409f (1:409f)
 	cp DUEL_LOST
 	jr z, .activeDuelistLostBattle
 	ld a, $5f
-	ld c, $1a
+	ld c, MUSIC_DARKDIDDLY
 	text_hl DuelWasDrawText
-	jr .asm_4196
+	jr .handleDuelFinished
 
 .activeDuelistWonBattle
 	ldh a, [hWhoseTurn]
@@ -158,23 +158,22 @@ StartDuel: ; 409f (1:409f)
 	xor a
 	ld [$d0c3], a
 	ld a, $5d
-	ld c, $18
+	ld c, MUSIC_MATCHVICTORY
 	text_hl WonDuelText
-	jr .asm_4196
+	jr .handleDuelFinished
 
 .activeDuelistLostBattle
 	ldh a, [hWhoseTurn]
 	cp PLAYER_TURN
 	jr nz, .playerWonBattle
-
 .opponentWonBattle
 	ld a, $1
 	ld [$d0c3], a
 	ld a, $5e
-	ld c, $19
+	ld c, MUSIC_MATCHLOSS
 	text_hl LostDuelText
 
-.asm_4196
+.handleDuelFinished
 	call Func_3b6a
 	ld a, c
 	call PlaySong
@@ -234,7 +233,7 @@ StartDuel: ; 409f (1:409f)
 
 INCBIN "baserom.gbc",$420b,$4225 - $420b
 
-Func_4225: ; 4225 (1:4225)
+DrawCardFromDeck: ; 4225 (1:4225)
 	ld a, DUELVARS_DUELIST_TYPE
 	call GetTurnDuelistVariable
 	ld [$cc0d], a
@@ -246,13 +245,13 @@ Func_4225: ; 4225 (1:4225)
 .asm_4237
 	call $70e6
 	call $4933
-	call DrawCardFromDeck
-	jr nc, .asm_4248
+	call _DrawCardFromDeck
+	jr nc, .deckNotEmpty
 	ld a, DUEL_LOST
 	ld [wDuelFinished], a
 	ret
 
-.asm_4248
+.deckNotEmpty
 	ldh [$ff98], a
 	call AddCardToHand
 	ld a, [$cc0d]
@@ -276,7 +275,7 @@ Func_426d:
 	call $4f9d
 	ld a, [$cc0d]
 	cp a, $00
-	jr z, Func_4295
+	jr z, PrintDuelMenu
 	cp a, $01
 	jp z, $6911
 	xor a
@@ -290,7 +289,7 @@ Func_426d:
 	ld [$cc10], a
 	ret
 
-Func_4295:
+PrintDuelMenu:
 	call DrawWideTextBox
 	ld hl, $54e9
 	call Func_2c08
@@ -356,12 +355,12 @@ Func_4311: ; 4311 (1:4311)
 
 Func_4317: ; 4317 (1:4317)
 	call Func_4339
-	jp c, Func_4295
+	jp c, PrintDuelMenu
 	jp Func_426d
 
 Func_4320: ; 4320 (1:4320)
 	call Func_4342
-	jp c, Func_4295
+	jp c, PrintDuelMenu
 	jp Func_426d
 
 Func_4329: ; 4329 (1:4329)
@@ -429,7 +428,7 @@ PlayerRetreat: ; 43ab (1:43ab)
 Func_43e8: ; 43e8
 	text_hl UnableToRetreatText
 	call DrawWideTextBox_WaitForInput
-	jp Func_4295
+	jp PrintDuelMenu
 
 Func_43f1: ; 43f1 (1:43f1)
 	call $45bb
@@ -455,7 +454,7 @@ Func_441c: ; 441c (1:441c)
 
 Func_441f: ; 441f (1:441f)
 	call DrawWideTextBox_WaitForInput
-	jp Func_4295
+	jp PrintDuelMenu
 
 OpenHandMenu: ; 4425 (1:4425)
 	ld a, DUELVARS_NUMBER_OF_CARDS_IN_HAND
@@ -464,7 +463,7 @@ OpenHandMenu: ; 4425 (1:4425)
 	jr nz, Func_4436
 	text_hl NoCardsInHandText
 	call DrawWideTextBox_WaitForInput
-	jp Func_4295
+	jp PrintDuelMenu
 
 Func_4436: ; 4436 (1:4436)
 INCBIN "baserom.gbc",$4436, $4585 - $4436
@@ -484,7 +483,7 @@ OpenBattleAttackMenu: ; 46fc (1:46fc)
 
 .alertCantAttackAndCancelMenu
 	call DrawWideTextBox_WaitForInput
-	jp Func_4295
+	jp PrintDuelMenu
 
 .clearSubMenuSelection
 	xor a
@@ -496,7 +495,7 @@ OpenBattleAttackMenu: ; 46fc (1:46fc)
 	jr nz, .openAttackMenu
 	text_hl NoSelectableAttackText
 	call DrawWideTextBox_WaitForInput
-	jp Func_4295
+	jp PrintDuelMenu
 
 .openAttackMenu
 	push af
@@ -511,15 +510,15 @@ OpenBattleAttackMenu: ; 46fc (1:46fc)
 	ld a, [hl]
 	call LoadDeckCardToBuffer1
 
-.asm_4736
+.waitForInput
 	call DoFrame
 	ldh a, [hButtonsPressed]
 	and START
 	jr nz, .displaySelectedMoveInfo
 	call MenuCursorAcceptInput
-	jr nc, .asm_4736
-	cp $ff
-	jp z, Func_4295
+	jr nc, .waitForInput
+	cp $ff ; was B pressed?
+	jp z, PrintDuelMenu
 	ld [wSelectedDuelSubMenuItem], a
 	call $488f
 	jr nc, .asm_4759
@@ -534,9 +533,9 @@ OpenBattleAttackMenu: ; 46fc (1:46fc)
 	ld d, $00
 	ld hl, wDuelCardOrAttackList
 	add hl, de
-	ld d, [hl]
+	ld d, [hl] ; card id
 	inc hl
-	ld e, [hl]
+	ld e, [hl] ; attack index (0 or 1)
 	call Func_16c0
 	call HandleAmnesiaSubstatus
 	jr c, .asm_477d
@@ -891,7 +890,7 @@ InitializeDuelVariables: ; 7107 (1:7107)
 
 INCBIN "baserom.gbc",$7133,$71ad - $7133
 
-TossCoin: ; 71ad (1:71ad)
+_TossCoin: ; 71ad (1:71ad)
 	ld [$cd9c], a
 	ld a, [wcac2]
 	cp $6
diff --git a/src/engine/effect_functions.asm b/src/engine/effect_functions.asm
index 25c1ce2..143ab22 100644
--- a/src/engine/effect_functions.asm
+++ b/src/engine/effect_functions.asm
@@ -1,6 +1,6 @@
 Poison50PercentEffect: ; 2c000 (b:4000)
 	text_de PoisonCheckText
-	call DisplayCoinTossScreen2_BankB
+	call TossCoin_BankB
 	ret nc
 
 PoisonEffect: ; 2c007 (b:4007)
@@ -12,20 +12,20 @@ PoisonEffect: ; 2c007 (b:4007)
 
 Paralysis50PercentEffect: ; 2c011 (b:4011)
 	text_de ParalysisCheckText
-	call DisplayCoinTossScreen2_BankB
+	call TossCoin_BankB
 	ret nc
 	lb bc, $f0, PARALYZED
 	jr applyEffect
 
 Confusion50PercentEffect: ; 2c01d (b:401d)
 	text_de ConfusionCheckText
-	call DisplayCoinTossScreen2_BankB
+	call TossCoin_BankB
 	ret nc
 	lb bc, $f0, CONFUSED
 	jr applyEffect
 
 	text_de SleepCheckText
-	call DisplayCoinTossScreen2_BankB
+	call TossCoin_BankB
 	ret nc
 
 SleepEffect: ; 2c030 (b:4030)
@@ -79,8 +79,8 @@ applyEffect
 	ret
 ; 0x2c07e
 
-DisplayCoinTossScreen2_BankB: ; 2c07e (b:407e)
-	call DisplayCoinTossScreen2
+TossCoin_BankB: ; 2c07e (b:407e)
+	call TossCoin
 	ret
 ; 0x2c082
 
diff --git a/src/engine/home.asm b/src/engine/home.asm
index 4c64ed1..50ab9d2 100755
--- a/src/engine/home.asm
+++ b/src/engine/home.asm
@@ -2276,7 +2276,7 @@ ShuffleDeck: ; 10bc (0:10bc)
 
 ; draw a card from the deck, saving its location as $40
 ; returns c if deck is empty, nc if a card was succesfully drawn
-DrawCardFromDeck: ; 10cf (0:10cf)
+_DrawCardFromDeck: ; 10cf (0:10cf)
 	push hl
 	ld a, DUELVARS_NUMBER_OF_CARDS_NOT_IN_DECK
 	call GetTurnDuelistVariable
@@ -2500,19 +2500,19 @@ Func_16c0: ; 16c0 (0:16c0)
 	call LoadDeckCardToBuffer1
 	ld a, [$cc2b]
 	ld [wccc2], a
-	ld hl, $cc30
+	ld hl, wCardBuffer1Move1
 	dec e
-	jr nz, .asm_16d9
-	ld hl, $cc43
-.asm_16d9
-	ld de, $cca6
-	ld c, $13
-.asm_16de
+	jr nz, .gotMove
+	ld hl, wCardBuffer1Move2
+.gotMove
+	ld de, wcca6
+	ld c, wCardBuffer1Move2 - wCardBuffer1Move1
+.copyLoop
 	ld a, [hli]
 	ld [de], a
 	inc de
 	dec c
-	jr nz, .asm_16de
+	jr nz, .copyLoop
 	ld a, [wccb0]
 	ld hl, $ccb9
 	ld [hli], a
@@ -2775,7 +2775,7 @@ Func_18d7: ; 18d7 (0:18d7)
 	ret
 .confused
 	ld de, $00f7
-	call DisplayCoinTossScreen2
+	call TossCoin
 	jr c, .asm_18f7
 	ld a, $1
 	ld [wccc9], a
@@ -4244,7 +4244,8 @@ InitializeCursorParameters: ; 2636 (0:2636)
 	ld [wCursorBlinkCounter], a
 	ret
 
-; returns with the carry flag set if a or b were pressed
+; returns with the carry flag set if A or B were pressed
+; returns a = 0 if A was pressed, a = -1 if B was pressed
 MenuCursorAcceptInput: ; 264b (0:264b)
 	xor a
 	ld [wcd99], a
@@ -5448,14 +5449,14 @@ Func_3061: ; 3061 (0:3061)
 ; displaying each result ([O] or [X]) starting from the top left corner of the screen.
 ; text at de is printed in a text box during the coin toss.
 ;   returns: the number of heads in a and in $cd9d, and carry if at least one heads
-DisplayCoinTossScreen1: ; 3071 (0:3071)
+TossCoinATimes: ; 3071 (0:3071)
 	push hl
 	ld hl, wCoinTossScreenTextId
 	ld [hl], e
 	inc hl
 	ld [hl], d
 	rst $18
-	dw TossCoin
+	dw _TossCoin
 	pop hl
 	ret
 
@@ -5463,7 +5464,7 @@ DisplayCoinTossScreen1: ; 3071 (0:3071)
 ; text at de is printed in a text box during the coin toss.
 ;   returns: - carry, and 1 in a and in $cd9d if heads
 ;            - nc, and 0 in a and in $cd9d if tails
-DisplayCoinTossScreen2: ; 307d (0:307d)
+TossCoin: ; 307d (0:307d)
 	push hl
 	ld hl, wCoinTossScreenTextId
 	ld [hl], e
@@ -5471,7 +5472,7 @@ DisplayCoinTossScreen2: ; 307d (0:307d)
 	ld [hl], d
 	ld a, $1
 	rst $18
-	dw TossCoin
+	dw _TossCoin
 	ld hl, $cac2
 	ld [hl], $0
 	pop hl
@@ -5943,7 +5944,7 @@ HandleAmnesiaSubstatus: ; 33e1 (0:33e1)
 HandleSandAttackOrSmokescreenSubstatus: ; 3400 (0:3400)
 	call CheckSandAttackOrSmokescreenSubstatus
 	ret nc
-	call DisplayCoinTossScreen2
+	call TossCoin
 	ld [wcc0a], a
 	ccf
 	ret nc
@@ -6041,7 +6042,7 @@ Func_348a: ; 348a (0:348a)
 	xor a
 	ld [wcac2], a
 	ld de, $00f6
-	call DisplayCoinTossScreen2
+	call TossCoin
 	ret nc
 	ld a, $4
 	ld [wNoDamageOrEffect], a
diff --git a/src/wram.asm b/src/wram.asm
index bdfe262..c675f9e 100755
--- a/src/wram.asm
+++ b/src/wram.asm
@@ -455,6 +455,7 @@ wCardBuffer1:: ; cc24
 wCardBuffer2:: ; cc65
 	card_data_struct wCardBuffer2
 
+wcca6:: ; cca6
 	ds $4
 
 wccaa:: ; ccaa