Merge branch 'master' of https://github.com/YamaArashi/pokered

audio.asm

@@ -364,10 +364,10 @@ SECTION "Audio Engine 1", ROMX, BANK[AUDIO_1]
 
 PlayBattleMusic:: ; 0x90c6
 	xor a
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
 	ld [wLowHealthAlarm], a
 	dec a
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound ; stop music
 	call DelayFrame
 	ld c, BANK(Music_GymLeaderBattle)
@@ -406,7 +406,7 @@ Music_RivalAlternateStart:: ; 0x9b47
 	ld c, BANK(Music_MeetRival)
 	ld a, MUSIC_MEET_RIVAL
 	call PlayMusic
-	ld hl, wc006
+	ld hl, wChannelCommandPointers
 	ld de, Music_MeetRival_branch_b1a2
 	call Audio1_OverwriteChannelPointer
 	ld de, Music_MeetRival_branch_b21d
@@ -425,30 +425,30 @@ Music_RivalAlternateTempo:: ; 0x9b65
 	ld c, BANK(Music_MeetRival)
 	ld a, MUSIC_MEET_RIVAL
 	call PlayMusic
-	ld hl, wc006
+	ld hl, wChannelCommandPointers
 	ld de, Music_MeetRival_branch_b119
 	jp Audio1_OverwriteChannelPointer
 
 ; applies both the alternate start and alternate tempo
 Music_RivalAlternateStartAndTempo:: ; 0x9b75
 	call Music_RivalAlternateStart
-	ld hl, wc006
+	ld hl, wChannelCommandPointers
 	ld de, Music_MeetRival_branch_b19b
 	jp Audio1_OverwriteChannelPointer
 
 ; an alternate tempo for Cities1 which is used for the Hall of Fame room
 Music_Cities1AlternateTempo:: ; 0x9b81
-	ld a, $a
+	ld a, 10
-	ld [wcfc8], a
+	ld [wAudioFadeOutCounterReloadValue], a
-	ld [wcfc9], a
+	ld [wAudioFadeOutCounter], a
-	ld a, $ff
+	ld a, $ff ; stop playing music after the fade-out is finished
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
 	ld c, 100
-	call DelayFrames
+	call DelayFrames ; wait for the fade-out to finish
 	ld c, BANK(Music_Cities1)
 	ld a, MUSIC_CITIES1
 	call PlayMusic
-	ld hl, wc006
+	ld hl, wChannelCommandPointers
 	ld de, Music_Cities1_branch_aa6f
 	jp Audio1_OverwriteChannelPointer
 
@@ -477,7 +477,7 @@ Music_DoLowHealthAlarm:: ; 2136e (8:536e)
 
 .asm_2138a
 	ld a, $86
-	ld [wc02a], a ;disable sound channel?
+	ld [wChannelSoundIDs + CH4], a ;disable sound channel?
 	ld a, [wLowHealthAlarm]
 	and $7f ;decrement alarm timer.
 	dec a
@@ -491,7 +491,7 @@ Music_DoLowHealthAlarm:: ; 2136e (8:536e)
 .disableAlarm
 	xor a
 	ld [wLowHealthAlarm], a  ;disable alarm
-	ld [wc02a], a  ;re-enable sound channel?
+	ld [wChannelSoundIDs + CH4], a  ;re-enable sound channel?
 	ld de, .toneDataSilence
 	jr .playTone
 
@@ -542,7 +542,7 @@ Music_PokeFluteInBattle:: ; 22306 (8:6306)
 	ld a, SFX_CAUGHT_MON
 	call PlaySoundWaitForCurrent
 	; then immediately overwrtie the channel pointers
-	ld hl, wc00e
+	ld hl, wChannelCommandPointers + CH4 * 2
 	ld de, SFX_08_PokeFlute_Ch1
 	call Audio2_OverwriteChannelPointer
 	ld de, SFX_08_PokeFlute_Ch2
@@ -572,7 +572,7 @@ PlayPokedexRatingSfx:: ; 7d13b (1f:513b)
 .gotSfxPointer
 	push bc
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySoundWaitForCurrent
 	pop bc
 	ld b, $0

constants/hardware_constants.asm

@@ -107,4 +107,3 @@ rUNKNOWN5   EQU $ff75 ; (8Fh) - Bit 4-6 (Read/Write)
 rUNKNOWN6   EQU $ff76 ; (00h) - Always 00h (Read Only)
 rUNKNOWN7   EQU $ff77 ; (00h) - Always 00h (Read Only)
 rIE         EQU $ffff ; Interrupt Enable (R/W)
-

constants/music_constants.asm

@@ -1,3 +1,42 @@
+; HW sound channel register base addresses
+HW_CH1_BASE EQU (rNR10 % $100)
+HW_CH2_BASE EQU ((rNR21 % $100) - 1)
+HW_CH3_BASE EQU (rNR30 % $100)
+HW_CH4_BASE EQU ((rNR41 % $100) - 1)
+
+; HW sound channel enable bit masks
+HW_CH1_ENABLE_MASK EQU %00010001
+HW_CH2_ENABLE_MASK EQU %00100010
+HW_CH3_ENABLE_MASK EQU %01000100
+HW_CH4_ENABLE_MASK EQU %10001000
+
+; HW sound channel disable bit masks
+HW_CH1_DISABLE_MASK EQU (~HW_CH1_ENABLE_MASK & $ff)
+HW_CH2_DISABLE_MASK EQU (~HW_CH2_ENABLE_MASK & $ff)
+HW_CH3_DISABLE_MASK EQU (~HW_CH3_ENABLE_MASK & $ff)
+HW_CH4_DISABLE_MASK EQU (~HW_CH4_ENABLE_MASK & $ff)
+
+REG_DUTY_SOUND_LEN  EQU 1
+REG_VOLUME_ENVELOPE EQU 2
+REG_FREQUENCY_LO    EQU 3
+
+MAX_SFX_ID EQU $B9
+
+CRY_SFX_START EQU $14
+CRY_SFX_END   EQU $86
+
+; wChannelFlags1 constants
+BIT_PERFECT_PITCH         EQU 0 ; controlled by toggleperfectpitch command
+BIT_CHANNEL_CALL          EQU 1 ; if in channel call
+BIT_NOISE_OR_SFX          EQU 2 ; if channel is the music noise channel or an SFX channel
+BIT_VIBRATO_DIRECTION     EQU 3 ; if the pitch is above or below normal (cycles)
+BIT_PITCH_BEND_ON         EQU 4 ; if pitch bend is active
+BIT_PITCH_BEND_DECREASING EQU 5 ; if the pitch bend frequency is decreasing (instead of increasing)
+BIT_ROTATE_DUTY           EQU 6 ; if rotating duty
+
+; wChannelFlags2 constant (only has one flag)
+BIT_EXECUTE_MUSIC EQU 0 ; if in execute music
+
 ; Song ids are calculated by address to save space.
 
 music_const: MACRO

engine/battle/animations.asm

@@ -772,7 +772,7 @@ DoBallTossSpecialEffects: ; 78f3e (1e:4f3e)
 	dec b
 	jr nz,.loop
 	ld a,%00001000
-	ld [$ff10],a ; Channel 1 sweep register
+	ld [rNR10],a ; Channel 1 sweep register
 	ret
 .isTrainerBattle ; if it's a trainer battle, shorten the animation by one frame
 	ld a,[W_SUBANIMCOUNTER]
@@ -2335,19 +2335,19 @@ GetMoveSound: ; 7986f (1e:586f)
 	call GetCryData
 	ld b,a
 	pop hl
-	ld a,[wc0f1]
+	ld a,[wFrequencyModifier]
 	add [hl]
-	ld [wc0f1],a
+	ld [wFrequencyModifier],a
 	inc hl
-	ld a,[wc0f2]
+	ld a,[wTempoModifier]
 	add [hl]
-	ld [wc0f2],a
+	ld [wTempoModifier],a
 	jr .done
 .NotCryMove
 	ld a,[hli]
-	ld [wc0f1],a
+	ld [wFrequencyModifier],a
 	ld a,[hli]
-	ld [wc0f2],a
+	ld [wTempoModifier],a
 .done
 	ld a,b
 	ret
@@ -2956,7 +2956,7 @@ TossBallAnimation: ; 79e16 (1e:5e16)
 	ld a,[W_ISINBATTLE]
 	cp a,2
 	jr z,.BlockBall ; if in trainer battle, play different animation
-	ld a,[wd11e]
+	ld a,[wPokeBallAnimData]
 	ld b,a
 
 	; upper nybble: how many animations (from PokeBallAnimations) to play
@@ -3029,8 +3029,8 @@ PlayApplyingAttackSound: ; 79e6a (1e:5e6a)
 	ld b, $1
 	ld c, SFX_NOT_VERY_EFFECTIVE
 .playSound
-	ld [wc0f1], a
+	ld [wFrequencyModifier], a
 	ld a, b
-	ld [wc0f2], a
+	ld [wTempoModifier], a
 	ld a, c
 	jp PlaySound

engine/battle/bank_e_misc.asm

@@ -92,9 +92,9 @@ InitList: ; 39bd5 (e:5bd5)
 	ld a, h
 	ld [wListPointer + 1], a
 	ld a, e
-	ld [wcf8d], a
+	ld [wUnusedCF8D], a
 	ld a, d
-	ld [wcf8e], a
+	ld [wUnusedCF8D + 1], a
 	ld bc, ItemPrices
 	ld a, c
 	ld [wItemPrices], a

engine/battle/common_text.asm

@@ -61,9 +61,9 @@ PrintBeginningBattleText: ; 58d99 (16:4d99)
 
 .playSFX
 	xor a
-	ld [wc0f1], a
+	ld [wFrequencyModifier], a
 	ld a, $80
-	ld [wc0f2], a
+	ld [wTempoModifier], a
 	ld a, SFX_SILPH_SCOPE
 	call PlaySound
 	jp WaitForSoundToFinish

engine/battle/core.asm

@@ -834,8 +834,17 @@ FaintEnemyPokemon: ; 0x3c567
 .wild
 	ld hl, W_PLAYERBATTSTATUS1
 	res AttackingMultipleTimes, [hl]
+; Bug. This only zeroes the high byte of the player's accumulated damage,
+; setting the accumulated damage to itself mod 256 instead of 0 as was probably
+; intended. That alone is problematic, but this mistake has another more severe
+; effect. This function's counterpart for when the player mon faints,
+; RemoveFaintedPlayerMon, zeroes both the high byte and the low byte. In a link
+; battle, the other player's Game Boy will call that function in response to
+; the enemy mon (the player mon from the other side's perspective) fainting,
+; and the states of the two Game Boys will go out of sync unless the damage
+; was congruent to 0 modulo 256.
 	xor a
-	ld [wPlayerNumHits], a
+	ld [wPlayerBideAccumulatedDamage], a
 	ld hl, wEnemyStatsToDouble ; clear enemy statuses
 	ld [hli], a
 	ld [hli], a
@@ -858,12 +867,12 @@ FaintEnemyPokemon: ; 0x3c567
 	dec a
 	jr z, .wild_win
 	xor a
-	ld [wc0f1], a
+	ld [wFrequencyModifier], a
-	ld [wc0f2], a
+	ld [wTempoModifier], a
 	ld a, SFX_FAINT_FALL
 	call PlaySoundWaitForCurrent
 .sfxwait
-	ld a, [wc02a]
+	ld a, [wChannelSoundIDs + CH4]
 	cp SFX_FAINT_FALL
 	jr z, .sfxwait
 	ld a, SFX_FAINT_THUD
@@ -943,7 +952,7 @@ EnemyMonFaintedText: ; 0x3c63e
 EndLowHealthAlarm: ; 3c643 (f:4643)
 	xor a
 	ld [wLowHealthAlarm], a ;disable low health alarm
-	ld [wc02a], a
+	ld [wChannelSoundIDs + CH4], a
 	inc a
 	ld [wccf6], a
 	ret
@@ -1036,7 +1045,7 @@ TrainerDefeatedText: ; 3c6e9 (f:46e9)
 PlayBattleVictoryMusic: ; 3c6ee (f:46ee)
 	push af
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySoundWaitForCurrent
 	ld c, BANK(Music_DefeatedTrainer)
 	pop af
@@ -1092,8 +1101,7 @@ RemoveFaintedPlayerMon: ; 3c741 (f:4741)
 	ld [wLowHealthAlarm], a ;disable low health alarm
 	call WaitForSoundToFinish
 .skipWaitForSound
-; bug? if the player mon faints while the enemy mon is using bide,
+; a is 0, so this zeroes the enemy's accumulated damage.
-; the accumulated damage is overwritten. xxx what values can [wLowHealthAlarm] have here?
 	ld hl, wEnemyBideAccumulatedDamage
 	ld [hli], a
 	ld [hl], a
@@ -1936,7 +1944,7 @@ DrawPlayerHUDAndHPBar: ; 3cd60 (f:4d60)
 	ld [hl], $0
 	ret z
 	xor a
-	ld [wc02a], a
+	ld [wChannelSoundIDs + CH4], a
 	ret
 .asm_3cde6
 	ld hl, wLowHealthAlarm
@@ -2954,7 +2962,7 @@ PrintMenuItem: ; 3d4b6 (f:54b6)
 	lb bc, 1, 2
 	call PrintNumber
 	coord hl, 8, 11
-	ld de, wd11e
+	ld de, wMaxPP
 	lb bc, 1, 2
 	call PrintNumber
 	call GetCurrentMove
@@ -5279,7 +5287,7 @@ AdjustDamageForMoveType: ; 3e3a5 (f:63a5)
 	ld d,a    ; d = type 1 of defender
 	ld e,[hl] ; e = type 2 of defender
 	ld a,[W_PLAYERMOVETYPE]
-	ld [wd11e],a
+	ld [wMoveType],a
 	ld a,[H_WHOSETURN]
 	and a
 	jr z,.next
@@ -5293,9 +5301,9 @@ AdjustDamageForMoveType: ; 3e3a5 (f:63a5)
 	ld d,a    ; d = type 1 of defender
 	ld e,[hl] ; e = type 2 of defender
 	ld a,[W_ENEMYMOVETYPE]
-	ld [wd11e],a
+	ld [wMoveType],a
 .next
-	ld a,[wd11e] ; move type
+	ld a,[wMoveType]
 	cp b ; does the move type match type 1 of the attacker?
 	jr z,.sameTypeAttackBonus
 	cp c ; does the move type match type 2 of the attacker?
@@ -5320,8 +5328,8 @@ AdjustDamageForMoveType: ; 3e3a5 (f:63a5)
 	ld hl,wDamageMultipliers
 	set 7,[hl]
 .skipSameTypeAttackBonus
-	ld a,[wd11e]
+	ld a,[wMoveType]
-	ld b,a ; b = move type
+	ld b,a
 	ld hl,TypeEffects
 .loop
 	ld a,[hli] ; a = "attacking type" of the current type pair
@@ -5384,29 +5392,29 @@ AdjustDamageForMoveType: ; 3e3a5 (f:63a5)
 ; function to tell how effective the type of an enemy attack is on the player's current pokemon
 ; this doesn't take into account the effects that dual types can have
 ; (e.g. 4x weakness / resistance, weaknesses and resistances canceling)
-; the result is stored in [wd11e]
+; the result is stored in [wTypeEffectiveness]
 ; ($05 is not very effective, $10 is neutral, $14 is super effective)
 ; as far is can tell, this is only used once in some AI code to help decide which move to use
 AIGetTypeEffectiveness: ; 3e449 (f:6449)
 	ld a,[W_ENEMYMOVETYPE]
-	ld d,a                 ; d = type of enemy move
+	ld d,a                    ; d = type of enemy move
 	ld hl,wBattleMonType
-	ld b,[hl]              ; b = type 1 of player's pokemon
+	ld b,[hl]                 ; b = type 1 of player's pokemon
 	inc hl
-	ld c,[hl]              ; c = type 2 of player's pokemon
+	ld c,[hl]                 ; c = type 2 of player's pokemon
 	ld a,$10
-	ld [wd11e],a           ; initialize [wd11e] to neutral effectiveness
+	ld [wTypeEffectiveness],a ; initialize to neutral effectiveness
 	ld hl,TypeEffects
 .loop
 	ld a,[hli]
 	cp a,$ff
 	ret z
-	cp d                   ; match the type of the move
+	cp d                      ; match the type of the move
 	jr nz,.nextTypePair1
 	ld a,[hli]
-	cp b                   ; match with type 1 of pokemon
+	cp b                      ; match with type 1 of pokemon
 	jr z,.done
-	cp c                   ; or match with type 2 of pokemon
+	cp c                      ; or match with type 2 of pokemon
 	jr z,.done
 	jr .nextTypePair2
 .nextTypePair1
@@ -5416,7 +5424,7 @@ AIGetTypeEffectiveness: ; 3e449 (f:6449)
 	jr .loop
 .done
 	ld a,[hl]
-	ld [wd11e],a           ; store damage multiplier
+	ld [wTypeEffectiveness],a ; store damage multiplier
 	ret
 
 INCLUDE "data/type_effects.asm"
@@ -6569,12 +6577,12 @@ CalculateModifiedStats: ; 3ed99 (f:6d99)
 CalculateModifiedStat: ; 3eda5 (f:6da5)
 	push bc
 	push bc
-	ld a, [wd11e]
+	ld a, [wCalculateWhoseStats]
 	and a
 	ld a, c
 	ld hl, wBattleMonAttack
 	ld de, wPlayerMonUnmodifiedAttack
-	ld bc, wPlayerMonAttackMod
+	ld bc, wPlayerMonStatMods
 	jr z, .next
 	ld hl, wEnemyMonAttack
 	ld de, wEnemyMonUnmodifiedAttack
@@ -6985,8 +6993,8 @@ _LoadTrainerPic: ; 3f04b (f:704b)
 ; unreferenced
 ResetCryModifiers: ; 3f069 (f:7069)
 	xor a
-	ld [wc0f1], a
+	ld [wFrequencyModifier], a
-	ld [wc0f2], a
+	ld [wTempoModifier], a
 	jp PlaySound
 
 ; animates the mon "growing" out of the pokeball

engine/battle/end_of_battle.asm

@@ -46,7 +46,7 @@ EndOfBattle: ; 137aa (4:77aa)
 .resetVariables
 	xor a
 	ld [wLowHealthAlarm], a ;disable low health alarm
-	ld [wc02a], a
+	ld [wChannelSoundIDs + CH4], a
 	ld [W_ISINBATTLE], a
 	ld [W_BATTLETYPE], a
 	ld [W_MOVEMISSED], a

engine/battle/experience.asm

@@ -231,8 +231,8 @@ GainExperience: ; 5524f (15:524f)
 	ld bc, 1 + NUM_STATS * 2
 	call CopyData
 .recalcStatChanges
-	xor a
+	xor a ; battle mon
-	ld [wd11e], a
+	ld [wCalculateWhoseStats], a
 	callab CalculateModifiedStats
 	callab ApplyBurnAndParalysisPenaltiesToPlayer
 	callab ApplyBadgeStatBoosts

engine/battle/trainer_ai.asm

@@ -191,7 +191,7 @@ AIMoveChoiceModification2: ; 397e7 (e:57e7)
 AIMoveChoiceModification3: ; 39817 (e:5817)
 	ld hl, wBuffer - 1 ; temp move selection array (-1 byte offset)
 	ld de, wEnemyMonMoves ; enemy moves
-	ld b, $5
+	ld b, NUM_MOVES + 1
 .nextMove
 	dec b
 	ret z ; processed all 4 moves
@@ -208,7 +208,7 @@ AIMoveChoiceModification3: ; 39817 (e:5817)
 	pop de
 	pop bc
 	pop hl
-	ld a, [wd11e]
+	ld a, [wTypeEffectiveness]
 	cp $10
 	jr z, .nextMove
 	jr c, .notEffectiveMove

engine/cable_club.asm

@@ -256,9 +256,9 @@ CableClub_DoBattleOrTradeAgain: ; 5345
 	dec c
 	jr nz, .unpatchEnemyMonsLoop
 	ld a, wEnemyMonOT % $100
-	ld [wcf8d], a
+	ld [wUnusedCF8D], a
 	ld a, wEnemyMonOT / $100
-	ld [wcf8e], a
+	ld [wUnusedCF8D + 1], a
 	xor a
 	ld [wTradeCenterPointerTableIndex], a
 	ld a, $ff
@@ -824,12 +824,12 @@ TradeCenter_Trade:
 	add hl, bc
 	ld a, [hl]
 	ld [wTradedEnemyMonSpecies], a
-	ld a, $a
+	ld a, 10
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
 	ld a, $2
-	ld [wc0f0], a
+	ld [wAudioSavedROMBank], a
 	ld a, MUSIC_SAFARI_ZONE
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld c, 100
 	call DelayFrames
@@ -915,12 +915,12 @@ CableClub_Run: ; 5a5f (1:5a5f)
 	inc a ; LINK_STATE_IN_CABLE_CLUB
 	ld [wLinkState], a
 	ld [$ffb5], a
-	ld a, $a
+	ld a, 10
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
 	ld a, BANK(Music_Celadon)
-	ld [wc0f0], a
+	ld [wAudioSavedROMBank], a
 	ld a, MUSIC_CELADON
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	jp PlaySound
 
 EmptyFunc3: ; 5aaf (1:5aaf)

engine/evolution.asm

@@ -8,9 +8,9 @@ EvolveMon: ; 7bde9 (1e:7de9)
 	push af
 	xor a
 	ld [wLowHealthAlarm], a
-	ld [wc02a], a
+	ld [wChannelSoundIDs + CH4], a
 	dec a
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld a, $1
 	ld [H_AUTOBGTRANSFERENABLED], a
@@ -68,7 +68,7 @@ EvolveMon: ; 7bde9 (1e:7de9)
 .done
 	ld [wcf1d], a
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld a, [wcf1d]
 	call PlayCry

engine/evos_moves.asm

@@ -166,7 +166,7 @@ Evolution_PartyMonLoop: ; loop over party mons
 	ld de, W_MONHEADER
 	call CopyData
 	ld a, [wd0b5]
-	ld [W_MONHDEXNUM], a
+	ld [W_MONHINDEX], a
 	pop af
 	ld [wd11e], a
 	ld hl, wLoadedMonHPExp - 1
@@ -257,12 +257,12 @@ Evolution_PartyMonLoop: ; loop over party mons
 	call nz, PlayDefaultMusic
 	ret
 
-; checks if the evolved mon's name is different from the standard name (i.e. it has a nickname)
-; if so, rename it to is evolved form's standard name
 RenameEvolvedMon: ; 3aef7 (e:6ef7)
+; Renames the mon to its new, evolved form's standard name unless it had a
+; nickname, in which case the nickname is kept.
 	ld a, [wd0b5]
 	push af
-	ld a, [W_MONHDEXNUM]
+	ld a, [W_MONHINDEX]
 	ld [wd0b5], a
 	call GetName
 	pop af
@@ -275,7 +275,7 @@ RenameEvolvedMon: ; 3aef7 (e:6ef7)
 	cp [hl]
 	inc hl
 	ret nz
-	cp $50
+	cp "@"
 	jr nz, .compareNamesLoop
 	ld a, [wWhichPokemon]
 	ld bc, 11

engine/hall_of_fame.asm

@@ -280,9 +280,9 @@ HoFRecordMonInfo: ; 70404 (1c:4404)
 	jp CopyData
 
 HoFFadeOutScreenAndMusic: ; 70423 (1c:4423)
-	ld a, $a
+	ld a, 10
-	ld [wcfc8], a
+	ld [wAudioFadeOutCounterReloadValue], a
-	ld [wcfc9], a
+	ld [wAudioFadeOutCounter], a
 	ld a, $ff
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
 	jp GBFadeOutToWhite

engine/hidden_object_functions14.asm

@@ -2,7 +2,7 @@ PrintNotebookText: ; 52996 (14:6996)
 	call EnableAutoTextBoxDrawing
 	ld a, $1
 	ld [wDoNotWaitForButtonPressAfterDisplayingText], a
-	ld a, [wTrainerSpriteOffset]
+	ld a, [wHiddenObjectFunctionArgument]
 	jp PrintPredefTextID
 
 TMNotebook: ; 529a4 (14:69a4)

engine/hidden_object_functions7.asm

@@ -19,8 +19,8 @@ DisplayOakLabRightPoster: ; 1e965 (7:6965)
 	ld hl, wPokedexOwned
 	ld b, wPokedexOwnedEnd - wPokedexOwned
 	call CountSetBits
-	ld a, [wd11e]
+	ld a, [wNumSetBits]
-	cp $2
+	cp 2
 	tx_pre_id SaveOptionText
 	jr c, .ownThreeOrMoreMon
 	tx_pre_id StrengthsAndWeaknessesText
@@ -63,14 +63,14 @@ SafariZoneGameStillGoing: ; 1e9ab (7:69ab)
 SafariZoneGameOver: ; 1e9b0 (7:69b0)
 	call EnableAutoTextBoxDrawing
 	xor a
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
 	dec a
 	call PlaySound
 	ld c, BANK(SFX_Safari_Zone_PA)
 	ld a, SFX_SAFARI_ZONE_PA
 	call PlayMusic
 .asm_1e9c2
-	ld a, [wc02a]
+	ld a, [wChannelSoundIDs + CH4]
 	cp $b9
 	jr nz, .asm_1e9c2
 	ld a, TEXT_SAFARI_GAME_OVER
@@ -374,7 +374,7 @@ BillsHouseInitiatedText: ; 1ebe2 (7:6be2)
 	db $06
 	TX_ASM
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld c, 16
 	call DelayFrames

engine/intro.asm

@@ -325,10 +325,10 @@ PlayShootingStar: ; 4188a (10:588a)
 	call DelayFrames
 .next
 	ld a, BANK(Music_IntroBattle)
-	ld [wc0ef], a
+	ld [wAudioROMBank], a
-	ld [wc0f0], a
+	ld [wAudioSavedROMBank], a
 	ld a, MUSIC_INTRO_BATTLE
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	call IntroClearMiddleOfScreen
 	call ClearSprites

engine/items/items.asm

@@ -312,7 +312,7 @@ ItemUseBall: ; d687 (3:5687)
 	ld b,$63
 .next12
 	ld a,b
-	ld [wd11e],a
+	ld [wPokeBallAnimData],a
 .BallSuccess2
 	ld c,20
 	call DelayFrames
@@ -331,7 +331,7 @@ ItemUseBall: ; d687 (3:5687)
 	ld [wcf91],a
 	pop af
 	ld [wWhichPokemon],a
-	ld a,[wd11e]
+	ld a,[wPokeBallAnimData]
 	cp a,$10
 	ld hl,ItemUseBallText00
 	jp z,.printText0
@@ -856,7 +856,7 @@ ItemUseMedicine: ; dabb (3:5abb)
 .notFullHP ; if the pokemon's current HP doesn't equal its max HP
 	xor a
 	ld [wLowHealthAlarm],a ;disable low health alarm
-	ld [wc02a],a
+	ld [wChannelSoundIDs + CH4],a
 	push hl
 	push de
 	ld bc,32
@@ -1643,7 +1643,7 @@ ItemUsePokeflute: ; e140 (3:6140)
 	call WaitForSoundToFinish ; wait for sound to end
 	callba Music_PokeFluteInBattle ; play in-battle pokeflute music
 .musicWaitLoop ; wait for music to finish playing
-	ld a,[wc02c]
+	ld a,[wChannelSoundIDs + CH6]
 	and a ; music off?
 	jr nz,.musicWaitLoop
 .skipMusic
@@ -1716,8 +1716,8 @@ PlayedFluteHadEffectText: ; e215 (3:6215)
 	ld c, BANK(SFX_Pokeflute)
 	call PlayMusic
 .musicWaitLoop ; wait for music to finish playing
-	ld a,[wc028]
+	ld a,[wChannelSoundIDs + CH2]
-	cp a,$b8
+	cp a, SFX_POKEFLUE
 	jr z,.musicWaitLoop
 	call PlayDefaultMusic ; start playing normal music again
 .done
@@ -1895,7 +1895,7 @@ ItemUsePPRestore: ; e31e (3:631e)
 	ld [wPlayerMoveListIndex],a
 	jr nz,.chooseMon
 	ld hl,wPartyMon1Moves
-	ld bc,44
+	ld bc, wPartyMon2 - wPartyMon1
 	call GetSelectedMoveOffset
 	push hl
 	ld a,[hl]
@@ -1937,7 +1937,7 @@ ItemUsePPRestore: ; e31e (3:631e)
 	cp b ; is the pokemon whose PP was restored active in battle?
 	jr nz,.skipUpdatingInBattleData
 	ld hl,wPartyMon1PP
-	ld bc,wPartyMon2 - wPartyMon1
+	ld bc, wPartyMon2 - wPartyMon1
 	call AddNTimes
 	ld de,wBattleMonPP
 	ld bc,4
@@ -1959,12 +1959,12 @@ ItemUsePPRestore: ; e31e (3:631e)
 	ld [wMonDataLocation],a
 	call GetMaxPP
 	ld hl,wPartyMon1Moves
-	ld bc,44
+	ld bc, wPartyMon2 - wPartyMon1
 	call GetSelectedMoveOffset
-	ld bc,21
+	ld bc, wPartyMon1PP - wPartyMon1Moves
 	add hl,bc ; hl now points to move's PP
-	ld a,[wd11e]
+	ld a,[wMaxPP]
-	ld b,a ; b = max PP
+	ld b,a
 	ld a,[wPPRestoreItem]
 	cp a,MAX_ETHER
 	jr z,.fullyRestorePP
@@ -2009,7 +2009,7 @@ ItemUsePPRestore: ; e31e (3:631e)
 .elixirLoop
 	push bc
 	ld hl,wPartyMon1Moves
-	ld bc,44
+	ld bc, wPartyMon2 - wPartyMon1
 	call GetSelectedMoveOffset
 	ld a,[hl]
 	and a ; does the current slot have a move?
@@ -2283,20 +2283,17 @@ GotOffBicycleText: ; e5fc (3:65fc)
 ; also, when a PP Up is used, it increases the current PP by one PP Up bonus
 ; INPUT:
 ; [wWhichPokemon] = index of pokemon in party
-; [wd11e] = mode
-; 0: Pokemon Center healing
-; 1: using a PP Up
 ; [wCurrentMenuItem] = index of move (when using a PP Up)
 RestoreBonusPP: ; e606 (3:6606)
 	ld hl,wPartyMon1Moves
-	ld bc,wPartyMon2 - wPartyMon1
+	ld bc, wPartyMon2 - wPartyMon1
 	ld a,[wWhichPokemon]
 	call AddNTimes
 	push hl
 	ld de,wNormalMaxPPList - 1
 	predef LoadMovePPs ; loads the normal max PP of each of the pokemon's moves to wNormalMaxPPList
 	pop hl
-	ld c,21
+	ld c, wPartyMon1PP - wPartyMon1Moves
 	ld b,0
 	add hl,bc ; hl now points to move 1 PP
 	ld de,wNormalMaxPPList
@@ -2307,7 +2304,7 @@ RestoreBonusPP: ; e606 (3:6606)
 	ld a,b
 	cp a,5 ; reached the end of the pokemon's moves?
 	ret z ; if so, return
-	ld a,[wd11e]
+	ld a,[wUsingPPUp]
 	dec a ; using a PP Up?
 	jr nz,.skipMenuItemIDCheck
 ; if using a PP Up, check if this is the move it's being used on
@@ -2329,8 +2326,6 @@ RestoreBonusPP: ; e606 (3:6606)
 ; INPUT:
 ; [de] = normal max PP
 ; [hl] = move PP
-; [wd11e] = max number of times to add bonus
-; set to 1 when using a PP Up, set to 255 otherwise
 AddBonusPP: ; e642 (3:6642)
 	push bc
 	ld a,[de] ; normal max PP of move
@@ -2358,9 +2353,9 @@ AddBonusPP: ; e642 (3:6642)
 .addAmount
 	add b
 	ld b,a
-	ld a,[wd11e]
+	ld a,[wUsingPPUp]
-	dec a
+	dec a ; is the player using a PP Up right now?
-	jr z,.done
+	jr z,.done ; if so, only add the bonus once
 	dec c
 	jr nz,.loop
 .done
@@ -2379,7 +2374,7 @@ AddBonusPP: ; e642 (3:6642)
 ; 04: player's in-battle pokemon
 ; [wCurrentMenuItem] = move index
 ; OUTPUT:
-; [wd11e] = max PP
+; [wMaxPP] = max PP
 GetMaxPP: ; e677 (3:6677)
 	ld a,[wMonDataLocation]
 	and a
@@ -2432,12 +2427,12 @@ GetMaxPP: ; e677 (3:6677)
 	ld l,e
 	inc hl ; hl = wcd73
 	ld [hl],a
-	xor a
+	xor a ; add the bonus for the existing PP Up count
-	ld [wd11e],a ; no limit on PP Up amount
+	ld [wUsingPPUp],a
 	call AddBonusPP ; add bonus PP from PP Ups
 	ld a,[hl]
 	and a,%00111111 ; mask out the PP Up count
-	ld [wd11e],a ; store max PP
+	ld [wMaxPP],a ; store max PP
 	ret
 
 GetSelectedMoveOffset: ; e6e3 (3:66e3)

engine/menu/main_menu.asm

@@ -395,7 +395,7 @@ PrintNumBadges: ; 5e2f (1:5e2f)
 	ld b, $1
 	call CountSetBits
 	pop hl
-	ld de, wd11e
+	ld de, wNumSetBits
 	lb bc, 1, 2
 	jp PrintNumber
 
@@ -405,7 +405,7 @@ PrintNumOwnedMons: ; 5e42 (1:5e42)
 	ld b, wPokedexOwnedEnd - wPokedexOwned
 	call CountSetBits
 	pop hl
-	ld de, wd11e
+	ld de, wNumSetBits
 	lb bc, 1, 3
 	jp PrintNumber
 

engine/menu/pokedex.asm

@@ -169,14 +169,14 @@ HandlePokedexListMenu: ; 40111 (10:4111)
 	ld hl,wPokedexSeen
 	ld b,wPokedexSeenEnd - wPokedexSeen
 	call CountSetBits
-	ld de,wd11e
+	ld de, wNumSetBits
 	coord hl, 16, 3
 	lb bc, 1, 3
 	call PrintNumber ; print number of seen pokemon
 	ld hl,wPokedexOwned
 	ld b,wPokedexOwnedEnd - wPokedexOwned
 	call CountSetBits
-	ld de,wd11e
+	ld de, wNumSetBits
 	coord hl, 16, 6
 	lb bc, 1, 3
 	call PrintNumber ; print number of owned pokemon
@@ -397,7 +397,7 @@ ShowPokedexDataInternal: ; 402e2 (10:42e2)
 	ld hl,wd72c
 	set 1,[hl]
 	ld a,$33 ; 3/7 volume
-	ld [$ff24],a
+	ld [rNR50],a
 	call GBPalWhiteOut ; zero all palettes
 	call ClearScreen
 	ld a,[wd11e] ; pokemon ID
@@ -566,7 +566,7 @@ ShowPokedexDataInternal: ; 402e2 (10:42e2)
 	ld hl,wd72c
 	res 1,[hl]
 	ld a,$77 ; max volume
-	ld [$ff24],a
+	ld [rNR50],a
 	ret
 
 HeightWeightText: ; 40448 (10:4448)

engine/menu/status_screen.asm

@@ -80,7 +80,7 @@ StatusScreen: ; 12953 (4:6953)
 	ld hl, wd72c
 	set 1, [hl]
 	ld a, $33
-	ld [$ff24], a ; Reduce the volume
+	ld [rNR50], a ; Reduce the volume
 	call GBPalWhiteOutWithDelay3
 	call ClearScreen
 	call UpdateSprites
@@ -138,7 +138,7 @@ StatusScreen: ; 12953 (4:6953)
 	call PlaceString ; "STATUS/"
 	coord hl, 14, 2
 	call PrintLevel ; Pokémon level
-	ld a, [W_MONHDEXNUM]
+	ld a, [W_MONHINDEX]
 	ld [wd11e], a
 	ld [wd0b5], a
 	predef IndexToPokedex
@@ -372,7 +372,7 @@ StatusScreen2: ; 12b57 (4:6b57)
 	call PrintNumber
 	ld a, "/"
 	ld [hli], a
-	ld de, wd11e
+	ld de, wMaxPP
 	lb bc, 1, 2
 	call PrintNumber
 	pop hl
@@ -417,7 +417,7 @@ StatusScreen2: ; 12b57 (4:6b57)
 	call StatusScreen_ClearName
 	coord hl, 9, 1
 	call StatusScreen_ClearName
-	ld a, [W_MONHDEXNUM]
+	ld a, [W_MONHINDEX]
 	ld [wd11e], a
 	call GetMonName
 	coord hl, 9, 1
@@ -431,7 +431,7 @@ StatusScreen2: ; 12b57 (4:6b57)
 	ld hl, wd72c
 	res 1, [hl]
 	ld a, $77
-	ld [$ff24], a
+	ld [rNR50], a
 	call GBPalWhiteOut
 	jp ClearScreen
 

engine/oak_speech.asm

@@ -129,12 +129,12 @@ OakSpeech: ; 6115 (1:6115)
 	ld a,[H_LOADEDROMBANK]
 	push af
 	ld a, BANK(Music_PalletTown)
-	ld [wc0ef],a
+	ld [wAudioROMBank],a
-	ld [wc0f0],a
+	ld [wAudioSavedROMBank],a
-	ld a,$A
+	ld a, 10
-	ld [wMusicHeaderPointer],a
+	ld [wAudioFadeOutControl],a
 	ld a,$FF
-	ld [wc0ee],a
+	ld [wNewSoundID],a
 	call PlaySound ; stop music
 	pop af
 	ld [H_LOADEDROMBANK],a

engine/overworld/elevator.asm

@@ -33,7 +33,7 @@ ShakeElevator: ; 7bf15 (1e:7f15)
 	ld a, SFX_SAFARI_ZONE_PA
 	call PlayMusic
 .musicLoop
-	ld a, [wc02a]
+	ld a, [wChannelSoundIDs + CH4]
 	cp $b9
 	jr z, .musicLoop
 	call UpdateSprites

engine/overworld/healing_machine.asm

@@ -15,44 +15,44 @@ AnimateHealingMachine: ; 70433 (1c:4433)
 	ld hl, wOAMBuffer + $84
 	ld de, PokeCenterOAMData
 	call CopyHealingMachineOAM
-	ld a, $4
+	ld a, 4
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
-.asm_70464
+.waitLoop
-	ld a, [wMusicHeaderPointer]
+	ld a, [wAudioFadeOutControl]
-	and a
+	and a ; is fade-out finished?
-	jr nz, .asm_70464
+	jr nz, .waitLoop ; if not, check again
 	ld a, [wPartyCount]
 	ld b, a
-.asm_7046e
+.partyLoop
 	call CopyHealingMachineOAM
 	ld a, SFX_HEALING_MACHINE
 	call PlaySound
 	ld c, 30
 	call DelayFrames
 	dec b
-	jr nz, .asm_7046e
+	jr nz, .partyLoop
-	ld a, [wc0ef]
+	ld a, [wAudioROMBank]
 	cp BANK(Audio3_UpdateMusic)
-	ld [wc0f0], a
+	ld [wAudioSavedROMBank], a
-	jr nz, .asm_70495
+	jr nz, .next
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld a, BANK(Music_PkmnHealed)
-	ld [wc0ef], a
+	ld [wAudioROMBank], a
-.asm_70495
+.next
 	ld a, MUSIC_PKMN_HEALED
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld d, $28
 	call FlashSprite8Times
-.asm_704a2
+.waitLoop2
-	ld a, [wc026]
+	ld a, [wChannelSoundIDs]
-	cp MUSIC_PKMN_HEALED
+	cp MUSIC_PKMN_HEALED ; is the healed music still playing?
-	jr z, .asm_704a2
+	jr z, .waitLoop2 ; if so, check gain
 	ld c, 32
 	call DelayFrames
 	pop af

engine/overworld/npc_movement.asm

@@ -163,10 +163,10 @@ PewterMuseumGuyMovementScriptPointerTable: ; 1a510 (6:6510)
 
 PewterMovementScript_WalkToMuseum: ; 1a514 (6:6514)
 	ld a, BANK(Music_MuseumGuy)
-	ld [wc0ef], a
+	ld [wAudioROMBank], a
-	ld [wc0f0], a
+	ld [wAudioSavedROMBank], a
 	ld a, MUSIC_MUSEUM_GUY
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld a, [wSpriteIndex]
 	swap a
@@ -219,10 +219,10 @@ PewterGymGuyMovementScriptPointerTable: ; 1a57d (6:657d)
 
 PewterMovementScript_WalkToGym: ; 1a581 (6:6581)
 	ld a, BANK(Music_MuseumGuy)
-	ld [wc0ef], a
+	ld [wAudioROMBank], a
-	ld [wc0f0], a
+	ld [wAudioSavedROMBank], a
 	ld a, MUSIC_MUSEUM_GUY
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld a, [wSpriteIndex]
 	swap a

engine/overworld/oaks_aide.asm

@@ -4,45 +4,45 @@ OaksAideScript: ; 0x59035
 	call YesNoChoice
 	ld a, [wCurrentMenuItem]
 	and a
-	jr nz, .asm_59086
+	jr nz, .choseNo
 	ld hl, wPokedexOwned
 	ld b, wPokedexOwnedEnd - wPokedexOwned
 	call CountSetBits
-	ld a, [wd11e]
+	ld a, [wNumSetBits]
-	ld [$ffdd], a
+	ld [hOaksAideNumMonsOwned], a
 	ld b, a
-	ld a, [$ffdb]
+	ld a, [hOaksAideRequirement]
 	cp b
-	jr z, .asm_59059
+	jr z, .giveItem
-	jr nc, .asm_5907c
+	jr nc, .notEnoughOwnedMons
-.asm_59059
+.giveItem
 	ld hl, OaksAideHereYouGoText
 	call PrintText
-	ld a, [$ffdc]
+	ld a, [hOaksAideItemReward]
 	ld b, a
 	ld c, 1
 	call GiveItem
-	jr nc, .BagFull
+	jr nc, .bagFull
 	ld hl, OaksAideGotItemText
 	call PrintText
 	ld a, $1
-	jr .asm_5908e
+	jr .done
-.BagFull
+.bagFull
 	ld hl, OaksAideNoRoomText
 	call PrintText
 	xor a
-	jr .asm_5908e
+	jr .done
-.asm_5907c
+.notEnoughOwnedMons
 	ld hl, OaksAideUhOhText
 	call PrintText
 	ld a, $80
-	jr .asm_5908e
+	jr .done
-.asm_59086
+.choseNo
 	ld hl, OaksAideComeBackText
 	call PrintText
 	ld a, $ff
-.asm_5908e
+.done
-	ld [$ffdb], a
+	ld [hOaksAideResult], a
 	ret
 
 OaksAideHiText: ; 59091 (16:5091)

engine/overworld/pokecenter.asm

@@ -24,12 +24,12 @@ DisplayPokemonCenterDialogue_: ; 6fe6 (1:6fe6)
 	predef HealParty
 	callba AnimateHealingMachine ; do the healing machine animation
 	xor a
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
-	ld a, [wc0f0]
+	ld a, [wAudioSavedROMBank]
-	ld [wc0ef], a
+	ld [wAudioROMBank], a
-	ld a, [wd35b]
+	ld a, [wMapMusicSoundID]
-	ld [wcfca], a
+	ld [wLastMusicSoundID], a
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld hl, PokemonFightingFitText
 	call PrintText

engine/pokedex_rating.asm

@@ -2,18 +2,18 @@ DisplayDexRating: ; 44169 (11:4169)
 	ld hl, wPokedexSeen
 	ld b, wPokedexSeenEnd - wPokedexSeen
 	call CountSetBits
-	ld a, [wd11e] ; result of CountSetBits (seen count)
+	ld a, [wNumSetBits]
-	ld [$FFDB], a
+	ld [hDexRatingNumMonsSeen], a
 	ld hl, wPokedexOwned
 	ld b, wPokedexOwnedEnd - wPokedexOwned
 	call CountSetBits
-	ld a, [wd11e] ; result of CountSetBits (own count)
+	ld a, [wNumSetBits]
-	ld [$FFDC], a
+	ld [hDexRatingNumMonsOwned], a
 	ld hl, DexRatingsTable
 .findRating
 	ld a, [hli]
 	ld b, a
-	ld a, [$FFDC] ; number of pokemon owned
+	ld a, [hDexRatingNumMonsOwned]
 	cp b
 	jr c, .foundRating
 	inc hl
@@ -24,30 +24,30 @@ DisplayDexRating: ; 44169 (11:4169)
 	ld h, [hl]
 	ld l, a ; load text pointer into hl
 	CheckAndResetEventA EVENT_HALL_OF_FAME_DEX_RATING
-	jr nz, .label3
+	jr nz, .hallOfFame
 	push hl
 	ld hl, PokedexRatingText_441cc
 	call PrintText
 	pop hl
 	call PrintText
 	callba PlayPokedexRatingSfx
-	jp WaitForTextScrollButtonPress ; wait for button press
+	jp WaitForTextScrollButtonPress
-.label3
+.hallOfFame
 	ld de, wcc5b
-	ld a, [$FFDB]
+	ld a, [hDexRatingNumMonsSeen]
 	ld [de], a
 	inc de
-	ld a, [$FFDC]
+	ld a, [hDexRatingNumMonsOwned]
 	ld [de], a
 	inc de
-.label4
+.copyRatingTextLoop
 	ld a, [hli]
-	cp a, $50
+	cp a, "@"
-	jr z, .label5
+	jr z, .doneCopying
 	ld [de], a
 	inc de
-	jr .label4
+	jr .copyRatingTextLoop
-.label5
+.doneCopying
 	ld [de], a
 	ret
 

engine/slot_machine.asm

@@ -411,7 +411,7 @@ SlotMachine_CheckForMatches: ; 37588 (d:7588)
 	call PrintText
 .done
 	xor a
-	ld [wc002], a
+	ld [wMuteAudioAndPauseMusic], a
 	ret
 .rollWheel3DownByOneSymbol
 	call SlotMachine_AnimWheel3
@@ -654,7 +654,7 @@ SlotMachine_PrintPayoutCoins: ; 3775f (d:775f)
 
 SlotMachine_PayCoinsToPlayer: ; 3776b (d:776b)
 	ld a, $1
-	ld [wc002], a
+	ld [wMuteAudioAndPauseMusic], a
 	call WaitForSoundToFinish
 
 ; Put 1 in the temp coins variable. This value is added to the player's coins

engine/titlescreen.asm

@@ -18,8 +18,8 @@ SetDefaultNamesBeforeTitlescreen: ; 42b7 (1:42b7)
 	ld [hli], a
 	ld [hl], a
 	ld a, BANK(Music_TitleScreen)
-	ld [wc0ef], a
+	ld [wAudioROMBank], a
-	ld [wc0f0], a
+	ld [wAudioSavedROMBank], a
 
 DisplayTitleScreen: ; 42dd (1:42dd)
 	call GBPalWhiteOut
@@ -212,7 +212,7 @@ ENDC
 	call Delay3
 	call WaitForSoundToFinish
 	ld a, MUSIC_TITLE_SCREEN
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	xor a
 	ld [wcc5b], a

home.asm

@@ -240,7 +240,7 @@ DrawHPBar:: ; 1336 (0:1336)
 
 
 ; loads pokemon data from one of multiple sources to wLoadedMon
-; loads base stats to W_MONHDEXNUM
+; loads base stats to W_MONHEADER
 ; INPUT:
 ; [wWhichPokemon] = index of pokemon within party/box
 ; [wMonDataLocation] = source
@@ -251,7 +251,7 @@ DrawHPBar:: ; 1336 (0:1336)
 ; OUTPUT:
 ; [wcf91] = pokemon ID
 ; wLoadedMon = base address of pokemon data
-; W_MONHDEXNUM = base address of base stats
+; W_MONHEADER = base address of base stats
 LoadMonData:: ; 1372 (0:1372)
 	jpab LoadMonData_
 
@@ -332,9 +332,9 @@ GetCryData:: ; 13d9 (0:13d9)
 	ld a, [hli]
 	ld b, a ; cry id
 	ld a, [hli]
-	ld [wc0f1], a
+	ld [wFrequencyModifier], a
 	ld a, [hl]
-	ld [wc0f2], a
+	ld [wTempoModifier], a
 	call BankswitchBack
 
 	; Cry headers have 3 channels,
@@ -551,7 +551,7 @@ GetwMoves:: ; 152e (0:152e)
 	ld a,[hl]
 	ret
 
-; copies the base stat data of a pokemon to W_MONHDEXNUM (W_MONHEADER)
+; copies the base stat data of a pokemon to W_MONHEADER
 ; INPUT:
 ; [wd0b5] = pokemon ID
 GetMonHeader:: ; 1537 (0:1537)
@@ -606,7 +606,7 @@ GetMonHeader:: ; 1537 (0:1537)
 	call FarCopyData
 .done
 	ld a,[wd0b5]
-	ld [W_MONHDEXNUM],a
+	ld [W_MONHINDEX],a
 	pop af
 	ld [wd11e],a
 	pop hl
@@ -998,27 +998,27 @@ ResetPlayerSpriteData_ClearSpriteData:: ; 28c4 (0:28c4)
 	xor a
 	jp FillMemory
 
-Func_28cb:: ; 28cb (0:28cb)
+FadeOutAudio:: ; 28cb (0:28cb)
-	ld a, [wMusicHeaderPointer]
+	ld a, [wAudioFadeOutControl]
 	and a
 	jr nz, .asm_28dc
 	ld a, [wd72c]
 	bit 1, a
 	ret nz
 	ld a, $77
-	ld [$ff24], a
+	ld [rNR50], a
 	ret
 .asm_28dc
-	ld a, [wcfc9]
+	ld a, [wAudioFadeOutCounter]
 	and a
-	jr z, .asm_28e7
+	jr z, .counterReachedZero
 	dec a
-	ld [wcfc9], a
+	ld [wAudioFadeOutCounter], a
 	ret
-.asm_28e7
+.counterReachedZero
-	ld a, [wcfc8]
+	ld a, [wAudioFadeOutCounterReloadValue]
-	ld [wcfc9], a
+	ld [wAudioFadeOutCounter], a
-	ld a, [$ff24]
+	ld a, [rNR50]
 	and a
 	jr z, .asm_2903
 	ld b, a
@@ -1031,20 +1031,20 @@ Func_28cb:: ; 28cb (0:28cb)
 	dec a
 	swap a
 	or c
-	ld [$ff24], a
+	ld [rNR50], a
 	ret
 .asm_2903
-	ld a, [wMusicHeaderPointer]
+	ld a, [wAudioFadeOutControl]
 	ld b, a
 	xor a
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
-	ld a, [wc0f0]
+	ld a, [wAudioSavedROMBank]
-	ld [wc0ef], a
+	ld [wAudioROMBank], a
 	ld a, b
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	jp PlaySound
 
 ; this function is used to display sign messages, sprite dialog, etc.
@@ -1292,7 +1292,7 @@ INCLUDE "engine/menu/start_menu.asm"
 ; hl = address of string of bytes
 ; b = length of string of bytes
 ; OUTPUT:
-; [wd11e] = number of set bits
+; [wNumSetBits] = number of set bits
 CountSetBits:: ; 2b7f (0:2b7f)
 	ld c,0
 .loop
@@ -1309,7 +1309,7 @@ CountSetBits:: ; 2b7f (0:2b7f)
 	dec b
 	jr nz,.loop
 	ld a,c
-	ld [wd11e],a ; store number of set bits
+	ld [wNumSetBits],a
 	ret
 
 ; subtracts the amount the player paid from their money
@@ -2604,12 +2604,12 @@ PlayTrainerMusic:: ; 33e8 (0:33e8)
 	and a
 	ret nz
 	xor a
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
 	ld a, $ff
 	call PlaySound
 	ld a, BANK(Music_MeetEvilTrainer)
-	ld [wc0ef], a
+	ld [wAudioROMBank], a
-	ld [wc0f0], a
+	ld [wAudioSavedROMBank], a
 	ld a, [wEngagedTrainerClass]
 	ld b, a
 	ld hl, EvilTrainerList
@@ -2634,7 +2634,7 @@ PlayTrainerMusic:: ; 33e8 (0:33e8)
 .maleTrainer
 	ld a, MUSIC_MEET_MALE_TRAINER
 .PlaySound
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	jp PlaySound
 
 INCLUDE "data/trainer_types.asm"
@@ -3217,8 +3217,8 @@ WaitForSoundToFinish:: ; 3748 (0:3748)
 	and $80
 	ret nz
 	push hl
-.asm_374f
+.waitLoop
-	ld hl, wc02a
+	ld hl, wChannelSoundIDs + CH4
 	xor a
 	or [hl]
 	inc hl
@@ -3226,7 +3226,7 @@ WaitForSoundToFinish:: ; 3748 (0:3748)
 	inc hl
 	inc hl
 	or [hl]
-	jr nz, .asm_374f
+	jr nz, .waitLoop
 	pop hl
 	ret
 
@@ -3313,9 +3313,9 @@ GetName:: ; 376b (0:376b)
 	call CopyData
 .gotPtr
 	ld a,e
-	ld [wcf8d],a
+	ld [wUnusedCF8D],a
 	ld a,d
-	ld [wcf8e],a
+	ld [wUnusedCF8D + 1],a
 	pop de
 	pop bc
 	pop hl

home/audio.asm

@@ -3,112 +3,139 @@ PlayDefaultMusic:: ; 2307 (0:2307)
 	xor a
 	ld c, a
 	ld d, a
-	ld [wcfca], a
+	ld [wLastMusicSoundID], a
-	jr Func_2324
+	jr PlayDefaultMusicCommon
 
-Func_2312:: ; 2312 (0:2312)
+PlayDefaultMusicFadeOutCurrent:: ; 2312 (0:2312)
-	ld c, $a
+; Fade out the current music and then play the default music.
-	ld d, $0
+	ld c, 10
+	ld d, 0
 	ld a, [wd72e]
-	bit 5, a
+	bit 5, a ; has a battle just ended?
-	jr z, Func_2324
+	jr z, PlayDefaultMusicCommon
 	xor a
-	ld [wcfca], a
+	ld [wLastMusicSoundID], a
-	ld c, $8
+	ld c, 8
 	ld d, c
-Func_2324:: ; 2324 (0:2324)
+
+PlayDefaultMusicCommon:: ; 2324 (0:2324)
 	ld a, [wWalkBikeSurfState]
 	and a
-	jr z, .asm_2343
+	jr z, .walking
 	cp $2
-	jr z, .asm_2332
+	jr z, .surfing
 	ld a, MUSIC_BIKE_RIDING
-	jr .asm_2334
+	jr .next
-.asm_2332
+
+.surfing
 	ld a, MUSIC_SURFING
-.asm_2334
+
+.next
 	ld b, a
 	ld a, d
-	and a
+	and a ; should current music be faded out first?
 	ld a, BANK(Music_BikeRiding)
-	jr nz, .asm_233e
+	jr nz, .next2
-	ld [wc0ef], a
+
-.asm_233e
+; Only change the audio ROM bank if the current music isn't going to be faded
-	ld [wc0f0], a
+; out before the default music begins.
-	jr .asm_234c
+	ld [wAudioROMBank], a
-.asm_2343
+
-	ld a, [wd35b]
+.next2
+; [wAudioSavedROMBank] will be copied to [wAudioROMBank] after fading out the
+; current music (if the current music is faded out).
+	ld [wAudioSavedROMBank], a
+	jr .next3
+
+.walking
+	ld a, [wMapMusicSoundID]
 	ld b, a
-	call Func_2385
+	call CompareMapMusicBankWithCurrentBank
-	jr c, .asm_2351
+	jr c, .next4
-.asm_234c
+
-	ld a, [wcfca]
+.next3
-	cp b
+	ld a, [wLastMusicSoundID]
-	ret z
+	cp b ; is the default music already playing?
-.asm_2351
+	ret z ; if so, do nothing
+
+.next4
 	ld a, c
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
 	ld a, b
-	ld [wcfca], a
+	ld [wLastMusicSoundID], a
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	jp PlaySound
 
-Func_235f:: ; 235f (0:235f)
+UpdateMusic6Times:: ; 235f (0:235f)
-	ld a, [wc0ef]
+; This is called when entering a map, before fading out the current music and
+; playing the default music (i.e. the map's music or biking/surfing music).
+	ld a, [wAudioROMBank]
 	ld b, a
 	cp BANK(Audio1_UpdateMusic)
 	jr nz, .checkForAudio2
-.audio1
+
+; audio 1
 	ld hl, Audio1_UpdateMusic
-	jr .asm_2378
+	jr .next
+
 .checkForAudio2
 	cp BANK(Audio2_UpdateMusic)
 	jr nz, .audio3
-.audio2
+
+; audio 2
 	ld hl, Audio2_UpdateMusic
-	jr .asm_2378
+	jr .next
+
 .audio3
 	ld hl, Audio3_UpdateMusic
-.asm_2378
+
-	ld c, $6
+.next
-.asm_237a
+	ld c, 6
+.loop
 	push bc
 	push hl
 	call Bankswitch
 	pop hl
 	pop bc
 	dec c
-	jr nz, .asm_237a
+	jr nz, .loop
 	ret
 
-Func_2385:: ; 2385 (0:2385)
+CompareMapMusicBankWithCurrentBank:: ; 2385 (0:2385)
-	ld a, [wd35c]
+; Compares the map music's audio ROM bank with the current audio ROM bank
+; and updates the audio ROM bank variables.
+; Returns whether the banks are different in carry.
+	ld a, [wMapMusicROMBank]
 	ld e, a
-	ld a, [wc0ef]
+	ld a, [wAudioROMBank]
 	cp e
-	jr nz, .asm_2394
+	jr nz, .differentBanks
-	ld [wc0f0], a
+	ld [wAudioSavedROMBank], a
 	and a
 	ret
-.asm_2394
+.differentBanks
-	ld a, c
+	ld a, c ; this is a fade-out counter value and it's always non-zero
 	and a
 	ld a, e
-	jr nz, .asm_239c
+	jr nz, .next
-	ld [wc0ef], a
+; If the fade-counter is non-zero, we don't change the audio ROM bank because
-.asm_239c
+; it's needed to keep playing the music as it fades out. The FadeOutAudio
-	ld [wc0f0], a
+; routine will take care of copying [wAudioSavedROMBank] to [wAudioROMBank]
+; when the music has faded out.
+	ld [wAudioROMBank], a
+.next
+	ld [wAudioSavedROMBank], a
 	scf
 	ret
 
 PlayMusic:: ; 23a1 (0:23a1)
 	ld b, a
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	xor a
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
 	ld a, c
-	ld [wc0ef], a
+	ld [wAudioROMBank], a
-	ld [wc0f0], a
+	ld [wAudioSavedROMBank], a
 	ld a, b
 
 ; plays music specified by a. If value is $ff, music is stopped
@@ -117,66 +144,74 @@ PlaySound:: ; 23b1 (0:23b1)
 	push de
 	push bc
 	ld b, a
-	ld a, [wc0ee]
+	ld a, [wNewSoundID]
 	and a
-	jr z, .asm_23c8
+	jr z, .next
 	xor a
-	ld [wc02a], a
+	ld [wChannelSoundIDs + CH4], a
-	ld [wc02b], a
+	ld [wChannelSoundIDs + CH5], a
-	ld [wc02c], a
+	ld [wChannelSoundIDs + CH6], a
-	ld [wc02d], a
+	ld [wChannelSoundIDs + CH7], a
-.asm_23c8
+.next
-	ld a, [wMusicHeaderPointer]
+	ld a, [wAudioFadeOutControl]
-	and a
+	and a ; has a fade-out length been specified?
-	jr z, .asm_23e3
+	jr z, .noFadeOut
-	ld a, [wc0ee]
+	ld a, [wNewSoundID]
-	and a
+	and a ; is the new sound ID 0?
-	jr z, .asm_2425
+	jr z, .done ; if so, do nothing
 	xor a
-	ld [wc0ee], a
+	ld [wNewSoundID], a
-	ld a, [wcfca]
+	ld a, [wLastMusicSoundID]
-	cp $ff
+	cp $ff ; has the music been stopped?
-	jr nz, .asm_2414
+	jr nz, .fadeOut ; if not, fade out the current music
+; If it has been stopped, start playing the new music immediately.
 	xor a
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
-.asm_23e3
+.noFadeOut
 	xor a
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	ld a, [H_LOADEDROMBANK]
-	ld [$ffb9], a
+	ld [hSavedROMBank], a
-	ld a, [wc0ef]
+	ld a, [wAudioROMBank]
 	ld [H_LOADEDROMBANK], a
 	ld [MBC1RomBank], a
-	cp BANK(Audio1_9876)
+	cp BANK(Audio1_PlaySound)
 	jr nz, .checkForAudio2
-.audio1
+
+; audio 1
 	ld a, b
-	call Audio1_9876
+	call Audio1_PlaySound
-	jr .asm_240b
+	jr .next2
+
 .checkForAudio2
-	cp BANK(Audio2_22035)
+	cp BANK(Audio2_PlaySound)
 	jr nz, .audio3
-.audio2
+
+; audio 2
 	ld a, b
-	call Audio2_22035
+	call Audio2_PlaySound
-	jr .asm_240b
+	jr .next2
+
 .audio3
 	ld a, b
-	call Audio3_7d8ea
+	call Audio3_PlaySound
-.asm_240b
+
-	ld a, [$ffb9]
+.next2
+	ld a, [hSavedROMBank]
 	ld [H_LOADEDROMBANK], a
 	ld [MBC1RomBank], a
-	jr .asm_2425
+	jr .done
-.asm_2414
+
+.fadeOut
 	ld a, b
-	ld [wcfca], a
+	ld [wLastMusicSoundID], a
-	ld a, [wMusicHeaderPointer]
+	ld a, [wAudioFadeOutControl]
-	ld [wcfc8], a
+	ld [wAudioFadeOutCounterReloadValue], a
-	ld [wcfc9], a
+	ld [wAudioFadeOutCounter], a
 	ld a, b
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
-.asm_2425
+
+.done
 	pop bc
 	pop de
 	pop hl

home/init.asm

@@ -98,8 +98,8 @@ rLCDC_DEFAULT EQU %11100011
 	predef LoadSGB
 
 	ld a, BANK(SFX_Shooting_Star)
-	ld [wc0ef], a
+	ld [wAudioROMBank], a
-	ld [wc0f0], a
+	ld [wAudioSavedROMBank], a
 	ld a, $9c
 	ld [H_AUTOBGTRANSFERDEST + 1], a
 	xor a
@@ -127,11 +127,11 @@ ClearVram:
 
 StopAllSounds::
 	ld a, BANK(Audio1_UpdateMusic)
-	ld [wc0ef], a
+	ld [wAudioROMBank], a
-	ld [wc0f0], a
+	ld [wAudioSavedROMBank], a
 	xor a
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
-	ld [wc0ee], a
+	ld [wNewSoundID], a
-	ld [wcfca], a
+	ld [wLastMusicSoundID], a
 	dec a
 	jp PlaySound

home/overworld.asm

@@ -658,7 +658,7 @@ CheckMapConnections:: ; 07ba (0:07ba)
 	ld [wCurrentTileBlockMapViewPointer + 1],a
 .loadNewMap ; load the connected map that was entered
 	call LoadMapHeader
-	call Func_2312 ; music
+	call PlayDefaultMusicFadeOutCurrent
 	ld b,$09
 	call GoPAL_SET
 ; Since the sprite set shouldn't change, this will just update VRAM slots at
@@ -750,16 +750,16 @@ HandleBlackOut::
 	ld [MBC1RomBank], a
 	call ResetStatusAndHalveMoneyOnBlackout
 	call SpecialWarpIn
-	call Func_2312
+	call PlayDefaultMusicFadeOutCurrent
 	jp SpecialEnterMap
 
 StopMusic::
-	ld [wMusicHeaderPointer], a
+	ld [wAudioFadeOutControl], a
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 .wait
-	ld a, [wMusicHeaderPointer]
+	ld a, [wAudioFadeOutControl]
 	and a
 	jr nz, .wait
 	jp StopAllSounds
@@ -1224,7 +1224,7 @@ CollisionCheckOnLand:: ; 0bd1 (0:0bd1)
 	call CheckTilePassable
 	jr nc,.noCollision
 .collision
-	ld a,[wc02a]
+	ld a,[wChannelSoundIDs + CH4]
 	cp a,SFX_COLLISION ; check if collision sound is already playing
 	jr z,.setCarry
 	ld a,SFX_COLLISION
@@ -1927,7 +1927,7 @@ CollisionCheckOnWater:: ; 0fb7 (0:0fb7)
 	jr z,.stopSurfing ; stop surfing if the tile is passable
 	jr .loop
 .collision
-	ld a,[wc02a]
+	ld a,[wChannelSoundIDs + CH4]
 	cp a,SFX_COLLISION ; check if collision sound is already playing
 	jr z,.setCarry
 	ld a,SFX_COLLISION
@@ -2279,9 +2279,9 @@ LoadMapHeader:: ; 107c (0:107c)
 	add hl,bc
 	add hl,bc
 	ld a,[hli]
-	ld [wd35b],a ; music 1
+	ld [wMapMusicSoundID],a ; music 1
 	ld a,[hl]
-	ld [wd35c],a ; music 2
+	ld [wMapMusicROMBank],a ; music 2
 	pop af
 	ld [H_LOADEDROMBANK],a
 	ld [MBC1RomBank],a
@@ -2352,8 +2352,8 @@ LoadMapData:: ; 1241 (0:1241)
 	ld a,[W_FLAGS_D733]
 	bit 1,a
 	jr nz,.restoreRomBank
-	call Func_235f ; music related
+	call UpdateMusic6Times
-	call Func_2312 ; music related
+	call PlayDefaultMusicFadeOutCurrent
 .restoreRomBank
 	pop af
 	ld [H_LOADEDROMBANK],a

home/vblank.asm

@@ -38,21 +38,21 @@ VBlank::
 
 	ld a, [H_VBLANKOCCURRED]
 	and a
-	jr z, .vblanked
+	jr z, .skipZeroing
 	xor a
 	ld [H_VBLANKOCCURRED], a
-.vblanked
 
+.skipZeroing
 	ld a, [H_FRAMECOUNTER]
 	and a
-	jr z, .decced
+	jr z, .skipDec
 	dec a
 	ld [H_FRAMECOUNTER], a
-.decced
 
-	call Func_28cb
+.skipDec
+	call FadeOutAudio
 
-	ld a, [wc0ef] ; music ROM bank
+	ld a, [wAudioROMBank] ; music ROM bank
 	ld [H_LOADEDROMBANK], a
 	ld [MBC1RomBank], a
 

hram.asm

@@ -182,7 +182,9 @@ hJoy5        EQU $FFB5
 hJoy6        EQU $FFB6
 hJoy7        EQU $FFB7
 
-H_LOADEDROMBANK     EQU $FFB8
+H_LOADEDROMBANK EQU $FFB8
+
+hSavedROMBank EQU $FFB9
 
 ; is automatic background transfer during V-blank enabled?
 ; if nonzero, yes
@@ -273,6 +275,19 @@ hGymGateIndex EQU $FFDB
 
 hGymTrashCanRandNumMask EQU $FFDB
 
+hDexRatingNumMonsSeen  EQU $FFDB
+hDexRatingNumMonsOwned EQU $FFDC
+
+; $00 = bag full
+; $01 = got item
+; $80 = didn't meet required number of owned mons
+; $FF = player cancelled
+hOaksAideResult       EQU $FFDB
+
+hOaksAideRequirement  EQU $FFDB ; required number of owned mons
+hOaksAideItemReward   EQU $FFDC
+hOaksAideNumMonsOwned EQU $FFDD
+
 hItemToRemoveID    EQU $FFDB
 hItemToRemoveIndex EQU $FFDC
 

main.asm

@@ -86,7 +86,7 @@ LoadMonData_:
 ;  2: boxmon
 ;  3: daycaremon
 ; Return monster id at wcf91 and its data at wLoadedMon.
-; Also load base stats at W_MONHDEXNUM for convenience.
+; Also load base stats at W_MONHEADER for convenience.
 
 	ld a, [wDayCareMonSpecies]
 	ld [wcf91], a
@@ -284,7 +284,7 @@ DetectCollisionBetweenSprites:
 	ld [hld], a ; zero [$c1ic] (directions in which collisions occurred)
 
 	ld a, [$ff91]
-	ld [hld], a ; [$c1ib] = adjusted X coordiate
+	ld [hld], a ; [$c1ib] = adjusted X coordinate
 	ld a, [$ff90]
 	ld [hl], a ; [$c1ia] = adjusted Y coordinate
 

scripts/celadonmansion3.asm

@@ -30,7 +30,7 @@ DirectorText: ; 487b2 (12:47b2)
 	ld hl, wPokedexOwned
 	ld b, wPokedexOwnedEnd - wPokedexOwned
 	call CountSetBits
-	ld a, [wd11e]
+	ld a, [wNumSetBits]
 	cp 150
 	jr nc, .CompletedDex
 	ld hl, .GameDesigner

scripts/ceruleancity.asm

@@ -65,7 +65,7 @@ CeruleanCityScript0: ; 194c8 (6:54c8)
 	and a
 	jr z, .asm_19512
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 .asm_19512
 	ld c, BANK(Music_MeetRival)
@@ -172,7 +172,7 @@ CeruleanCityScript2: ; 195b1 (6:55b1)
 	ld [hSpriteIndexOrTextID], a
 	call DisplayTextID
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	callba Music_RivalAlternateStart
 	ld a, $1

scripts/oakslab.asm

@@ -511,7 +511,7 @@ OaksLabScript15: ; 1ceb0 (7:4eb0)
 	ld [hJoyHeld], a
 	call EnableAutoTextBoxDrawing
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	callba Music_RivalAlternateStart
 	ld a, $15
@@ -612,7 +612,7 @@ OaksLabScript16: ; 1cf12 (7:4f12)
 	call FillMemory
 	ld [hl], $ff
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	callba Music_RivalAlternateStart
 	ld a, $1
@@ -969,8 +969,8 @@ OaksLabText5: ; 1d248 (7:5248)
 	ld hl, wPokedexOwned
 	ld b, wPokedexOwnedEnd - wPokedexOwned
 	call CountSetBits
-	ld a, [wd11e]
+	ld a, [wNumSetBits]
-	cp $2
+	cp 2
 	jr c, .asm_1d279
 	CheckEvent EVENT_GOT_POKEDEX
 	jr z, .asm_1d279

scripts/pewterpokecenter.asm

@@ -59,9 +59,9 @@ PewterPokecenterText3: ; 5c59b (17:459b)
 	ld c, 24
 	call DelayFrames
 
-	ld a, [wc026]
+	ld a, [wChannelSoundIDs]
 	ld b, a
-	ld a, [wc027]
+	ld a, [wChannelSoundIDs + CH1]
 	or b
 	jr nz, .loop
 

scripts/pokemontower2.asm

@@ -23,7 +23,7 @@ PokemonTower2Script0: ; 6050f (18:450f)
 	call ArePlayerCoordsInArray
 	ret nc
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld c, BANK(Music_MeetRival)
 	ld a, MUSIC_MEET_RIVAL
@@ -77,7 +77,7 @@ PokemonTower2Script1: ; 60563 (18:4563)
 	ld [H_SPRITEINDEX], a
 	call MoveSprite
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	callba Music_RivalAlternateStart
 	ld a, $2

scripts/redshouse1f.asm

@@ -29,14 +29,14 @@ MomHealPokemon: ; 4818a (12:418a)
 	call ReloadMapData
 	predef HealParty
 	ld a, MUSIC_PKMN_HEALED
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 .next
-	ld a, [wc026]
+	ld a, [wChannelSoundIDs]
 	cp MUSIC_PKMN_HEALED
 	jr z, .next
-	ld a, [wd35b]
+	ld a, [wMapMusicSoundID]
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	call GBFadeInFromWhite
 	ld hl, MomHealText2

scripts/route11gateupstairs.asm

@@ -20,9 +20,9 @@ Route11GateUpstairsText2: ; 4946c (12:546c)
 	CheckEvent EVENT_GOT_ITEMFINDER, 1
 	jr c, .asm_4949b
 	ld a, 30 ; pokemon needed
-	ld [$ffdb], a
+	ld [hOaksAideRequirement], a
 	ld a, ITEMFINDER ; oak's aide reward
-	ld [$ffdc], a
+	ld [hOaksAideItemReward], a
 	ld [wd11e], a
 	call GetItemName
 	ld h, d
@@ -30,8 +30,8 @@ Route11GateUpstairsText2: ; 4946c (12:546c)
 	ld de, wcc5b
 	ld bc, $000d
 	call CopyData
-	predef OaksAideScript ; call oak's aide script
+	predef OaksAideScript
-	ld a, [$ffdb]
+	ld a, [hOaksAideResult]
 	dec a
 	jr nz, .asm_494a1
 	SetEvent EVENT_GOT_ITEMFINDER

scripts/route15gateupstairs.asm

@@ -10,17 +10,17 @@ Route15GateUpstairsText1: ; 49651 (12:5651)
 	CheckEvent EVENT_GOT_EXP_ALL
 	jr nz, .asm_49683
 	ld a, 50 ; pokemon needed
-	ld [$ffdb], a
+	ld [hOaksAideRequirement], a
 	ld a, EXP__ALL ; oak's aide reward
-	ld [$ffdc], a
+	ld [hOaksAideItemReward], a
 	ld [wd11e], a
 	call GetItemName
 	ld hl, wcd6d
 	ld de, wcc5b
 	ld bc, $000d
 	call CopyData
-	predef OaksAideScript ; call oak's aide script
+	predef OaksAideScript
-	ld a, [$ffdb]
+	ld a, [hOaksAideResult]
 	cp $1
 	jr nz, .asm_49689
 	SetEvent EVENT_GOT_EXP_ALL

scripts/route22.asm

@@ -89,7 +89,7 @@ Route22Script0: ; 50f00 (14:4f00)
 	and a
 	jr z, .asm_50f4e
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 .asm_50f4e
 	ld c, BANK(Music_MeetRival)
@@ -168,7 +168,7 @@ Route22Script2: ; 50fb5 (14:4fb5)
 	ld [hSpriteIndexOrTextID], a
 	call DisplayTextID
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	callba Music_RivalAlternateStart
 	ld a, [wcf0d]
@@ -242,11 +242,11 @@ Route22Script_5104e: ; 5104e (14:504e)
 	and a
 	jr z, .skipYVisibilityTesta
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 .skipYVisibilityTesta
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	callba Music_RivalAlternateTempo
 	ld a, $2
@@ -327,7 +327,7 @@ Route22Script5: ; 510df (14:50df)
 	ld [hSpriteIndexOrTextID], a
 	call DisplayTextID
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	callba Music_RivalAlternateStartAndTempo
 	ld a, [wcf0d]

scripts/route2gate.asm

@@ -10,17 +10,17 @@ Route2GateText1: ; 5d5db (17:55db)
 	CheckEvent EVENT_GOT_HM05
 	jr nz, .asm_5d60d
 	ld a, 10 ; pokemon needed
-	ld [$ffdb], a
+	ld [hOaksAideRequirement], a
 	ld a, HM_05 ; oak's aide reward
-	ld [$ffdc], a
+	ld [hOaksAideItemReward], a
 	ld [wd11e], a
 	call GetItemName
 	ld hl, wcd6d
 	ld de, wcc5b
 	ld bc, $000d
 	call CopyData
-	predef OaksAideScript ; call oak's aide script
+	predef OaksAideScript
-	ld a, [$ffdb]
+	ld a, [hOaksAideResult]
 	cp $1
 	jr nz, .asm_5d613
 	SetEvent EVENT_GOT_HM05

scripts/silphco7.asm

@@ -131,7 +131,7 @@ SilphCo7Script0: ; 51c23 (14:5c23)
 	ld a, PLAYER_DIR_DOWN
 	ld [wPlayerMovingDirection], a
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld c, BANK(Music_MeetRival)
 	ld a, MUSIC_MEET_RIVAL
@@ -220,7 +220,7 @@ SilphCo7Script4: ; 51cc8 (14:5cc8)
 	ld [hSpriteIndexOrTextID], a
 	call DisplayTextID
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	callba Music_RivalAlternateStart
 	ld de, MovementData_51d1d

scripts/ssanne2.asm

@@ -25,7 +25,7 @@ SSAnne2Script0: ; 613be (18:53be)
 	call ArePlayerCoordsInArray
 	ret nc
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld c, BANK(Music_MeetRival)
 	ld a, MUSIC_MEET_RIVAL
@@ -146,7 +146,7 @@ SSAnne2Script2: ; 6146d (18:546d)
 	ld [H_SPRITEINDEX], a
 	call MoveSprite
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	callba Music_RivalAlternateStart
 	ld a, $3

scripts/ssanne7.asm

@@ -44,21 +44,21 @@ SSAnne7Text1: ; 618ad (18:58ad)
 SSAnne7RubText: ; 618ec (18:58ec)
 	TX_FAR _SSAnne7RubText
 	TX_ASM
-	ld a, [wc0ef]
+	ld a, [wAudioROMBank]
 	cp BANK(Audio3_UpdateMusic)
-	ld [wc0f0], a
+	ld [wAudioSavedROMBank], a
 	jr nz, .asm_61908
 	ld a, $ff
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld a, Bank(Music_PkmnHealed)
-	ld [wc0ef], a
+	ld [wAudioROMBank], a
 .asm_61908
 	ld a, MUSIC_PKMN_HEALED
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 .asm_61910
-	ld a, [wc026]
+	ld a, [wChannelSoundIDs]
 	cp MUSIC_PKMN_HEALED
 	jr z, .asm_61910
 	call PlayDefaultMusic

scripts/vermiliondock.asm

@@ -40,7 +40,7 @@ VermilionDock_1db9b: ; 1db9b (7:5b9b)
 	SetEventForceReuseHL EVENT_SS_ANNE_LEFT
 	ld a, $ff
 	ld [wJoyIgnore], a
-	ld [wc0ee], a
+	ld [wNewSoundID], a
 	call PlaySound
 	ld c, BANK(Music_Surfing)
 	ld a, MUSIC_SURFING

text.asm

@@ -94,7 +94,7 @@ _OaksAideHiText:: ; 80143 (20:4143)
 	cont "AIDE!"
 
 	para "If you caught @"
-	TX_NUM $ffdb, 1, 3
+	TX_NUM hOaksAideRequirement, 1, 3
 	db $0
 	line "kinds of #MON,"
 	cont "I'm supposed to"
@@ -106,7 +106,7 @@ _OaksAideHiText:: ; 80143 (20:4143)
 	para "So, ", $52, "! Have"
 	line "you caught at"
 	cont "least @"
-	TX_NUM $ffdb, 1, 3
+	TX_NUM hOaksAideRequirement, 1, 3
 	text " kinds of"
 	cont "#MON?"
 	done
@@ -115,12 +115,12 @@ _OaksAideUhOhText:: ; 801e4 (20:41e4)
 	text "Let's see..."
 	line "Uh-oh! You have"
 	cont "caught only @"
-	TX_NUM $ffdd, 1, 3
+	TX_NUM hOaksAideNumMonsOwned, 1, 3
 	db $0
 	cont "kinds of #MON!"
 
 	para "You need @"
-	TX_NUM $ffdb, 1, 3
+	TX_NUM hOaksAideRequirement, 1, 3
 	text " kinds"
 	line "if you want the"
 	cont "@"
@@ -132,7 +132,7 @@ _OaksAideComeBackText:: ; 80250 (20:4250)
 	text "Oh. I see."
 
 	para "When you get @"
-	TX_NUM $ffdb, 1, 3
+	TX_NUM hOaksAideRequirement, 1, 3
 	db $0
 	line "kinds, come back"
 	cont "for @"
@@ -143,7 +143,7 @@ _OaksAideComeBackText:: ; 80250 (20:4250)
 _OaksAideHereYouGoText:: ; 8028c (20:428c)
 	text "Great! You have"
 	line "caught @"
-	TX_NUM $ffdd, 1, 3
+	TX_NUM hOaksAideNumMonsOwned, 1, 3
 	text " kinds "
 	cont "of #MON!"
 	cont "Congratulations!"

text/maps/oaks_lab.asm

@@ -547,10 +547,10 @@ _OaksLabText_441cc:: ; 9580c (25:580c)
 	line "letion is:"
 
 	para "@"
-	TX_NUM $ffdb, 1, 3
+	TX_NUM hDexRatingNumMonsSeen, 1, 3
 	text " #MON seen"
 	line "@"
-	TX_NUM $ffdc, 1, 3
+	TX_NUM hDexRatingNumMonsOwned, 1, 3
 	text " #MON owned"
 
 	para "PROF.OAK's"

wram.asm

@@ -61,66 +61,146 @@ ENDM
 
 SECTION "WRAM Bank 0", WRAM0
 
-wc000:: ds 1
+wUnusedC000:: ; c000
-wc001:: ds 1
+	ds 1
-wc002:: ds 1
+
-wc003:: ds 1
+wSoundID:: ; c001
-wc004:: ds 1
+	ds 1
-wc005:: ds 1
+
-wc006:: ds 8
+wMuteAudioAndPauseMusic:: ; c002
-wc00e:: ds 4
+; bit 7: whether sound has been muted
-wc012:: ds 4
+; all bits: whether the effective is active
-wc016:: ds 16
+; Store 1 to activate effect (any value in the range [1, 127] works).
-wc026:: ds 1
+; All audio is muted and music is paused. Sfx continues playing until it
-wc027:: ds 1
+; ends normally.
-wc028:: ds 2
+; Store 0 to resume music.
-wc02a:: ds 1
+	ds 1
-wc02b:: ds 1
+
-wc02c:: ds 1
+wDisableChannelOutputWhenSfxEnds:: ; c003
-wc02d:: ds 1
+	ds 1
-wc02e:: ds 8
+
-wc036:: ds 8
+wStereoPanning:: ; c004
-wc03e:: ds 8
+	ds 1
-wc046:: ds 8
+
-wc04e:: ds 8
+wSavedVolume:: ; c005
-wc056:: ds 8
+	ds 1
-wc05e:: ds 8
+
-wc066:: ds 8
+wChannelCommandPointers:: ; c006
-wc06e:: ds 8
+	ds 16
-wc076:: ds 8
+
-wc07e:: ds 8
+wChannelReturnAddresses:: ; c016
-wc086:: ds 8
+	ds 16
-wc08e:: ds 8
+
-wc096:: ds 8
+wChannelSoundIDs:: ; c026
-wc09e:: ds 8
+	ds 8
-wc0a6:: ds 8
+
-wc0ae:: ds 8
+wChannelFlags1:: ; c02e
-wc0b6:: ds 8
+	ds 8
-wc0be:: ds 8
+
-wc0c6:: ds 8
+wChannelFlags2:: ; c036
-wc0ce:: ds 1
+	ds 8
-wc0cf:: ds 1
+
-wc0d0:: ds 1
+wChannelDuties:: ; c03e
-wc0d1:: ds 1
+	ds 8
-wc0d2:: ds 1
+
-wc0d3:: ds 1
+wChannelDutyCycles:: ; c046
-wc0d4:: ds 1
+	ds 8
-wc0d5:: ds 1
+
-wc0d6:: ds 8
+wChannelVibratoDelayCounters:: ; c04e
-wc0de:: ds 8
+; reloaded at the beginning of a note. counts down until the vibrato begins.
-wc0e6:: ds 1
+	ds 8
-wc0e7:: ds 1
+
-wc0e8:: ds 1
+wChannelVibratoExtents:: ; c056
-wc0e9:: ds 1
+	ds 8
-wc0ea:: ds 1
+
-wc0eb:: ds 1
+wChannelVibratoRates:: ; c05e
-wc0ec:: ds 1
+; high nybble is rate (counter reload value) and low nybble is counter.
-wc0ed:: ds 1
+; time between applications of vibrato.
-wc0ee:: ds 1
+	ds 8
-wc0ef:: ds 1
+
-wc0f0:: ds 1
+wChannelFrequencyLowBytes:: ; c066
-wc0f1:: ds 1
+	ds 8
-wc0f2:: ds 14
+
+wChannelVibratoDelayCounterReloadValues:: ; c06e
+; delay of the beginning of the vibrato from the start of the note
+	ds 8
+
+wChannelPitchBendLengthModifiers:: ; c076
+	ds 8
+
+wChannelPitchBendFrequencySteps:: ; c07e
+	ds 8
+
+wChannelPitchBendFrequencyStepsFractionalPart:: ; c086
+	ds 8
+
+wChannelPitchBendCurrentFrequencyFractionalPart:: ; c08e
+	ds 8
+
+wChannelPitchBendCurrentFrequencyHighBytes:: ; c096
+	ds 8
+
+wChannelPitchBendCurrentFrequencyLowBytes:: ; c09e
+	ds 8
+
+wChannelPitchBendTargetFrequencyHighBytes:: ; c0a6
+	ds 8
+
+wChannelPitchBendTargetFrequencyLowBytes:: ; c0ae
+	ds 8
+
+wChannelNoteDelayCounters:: ; c0b6
+; Note delays are stored as 16-bit fixed-point numbers where the integer part
+; is 8 bits and the fractional part is 8 bits.
+	ds 8
+
+wChannelLoopCounters:: ; c0be
+	ds 8
+
+wChannelNoteSpeeds:: ; c0c6
+	ds 8
+
+wChannelNoteDelayCountersFractionalPart:: ; c0ce
+	ds 8
+
+wChannelOctaves:: ; c0d6
+	ds 8
+
+wChannelVolumes:: ; c0de
+; also includes fade for hardware channels that support it
+	ds 8
+
+wMusicWaveInstrument::
+	ds 1
+
+wSfxWaveInstrument::
+	ds 1
+
+wMusicTempo:: ; c0e8
+	ds 2
+
+wSfxTempo:: ; c0ea
+	ds 2
+
+wSfxHeaderPointer:: ; c0ec
+	ds 2
+
+wNewSoundID:: ; c0ee
+	ds 1
+
+wAudioROMBank:: ; c0ef
+	ds 1
+
+wAudioSavedROMBank:: ; c0f0
+	ds 1
+
+wFrequencyModifier:: ; c0f1
+	ds 1
+
+wTempoModifier:: ; c0f2
+	ds 1
+
+	ds 13
 
 
 SECTION "Sprite State Data", WRAM0[$c100]
@@ -1226,8 +1306,10 @@ wItemList:: ; cf7b
 wListPointer:: ; cf8b
 	ds 2
 
-wcf8d:: ds 1 ; used in GetMonName
+wUnusedCF8D:: ; cf8d
-wcf8e:: ds 1 ; also used in GetMonName (probably as a pointer)
+; 2 bytes
+; used to store pointers, but never read
+	ds 2
 
 wItemPrices:: ; cf8f
 	ds 2
@@ -1287,13 +1369,35 @@ wTileInFrontOfPlayer:: ; cfc6
 ; background tile number in front of the player (either 1 or 2 steps ahead)
 	ds 1
 
-wMusicHeaderPointer:: ; cfc7
+wAudioFadeOutControl:: ; cfc7
-; (the current music channel address - $4000) / 3
+; The desired fade counter reload value is stored here prior to calling
+; PlaySound in order to cause the current music to fade out before the new
+; music begins playing. Storing 0 causes no fade out to occur and the new music
+; to begin immediately.
+; This variable has another use related to fade-out, as well. PlaySound stores
+; the sound ID of the music that should be played after the fade-out is finished
+; in this variable. FadeOutAudio checks if it's non-zero every V-Blank and
+; fades out the current audio if it is. Once it has finished fading out the
+; audio, it zeroes this variable and starts playing the sound ID stored in it.
 	ds 1
 
-wcfc8:: ds 1 ; used with audio
+wAudioFadeOutCounterReloadValue:: ; cfc8
-wcfc9:: ds 1 ; also used with audio
+	ds 1
-wcfca:: ds 1 ; also used with audio too
+
+wAudioFadeOutCounter:: ; cfc9
+	ds 1
+
+wLastMusicSoundID:: ; cfca
+; This is used to determine whether the default music is already playing when
+; attempting to play the default music (in order to avoid restarting the same
+; music) and whether the music has already been stopped when attempting to
+; fade out the current music (so that the new music can be begin immediately
+; instead of waiting).
+; It sometimes contains the sound ID of the last music played, but it may also
+; contain $ff (if the music has been stopped) or 0 (because some routines zero
+; it in order to prevent assumptions from being made about the current state of
+; the music).
+	ds 1
 
 wUpdateSpritesEnabled:: ; cfcb
 ; $00 = causes sprites to be hidden and the value to change to $ff
@@ -1789,7 +1893,10 @@ wPredefBank:: ; d0b7
 	ds 1
 
 W_MONHEADER:: ; d0b8
-W_MONHDEXNUM:: ; d0b8
+
+W_MONHINDEX:: ; d0b8
+; In the ROM base stats data stucture, this is the dex number, but it is
+; overwritten with the internal index number after the header is copied to WRAM.
 	ds 1
 
 W_MONHBASESTATS:: ; d0b9
@@ -1882,6 +1989,23 @@ wFirstMonsNotOutYet:: ; d11d
 ; which will be the first mon sent out.
 	ds 1
 
+; lower nybble: number of shakes
+; upper nybble: number of animations to play
+wPokeBallAnimData:: ; d11e
+
+wUsingPPUp:: ; d11e
+
+wMaxPP:: ; d11e
+
+; 0 for player, non-zero for enemy
+wCalculateWhoseStats:: ; d11e
+
+wTypeEffectiveness:: ; d11e
+
+wMoveType:: ; d11e
+
+wNumSetBits:: ; d11e
+
 wd11e:: ds 1 ; used as a Pokemon and Item storage value. Also used as an output value for CountSetBits
 
 wForcePlayerToChooseMon:: ; d11f
@@ -2104,8 +2228,11 @@ wLetterPrintingDelayFlags:: ; d358
 wPlayerID:: ; d359
 	ds 2
 
-wd35b:: ds 1 ; used with audio stuff
+wMapMusicSoundID:: ; d35b
-wd35c:: ds 1 ; storage for audio bank for current map?
+	ds 1
+
+wMapMusicROMBank:: ; d35c
+	ds 1
 
 wMapPalOffset:: ; d35d
 ; offset subtracted from FadePal4 to get the background and object palettes for the current map