More general labeling and document the main evolve Pokemon functions

9 files changed, 138 insertions, 99 deletions

diff --git a/src/audio/music1.asm b/src/audio/music1.asm
index 86d76f4..0407f6c 100644
--- a/src/audio/music1.asm
+++ b/src/audio/music1.asm
@@ -13,11 +13,11 @@ _PlaySFX:: ; f4009 (3d:4009)
 Func_f400c:: ; f400c (3d:400c)
 	jp Func_f404e
 
-Func_f400f:: ; f400f (3d:400f)
-	jp Func_f4052
+_AssertSongFinished:: ; f400f (3d:400f)
+	jp Music1_AssertSongFinished
 
-Func_f4012:: ; f4012 (3d:4012)
-	jp Func_f405c
+_AssertSFXFinished:: ; f4012 (3d:4012)
+	jp Music1_AssertSFXFinished
 
 Func_f4015:: ; f4015 (3d:4015)
 	jp Func_f4066
@@ -70,7 +70,7 @@ Func_f404e: ; f404e (3d:404e)
 	ld [wddf0], a
 	ret
 
-Func_f4052: ; f4052 (3d:4052)
+Music1_AssertSongFinished: ; f4052 (3d:4052)
 	ld a, [wCurSongID]
 	cp $80
 	ld a, $1
@@ -78,7 +78,7 @@ Func_f4052: ; f4052 (3d:4052)
 	xor a
 	ret
 
-Func_f405c: ; f405c (3d:405c)
+Music1_AssertSFXFinished: ; f405c (3d:405c)
 	ld a, [wCurSfxID]
 	cp $80
 	ld a, $1
diff --git a/src/audio/music2.asm b/src/audio/music2.asm
index 41d58f8..499aafc 100644
--- a/src/audio/music2.asm
+++ b/src/audio/music2.asm
@@ -14,10 +14,10 @@ Func_f800c: ; f800c (3e:400c)
 	jp Func_f804e
 
 Func_f800f: ; f800f (3e:400f)
-	jp Func_f8052
+	jp Music2_AssertSongFinished
 
 Func_f8012: ; f8012 (3e:4012)
-	jp Func_f805c
+	jp Music2_AssertSFXFinished
 
 Func_f8015: ; f8015 (3e:4015)
 	jp Func_f8066
@@ -70,7 +70,7 @@ Func_f804e: ; f804e (3e:404e)
 	ld [wddf0], a
 	ret
 
-Func_f8052: ; f8052 (3e:4052)
+Music2_AssertSongFinished: ; f8052 (3e:4052)
 	ld a, [wCurSongID]
 	cp $80
 	ld a, $1
@@ -78,7 +78,7 @@ Func_f8052: ; f8052 (3e:4052)
 	xor a
 	ret
 
-Func_f805c: ; f805c (3e:405c)
+Music2_AssertSFXFinished: ; f805c (3e:405c)
 	ld a, [wCurSfxID]
 	cp $80
 	ld a, $1
diff --git a/src/constants/duel_constants.asm b/src/constants/duel_constants.asm
index d033722..7f2f4d4 100644
--- a/src/constants/duel_constants.asm
+++ b/src/constants/duel_constants.asm
@@ -5,6 +5,11 @@ MAX_PLAY_AREA_POKEMON EQU 6 ; arena + bench
 PLAYER_TURN   EQUS "HIGH(wPlayerDuelVariables)"
 OPPONENT_TURN EQUS "HIGH(wOpponentDuelVariables)"
 
+; wDuelType constants
+DUELTYPE_LINK     EQU $1
+DUELTYPE_PRACTICE EQU $80
+; for normal duels (vs AI), wDuelType is $80 + [wOpponentDeckID]
+
 ; wDuelFinished constants
 DUEL_WON  EQU $1
 DUEL_LOST EQU $2
@@ -27,6 +32,7 @@ DUELVARS_DECK_CARDS                      EQUS "LOW(wPlayerDeckCards)"
 DUELVARS_NUMBER_OF_CARDS_NOT_IN_DECK     EQUS "LOW(wPlayerNumberOfCardsNotInDeck)"     ; ba
 DUELVARS_ARENA_CARD                      EQUS "LOW(wPlayerArenaCard)"                  ; bb
 DUELVARS_BENCH                           EQUS "LOW(wPlayerBench)"                      ; bc
+DUELVARS_ARENA_CARD_FLAGS_C2             EQU                                            $c2
 DUELVARS_ARENA_CARD_HP                   EQUS "LOW(wPlayerArenaCardHP)"                ; c8
 DUELVARS_BENCH1_CARD_HP                  EQUS "LOW(wPlayerBench1CardHP)"               ; c9
 DUELVARS_BENCH2_CARD_HP                  EQUS "LOW(wPlayerBench2CardHP)"               ; ca
@@ -53,7 +59,7 @@ DUELVARS_ARENA_CARD_SUBSTATUS3           EQUS "LOW(wPlayerArenaCardSubstatus3)"
 DUELVARS_PRIZES                          EQUS "LOW(wPlayerPrizes)"                     ; ec
 DUELVARS_NUMBER_OF_CARDS_IN_DISCARD_PILE EQUS "LOW(wPlayerNumberOfCardsInDiscardPile)" ; ed
 DUELVARS_NUMBER_OF_CARDS_IN_HAND         EQUS "LOW(wPlayerNumberOfCardsInHand)"        ; ee
-DUELVARS_NUMBER_OF_POKEMON_IN_PLAY       EQUS "LOW(wPlayerNumberOfPokemonInPlay)"      ; ef
+DUELVARS_NUMBER_OF_POKEMON_IN_PLAY_AREA  EQUS "LOW(wPlayerNumberOfPokemonInPlayArea)"  ; ef
 DUELVARS_ARENA_CARD_STATUS               EQUS "LOW(wPlayerArenaCardStatus)"            ; f0
 DUELVARS_DUELIST_TYPE                    EQUS "LOW(wPlayerDuelistType)"                ; f1
 DUELVARS_ARENA_CARD_DISABLED_MOVE_INDEX  EQUS "LOW(wPlayerArenaCardDisabledMoveIndex)" ; f2
@@ -87,7 +93,7 @@ PLAY_AREA_BENCH_5 EQU $5
 ; duelist types (DUELVARS_DUELIST_TYPE)
 DUELIST_TYPE_PLAYER   EQU $00
 DUELIST_TYPE_LINK_OPP EQU $01
-DUELIST_TYPE_AI_OPP   EQU $80
+DUELIST_TYPE_AI_OPP   EQU $80 ; $80 + [wOpponentDeckID]
 
 ; status conditions (DUELVARS_ARENA_CARD_STATUS)
 ; two statuses can be combined if they are identified by a different nybble
@@ -129,6 +135,10 @@ SUBSTATUS2_GROWL          EQU $12
 SUBSTATUS3_THIS_TURN_DOUBLE_DAMAGE EQU 0
 SUBSTATUS3_HEADACHE                EQU 1
 
+; DUELVARS_ARENA_CARD_FLAGS_C2 constants
+CAN_EVOLVE_THIS_TURN_F EQU 7
+CAN_EVOLVE_THIS_TURN   EQU 1 << CAN_EVOLVE_THIS_TURN_F
+
 ; wNoDamageOrEffect constants
 NO_DAMAGE_OR_EFFECT_AGILITY      EQU $01
 NO_DAMAGE_OR_EFFECT_BARRIER      EQU $02
diff --git a/src/engine/bank1.asm b/src/engine/bank1.asm
index cb9f3a9..cb8604a 100644
--- a/src/engine/bank1.asm
+++ b/src/engine/bank1.asm
@@ -67,16 +67,16 @@ TryContinueDuel: ; 406f (1:406f)
 ContinueDuel: ; 407a (1:407a)
 	ld hl, sp+$00
 	ld a, l
-	ld [wcbe5], a
+	ld [wDuelReturnAddress], a
 	ld a, h
-	ld [wcbe5 + 1], a
+	ld [wDuelReturnAddress + 1], a
 	call ClearJoypad
 	ld a, [wDuelTheme]
 	call PlaySong
 	xor a
 	ld [wDuelFinished], a
 	call DuelMainScene
-	jp StartDuel.asm_40fb
+	jp StartDuel.begin_turn
 ; 0x4097
 
 FailedToContinueDuel: ; 4097 (1:4097)
@@ -99,7 +99,7 @@ StartDuel: ; 409f (1:409f)
 	call SwapTurn
 	call LoadOpponentDeck
 	call SwapTurn
-	jr .asm_40ca
+	jr .continue
 
 	ld a, MUSIC_DUEL_THEME_1
 	ld [wDuelTheme], a
@@ -109,17 +109,17 @@ StartDuel: ; 409f (1:409f)
 	ld [hl], a
 	ld [wIsPracticeDuel], a
 
-.asm_40ca
+.continue
 	ld hl, sp+$0
 	ld a, l
-	ld [wcbe5], a
+	ld [wDuelReturnAddress], a
 	ld a, h
-	ld [wcbe5 + 1], a
+	ld [wDuelReturnAddress + 1], a
 	xor a
 	ld [wCurrentDuelMenuItem], a
 	call Func_420b
 	ld a, [wcc18]
-	ld [wcc08], a
+	ld [wDuelInitialPrizes], a
 	call $70aa
 	ld a, [wDuelTheme]
 	call PlaySong
@@ -134,7 +134,7 @@ StartDuel: ; 409f (1:409f)
 	call $54c8
 	call HandleTurn
 
-.asm_40fb
+.begin_turn
 	call Func_0f58
 	ld a, [wDuelFinished]
 	or a
@@ -148,23 +148,23 @@ StartDuel: ; 409f (1:409f)
 	jr nz, .duel_finished
 	ld hl, wDuelTurns
 	inc [hl]
-	ld a, [wcc09]
-	cp $80
-	jr z, .asm_4126
+	ld a, [wDuelType]
+	cp DUELTYPE_PRACTICE
+	jr z, .practice_duel
 
 .next_turn
 	call SwapTurn
 	jr .main_duel_loop
 
-.asm_4126
+.practice_duel
 	ld a, [wIsPracticeDuel]
 	or a
 	jr z, .next_turn
 	ld a, [hl]
-	cp $f
+	cp 15 ; the practice duel lasts 15 turns
 	jr c, .next_turn
 	xor a
-	ld [wd0c3], a
+	ld [wDuelResult], a
 	ret
 
 .duel_finished
@@ -200,7 +200,7 @@ StartDuel: ; 409f (1:409f)
 	jr nz, .opponent_won_battle
 .player_won_battle
 	xor a
-	ld [wd0c3], a
+	ld [wDuelResult], a
 	ld a, $5d
 	ld c, MUSIC_MATCH_VICTORY
 	ldtx hl, WonDuelText
@@ -211,8 +211,8 @@ StartDuel: ; 409f (1:409f)
 	cp PLAYER_TURN
 	jr nz, .player_won_battle
 .opponent_won_battle
-	ld a, $1
-	ld [wd0c3], a
+	ld a, 1
+	ld [wDuelResult], a
 	ld a, $5e
 	ld c, MUSIC_MATCH_LOSS
 	ldtx hl, LostDuelText
@@ -225,11 +225,11 @@ StartDuel: ; 409f (1:409f)
 	ldh [hWhoseTurn], a
 	call DrawWideTextBox_PrintText
 	call EnableLCD
-.asm_41a7
+.wait_song
 	call DoFrame
-	call Func_378a
+	call AssertSongFinished
 	or a
-	jr nz, .asm_41a7
+	jr nz, .wait_song
 	ld a, [wDuelFinished]
 	cp DUEL_DRAW
 	jr z, .tied_battle
@@ -248,26 +248,26 @@ StartDuel: ; 409f (1:409f)
 	call PlaySong
 	ldtx hl, StartSuddenDeathMatchText
 	call DrawWideTextBox_WaitForInput
-	ld a, $1
-	ld [wcc08], a
+	ld a, 1
+	ld [wDuelInitialPrizes], a
 	call $70aa
-	ld a, [wcc09]
-	cp $1
-	jr z, .asm_41f3
+	ld a, [wDuelType]
+	cp DUELTYPE_LINK
+	jr z, .link_duel
 	ld a, PLAYER_TURN
 	ldh [hWhoseTurn], a
 	call Func_4b60
 	jp .main_duel_loop
 
-.asm_41f3
+.link_duel
 	call Func_0f58
 	ld h, PLAYER_TURN
 	ld a, [wSerialOp]
 	cp $29
-	jr z, .asm_4201
+	jr z, .got_turn
 	ld h, OPPONENT_TURN
 
-.asm_4201
+.got_turn
 	ld a, h
 	ldh [hWhoseTurn], a
 	call Func_4b60
@@ -294,10 +294,10 @@ HandleTurn: ; 4225 (1:4225)
 	ld [wDuelistType], a
 	ld a, [wDuelTurns]
 	cp 2
-	jr c, .asm_4237 ; jump if it's the turn holder's first turn
+	jr c, .first_turn ; jump if it's the turn holder's first turn
 	call $70f6
 
-.asm_4237
+.first_turn
 	call $70e6
 	call $4933
 	call DrawCardFromDeck
@@ -1102,7 +1102,7 @@ Func_4b60: ; 4b60 (1:4b60)
 	ldtx hl, PlacingThePrizesText
 	call DrawWideTextBox_WaitForInput
 	call Func_0f58
-	ld a, [wcc08]
+	ld a, [wDuelInitialPrizes]
 	ld l, a
 	ld h, 0
 	call LoadTxRam3
@@ -1240,7 +1240,7 @@ Func_4cd5: ; 4cd5 (1:4cd5)
 	ld hl, $006f
 	call $5502
 	jr c, .asm_4d8e
-	ld a, DUELVARS_NUMBER_OF_POKEMON_IN_PLAY
+	ld a, DUELVARS_NUMBER_OF_POKEMON_IN_PLAY_AREA
 	call GetTurnDuelistVariable
 	cp MAX_PLAY_AREA_POKEMON
 	jr nc, .asm_4d86
diff --git a/src/engine/bank3.asm b/src/engine/bank3.asm
index 79b2a1b..f435924 100644
--- a/src/engine/bank3.asm
+++ b/src/engine/bank3.asm
@@ -3118,7 +3118,7 @@ OWSequence_Joshua:
 
 FindEndOfBattleScript: ; e52c (3:652c)
 	ld c, $0
-	ld a, [wd0c3]
+	ld a, [wDuelResult]
 	or a
 	jr z, .player_won
 	ld c, $2
@@ -3186,7 +3186,7 @@ Func_f580: ; f580 (3:7580)
 	INCROM $f5b3, $fc2b
 
 Func_fc2b: ; fc2b (3:7c2b)
-	ld a, [wd0c3]
+	ld a, [wDuelResult]
 	cp $2
 	jr c, .asm_fc34
 	ld a, $2
diff --git a/src/engine/bank6.asm b/src/engine/bank6.asm
index 0abc3ac..353044e 100644
--- a/src/engine/bank6.asm
+++ b/src/engine/bank6.asm
@@ -159,7 +159,7 @@ Func_1a61f: ; 1a61f (6:661f)
 	pop hl
 	bank1call $5e5f
 .asm_1a680
-	call Func_378a
+	call AssertSongFinished
 	or a
 	jr nz, .asm_1a680
 	call ResumeSong
diff --git a/src/engine/bank7.asm b/src/engine/bank7.asm
index 156d421..725b51b 100644
--- a/src/engine/bank7.asm
+++ b/src/engine/bank7.asm
@@ -389,7 +389,7 @@ Func_1d078: ; 1d078 (7:5078)
 	call $5614
 	ld hl, wd635
 	inc [hl]
-	call Func_378a
+	call AssertSongFinished
 	or a
 	jr nz, .asm_1d0ae
 	farcall Func_10ab4
@@ -492,7 +492,7 @@ Func_1d306: ; 1d306 (7:5306)
 	INCROM $1d306, $1d386
 
 Titlescreen_1d386: ; 1d386 (7:5386)
-	call Func_378a
+	call AssertSongFinished
 	or a
 	jr nz, .asm_1d39f
 	call DisableLCD
diff --git a/src/engine/home.asm b/src/engine/home.asm
index 953e35a..cd347aa 100644
--- a/src/engine/home.asm
+++ b/src/engine/home.asm
@@ -2460,9 +2460,9 @@ DuelTransmissionError: ; 0f35 (0:0f35)
 	call LoadTxRam3
 	ldtx hl, TransmissionErrorText
 	call DrawWideTextBox_WaitForInput
-	ld a, $ff
-	ld [wd0c3], a
-	ld hl, wcbe5
+	ld a, -1
+	ld [wDuelResult], a
+	ld hl, wDuelReturnAddress
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
@@ -2473,8 +2473,8 @@ DuelTransmissionError: ; 0f35 (0:0f35)
 	ret
 
 Func_0f58: ; 0f58 (0:0f58)
-	ld a, [wcc09]
-	cp $1
+	ld a, [wDuelType]
+	cp DUELTYPE_LINK
 	jr z, .asm_f60
 	ret
 .asm_f60
@@ -3437,26 +3437,34 @@ LoadCardDataToBuffer2_FromDeckIndex: ; 138c (0:138c)
 	ret
 ; 0x13a2
 
-Func_13a2: ; 13a2 (0:13a2)
+; evolve a turn holder's Pokemon card in the play area slot determined by hTempPlayAreaLocationOffset_ff9d
+; into another turn holder's Pokemon card identifier by it's deck index (0-59) in hTempCardIndex_ff98.
+; always returns nc, but it's unclear if it's intentional.
+EvolvePokemonCard: ; 13a2 (0:13a2)
+	; first make sure the attempted evolution is viable
 	ldh a, [hTempCardIndex_ff98]
 	ld d, a
 	ldh a, [hTempPlayAreaLocationOffset_ff9d]
 	ld e, a
-	call Func_13f7
-	ret c
+	call CheckIfCanEvolveInto
+	ret c ; return if it's not capable of evolving into the selected Pokemon
+
+	; place the evolved Pokemon card in the play area location of the pre-evolved Pokemon card
 	ldh a, [hTempPlayAreaLocationOffset_ff9d]
 	ld e, a
 	add DUELVARS_ARENA_CARD
 	call GetTurnDuelistVariable
-	ld [wccee], a
+	ld [wccee], a ; save pre-evolved Pokemon card into wccee
 	call LoadCardDataToBuffer2_FromDeckIndex
 	ldh a, [hTempCardIndex_ff98]
 	ld [hl], a
 	call LoadCardDataToBuffer1_FromDeckIndex
 	ldh a, [hTempCardIndex_ff98]
 	call PutHandCardInPlayArea
+
+	; update the Pokemon's HP with the difference
 	ldh a, [hTempPlayAreaLocationOffset_ff9d]
-	ld a, e
+	ld a, e ; derp
 	add DUELVARS_ARENA_CARD_HP
 	call GetTurnDuelistVariable
 	ld a, [wLoadedCard2HP]
@@ -3465,8 +3473,9 @@ Func_13a2: ; 13a2 (0:13a2)
 	sub c
 	add [hl]
 	ld [hl], a
+	; reset status (if in arena) and set the flag that prevents it from evolving again this turn
 	ld a, e
-	add $c2
+	add DUELVARS_ARENA_CARD_FLAGS_C2
 	ld l, a
 	ld [hl], $00
 	ld a, e
@@ -3476,18 +3485,24 @@ Func_13a2: ; 13a2 (0:13a2)
 	ld a, e
 	or a
 	call z, ResetStatusConditions
+
+	; set the new evolution stage of the card
 	ldh a, [hTempPlayAreaLocationOffset_ff9d]
 	add DUELVARS_ARENA_CARD_STAGE
 	call GetTurnDuelistVariable
 	ld a, [wLoadedCard1Stage]
 	ld [hl], a
+	; this is buggy but the return value would've always been the same anyway, as the Pokemon can't be basic
 	or a
 	ret ; !
 	scf
 	ret
 ; 0x13f7
 
-Func_13f7: ; 13f7 (0:13f7)
+; check if the turn holder's Pokemon card e can evolve into the turn holder's Pokemon card d.
+; e is the play area location offset (PLAY_AREA_*) of the Pokemon trying to evolve.
+; d is the deck index (0-59) of the Pokemon card that was selected to be the evolution target.
+CheckIfCanEvolveInto: ; 13f7 (0:13f7)
 	push de
 	ld a, e
 	add DUELVARS_ARENA_CARD
@@ -3496,43 +3511,45 @@ Func_13f7: ; 13f7 (0:13f7)
 	ld a, d
 	call LoadCardDataToBuffer1_FromDeckIndex
 	ld hl, wLoadedCard2Name
-	ld de, wLoadedCard1NonPokemonDescription
+	ld de, wLoadedCard1PreEvoName
 	ld a, [de]
 	cp [hl]
-	jr nz, .asm_1427
+	jr nz, .cant_evolve ; jump if they are incompatible to evolve
 	inc de
 	inc hl
 	ld a, [de]
 	cp [hl]
-	jr nz, .asm_1427
+	jr nz, .cant_evolve ; jump if they are incompatible to evolve
 	pop de
 	ld a, e
-	add $c2
+	add DUELVARS_ARENA_CARD_FLAGS_C2
 	call GetTurnDuelistVariable
-	and $80
-	jr nz, .asm_1425
+	and CAN_EVOLVE_THIS_TURN
+	jr nz, .can_evolve
+	; if the card trying to evolve was played this turn, it can't evolve
 	ld a, $01
 	or a
 	scf
 	ret
-.asm_1425
+.can_evolve
 	or a
 	ret
-.asm_1427
+.cant_evolve
 	pop de
 	xor a
 	scf
 	ret
 ; 0x142b
 
+; similar to CheckIfCanEvolveInto, but with the twist of calling Func_2ecd
 Func_142b: ; 142b (0:142b)
 	ld a, e
-	add $c2
+	add DUELVARS_ARENA_CARD_FLAGS_C2
 	call GetTurnDuelistVariable
-	and $80
-	jr nz, .asm_1437
-	jr .asm_145e
-.asm_1437
+	and CAN_EVOLVE_THIS_TURN
+	jr nz, .can_evolve
+	jr .cant_evolve
+.can_evolve
 	ld a, e
 	add DUELVARS_ARENA_CARD
 	ld l, a
@@ -3540,24 +3557,24 @@ Func_142b: ; 142b (0:142b)
 	call LoadCardDataToBuffer2_FromDeckIndex
 	ld a, d
 	call LoadCardDataToBuffer1_FromDeckIndex
-	ld hl, wLoadedCard1NonPokemonDescription
+	ld hl, wLoadedCard1PreEvoName
 	ld e, [hl]
 	inc hl
 	ld d, [hl]
 	call $2ecd
 	ld hl, wLoadedCard2Name
-	ld de, wLoadedCard1NonPokemonDescription
+	ld de, wLoadedCard1PreEvoName
 	ld a, [de]
 	cp [hl]
-	jr nz, .asm_145e
+	jr nz, .cant_evolve
 	inc de
 	inc hl
 	ld a, [de]
 	cp [hl]
-	jr nz, .asm_145e
+	jr nz, .cant_evolve
 	or a
 	ret
-.asm_145e
+.cant_evolve
 	xor a
 	scf
 	ret
@@ -3603,7 +3620,7 @@ ResetStatusConditions: ; 1461 (0:1461)
 ; return carry if there is no room for more Pokemon
 PutHandPokemonCardInPlayArea: ; 1485 (0:1485)
 	push af
-	ld a, DUELVARS_NUMBER_OF_POKEMON_IN_PLAY
+	ld a, DUELVARS_NUMBER_OF_POKEMON_IN_PLAY_AREA
 	call GetTurnDuelistVariable
 	cp MAX_PLAY_AREA_POKEMON
 	jr nc, .already_max_pkmn_in_play
@@ -3623,7 +3640,7 @@ PutHandPokemonCardInPlayArea: ; 1485 (0:1485)
 	ld l, a
 	ld a, [wLoadedCard2HP]
 	ld [hl], a ; set card's HP
-	ld a, $c2
+	ld a, DUELVARS_ARENA_CARD_FLAGS_C2
 	add e
 	ld l, a
 	ld [hl], $0
@@ -3677,7 +3694,7 @@ PutHandCardInPlayArea: ; 14d2 (0:14d2)
 ; to the discard pile
 MovePlayAreaCardToDiscardPile: ; 14dd (0:14dd)
 	call EmptyPlayAreaSlot
-	ld l, DUELVARS_NUMBER_OF_POKEMON_IN_PLAY
+	ld l, DUELVARS_NUMBER_OF_POKEMON_IN_PLAY_AREA
 	dec [hl]
 	ld l, DUELVARS_CARD_LOCATIONS
 .next_card
@@ -3776,7 +3793,7 @@ SwapPlayAreaPokemon: ; 1548 (0:1548)
 	call .swap_duelvar
 	ld a, DUELVARS_ARENA_CARD_HP
 	call .swap_duelvar
-	ld a, $c2
+	ld a, DUELVARS_ARENA_CARD_FLAGS_C2
 	call .swap_duelvar
 	ld a, DUELVARS_ARENA_CARD_STAGE
 	call .swap_duelvar
@@ -9028,12 +9045,14 @@ PlaySong: ; 3785 (0:3785)
 	farcall _PlaySong
 	ret
 
-Func_378a: ; 378a (0:378a)
-	farcall Func_f400f
+; return a = 0: song finished, a = 1: song not finished
+AssertSongFinished: ; 378a (0:378a)
+	farcall _AssertSongFinished
 	ret
 
-Func_378f: ; 378f (0:378f)
-	farcall Func_f4012
+; return a = 0: SFX finished, a = 1: SFX not finished
+AssertSFXFinished: ; 378f (0:378f)
+	farcall _AssertSFXFinished
 	ret
 
 Func_3794: ; 3794 (0:3794)
@@ -9142,8 +9161,8 @@ GameEvent_BattleCenter: ; 38a3 (0:38a3)
 	ld [wd0c2], a
 	xor a
 	ld [wd112], a
-	ld a, $ff
-	ld [wd0c3], a
+	ld a, -1
+	ld [wDuelResult], a
 	ld a, $2
 	ld [wDuelTheme], a
 	ld a, MUSIC_CARD_POP
@@ -9308,6 +9327,7 @@ Func_39a7: ; 39a7 (0:39a7)
 	call Func_39ad
 	ret
 
+; return hl = wd34a + a * $c + l, a < $8
 Func_39ad: ; 39ad (0:39ad)
 	push bc
 	cp $8
@@ -9377,7 +9397,7 @@ Func_39ea: ; 39ea (0:39ea)
 Func_39fc: ; 39fc (0:39fc)
 	push hl
 	push bc
-	call Func_378a
+	call AssertSongFinished
 	or a
 	push af
 	call Func_3a1f
@@ -9788,7 +9808,7 @@ Func_3c87: ; 3c87 (0:3c87)
 
 Func_3c96: ; 3c96 (0:3c96)
 	call DoFrameIfLCDEnabled
-	call Func_378a
+	call AssertSongFinished
 	or a
 	jr nz, Func_3c96
 	ret
diff --git a/src/wram.asm b/src/wram.asm
index b100a57..345ba49 100644
--- a/src/wram.asm
+++ b/src/wram.asm
@@ -135,7 +135,7 @@ wPlayerNumberOfCardsInHand:: ; c2ee
 	ds $1
 
 ; Pokemon cards in arena + bench
-wPlayerNumberOfPokemonInPlay:: ; c2ef
+wPlayerNumberOfPokemonInPlayArea:: ; c2ef
 	ds $1
 
 wPlayerArenaCardStatus:: ; c2f0
@@ -242,7 +242,7 @@ wOpponentNumberOfCardsInDiscardPile:: ; c3ed
 wOpponentNumberOfCardsInHand:: ; c3ee
 	ds $1
 
-wOpponentNumberOfPokemonInPlay:: ; c3ef
+wOpponentNumberOfPokemonInPlayArea:: ; c3ef
 	ds $1
 
 wOpponentArenaCardStatus:: ; c3f0
@@ -251,6 +251,7 @@ wOpponentArenaCardStatus:: ; c3f0
 ; $00   - player
 ; $01   - link
 ; other - AI controlled
+; this is equal to wDuelType
 wOpponentDuelistType:: ; c3f1
 	ds $1
 
@@ -554,7 +555,9 @@ wcbe1:: ; cbe1
 wcbe2:: ; cbe2
 	ds $3
 
-wcbe5:: ; cbe5
+; sp is saved here when starting a duel, in order to save the return address
+; however, it only seems to be read after a transmission error in a link duel
+wDuelReturnAddress:: ; cbe5
 	ds $2
 
 wcbe7:: ; cbe7
@@ -582,17 +585,20 @@ wcc05:: ; cc05
 wDuelTurns:: ; cc06
 	ds $1
 
+; used to signal that the current duel has finished, not to be mistaken with wDuelResult
 ; 0 = no one has won duel yet
 ; 1 = player whose turn it is has won the duel
 ; 2 = player whose turn it is has lost the duel
-; 3 = duel ended in a draw
+; 3 = duel ended in a draw (start sudden death match)
 wDuelFinished:: ; cc07
 	ds $1
 
-wcc08:: ; cc08
+; current duel is a [wDuelInitialPrizes]-prize match
+wDuelInitialPrizes:: ; cc08
 	ds $1
 
-wcc09:: ; cc09
+; note that for a practice duel, wIsPracticeDuel must also be set to $1
+wDuelType:: ; cc09
 	ds $1
 
 wcc0a:: ; cc0a
@@ -638,9 +644,11 @@ wOpponentPortrait:: ; cc15
 wOpponentName:: ; cc16
 	ds $2
 
+; an overworld script starting a duel sets this address to the value to be written into wDuelInitialPrizes
 wcc18:: ; cc18
 	ds $1
 
+; an overworld script starting a duel sets this address to the value to be written into wOpponentDeckID
 wcc19:: ; cc19
 	ds $1
 
@@ -1196,7 +1204,8 @@ wd0c1:: ; d0c1
 wd0c2:: ; d0c2
 	ds $1
 
-wd0c3:: ; d0c3
+; stores the result of a duel (0: lost, 1: won, -1: transmission error (?) ) to be read by the overworld caller
+wDuelResult:: ; d0c3
 	ds $1
 
 wd0c4:: ; d0c4