Merge remote-tracking branch 'YamaArashi/master'

Conflicts:
	constants/misc_constants.asm
	engine/battle/core.asm
	engine/menu/pokedex.asm
	engine/town_map.asm
	home.asm
	hram.asm

audio.asm

@@ -563,7 +563,7 @@ Func_7d13b:: ; 7d13b (1f:513b)
 	ld a, [hli]
 	ld c, [hl]
 	call PlayMusic
-	jp Func_2307
+	jp PlayDefaultMusic
 
 PokedexRatingSfxPointers: ; 7d162 (1f:5162)
 	db (SFX_1f_51 - SFX_Headers_1f) / 3, BANK(SFX_1f_51)

constants/hardware_constants.asm

@@ -2,27 +2,17 @@
 
 GBC EQU $11
 
-; MBC3
-MBC3SRamEnable EQU $0000
-MBC3RomBank    EQU $2000
-MBC3SRamBank   EQU $4000
-MBC3LatchClock EQU $6000
-MBC3RTC        EQU $a000
+; MBC1
+MBC1SRamEnable      EQU $0000
+MBC1RomBank         EQU $2000
+MBC1SRamBank        EQU $4000
+MBC1SRamBankingMode EQU $6000
 
 SRAM_DISABLE EQU $00
 SRAM_ENABLE  EQU $0a
 
 NUM_SRAM_BANKS EQU 4
 
-RTC_S  EQU $08 ; Seconds   0-59 (0-3Bh)
-RTC_M  EQU $09 ; Minutes   0-59 (0-3Bh)
-RTC_H  EQU $0a ; Hours     0-23 (0-17h)
-RTC_DL EQU $0b ; Lower 8 bits of Day Counter (0-FFh)
-RTC_DH EQU $0c ; Upper 1 bit of Day Counter, Carry Bit, Halt Flag
-        ; Bit 0  Most significant bit of Day Counter (Bit 8)
-        ; Bit 6  Halt (0=Active, 1=Stop Timer)
-        ; Bit 7  Day Counter Carry Bit (1=Counter Overflow)
-
 ; interrupt flags
 VBLANK   EQU 0
 LCD_STAT EQU 1

constants/misc_constants.asm

@@ -22,3 +22,8 @@ D_DOWN   EQU %10000000
 
 SCREEN_WIDTH  EQU 20
 SCREEN_HEIGHT EQU 18
+
+NPC_MOVEMENT_DOWN  EQU $00
+NPC_MOVEMENT_UP    EQU $40
+NPC_MOVEMENT_LEFT  EQU $80
+NPC_MOVEMENT_RIGHT EQU $C0

constants/sprite_constants.asm

@@ -86,4 +86,12 @@ SPRITE_LYING_OLD_MAN             EQU $48
 
 ; different kinds of people events
 ITEM    EQU $80
-TRAINER EQU $40
+TRAINER EQU $40
+
+BOULDER_MOVEMENT_BYTE_2 EQU $10
+
+; sprite facing directions
+SPRITE_FACING_DOWN  EQU $00
+SPRITE_FACING_UP    EQU $04
+SPRITE_FACING_LEFT  EQU $08
+SPRITE_FACING_RIGHT EQU $0C

data/mapObjects/fuchsiahouse2.asm

@@ -12,7 +12,7 @@ FuchsiaHouse2Object: ; 0x75180 (size=45)
 	db $3 ; people
 	db SPRITE_WARDEN, $3 + 4, $2 + 4, $ff, $ff, $1 ; person
 	db SPRITE_BALL, $3 + 4, $8 + 4, $ff, $ff, ITEM | $2, RARE_CANDY
-	db SPRITE_BOULDER, $4 + 4, $8 + 4, $ff, $10, $3 ; person
+	db SPRITE_BOULDER, $4 + 4, $8 + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $3 ; person
 
 	; warp-to
 	EVENT_DISP FUCHSIA_HOUSE_2_WIDTH, $7, $4

data/mapObjects/seafoamislands1.asm

@@ -13,8 +13,8 @@ SeafoamIslands1Object: ; 0x4484f (size=72)
 	db $0 ; signs
 
 	db $2 ; people
-	db SPRITE_BOULDER, $a + 4, $12 + 4, $ff, $10, $1 ; person
-	db SPRITE_BOULDER, $7 + 4, $1a + 4, $ff, $10, $2 ; person
+	db SPRITE_BOULDER, $a + 4, $12 + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $1 ; person
+	db SPRITE_BOULDER, $7 + 4, $1a + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $2 ; person
 
 	; warp-to
 	EVENT_DISP SEAFOAM_ISLANDS_1_WIDTH, $11, $4

data/mapObjects/seafoamislands2.asm

@@ -13,8 +13,8 @@ SeafoamIslands2Object: ; 0x46376 (size=72)
 	db $0 ; signs
 
 	db $2 ; people
-	db SPRITE_BOULDER, $6 + 4, $11 + 4, $ff, $10, $1 ; person
-	db SPRITE_BOULDER, $6 + 4, $16 + 4, $ff, $10, $2 ; person
+	db SPRITE_BOULDER, $6 + 4, $11 + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $1 ; person
+	db SPRITE_BOULDER, $6 + 4, $16 + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $2 ; person
 
 	; warp-to
 	EVENT_DISP SEAFOAM_ISLANDS_2_WIDTH, $2, $4 ; SEAFOAM_ISLANDS_3

data/mapObjects/seafoamislands3.asm

@@ -13,8 +13,8 @@ SeafoamIslands3Object: ; 0x464b2 (size=72)
 	db $0 ; signs
 
 	db $2 ; people
-	db SPRITE_BOULDER, $6 + 4, $12 + 4, $ff, $10, $1 ; person
-	db SPRITE_BOULDER, $6 + 4, $17 + 4, $ff, $10, $2 ; person
+	db SPRITE_BOULDER, $6 + 4, $12 + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $1 ; person
+	db SPRITE_BOULDER, $6 + 4, $17 + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $2 ; person
 
 	; warp-to
 	EVENT_DISP SEAFOAM_ISLANDS_3_WIDTH, $3, $5 ; SEAFOAM_ISLANDS_2

data/mapObjects/seafoamislands4.asm

@@ -13,10 +13,10 @@ SeafoamIslands4Object: ; 0x466a6 (size=96)
 	db $0 ; signs
 
 	db $6 ; people
-	db SPRITE_BOULDER, $e + 4, $5 + 4, $ff, $10, $1 ; person
-	db SPRITE_BOULDER, $f + 4, $3 + 4, $ff, $10, $2 ; person
-	db SPRITE_BOULDER, $e + 4, $8 + 4, $ff, $10, $3 ; person
-	db SPRITE_BOULDER, $e + 4, $9 + 4, $ff, $10, $4 ; person
+	db SPRITE_BOULDER, $e + 4, $5 + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $1 ; person
+	db SPRITE_BOULDER, $f + 4, $3 + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $2 ; person
+	db SPRITE_BOULDER, $e + 4, $8 + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $3 ; person
+	db SPRITE_BOULDER, $e + 4, $9 + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $4 ; person
 	db SPRITE_BOULDER, $6 + 4, $12 + 4, $ff, $ff, $5 ; person
 	db SPRITE_BOULDER, $6 + 4, $13 + 4, $ff, $ff, $6 ; person
 

data/mapObjects/victoryroad1.asm

@@ -13,9 +13,9 @@ VictoryRoad1Object: ; 0x5dab8 (size=76)
 	db SPRITE_BLACK_HAIR_BOY_1, $2 + 4, $3 + 4, $ff, $d0, TRAINER | $2, COOLTRAINER_M + $C8, $5
 	db SPRITE_BALL, $0 + 4, $b + 4, $ff, $ff, ITEM | $3, TM_43
 	db SPRITE_BALL, $2 + 4, $9 + 4, $ff, $ff, ITEM | $4, RARE_CANDY
-	db SPRITE_BOULDER, $f + 4, $5 + 4, $ff, $10, $5 ; person
-	db SPRITE_BOULDER, $2 + 4, $e + 4, $ff, $10, $6 ; person
-	db SPRITE_BOULDER, $a + 4, $2 + 4, $ff, $10, $7 ; person
+	db SPRITE_BOULDER, $f + 4, $5 + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $5 ; person
+	db SPRITE_BOULDER, $2 + 4, $e + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $6 ; person
+	db SPRITE_BOULDER, $a + 4, $2 + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $7 ; person
 
 	; warp-to
 	EVENT_DISP VICTORY_ROAD_1_WIDTH, $11, $8

data/mapObjects/victoryroad2.asm

@@ -23,9 +23,9 @@ VictoryRoad2Object: ; 0x51915 (size=154)
 	db SPRITE_BALL, $9 + 4, $12 + 4, $ff, $ff, ITEM | $8, FULL_HEAL
 	db SPRITE_BALL, $b + 4, $9 + 4, $ff, $ff, ITEM | $9, TM_05
 	db SPRITE_BALL, $0 + 4, $b + 4, $ff, $ff, ITEM | $a, GUARD_SPEC_
-	db SPRITE_BOULDER, $e + 4, $4 + 4, $ff, $10, $b ; person
-	db SPRITE_BOULDER, $5 + 4, $5 + 4, $ff, $10, $c ; person
-	db SPRITE_BOULDER, $10 + 4, $17 + 4, $ff, $10, $d ; person
+	db SPRITE_BOULDER, $e + 4, $4 + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $b ; person
+	db SPRITE_BOULDER, $5 + 4, $5 + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $c ; person
+	db SPRITE_BOULDER, $10 + 4, $17 + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $d ; person
 
 	; warp-to
 	EVENT_DISP VICTORY_ROAD_2_WIDTH, $8, $0 ; VICTORY_ROAD_1

data/mapObjects/victoryroad3.asm

@@ -16,10 +16,10 @@ VictoryRoad3Object: ; 0x44acd (size=106)
 	db SPRITE_LASS, $3 + 4, $d + 4, $ff, $d3, TRAINER | $4, COOLTRAINER_F + $C8, $3
 	db SPRITE_BALL, $5 + 4, $1a + 4, $ff, $ff, ITEM | $5, MAX_REVIVE
 	db SPRITE_BALL, $7 + 4, $7 + 4, $ff, $ff, ITEM | $6, TM_47
-	db SPRITE_BOULDER, $3 + 4, $16 + 4, $ff, $10, $7 ; person
-	db SPRITE_BOULDER, $c + 4, $d + 4, $ff, $10, $8 ; person
-	db SPRITE_BOULDER, $a + 4, $18 + 4, $ff, $10, $9 ; person
-	db SPRITE_BOULDER, $f + 4, $16 + 4, $ff, $10, $a ; person
+	db SPRITE_BOULDER, $3 + 4, $16 + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $7 ; person
+	db SPRITE_BOULDER, $c + 4, $d + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $8 ; person
+	db SPRITE_BOULDER, $a + 4, $18 + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $9 ; person
+	db SPRITE_BOULDER, $f + 4, $16 + 4, $ff, BOULDER_MOVEMENT_BYTE_2, $a ; person
 
 	; warp-to
 	EVENT_DISP VICTORY_ROAD_3_WIDTH, $7, $17 ; VICTORY_ROAD_2

data/special_warps.asm

@@ -1,3 +1,6 @@
+; Format: (size 2 bytes)
+; 00: target map ID
+; 01: which dungeon warp in the source map was used
 DungeonWarpList: ; 63bf (1:63bf)
 	db SEAFOAM_ISLANDS_2,$01
 	db SEAFOAM_ISLANDS_2,$02

engine/HoF_room_pc.asm

@@ -92,7 +92,7 @@ DisplayCreditsMon: ; 740cb (1d:40cb)
 	dec c
 	jr nz,.next2
 	xor a
-	ld [$FFB0],a
+	ld [hVBlankWY],a
 	ld a,$C0
 	ld [$FF47],a
 	ret

engine/battle/1.asm

@@ -75,8 +75,8 @@ Func_7861: ; 7861 (1:7861)
 .asm_78aa
 	ld [wListMenuID], a ; wListMenuID
 	predef UpdateHPBar2
-	predef Func_3cd60
-	predef Func_3cdec
+	predef DrawPlayerHUDAndHPBar
+	predef DrawEnemyHUDAndHPBar
 	callab ReadPlayerMonCurHPAndStatus
 	ld hl, SuckedHealthText ; $78dc
 	ld a, [H_WHOSETURN] ; $fff3

engine/battle/14.asm

@@ -1,21 +1,21 @@
 Func_525af: ; 525af (14:65af)
-	ld a, [$ffd7]
+	ld a, [hTilesetType]
 	ld [wd0d4], a
 	xor a
 	ld [wcd6a], a
-	ld [wcf0b], a
+	ld [wBattleResult], a
 	ld hl, wcc2b
 	ld [hli], a
 	ld [hli], a
 	ld [hli], a
 	ld [hl], a
 	ld [wListScrollOffset], a ; wcc36
-	ld [wd05e], a
+	ld [wCriticalHitOrOHKO], a
 	ld [wBattleMonSpecies], a
-	ld [wPartyAliveFlags], a
+	ld [wPartyGainExpFlags], a
 	ld [wPlayerMonNumber], a ; wPlayerMonNumber
-	ld [wd078], a
-	ld [wd35d], a
+	ld [wEscapedFromBattle], a
+	ld [wMapPalOffset], a
 	ld hl, wcf1d
 	ld [hli], a
 	ld [hl], a
@@ -73,7 +73,7 @@ ParalyzeEffect_: ; 52601 (14:6601)
 	and a
 	jr nz, .asm_52659
 	set 6, [hl]
-	callab Func_3ed27
+	callab QuarterSpeedDueToParalysis
 	ld c, $1e
 	call DelayFrames
 	callab Func_3fba8

engine/battle/15.asm

@@ -1,63 +1,63 @@
 GainExperience: ; 5524f (15:524f)
 	ld a, [W_ISLINKBATTLE]
 	cp $4
-	ret z
-	call Func_5546c
-	ld hl, wPartyMons
+	ret z ; return if link battle
+	call DivideExpDataByNumMonsGainingExp
+	ld hl, wPartyMon1
 	xor a
 	ld [wWhichPokemon], a
-
-Func_5525f: ; 5525f (15:525f)
+.partyMonLoop ; loop over each mon and add gained exp
 	inc hl
 	ld a, [hli]
-	or [hl]
-	jp z, Func_55436
+	or [hl] ; is mon's HP 0?
+	jp z, .nextMon ; if so, go to next mon
 	push hl
-	ld hl, wPartyAliveFlags
+	ld hl, wPartyGainExpFlags
 	ld a, [wWhichPokemon]
 	ld c, a
 	ld b, $2
 	predef FlagActionPredef
 	ld a, c
-	and a
+	and a ; is mon's gain exp flag set?
 	pop hl
-	jp z, Func_55436
-	ld de, $10
+	jp z, .nextMon ; if mon's gain exp flag not set, go to next mon
+	ld de, (wPartyMon1HPExp + 1) - (wPartyMon1HP + 1)
 	add hl, de
 	ld d, h
 	ld e, l
-	ld hl, wd002
+	ld hl, wEnemyMonBaseStats
 	ld c, $5
-.asm_55285
+.gainStatExpLoop
 	ld a, [hli]
-	ld b, a
-	ld a, [de]
-	add b
+	ld b, a ; enemy mon base stat
+	ld a, [de] ; stat exp
+	add b ; add enemy mon base state to stat exp
 	ld [de], a
-	jr nc, .asm_5529a
+	jr nc, .nextBaseStat
+; if there was a carry, increment the upper byte
 	dec de
 	ld a, [de]
 	inc a
-	jr z, .asm_55295
+	jr z, .maxStatExp ; jump if the value overflowed
 	ld [de], a
 	inc de
-	jr .asm_5529a
-.asm_55295
+	jr .nextBaseStat
+.maxStatExp ; if the upper byte also overflowed, then we have hit the max stat exp
 	ld a, $ff
 	ld [de], a
 	inc de
 	ld [de], a
-.asm_5529a
+.nextBaseStat
 	dec c
 	jr z, .asm_552a1
 	inc de
 	inc de
-	jr .asm_55285
+	jr .gainStatExpLoop
 .asm_552a1
 	xor a
 	ld [H_MULTIPLICAND], a
 	ld [H_MULTIPLICAND + 1], a
-	ld a, [wd008]
+	ld a, [wEnemyMonBaseExp]
 	ld [H_MULTIPLICAND + 2], a
 	ld a, [wEnemyMonLevel]
 	ld [H_MULTIPLIER], a
@@ -66,44 +66,46 @@ Func_5525f: ; 5525f (15:525f)
 	ld [H_DIVISOR], a
 	ld b, 4
 	call Divide
-	ld hl, $fff2
+	ld hl, -((wPartyMon1HPExp + 1) - wPartyMon1OTID + 4 * 2)
 	add hl, de
-	ld b, [hl]
+	ld b, [hl] ; party mon OTID
 	inc hl
 	ld a, [wPlayerID]
 	cp b
-	jr nz, .asm_552d1
+	jr nz, .tradedMon
 	ld b, [hl]
 	ld a, [wPlayerID + 1]
 	cp b
 	ld a, $0
-	jr z, .asm_552d6
-.asm_552d1
-	call Func_5549f
+	jr z, .next
+.tradedMon
+	call BoostExp ; traded mon exp boost
 	ld a, $1
-.asm_552d6
+.next
 	ld [wcf4d], a
 	ld a, [W_ISINBATTLE]
-	dec a
-	call nz, Func_5549f
+	dec a ; is it a trainer battle?
+	call nz, BoostExp ; if so, boost exp
 	inc hl
 	inc hl
 	inc hl
+; add the gained exp to the party mon's exp
 	ld b, [hl]
-	ld a, [$ff98]
+	ld a, [H_QUOTIENT + 3]
 	ld [wcf4c], a
 	add b
 	ld [hld], a
 	ld b, [hl]
-	ld a, [$ff97]
+	ld a, [H_QUOTIENT + 2]
 	ld [wcf4b], a
 	adc b
 	ld [hl], a
-	jr nc, .asm_552f8
+	jr nc, .noCarry
 	dec hl
 	inc [hl]
 	inc hl
-.asm_552f8
+.noCarry
+; calculate exp for the mon at max level, and cap the exp at that value
 	inc hl
 	push hl
 	ld a, [wWhichPokemon]
@@ -111,11 +113,12 @@ Func_5525f: ; 5525f (15:525f)
 	ld b, 0
 	ld hl, wPartySpecies
 	add hl, bc
-	ld a, [hl]
+	ld a, [hl] ; species
 	ld [wd0b5], a
 	call GetMonHeader
 	ld d, MAX_LEVEL
-	callab CalcExperience
+	callab CalcExperience ; get max exp
+; compare max exp with current exp
 	ld a, [$ff96]
 	ld b, a
 	ld a, [$ff97]
@@ -129,7 +132,8 @@ Func_5525f: ; 5525f (15:525f)
 	sbc c
 	ld a, [hl]
 	sbc b
-	jr c, .asm_5532e
+	jr c, .next2
+; the mon's exp is greater than the max exp, so overwrite it with the max exp
 	ld a, b
 	ld [hli], a
 	ld a, c
@@ -137,103 +141,108 @@ Func_5525f: ; 5525f (15:525f)
 	ld a, d
 	ld [hld], a
 	dec hl
-.asm_5532e
+.next2
 	push hl
 	ld a, [wWhichPokemon]
 	ld hl, wPartyMonNicks
 	call GetPartyMonName
 	ld hl, GainedText
 	call PrintText
-	xor a
+	xor a ; party mon data
 	ld [wcc49], a
 	call LoadMonData
 	pop hl
-	ld bc, $13
+	ld bc, wPartyMon1Level - wPartyMon1Exp
 	add hl, bc
 	push hl
-	callba Func_58f43
+	callba CalcLevelFromExperience
 	pop hl
-	ld a, [hl]
+	ld a, [hl] ; current level
 	cp d
-	jp z, Func_55436
+	jp z, .nextMon ; if level didn't change, go to next mon
 	ld a, [W_CURENEMYLVL]
 	push af
 	push hl
 	ld a, d
 	ld [W_CURENEMYLVL], a
 	ld [hl], a
-	ld bc, $ffdf
+	ld bc, wPartyMon1Species - wPartyMon1Level
 	add hl, bc
-	ld a, [hl]
+	ld a, [hl] ; species
 	ld [wd0b5], a
 	ld [wd11e], a
 	call GetMonHeader
-	ld bc, $23
+	ld bc, (wPartyMon1MaxHP + 1) - wPartyMon1Species
 	add hl, bc
 	push hl
 	ld a, [hld]
 	ld c, a
 	ld b, [hl]
-	push bc
+	push bc ; push max HP (from before levelling up)
 	ld d, h
 	ld e, l
-	ld bc, $ffee
+	ld bc, (wPartyMon1HPExp - 1) - wPartyMon1MaxHP
 	add hl, bc
-	ld b, $1
+	ld b, $1 ; consider stat exp when calculating stats
 	call CalcStats
-	pop bc
+	pop bc ; pop max HP (from before levelling up)
 	pop hl
 	ld a, [hld]
 	sub c
 	ld c, a
 	ld a, [hl]
 	sbc b
-	ld b, a
-	ld de, $ffe0
+	ld b, a ; bc = difference between old max HP and new max HP after levelling
+	ld de, (wPartyMon1HP + 1) - wPartyMon1MaxHP
 	add hl, de
-	ld a, [hl]
+; add to the current HP the amount of max HP gained when levelling
+	ld a, [hl] ; wPartyMon1HP + 1
 	add c
 	ld [hld], a
-	ld a, [hl]
+	ld a, [hl] ; wPartyMon1HP + 1
 	adc b
-	ld [hl], a
+	ld [hl], a ; wPartyMon1HP
 	ld a, [wPlayerMonNumber]
 	ld b, a
 	ld a, [wWhichPokemon]
-	cp b
-	jr nz, .asm_553f7
+	cp b ; is the current mon in battle?
+	jr nz, .printGrewLevelText
+; current mon is in battle
 	ld de, wBattleMonHP
+; copy party mon HP to battle mon HP
 	ld a, [hli]
 	ld [de], a
 	inc de
 	ld a, [hl]
 	ld [de], a
-	ld bc, $1f
+; copy other stats from party mon to battle mon
+	ld bc, wPartyMon1Level - (wPartyMon1HP + 1)
 	add hl, bc
 	push hl
-	ld de, wBattleMonLevel ; wBattleMonLevel
-	ld bc, $b
+	ld de, wBattleMonLevel
+	ld bc, $b ; size of stats
 	call CopyData
 	pop hl
-	ld a, [W_PLAYERBATTSTATUS3] ; W_PLAYERBATTSTATUS3
-	bit 3, a
-	jr nz, .asm_553c8
+	ld a, [W_PLAYERBATTSTATUS3]
+	bit 3, a ; is the mon transformed?
+	jr nz, .recalcStatChanges
+; the mon is transformed, so copy transformed data
 	ld de, wcd0f
 	ld bc, $b
 	call CopyData
-.asm_553c8
+.recalcStatChanges
 	xor a
 	ld [wd11e], a
-	callab Func_3ed99
-	callab Func_3ed1a
-	callab Func_3ee19
-	callab Func_3cd60
-	callab Func_3ee94
+	callab CalculateModifiedStats
+	callab ApplyBurnAndParalysisPenaltiesToPlayer
+	callab ApplyBadgeStatBoosts
+	callab DrawPlayerHUDAndHPBar
+	callab PrintEmptyString
 	call SaveScreenTilesToBuffer1
-.asm_553f7
+.printGrewLevelText
 	ld hl, GrewLevelText
 	call PrintText
-	xor a
+	xor a ; party mon data
 	ld [wcc49], a
 	call LoadMonData
 	ld d, $1
@@ -244,88 +253,90 @@ Func_5525f: ; 5525f (15:525f)
 	ld [wcc49], a
 	ld a, [wd0b5]
 	ld [wd11e], a
-	predef Func_3af5b
+	predef LearnMoveFromLevelUp
 	ld hl, wccd3
-	ld a, [wWhichPokemon] ; wWhichPokemon
+	ld a, [wWhichPokemon]
 	ld c, a
 	ld b, $1
 	predef FlagActionPredef
 	pop hl
 	pop af
-	ld [W_CURENEMYLVL], a ; W_CURENEMYLVL
+	ld [W_CURENEMYLVL], a
 
-Func_55436: ; 55436 (15:5436)
-	ld a, [wPartyCount] ; wPartyCount
+.nextMon
+	ld a, [wPartyCount]
 	ld b, a
-	ld a, [wWhichPokemon] ; wWhichPokemon
+	ld a, [wWhichPokemon]
 	inc a
 	cp b
-	jr z, .asm_55450
-	ld [wWhichPokemon], a ; wWhichPokemon
-	ld bc, $2c
-	ld hl, wPartyMon1Species ; wPartyMon1Species (aliases: wPartyMon1)
+	jr z, .done
+	ld [wWhichPokemon], a
+	ld bc, wPartyMon2 - wPartyMon1
+	ld hl, wPartyMon1
 	call AddNTimes
-	jp Func_5525f
-.asm_55450
-	ld hl, wPartyAliveFlags
+	jp .partyMonLoop
+.done
+	ld hl, wPartyGainExpFlags
 	xor a
-	ld [hl], a
-	ld a, [wPlayerMonNumber] ; wPlayerMonNumber
+	ld [hl], a ; clear gain exp flags
+	ld a, [wPlayerMonNumber]
 	ld c, a
 	ld b, $1
 	push bc
-	predef FlagActionPredef
-	ld hl, wccf5
+	predef FlagActionPredef ; set the gain exp flag for the mon that is currently out
+	ld hl, wPartyFoughtCurrentEnemyFlags
 	xor a
 	ld [hl], a
 	pop bc
-	predef_jump FlagActionPredef
+	predef_jump FlagActionPredef ; set the fought current enemy flag for the mon that is currently out
 
-Func_5546c: ; 5546c (15:546c)
-	ld a, [wPartyAliveFlags]
+; divide enemy base stats, catch rate, and base exp by the number of mons gaining exp
+DivideExpDataByNumMonsGainingExp: ; 5546c (15:546c)
+	ld a, [wPartyGainExpFlags]
 	ld b, a
 	xor a
 	ld c, $8
 	ld d, $0
-.asm_55475
+.countSetBitsLoop ; loop to count set bits in wPartyGainExpFlags
 	xor a
 	srl b
 	adc d
 	ld d, a
 	dec c
-	jr nz, .asm_55475
+	jr nz, .countSetBitsLoop
 	cp $2
-	ret c
-	ld [wd11e], a
-	ld hl, wd002
+	ret c ; return if only one mon is gaining exp
+	ld [wd11e], a ; store number of mons gaining exp
+	ld hl, wEnemyMonBaseStats
 	ld c, $7
-.asm_55488
+.divideLoop
 	xor a
-	ld [H_DIVIDEND], a ; $ff95 (aliases: H_PRODUCT, H_PASTLEADINGZEROES, H_QUOTIENT)
+	ld [H_DIVIDEND], a
 	ld a, [hl]
-	ld [H_NUMTOPRINT], a ; $ff96 (aliases: H_MULTIPLICAND)
+	ld [H_DIVIDEND + 1], a
 	ld a, [wd11e]
-	ld [H_REMAINDER], a ; $ff99 (aliases: H_DIVISOR, H_MULTIPLIER, H_POWEROFTEN)
+	ld [H_DIVISOR], a
 	ld b, $2
-	call Divide
-	ld a, [$ff98]
+	call Divide ; divide value by number of mons gaining exp
+	ld a, [H_QUOTIENT + 3]
 	ld [hli], a
 	dec c
-	jr nz, .asm_55488
+	jr nz, .divideLoop
 	ret
 
-Func_5549f: ; 5549f (15:549f)
-	ld a, [$ff97]
+; multiplies exp by 1.5
+BoostExp: ; 5549f (15:549f)
+	ld a, [H_QUOTIENT + 2]
 	ld b, a
-	ld a, [$ff98]
+	ld a, [H_QUOTIENT + 3]
 	ld c, a
 	srl b
 	rr c
 	add c
-	ld [$ff98], a
-	ld a, [$ff97]
+	ld [H_QUOTIENT + 3], a
+	ld a, [H_QUOTIENT + 2]
 	adc b
-	ld [$ff97], a
+	ld [H_QUOTIENT + 2], a
 	ret
 
 GainedText: ; 554b2 (15:54b2)

engine/battle/16.asm

@@ -38,7 +38,7 @@ PrintBeginningBattleText: ; 58d99 (16:4d99)
 	ld a, b
 	and a
 	jr z, .noSilphScope
-	callab Func_3eb01
+	callab LoadEnemyMonData
 	jr .notPokemonTower
 .noSilphScope
 	ld hl, EnemyAppearedText
@@ -54,7 +54,7 @@ PrintBeginningBattleText: ; 58d99 (16:4d99)
 	call PrintText
 	ld hl, UnveiledGhostText
 	call PrintText
-	callab Func_3eb01
+	callab LoadEnemyMonData
 	callab Func_708ca
 	ld hl, WildMonAppearedText
 	call PrintText
@@ -94,25 +94,25 @@ GhostCantBeIDdText: ; 58e54 (16:4e54)
 	TX_FAR _GhostCantBeIDdText
 	db "@"
 
-SendOutMon: ; 58e59 (16:4e59)
-	ld hl, wEnemyMonHP ; wEnemyMonHP
+PrintSendOutMonMessage: ; 58e59 (16:4e59)
+	ld hl, wEnemyMonHP
 	ld a, [hli]
 	or [hl]
 	ld hl, GoText
 	jr z, .printText
 	xor a
-	ld [H_NUMTOPRINT], a ; $ff96 (aliases: H_MULTIPLICAND)
-	ld hl, wEnemyMonHP ; wEnemyMonHP
+	ld [H_MULTIPLICAND], a
+	ld hl, wEnemyMonHP
 	ld a, [hli]
 	ld [wcce3], a
-	ld [$ff97], a
+	ld [H_MULTIPLICAND + 1], a
 	ld a, [hl]
 	ld [wcce4], a
-	ld [$ff98], a
-	ld a, $19
-	ld [H_REMAINDER], a ; $ff99 (aliases: H_DIVISOR, H_MULTIPLIER, H_POWEROFTEN)
+	ld [H_MULTIPLICAND + 2], a
+	ld a, 25
+	ld [H_MULTIPLIER], a
 	call Multiply
-	ld hl, wEnemyMonMaxHP ; wEnemyMonMaxHP
+	ld hl, wEnemyMonMaxHP
 	ld a, [hli]
 	ld b, [hl]
 	srl a
@@ -121,19 +121,19 @@ SendOutMon: ; 58e59 (16:4e59)
 	rr b
 	ld a, b
 	ld b, $4
-	ld [H_REMAINDER], a ; $ff99 (aliases: H_DIVISOR, H_MULTIPLIER, H_POWEROFTEN)
+	ld [H_DIVISOR], a ; enemy mon max HP divided by 4
 	call Divide
-	ld a, [$ff98]
-	ld hl, GoText
-	cp $46
+	ld a, [H_QUOTIENT + 3] ; a = (enemy mon current HP * 25) / (enemy max HP / 4); this approximates the current percentage of max HP
+	ld hl, GoText ; 70% or greater
+	cp 70
 	jr nc, .printText
-	ld hl, DoItText
-	cp $28
+	ld hl, DoItText ; 40% - 69%
+	cp 40
 	jr nc, .printText
-	ld hl, GetmText
-	cp $a
+	ld hl, GetmText ; 10% - 39%
+	cp 10
 	jr nc, .printText
-	ld hl, EnemysWeakText
+	ld hl, EnemysWeakText ; 0% - 9%
 .printText
 	jp PrintText
 

engine/battle/1c.asm

@@ -87,9 +87,9 @@ BattleTransition: ; 7096d (1c:496d)
 	ld [H_AUTOBGTRANSFERENABLED], a
 	call Delay3
 	xor a
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	dec a
-	ld [wcfcb], a
+	ld [wUpdateSpritesEnabled], a
 	call DelayFrame
 	ld hl, wSpriteStateData1 + 2
 	ld a, [H_DOWNARROWBLINKCNT2]

engine/battle/4_2.asm

@@ -1,76 +1,77 @@
-Func_137aa: ; 137aa (4:77aa)
-	ld a, [W_ISLINKBATTLE] ; W_ISLINKBATTLE
+EndOfBattle: ; 137aa (4:77aa)
+	ld a, [W_ISLINKBATTLE]
 	cp $4
-	jr nz, .asm_137eb
+	jr nz, .notLinkBattle
+; link battle
 	ld a, [wEnemyMonPartyPos]
 	ld hl, wEnemyMon1Status
 	ld bc, wEnemyMon2 - wEnemyMon1
 	call AddNTimes
-	ld a, [wEnemyMonStatus] ; wcfe9
+	ld a, [wEnemyMonStatus]
 	ld [hl], a
 	call ClearScreen
-	callab Func_372d6
-	ld a, [wcf0b]
+	callab DisplayLinkBattleVersusTextBox
+	ld a, [wBattleResult]
 	cp $1
 	ld de, YouWinText
-	jr c, .asm_137de
+	jr c, .placeWinOrLoseString
 	ld de, YouLoseText
-	jr z, .asm_137de
+	jr z, .placeWinOrLoseString
 	ld de, DrawText
-.asm_137de
+.placeWinOrLoseString
 	hlCoord 6, 8
 	call PlaceString
 	ld c, $c8
 	call DelayFrames
-	jr .asm_1380a
-.asm_137eb
-	ld a, [wcf0b]
+	jr .evolution
+.notLinkBattle
+	ld a, [wBattleResult]
 	and a
-	jr nz, .asm_13813
-	ld hl, wcce5
+	jr nz, .resetVariables
+	ld hl, wTotalPayDayMoney
 	ld a, [hli]
 	or [hl]
 	inc hl
 	or [hl]
-	jr z, .asm_1380a
-	ld de, wPlayerMoney + 2 ; wd349
+	jr z, .evolution ; if pay day money is 0, jump
+	ld de, wPlayerMoney + 2
 	ld c, $3
 	predef AddBCDPredef
 	ld hl, PickUpPayDayMoneyText
 	call PrintText
-.asm_1380a
+.evolution
 	xor a
 	ld [wccd4], a
-	predef Func_3ad1c
-.asm_13813
+	predef EvolutionAfterBattle
+.resetVariables
 	xor a
 	ld [wd083], a
 	ld [wc02a], a
-	ld [W_ISINBATTLE], a ; W_ISINBATTLE
-	ld [W_BATTLETYPE], a ; wd05a
-	ld [W_MOVEMISSED], a ; W_MOVEMISSED
-	ld [W_CUROPPONENT], a ; wd059
+	ld [W_ISINBATTLE], a
+	ld [W_BATTLETYPE], a
+	ld [W_MOVEMISSED], a
+	ld [W_CUROPPONENT], a
 	ld [wd11f], a
-	ld [wd120], a
-	ld [wd078], a
+	ld [wNumRunAttempts], a
+	ld [wEscapedFromBattle], a
 	ld hl, wcc2b
 	ld [hli], a
 	ld [hli], a
 	ld [hli], a
 	ld [hl], a
-	ld [wListScrollOffset], a ; wcc36
+	ld [wListScrollOffset], a
 	ld hl, wd060
 	ld b, $18
-.asm_1383e
+.loop
 	ld [hli], a
 	dec b
-	jr nz, .asm_1383e
+	jr nz, .loop
 	ld hl, wd72c
 	set 0, [hl]
 	call WaitForSoundToFinish
 	call GBPalWhiteOut
 	ld a, $ff
-	ld [wd42f], a
+	ld [wDestinationWarpID], a
 	ret
 
 YouWinText: ; 13853 (4:7853)
@@ -87,13 +88,13 @@ PickUpPayDayMoneyText: ; 1386b (4:786b)
 	db "@"
 
 Func_13870: ; 13870 (4:7870)
-	ld a, [wcc57]
+	ld a, [wNPCMovementScriptPointerTableNum]
 	and a
 	ret nz
 	ld a, [wd736]
 	and a
 	ret nz
-	callab Func_c49d
+	callab IsPlayerStandingOnDoorTileOrWarpTile
 	jr nc, .asm_13888
 .asm_13884
 	ld a, $1
@@ -307,7 +308,7 @@ HazeEffect_: ; 139da (4:79da)
 	ld hl, wcd12
 	ld de, wBattleMonAttack
 	call Func_13a4a
-	ld hl, wcd26
+	ld hl, wEnemyMonUnmodifiedAttack
 	ld de, wEnemyMonAttack
 	call Func_13a4a
 	ld hl, wEnemyMonStatus

engine/battle/5.asm

@@ -53,8 +53,8 @@ SubstituteEffectHandler: ; 17dad (5:7dad)
 	call Bankswitch           ;jump to routine depending on animation setting
 	ld hl, SubstituteText
 	call PrintText
-	ld hl, Func_3cd5a
-	ld b, BANK(Func_3cd5a)
+	ld hl, DrawHUDsAndHPBars
+	ld b, BANK(DrawHUDsAndHPBars)
 	jp Bankswitch
 .alreadyHasSubstitute
 	ld hl, HasSubstituteText

engine/battle/animations.asm

@@ -517,7 +517,7 @@ Func_78e01: ; 78e01 (1e:4e01)
 	ret
 
 Func_78e23: ; 78e23 (1e:4e23)
-	ld a, [wcf1b]
+	ld a, [wOnSGB]
 	and a
 	ld a, $e4
 	jr z, .asm_78e47
@@ -1091,7 +1091,7 @@ CallWithTurnFlipped: ; 79155 (1e:5155)
 AnimationFlashScreenLong: ; 79165 (1e:5165)
 	ld a,3 ; cycle through the palettes 3 times
 	ld [wd08a],a
-	ld a,[wcf1b] ; running on SGB?
+	ld a,[wOnSGB] ; running on SGB?
 	and a
 	ld hl,FlashScreenLongMonochrome
 	jr z,.loop
@@ -1211,7 +1211,7 @@ Func_791f9: ; 791f9 (1e:51f9)
 	ld bc, $4040
 
 Func_791fc: ; 791fc (1e:51fc)
-	ld a, [wcf1b]
+	ld a, [wOnSGB]
 	and a
 	ld a, b
 	jr z, .asm_79204
@@ -1411,50 +1411,50 @@ Func_79329: ; 79329 (1e:5329)
 	ld [hli], a
 	ret
 
-Func_79337: ; 79337 (1e:5337)
+AdjustOAMBlockXPos: ; 79337 (1e:5337)
 	ld l, e
 	ld h, d
 
-Func_79339: ; 79339 (1e:5339)
+AdjustOAMBlockXPos2: ; 79339 (1e:5339)
 	ld de, $4
-.asm_7933c
+.loop
 	ld a, [wd08a]
 	ld b, a
 	ld a, [hl]
 	add b
 	cp $a8
-	jr c, .asm_7934a
+	jr c, .skipPuttingEntryOffScreen
 	dec hl
 	ld a, $a0
 	ld [hli], a
-.asm_7934a
+.skipPuttingEntryOffScreen
 	ld [hl], a
 	add hl, de
 	dec c
-	jr nz, .asm_7933c
+	jr nz, .loop
 	ret
 
-Func_79350: ; 79350 (1e:5350)
+AdjustOAMBlockYPos: ; 79350 (1e:5350)
 	ld l, e
 	ld h, d
 
-Func_79352: ; 79352 (1e:5352)
+AdjustOAMBlockYPos2: ; 79352 (1e:5352)
 	ld de, $4
-.asm_79355
+.loop
 	ld a, [wd08a]
 	ld b, a
 	ld a, [hl]
 	add b
 	cp $70
-	jr c, .asm_79363
+	jr c, .skipSettingPreviousEntrysAttribute
 	dec hl
-	ld a, $a0
+	ld a, $a0 ; bug, sets previous OAM entry's attribute
 	ld [hli], a
-.asm_79363
+.skipSettingPreviousEntrysAttribute
 	ld [hl], a
 	add hl, de
 	dec c
-	jr nz, .asm_79355
+	jr nz, .loop
 	ret
 
 AnimationBlinkEnemyMon: ; 79369 (1e:5369)
@@ -1962,7 +1962,7 @@ AnimationWavyScreen: ; 79666 (1e:5666)
 	xor a
 	ld [H_AUTOBGTRANSFERENABLED], a
 	ld a, $90
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	ld d, $80
 	ld e, $8f
 	ld c, $ff
@@ -1984,7 +1984,7 @@ AnimationWavyScreen: ; 79666 (1e:5666)
 	dec c
 	jr nz, .asm_7967f
 	xor a
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	call SaveScreenTilesToBuffer2
 	call ClearScreen
 	ld a, $1
@@ -2744,11 +2744,11 @@ AnimationShakeEnemyHUD: ; 79d77 (1e:5d77)
 	ld hl, vBGMap0
 	call Func_79e0d
 	ld a, $90
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	ld hl, vBGMap0 + $320
 	call Func_79e0d
 	ld a, $38
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	call Func_792fd
 	ld hl, vBGMap0
 	call Func_79e0d
@@ -2759,11 +2759,11 @@ AnimationShakeEnemyHUD: ; 79d77 (1e:5d77)
 	call AnimationShowMonPic
 	call ClearSprites
 	ld a, $90
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	ld hl, vBGMap1
 	call Func_79e0d
 	xor a
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	call SaveScreenTilesToBuffer1
 	ld hl, vBGMap0
 	call Func_79e0d

engine/battle/b_2.asm

@@ -88,10 +88,10 @@ PayDayEffect_ ; 2feb8 (b:7eb8)
 	xor a
 	ld hl, wcd6d
 	ld [hli], a
-	ld a, [$fff3]
+	ld a, [H_WHOSETURN]
 	and a
 	ld a, [wBattleMonLevel]
-	jr z, .asm_2fec8 ; 0x2fec3 $3
+	jr z, .asm_2fec8
 	ld a, [wEnemyMonLevel]
 .asm_2fec8
 	add a
@@ -118,10 +118,10 @@ PayDayEffect_ ; 2feb8 (b:7eb8)
 	ld a, [$ff99]
 	add b
 	ld [hl], a
-	ld de, wcce7
+	ld de, wTotalPayDayMoney + 2
 	ld c, $3
 	predef AddBCDPredef
-	ld hl, CoinsScatteredText ; $7f04
+	ld hl, CoinsScatteredText
 	jp PrintText
 
 CoinsScatteredText: ; 2ff04 (b:7f04)

engine/battle/c.asm

@@ -26,7 +26,7 @@ OneHitKOEffect_: ; 33f57 (c:7f57)
 	ld [hli], a
 	ld [hl], a ; set the damage output to zero
 	dec a
-	ld [wd05e], a
+	ld [wCriticalHitOrOHKO], a
 	ld hl, wBattleMonSpeed + 1
 	ld de, wEnemyMonSpeed + 1
 	ld a, [H_WHOSETURN] ; $fff3
@@ -50,7 +50,7 @@ OneHitKOEffect_: ; 33f57 (c:7f57)
 	ld [hli], a
 	ld [hl], a
 	ld a, $2
-	ld [wd05e], a
+	ld [wCriticalHitOrOHKO], a
 	ret
 .asm_33f8a
 	ld a, $1

engine/battle/d.asm

@@ -1,21 +1,23 @@
-Func_372d6: ; 372d6 (d:72d6)
+; display "[player] VS [enemy]" text box with pokeballs representing their parties next to the names
+DisplayLinkBattleVersusTextBox: ; 372d6 (d:72d6)
 	call LoadTextBoxTilePatterns
 	hlCoord 3, 4
 	ld b, $7
 	ld c, $c
 	call TextBoxBorder
 	hlCoord 4, 5
-	ld de, wPlayerName ; wd158
+	ld de, wPlayerName
 	call PlaceString
 	hlCoord 4, 10
-	ld de, W_GRASSRATE ; W_GRASSRATE
+	ld de, W_GRASSRATE ; enemy name
 	call PlaceString
+; place bold "VS" tiles between the names
 	hlCoord 9, 8
 	ld a, $69
 	ld [hli], a
 	ld [hl], $6a
 	xor a
-	ld [wcfcb], a
+	ld [wUpdateSpritesEnabled], a
 	callab SetupPlayerAndEnemyPokeballs
-	ld c, $96
+	ld c, 150
 	jp DelayFrames

engine/battle/e.asm

@@ -1203,11 +1203,11 @@ Func_3a72a: ; 3a72a (e:672a)
 
 	ld a,d ; how many available monsters are there?
 	cp 2 ; don't bother if only 1 or 2
-	jp nc,Func_3a74b
+	jp nc,SwitchEnemyMon
 	and a
 	ret
 
-Func_3a74b: ; 3a74b (e:674b)
+SwitchEnemyMon: ; 3a74b (e:674b)
 
 ; prepare to withdraw the active monster: copy hp, number, and status to roster
 

engine/battle/e_2.asm

@@ -93,7 +93,7 @@ HealEffect_: ; 3b9ec (e:79ec)
 .asm_3ba83
 	ld [wListMenuID], a ; wListMenuID
 	predef UpdateHPBar2
-	ld hl, Func_3cd5a ; $4d5a
+	ld hl, DrawHUDsAndHPBars ; $4d5a
 	call BankswitchEtoF
 	ld hl, RegainedHealthText ; $7aac
 	jp PrintText
@@ -226,8 +226,8 @@ TransformEffect_: ; 3bab1 (e:7ab1)
 	ld a, [hl]
 	ld [wd11e], a
 	call GetMonName
-	ld hl, wcd26
-	ld de, wcd12
+	ld hl, wEnemyMonUnmodifiedAttack
+	ld de, wPlayerMonUnmodifiedAttack
 	call Func_3bb7d
 	ld hl, wEnemyMonStatMods ; wcd2e
 	ld de, wPlayerMonStatMods ; wcd1a

engine/battle/safari_zone.asm

@@ -1,5 +1,5 @@
 PrintSafariZoneBattleText: ; 4277 (1:4277)
-	ld hl, wcce9
+	ld hl, wSafariBaitFactor
 	ld a, [hl]
 	and a
 	jr z, .asm_4284
@@ -19,7 +19,7 @@ PrintSafariZoneBattleText: ; 4277 (1:4277)
 	ld [wd0b5], a
 	call GetMonHeader
 	ld a, [W_MONHCATCHRATE]
-	ld [wd007], a
+	ld [wEnemyMonCatchRate], a
 	pop hl
 .asm_429f
 	push hl

engine/cable_club.asm

@@ -570,13 +570,13 @@ Func_577d: ; 577d (1:577d)
 	xor a
 	ld [wd72d], a
 	dec a
-	ld [wd42f], a
+	ld [wDestinationWarpID], a
 	call LoadMapData
-	callba Func_c335
+	callba ClearVariablesAfterLoadingMapData
 	pop hl
 	pop af
 	ld [hl], a
-	call GBFadeIn2
+	call GBFadeInFromWhite
 	ret
 
 Func_57a2:
@@ -826,7 +826,7 @@ TradeCenter_Trade:
 .asm_59d9
 	predef Func_410f3
 .asm_59de
-	callab Func_3ad0e
+	callab TryEvolvingMon
 	call ClearScreen
 	call LoadTrainerInfoTextBoxTiles
 	call Func_226e

engine/evolution.asm

@@ -19,7 +19,7 @@ Func_7bde9: ; 7bde9 (1e:7de9)
 	call Delay3
 	xor a
 	ld [H_AUTOBGTRANSFERENABLED], a ; $ffba
-	ld [$ffd7], a
+	ld [hTilesetType], a
 	ld a, [wHPBarMaxHP]
 	ld [wcf1d], a
 	ld c, $0

engine/evolve_trade.asm

@@ -38,7 +38,7 @@ EvolveTradeMon: ; 17d7d (5:7d7d)
 	ld [wccd4], a
 	ld a, $32
 	ld [W_ISLINKBATTLE], a ; W_ISLINKBATTLE
-	callab Func_3ad0e
+	callab TryEvolvingMon
 	xor a
 	ld [W_ISLINKBATTLE], a ; W_ISLINKBATTLE
-	jp Func_2307
+	jp PlayDefaultMusic

engine/evos_moves.asm

@@ -1,45 +1,49 @@
-Func_3ad0e: ; 3ad0e (e:6d0e)
+; try to evolve the mon in [wWhichPokemon]
+TryEvolvingMon: ; 3ad0e (e:6d0e)
 	ld hl, wccd3
 	xor a
 	ld [hl], a
-	ld a, [wWhichPokemon] ; wWhichPokemon
+	ld a, [wWhichPokemon]
 	ld c, a
 	ld b, $1
-	call Func_3b057
+	call Evolution_FlagAction
 
-Func_3ad1c: ; 3ad1c (e:6d1c)
-	ld a, [$ffd7]
+; this is only called after battle
+; it is supposed to do level up evolutions, though there is a bug that allows item evolutions to occur
+EvolutionAfterBattle: ; 3ad1c (e:6d1c)
+	ld a, [hTilesetType]
 	push af
 	xor a
 	ld [wd121], a
 	dec a
-	ld [wWhichPokemon], a ; wWhichPokemon
+	ld [wWhichPokemon], a
 	push hl
 	push bc
 	push de
-	ld hl, wPartyCount ; wPartyCount
+	ld hl, wPartyCount
 	push hl
-asm_3ad2e: ; 3ad2e (e:6d2e)
-	ld hl, wWhichPokemon ; wWhichPokemon
+
+Evolution_PartyMonLoop: ; loop over party mons
+	ld hl, wWhichPokemon
 	inc [hl]
 	pop hl
 	inc hl
 	ld a, [hl]
-	cp $ff
-	jp z, Func_3aede
+	cp $ff ; have we reached the end of the party?
+	jp z, .done
 	ld [wHPBarMaxHP], a
 	push hl
-	ld a, [wWhichPokemon] ; wWhichPokemon
+	ld a, [wWhichPokemon]
 	ld c, a
 	ld hl, wccd3
 	ld b, $2
-	call Func_3b057
+	call Evolution_FlagAction
 	ld a, c
-	and a
-	jp z, asm_3ad2e
+	and a ; is the mon's bit set?
+	jp z, Evolution_PartyMonLoop ; if not, go to the next mon
 	ld a, [wHPBarMaxHP]
 	dec a
-	ld b, $0
+	ld b, 0
 	ld hl, EvosMovesPointerTable
 	add a
 	rl b
@@ -58,56 +62,57 @@ asm_3ad2e: ; 3ad2e (e:6d2e)
 	ld [wcf91], a
 	pop hl
 
-Func_3ad71: ; 3ad71 (e:6d71)
+.evoEntryLoop ; loop over evolution entries
 	ld a, [hli]
-	and a
-	jr z, asm_3ad2e
-	ld b, a
-	cp $3
-	jr z, .asm_3ad91
-	ld a, [W_ISLINKBATTLE] ; W_ISLINKBATTLE
-	cp $32
-	jr z, asm_3ad2e
+	and a ; have we reached the end of the evolution data?
+	jr z, Evolution_PartyMonLoop
+	ld b, a ; evolution type
+	cp EV_TRADE
+	jr z, .checkTradeEvo
+; not trade evolution
+	ld a, [W_ISLINKBATTLE]
+	cp $32 ; in a trade?
+	jr z, Evolution_PartyMonLoop ; if so, go the next mon
 	ld a, b
-	cp $2
-	jr z, .asm_3ada4
+	cp EV_ITEM
+	jr z, .checkItemEvo
 	ld a, [wccd4]
 	and a
-	jr nz, asm_3ad2e
+	jr nz, Evolution_PartyMonLoop
 	ld a, b
-	cp $1
-	jr z, .asm_3adad
-.asm_3ad91
-	ld a, [W_ISLINKBATTLE] ; W_ISLINKBATTLE
-	cp $32
-	jp nz, Func_3aed9
-	ld a, [hli]
+	cp EV_LEVEL
+	jr z, .checkLevel
+.checkTradeEvo
+	ld a, [W_ISLINKBATTLE]
+	cp $32 ; in a trade?
+	jp nz, .nextEvoEntry1 ; if not, go to the next evolution entry
+	ld a, [hli] ; level requirement
 	ld b, a
 	ld a, [wcfb9]
-	cp b
-	jp c, asm_3ad2e
+	cp b ; is the mon's level greater than the evolution requirement?
+	jp c, Evolution_PartyMonLoop ; if so, go the next mon
 	jr .asm_3adb6
-.asm_3ada4
-	ld a, [hli]
-	ld b, a
-	ld a, [wcf91]
-	cp b
-	jp nz, Func_3aed9
-.asm_3adad
+.checkItemEvo
 	ld a, [hli]
+	ld b, a ; evolution item
+	ld a, [wcf91] ; this is supposed to be the last item used, but it is also used to hold species numbers
+	cp b ; was the evolution item in this entry used?
+	jp nz, .nextEvoEntry1 ; if not, go to the next evolution entry
+.checkLevel
+	ld a, [hli] ; level requirement
 	ld b, a
 	ld a, [wcfb9]
-	cp b
-	jp c, Func_3aeda
+	cp b ; is the mon's level greater than the evolution requirement?
+	jp c, .nextEvoEntry2 ; if so, go the next evolution entry
 .asm_3adb6
-	ld [W_CURENEMYLVL], a ; W_CURENEMYLVL
+	ld [W_CURENEMYLVL], a
 	ld a, $1
 	ld [wd121], a
 	push hl
 	ld a, [hl]
 	ld [wHPBarMaxHP + 1], a
-	ld a, [wWhichPokemon] ; wWhichPokemon
-	ld hl, wPartyMonNicks ; wPartyMonNicks
+	ld a, [wWhichPokemon]
+	ld hl, wPartyMonNicks
 	call GetPartyMonName
 	call CopyStringToCF4B
 	ld hl, IsEvolvingText
@@ -115,17 +120,17 @@ Func_3ad71: ; 3ad71 (e:6d71)
 	ld c, $32
 	call DelayFrames
 	xor a
-	ld [H_AUTOBGTRANSFERENABLED], a ; $ffba
+	ld [H_AUTOBGTRANSFERENABLED], a
 	ld hl, wTileMap
 	ld bc, $c14
 	call ClearScreenArea
 	ld a, $1
-	ld [H_AUTOBGTRANSFERENABLED], a ; $ffba
+	ld [H_AUTOBGTRANSFERENABLED], a
 	ld a, $ff
-	ld [wcfcb], a
+	ld [wUpdateSpritesEnabled], a
 	call ClearSprites
 	callab Func_7bde9
-	jp c, Func_3af2e
+	jp c, CancelledEvolution
 	ld hl, EvolvedText
 	call PrintText
 	pop hl
@@ -147,7 +152,7 @@ Func_3ad71: ; 3ad71 (e:6d71)
 	ld c, $28
 	call DelayFrames
 	call ClearScreen
-	call Func_3aef7
+	call RenameEvolvedMon
 	ld a, [wd11e]
 	push af
 	ld a, [wd0b5]
@@ -168,15 +173,15 @@ Func_3ad71: ; 3ad71 (e:6d71)
 	ld de, wcfba
 	ld b, $1
 	call CalcStats
-	ld a, [wWhichPokemon] ; wWhichPokemon
-	ld hl, wPartyMon1Species ; wPartyMon1Species (aliases: wPartyMon1)
-	ld bc, $2c
+	ld a, [wWhichPokemon]
+	ld hl, wPartyMon1
+	ld bc, wPartyMon2 - wPartyMon1
 	call AddNTimes
 	ld e, l
 	ld d, h
 	push hl
 	push bc
-	ld bc, $22
+	ld bc, wPartyMon1MaxHP - wPartyMon1
 	add hl, bc
 	ld a, [hli]
 	ld b, a
@@ -202,23 +207,23 @@ Func_3ad71: ; 3ad71 (e:6d71)
 	ld [wd11e], a
 	xor a
 	ld [wcc49], a
-	call Func_3af5b
+	call LearnMoveFromLevelUp
 	pop hl
 	predef SetPartyMonTypes
-	ld a, [W_ISINBATTLE] ; W_ISINBATTLE
+	ld a, [W_ISINBATTLE]
 	and a
-	call z, Func_3af52
+	call z, Evolution_ReloadTilesetTilePatterns
 	predef IndexToPokedex
 	ld a, [wd11e]
 	dec a
 	ld c, a
 	ld b, $1
-	ld hl, wPokedexOwned ; wPokedexOwned
+	ld hl, wPokedexOwned
 	push bc
-	call Func_3b057
+	call Evolution_FlagAction
 	pop bc
-	ld hl, wPokedexSeen ; wd30a
-	call Func_3b057
+	ld hl, wPokedexSeen
+	call Evolution_FlagAction
 	pop de
 	pop hl
 	ld a, [wcf98]
@@ -226,33 +231,35 @@ Func_3ad71: ; 3ad71 (e:6d71)
 	push hl
 	ld l, e
 	ld h, d
-	jr Func_3aeda
+	jr .nextEvoEntry2
 
-Func_3aed9: ; 3aed9 (e:6ed9)
+.nextEvoEntry1
 	inc hl
 
-Func_3aeda: ; 3aeda (e:6eda)
+.nextEvoEntry2
 	inc hl
-	jp Func_3ad71
+	jp .evoEntryLoop
 
-Func_3aede: ; 3aede (e:6ede)
+.done
 	pop de
 	pop bc
 	pop hl
 	pop af
-	ld [$ffd7], a
-	ld a, [W_ISLINKBATTLE] ; W_ISLINKBATTLE
+	ld [hTilesetType], a
+	ld a, [W_ISLINKBATTLE]
 	cp $32
 	ret z
-	ld a, [W_ISINBATTLE] ; W_ISINBATTLE
+	ld a, [W_ISINBATTLE]
 	and a
 	ret nz
 	ld a, [wd121]
 	and a
-	call nz, Func_2307
+	call nz, PlayDefaultMusic
 	ret
 
-Func_3aef7: ; 3aef7 (e:6ef7)
+; 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)
 	ld a, [wd0b5]
 	push af
 	ld a, [W_MONHDEXNUM]
@@ -262,17 +269,17 @@ Func_3aef7: ; 3aef7 (e:6ef7)
 	ld [wd0b5], a
 	ld hl, wcd6d
 	ld de, wcf4b
-.asm_3af0e
+.compareNamesLoop
 	ld a, [de]
 	inc de
 	cp [hl]
 	inc hl
 	ret nz
 	cp $50
-	jr nz, .asm_3af0e
-	ld a, [wWhichPokemon] ; wWhichPokemon
+	jr nz, .compareNamesLoop
+	ld a, [wWhichPokemon]
 	ld bc, $b
-	ld hl, wPartyMonNicks ; wPartyMonNicks
+	ld hl, wPartyMonNicks
 	call AddNTimes
 	push hl
 	call GetName
@@ -280,13 +287,13 @@ Func_3aef7: ; 3aef7 (e:6ef7)
 	pop de
 	jp CopyData
 
-Func_3af2e: ; 3af2e (e:6f2e)
+CancelledEvolution: ; 3af2e (e:6f2e)
 	ld hl, StoppedEvolvingText
 	call PrintText
 	call ClearScreen
 	pop hl
-	call Func_3af52
-	jp asm_3ad2e
+	call Evolution_ReloadTilesetTilePatterns
+	jp Evolution_PartyMonLoop
 
 EvolvedText: ; 3af3e (e:6f3e)
 	TX_FAR _EvolvedText
@@ -304,18 +311,18 @@ IsEvolvingText: ; 3af4d (e:6f4d)
 	TX_FAR _IsEvolvingText
 	db "@"
 
-Func_3af52: ; 3af52 (e:6f52)
+Evolution_ReloadTilesetTilePatterns: ; 3af52 (e:6f52)
 	ld a, [W_ISLINKBATTLE] ; W_ISLINKBATTLE
-	cp $32
-	ret z
+	cp $32 ; in a trade?
+	ret z ; if so, return
 	jp ReloadTilesetTilePatterns
 
-Func_3af5b: ; 3af5b (e:6f5b)
+LearnMoveFromLevelUp: ; 3af5b (e:6f5b)
 	ld hl, EvosMovesPointerTable
-	ld a, [wd11e]
+	ld a, [wd11e] ; species
 	ld [wcf91], a
 	dec a
-	ld bc, $0
+	ld bc, 0
 	ld hl, EvosMovesPointerTable
 	add a
 	rl b
@@ -324,42 +331,45 @@ Func_3af5b: ; 3af5b (e:6f5b)
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
-.asm_3af73
+.skipEvolutionDataLoop ; loop to skip past the evolution data, which comes before the move data
 	ld a, [hli]
-	and a
-	jr nz, .asm_3af73
-.asm_3af77
+	and a ; have we reached the end of the evolution data?
+	jr nz, .skipEvolutionDataLoop ; if not, jump back up
+.learnSetLoop ; loop over the learn set until we reach a move that is learnt at the current level or the end of the list
 	ld a, [hli]
-	and a
-	jr z, .asm_3afb1
-	ld b, a
-	ld a, [W_CURENEMYLVL] ; W_CURENEMYLVL
-	cp b
-	ld a, [hli]
-	jr nz, .asm_3af77
-	ld d, a
+	and a ; have we reached the end of the learn set?
+	jr z, .done ; if we've reached the end of the learn set, jump
+	ld b, a ; level the move is learnt at
+	ld a, [W_CURENEMYLVL]
+	cp b ; is the move learnt at the mon's current level?
+	ld a, [hli] ; move ID
+	jr nz, .learnSetLoop
+	ld d, a ; ID of move to learn
 	ld a, [wcc49]
 	and a
-	jr nz, .asm_3af96
-	ld hl, wPartyMon1Moves ; wPartyMon1Moves
-	ld a, [wWhichPokemon] ; wWhichPokemon
-	ld bc, $2c
+	jr nz, .next
+; if [wcc49] is 0, get the address of the mon's current moves
+; there is no reason to make this conditional because the code wouldn't work properly without doing this
+; every call to this function sets [wcc49] to 0
+	ld hl, wPartyMon1Moves
+	ld a, [wWhichPokemon]
+	ld bc, wPartyMon2 - wPartyMon1
 	call AddNTimes
-.asm_3af96
+.next
 	ld b, $4
-.asm_3af98
+.checkCurrentMovesLoop ; check if the move to learn is already known
 	ld a, [hli]
 	cp d
-	jr z, .asm_3afb1
+	jr z, .done ; if already known, jump
 	dec b
-	jr nz, .asm_3af98
+	jr nz, .checkCurrentMovesLoop
 	ld a, d
 	ld [wd0e0], a
 	ld [wd11e], a
 	call GetMoveName
 	call CopyStringToCF4B
 	predef LearnMove
-.asm_3afb1
+.done
 	ld a, [wcf91]
 	ld [wd11e], a
 	ret
@@ -484,7 +494,7 @@ WriteMonMoves_ShiftMoveData: ; 3b04e (e:704e)
 	jr nz, .asm_3b050
 	ret
 
-Func_3b057: ; 3b057 (e:7057)
+Evolution_FlagAction: ; 3b057 (e:7057)
 	predef_jump FlagActionPredef
 
 INCLUDE "data/evos_moves.asm"

engine/experience.asm

@@ -1,28 +1,30 @@
-Func_58f43: ; 58f43 (16:4f43)
+; calculates the level a mon should be based on its current exp
+CalcLevelFromExperience: ; 58f43 (16:4f43)
 	ld a, [wcf98]
 	ld [wd0b5], a
 	call GetMonHeader
-	ld d, $1
-.asm_58f4e
-	inc d
+	ld d, $1 ; init level to 1
+.loop
+	inc d ; increment level
 	call CalcExperience
 	push hl
-	ld hl, wcfa8
-	ld a, [$ff98]
+	ld hl, wcfa8 ; current exp
+; compare exp needed for level d with current exp
+	ld a, [H_MULTIPLICAND + 2]
 	ld c, a
 	ld a, [hld]
 	sub c
-	ld a, [$ff97]
+	ld a, [H_MULTIPLICAND + 1]
 	ld c, a
 	ld a, [hld]
 	sbc c
-	ld a, [H_NUMTOPRINT] ; $ff96 (aliases: H_MULTIPLICAND)
+	ld a, [H_MULTIPLICAND]
 	ld c, a
 	ld a, [hl]
 	sbc c
 	pop hl
-	jr nc, .asm_58f4e
-	dec d
+	jr nc, .loop ; if exp needed for level d is not greater than exp, try the next level
+	dec d ; since the exp was too high on the last loop iteration, go back to the previous value and return
 	ret
 
 ; calculates the amount of experience needed for level d

engine/give_pokemon.asm

@@ -12,7 +12,7 @@ _GivePokemon: ; 4fda5 (13:7da5)
 	ld [W_ENEMYBATTSTATUS3], a ; W_ENEMYBATTSTATUS3
 	ld a, [wcf91]
 	ld [wEnemyMonSpecies2], a
-	callab Func_3eb01
+	callab LoadEnemyMonData
 	call SetPokedexOwnedFlag
 	callab Func_e7a4
 	ld hl, wcf4b
@@ -43,7 +43,7 @@ _GivePokemon: ; 4fda5 (13:7da5)
 	call SetPokedexOwnedFlag
 	call AddPartyMon
 	ld a, $1
-	ld [wcc3c], a
+	ld [wDoNotWaitForButtonPressAfterDisplayingText], a
 	ld [wccd3], a
 	scf
 	ret

engine/hall_of_fame.asm

@@ -18,8 +18,8 @@ AnimateHallOfFame: ; 701a0 (1c:41a0)
 	ld bc, HOF_TEAM
 	call FillMemory
 	xor a
-	ld [wcfcb], a
-	ld [$ffd7], a
+	ld [wUpdateSpritesEnabled], a
+	ld [hTilesetType], a
 	ld [W_SPRITEFLIPPED], a
 	ld [wd358], a
 	ld [wTrainerScreenY], a
@@ -32,7 +32,7 @@ AnimateHallOfFame: ; 701a0 (1c:41a0)
 	inc [hl]
 .asm_701eb
 	ld a, $90
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	ld c, BANK(Music_HallOfFame)
 	ld a, MUSIC_HALL_OF_FAME
 	call PlayMusic
@@ -66,7 +66,7 @@ AnimateHallOfFame: ; 701a0 (1c:41a0)
 	call PlaceString
 	ld c, 180
 	call DelayFrames
-	call GBFadeOut2
+	call GBFadeOutToWhite
 	pop bc
 	pop hl
 	jr .asm_701fb
@@ -86,7 +86,7 @@ AnimateHallOfFame: ; 701a0 (1c:41a0)
 	call Func_70377
 	call Func_70423
 	xor a
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	ld hl, rLCDC ; $ff40
 	res 3, [hl]
 	ret
@@ -125,7 +125,7 @@ Func_70278: ; 70278 (1c:4278)
 	call Func_7036d
 	ld d, $a0
 	ld e, $4
-	ld a, [wcf1b]
+	ld a, [wOnSGB]
 	and a
 	jr z, .asm_702c7
 	sla e
@@ -282,4 +282,4 @@ Func_70423: ; 70423 (1c:4423)
 	ld [wcfc9], a
 	ld a, $ff
 	ld [wMusicHeaderPointer], a
-	jp GBFadeOut2
+	jp GBFadeOutToWhite

engine/hidden_object_functions14.asm

@@ -1,7 +1,7 @@
 PrintNotebookText: ; 52996 (14:6996)
 	call EnableAutoTextBoxDrawing
 	ld a, $1
-	ld [wcc3c], a
+	ld [wDoNotWaitForButtonPressAfterDisplayingText], a
 	ld a, [wTrainerSpriteOffset]
 	jp PrintPredefTextID
 

engine/hidden_object_functions17.asm

@@ -64,7 +64,7 @@ DisplayMonFrontSpriteInBox: ; 5dbd9 (17:5bd9)
 	ld [H_AUTOBGTRANSFERENABLED], a ; $ffba
 	call Delay3
 	xor a
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	call SaveScreenTilesToBuffer1
 	ld a, $11
 	ld [wd125], a
@@ -83,13 +83,13 @@ DisplayMonFrontSpriteInBox: ; 5dbd9 (17:5bd9)
 	call LoadScreenTilesFromBuffer1
 	call Delay3
 	ld a, $90
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	ret
 
 PrintBlackboardLinkCableText: ; 5dc1a (17:5c1a)
 	call EnableAutoTextBoxDrawing
 	ld a, $1
-	ld [wcc3c], a
+	ld [wDoNotWaitForButtonPressAfterDisplayingText], a
 	ld a, [wWhichTrade]
 	call PrintPredefTextID
 	ret

engine/hidden_object_functions18.asm

@@ -70,7 +70,7 @@ PrintBenchGuyText: ; 6245d (18:645d)
 	ld a, [hl]
 	jp PrintPredefTextID
 
-; format: db map id, 08, text id of PointerTable_3f22
+; format: db map id, 08, text id of PredefTextIDPointerTable
 PokeCenterMapIDList: ; 6247e (18:647e)
 	db VIRIDIAN_POKECENTER,$08,$0F
 	db PEWTER_POKECENTER,$08,$10
@@ -181,7 +181,7 @@ OpenPokemonCenterPC: ; 62516 (18:6516)
 	ret nz
 	call EnableAutoTextBoxDrawing
 	ld a, $1
-	ld [wcf0c], a
+	ld [wAutoTextBoxDrawingControl], a
 	ld a, $1f ; PredefText1f
 	jp PrintPredefTextID
 

engine/hidden_object_functions3.asm

@@ -1,22 +1,23 @@
 ; prints text for bookshelves in buildings without sign events
 PrintBookshelfText: ; fb50 (3:7b50)
-	ld a, [wSpriteStateData1 + 9]
-	cp $4
-	jr nz, .asm_fb7f
-	ld a, [W_CURMAPTILESET] ; W_CURMAPTILESET
+	ld a, [wSpriteStateData1 + 9] ; player's sprite facing direction
+	cp SPRITE_FACING_UP
+	jr nz, .noMatch
+; facing up
+	ld a, [W_CURMAPTILESET]
 	ld b, a
 	aCoord 8, 7
 	ld c, a
-	ld hl, BookshelfTileIDs ; $7b8b
-.asm_fb62
+	ld hl, BookshelfTileIDs
+.loop
 	ld a, [hli]
 	cp $ff
-	jr z, .asm_fb7f
+	jr z, .noMatch
 	cp b
-	jr nz, .asm_fb7b
+	jr nz, .nextBookshelfEntry1
 	ld a, [hli]
 	cp c
-	jr nz, .asm_fb7c
+	jr nz, .nextBookshelfEntry2
 	ld a, [hl]
 	push af
 	call EnableAutoTextBoxDrawing
@@ -25,12 +26,12 @@ PrintBookshelfText: ; fb50 (3:7b50)
 	xor a
 	ld [$ffdb], a
 	ret
-.asm_fb7b
+.nextBookshelfEntry1
 	inc hl
-.asm_fb7c
+.nextBookshelfEntry2
 	inc hl
-	jr .asm_fb62
-.asm_fb7f
+	jr .loop
+.noMatch
 	ld a, $ff
 	ld [$ffdb], a
 	ld b, BANK(PrintCardKeyText)
@@ -114,12 +115,12 @@ TownMapText: ; fc12 (3:7c12)
 	db $06
 	db $08 ; asm
 	ld a, $1
-	ld [wcc3c], a
+	ld [wDoNotWaitForButtonPressAfterDisplayingText], a
 	ld hl, wd730
 	set 6, [hl]
 	call GBPalWhiteOutWithDelay3
 	xor a
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	inc a
 	ld [H_AUTOBGTRANSFERENABLED], a
 	call LoadFontTilePatterns

engine/hidden_object_functions7.asm

@@ -60,7 +60,7 @@ SafariZoneCheckSteps: ; 1e997 (7:6997)
 	ld [wSafariSteps + 1], a ; wd70e
 asm_1e9ab: ; 1e9ab (7:69ab)
 	xor a
-	ld [wda46], a
+	ld [wSafariZoneGameOver], a
 	ret
 asm_1e9b0: ; 1e9b0 (7:69b0)
 	call EnableAutoTextBoxDrawing
@@ -83,13 +83,13 @@ asm_1e9b0: ; 1e9b0 (7:69b0)
 	ld a, $9c
 	ld [H_DOWNARROWBLINKCNT1], a ; $ff8b
 	ld a, $3
-	ld [wd42f], a
+	ld [wDestinationWarpID], a
 	ld a, $5
 	ld [W_SAFARIZONEENTRANCECURSCRIPT], a
 	ld hl, wd790
 	set 6, [hl]
 	ld a, $1
-	ld [wda46], a
+	ld [wSafariZoneGameOver], a
 	ret
 
 PrintSafariGameOverText: ; 1e9ed (7:69ed)
@@ -152,7 +152,7 @@ CinnabarGymQuiz: ; 1ea25 (7:6a25)
 	ld l, a
 	call PrintText
 	ld a, $1
-	ld [wcc3c], a
+	ld [wDoNotWaitForButtonPressAfterDisplayingText], a
 	call CinnabarGymQuiz_1ea92
 	jp TextScriptEnd
 
@@ -291,7 +291,7 @@ CinnabarGymQuiz_1eb0a: ; 1eb0a (7:6b0a)
 .asm_1eb38
 	pop bc
 	ld [wd09f], a
-	predef Func_ee9e
+	predef ReplaceTileBlock
 	ld hl, $ffdb
 	dec [hl]
 	jr nz, .asm_1eb0e
@@ -334,7 +334,7 @@ BillsHousePC: ; 1eb6e (7:6b6e)
 	jp PrintPredefTextID
 .asm_1eb8b
 	ld a, $1
-	ld [wcc3c], a
+	ld [wDoNotWaitForButtonPressAfterDisplayingText], a
 	ld a, $2e
 	call PrintPredefTextID
 	ld c, $20
@@ -357,13 +357,13 @@ BillsHousePC: ; 1eb6e (7:6b6e)
 	ld a, (SFX_02_3a - SFX_Headers_02) / 3
 	call PlaySound
 	call WaitForSoundToFinish
-	call Func_2307
+	call PlayDefaultMusic
 	ld hl, wd7f2
 	set 3, [hl]
 	ret
 .asm_1ebd2
 	ld a, $1
-	ld [wcc3c], a
+	ld [wDoNotWaitForButtonPressAfterDisplayingText], a
 	ld a, $2f
 	call PrintPredefTextID
 	ret

engine/in_game_trades.asm

@@ -88,7 +88,7 @@ Func_71c07: ; 71c07 (1c:5c07)
 	xor a
 	ld [wd07d],a
 	dec a
-	ld [wcfcb],a
+	ld [wUpdateSpritesEnabled],a
 	call DisplayPartyMenu
 	push af
 	call Func_71ca2
@@ -138,7 +138,7 @@ Func_71c07: ; 71c07 (1c:5c07)
 	callab EvolveTradeMon
 	call ClearScreen
 	call Func_71ca2
-	callba Func_eedc
+	callba RedrawMapView
 	and a
 	ld a,$3
 	jr .asm_ee803 ; 0x71c9b $1
@@ -150,7 +150,7 @@ Func_71c07: ; 71c07 (1c:5c07)
 
 Func_71ca2: ; 71ca2 (1c:5ca2)
 	call GBPalWhiteOutWithDelay3
-	call Func_3dbe
+	call RestoreScreenTilesAndReloadTilePatterns
 	call ReloadTilesetTilePatterns
 	call LoadScreenTilesFromBuffer2
 	call Delay3

engine/intro.asm

@@ -5,7 +5,7 @@ PlayIntro: ; 41682 (10:5682)
 	ld [H_AUTOBGTRANSFERENABLED], a
 	call PlayShootingStar
 	call PlayIntroScene
-	call GBFadeOut2
+	call GBFadeOutToWhite
 	xor a
 	ld [$ffae], a
 	ld [H_AUTOBGTRANSFERENABLED], a

engine/items/items.asm

@@ -237,7 +237,7 @@ ItemUseBall: ; d687 (3:5687)
 	ld [H_QUOTIENT + 3],a
 .next9	;$5776
 	pop bc
-	ld a,[wd007]	;enemy: Catch Rate
+	ld a,[wEnemyMonCatchRate]	;enemy: Catch Rate
 	cp b
 	jr c,.next10
 	ld a,[H_QUOTIENT + 2]
@@ -256,7 +256,7 @@ ItemUseBall: ; d687 (3:5687)
 	xor a
 	ld [H_MULTIPLICAND],a
 	ld [H_MULTIPLICAND + 1],a
-	ld a,[wd007]	;enemy: Catch Rate
+	ld a,[wEnemyMonCatchRate]	;enemy: Catch Rate
 	ld [H_MULTIPLICAND + 2],a
 	ld a,100
 	ld [H_MULTIPLIER],a
@@ -376,7 +376,7 @@ ItemUseBall: ; d687 (3:5687)
 	ld [wcf91],a
 	ld a,[wEnemyMonLevel]
 	ld [W_CURENEMYLVL],a
-	callab Func_3eb01
+	callab LoadEnemyMonData
 	pop af
 	ld [wcf91],a
 	pop hl
@@ -507,8 +507,8 @@ ItemUseBicycle: ; d977 (3:5977)
 	ld a,[W_ISINBATTLE]
 	and a
 	jp nz,ItemUseNotTime
-	ld a,[wd700]
-	ld [wd11a],a
+	ld a,[wWalkBikeSurfState]
+	ld [wWalkBikeSurfStateCopy],a
 	cp a,2 ; is the player surfing?
 	jp z,ItemUseNotTime
 	dec a ; is player already bicycling?
@@ -516,8 +516,8 @@ ItemUseBicycle: ; d977 (3:5977)
 .getOffBike
 	call ItemUseReloadOverworldData
 	xor a
-	ld [wd700],a ; change player state to walking
-	call Func_2307 ; play walking music
+	ld [wWalkBikeSurfState],a ; change player state to walking
+	call PlayDefaultMusic ; play walking music
 	ld hl,GotOffBicycleText
 	jr .printText
 .tryToGetOnBike
@@ -527,16 +527,16 @@ ItemUseBicycle: ; d977 (3:5977)
 	xor a ; no keys pressed
 	ld [hJoyHeld],a ; current joypad state
 	inc a
-	ld [wd700],a ; change player state to bicycling
+	ld [wWalkBikeSurfState],a ; change player state to bicycling
 	ld hl,GotOnBicycleText
-	call Func_2307 ; play bike riding music
+	call PlayDefaultMusic ; play bike riding music
 .printText
 	jp PrintText
 
 ; used for Surf out-of-battle effect
 ItemUseSurfboard: ; d9b4 (3:59b4)
-	ld a,[wd700]
-	ld [wd11a],a
+	ld a,[wWalkBikeSurfState]
+	ld [wWalkBikeSurfStateCopy],a
 	cp a,2 ; is the player already surfing?
 	jr z,.tryToStopSurfing
 .tryToSurf
@@ -550,8 +550,8 @@ ItemUseSurfboard: ; d9b4 (3:59b4)
 	ld hl,wd730
 	set 7,[hl]
 	ld a,2
-	ld [wd700],a ; change player state to surfing
-	call Func_2307 ; play surfing music
+	ld [wWalkBikeSurfState],a ; change player state to surfing
+	call PlayDefaultMusic ; play surfing music
 	ld hl,SurfingGotOnText
 	jp PrintText
 .tryToStopSurfing
@@ -570,7 +570,7 @@ ItemUseSurfboard: ; d9b4 (3:59b4)
 	ld a,[hli]
 	ld h,[hl]
 	ld l,a ; hl now points to passable tiles
-	ld a,[wcfc6] ; tile in front of the player
+	ld a,[wTileInFrontOfPlayer] ; tile in front of the player
 	ld b,a
 .passableTileLoop
 	ld a,[hli]
@@ -586,31 +586,31 @@ ItemUseSurfboard: ; d9b4 (3:59b4)
 	ld hl,wd730
 	set 7,[hl]
 	xor a
-	ld [wd700],a ; change player state to walking
+	ld [wWalkBikeSurfState],a ; change player state to walking
 	dec a
 	ld [wJoyIgnore],a
-	call Func_2307 ; play walking music
+	call PlayDefaultMusic ; play walking music
 	jp LoadWalkingPlayerSpriteGraphics
 ; uses a simulated button press to make the player move forward
 .makePlayerMoveForward
 	ld a,[wd52a] ; direction the player is going
 	bit 3,a
-	ld b,%01000000 ; Up key
+	ld b,D_UP
 	jr nz,.storeSimulatedButtonPress
 	bit 2,a
-	ld b,%10000000 ; Down key
+	ld b,D_DOWN
 	jr nz,.storeSimulatedButtonPress
 	bit 1,a
-	ld b,%00100000 ; Left key
+	ld b,D_LEFT
 	jr nz,.storeSimulatedButtonPress
-	ld b,%00010000 ; Right key
+	ld b,D_RIGHT
 .storeSimulatedButtonPress
 	ld a,b
-	ld [wccd3],a ; base address of simulated button presses
+	ld [wSimulatedJoypadStatesEnd],a
 	xor a
-	ld [wcd39],a
+	ld [wWastedByteCD39],a
 	inc a
-	ld [wcd38],a ; index of current simulated button press
+	ld [wSimulatedJoypadStatesIndex],a
 	ret
 
 SurfingGotOnText: ; da4c (3:5a4c)
@@ -636,7 +636,7 @@ ItemUseEvoStone: ; da5b (3:5a5b)
 	ld a,$05 ; evolution stone party menu
 	ld [wd07d],a
 	ld a,$ff
-	ld [wcfcb],a
+	ld [wUpdateSpritesEnabled],a
 	call DisplayPartyMenu
 	pop bc
 	jr c,.canceledItemUse
@@ -647,7 +647,7 @@ ItemUseEvoStone: ; da5b (3:5a5b)
 	ld a,(SFX_02_3e - SFX_Headers_02) / 3
 	call PlaySoundWaitForCurrent ; play sound
 	call WaitForSoundToFinish ; wait for sound to end
-	callab Func_3ad0e ; try to evolve pokemon
+	callab TryEvolvingMon ; try to evolve pokemon
 	ld a,[wd121]
 	and a
 	jr z,.noEffect
@@ -681,7 +681,7 @@ ItemUseMedicine: ; dabb (3:5abb)
 	ld a,$01
 	ld [wd07d],a ; item use party menu
 	ld a,$ff
-	ld [wcfcb],a
+	ld [wUpdateSpritesEnabled],a
 	ld a,[wd152]
 	and a ; using Softboiled?
 	jr z,.notUsingSoftboiled
@@ -805,7 +805,7 @@ ItemUseMedicine: ; dabb (3:5abb)
 	push bc
 	ld a,[wcf06]
 	ld c,a
-	ld hl,wccf5
+	ld hl,wPartyFoughtCurrentEnemyFlags
 	ld b,$02
 	predef FlagActionPredef
 	ld a,c
@@ -813,7 +813,7 @@ ItemUseMedicine: ; dabb (3:5abb)
 	jr z,.next
 	ld a,[wcf06]
 	ld c,a
-	ld hl,wPartyAliveFlags
+	ld hl,wPartyGainExpFlags
 	ld b,$01
 	predef FlagActionPredef
 .next
@@ -1096,7 +1096,7 @@ ItemUseMedicine: ; dabb (3:5abb)
 	ld [H_AUTOBGTRANSFERENABLED],a
 	call ClearScreen
 	dec a
-	ld [wcfcb],a
+	ld [wUpdateSpritesEnabled],a
 	call RedrawPartyMenu ; redraws the party menu and displays the message
 	ld a,1
 	ld [H_AUTOBGTRANSFERENABLED],a
@@ -1273,12 +1273,12 @@ ItemUseMedicine: ; dabb (3:5abb)
 	call WaitForTextScrollButtonPress ; wait for button press
 	xor a
 	ld [wcc49],a
-	predef Func_3af5b ; learn level up move, if any
+	predef LearnMoveFromLevelUp ; learn level up move, if any
 	xor a
 	ld [wccd4],a
-	callab Func_3ad0e ; evolve pokemon, if appropriate
+	callab TryEvolvingMon ; evolve pokemon, if appropriate
 	ld a,$01
-	ld [wcfcb],a
+	ld [wUpdateSpritesEnabled],a
 	pop af
 	ld [wcf91],a
 	pop af
@@ -1303,17 +1303,17 @@ VitaminText: ; df2e (3:5f2e)
 ItemUseBait: ; df52 (3:5f52)
 	ld hl,ThrewBaitText
 	call PrintText
-	ld hl,wd007 ; catch rate
+	ld hl,wEnemyMonCatchRate ; catch rate
 	srl [hl] ; halve catch rate
 	ld a,BAIT_ANIM
-	ld hl,wcce9 ; bait factor
-	ld de,wcce8 ; escape factor
+	ld hl,wSafariBaitFactor ; bait factor
+	ld de,wSafariEscapeFactor ; escape factor
 	jr BaitRockCommon
 
 ItemUseRock: ; df67 (3:5f67)
 	ld hl,ThrewRockText
 	call PrintText
-	ld hl,wd007 ; catch rate
+	ld hl,wEnemyMonCatchRate ; catch rate
 	ld a,[hl]
 	add a ; double catch rate
 	jr nc,.noCarry
@@ -1321,8 +1321,8 @@ ItemUseRock: ; df67 (3:5f67)
 .noCarry
 	ld [hl],a
 	ld a,ROCK_ANIM
-	ld hl,wcce8 ; escape factor
-	ld de,wcce9 ; bait factor
+	ld hl,wSafariEscapeFactor ; escape factor
+	ld de,wSafariBaitFactor ; bait factor
 
 BaitRockCommon: ; df7f (3:5f7f)
 	ld [W_ANIMATIONID],a
@@ -1383,7 +1383,7 @@ ItemUseEscapeRope: ; dfaf (3:5faf)
 	ld [W_NUMSAFARIBALLS],a
 	ld [W_SAFARIZONEENTRANCECURSCRIPT],a
 	inc a
-	ld [wd078],a
+	ld [wEscapedFromBattle],a
 	ld [wcd6a],a ; item used
 	ld a,[wd152]
 	and a ; using Dig?
@@ -1424,8 +1424,8 @@ ItemUseXAccuracy: ; e013 (3:6013)
 ItemUseCardKey: ; e022 (3:6022)
 	xor a
 	ld [wd71f],a
-	call Func_c586
-	ld a,[Func_c586] ; $4586
+	call GetTileAndCoordsInFrontOfPlayer
+	ld a,[GetTileAndCoordsInFrontOfPlayer] ; $4586
 	cp a,$18
 	jr nz,.next0
 	ld hl,CardKeyTable1
@@ -1517,7 +1517,7 @@ ItemUsePokedoll: ; e0cd (3:60cd)
 	dec a
 	jp nz,ItemUseNotTime
 	ld a,$01
-	ld [wd078],a
+	ld [wEscapedFromBattle],a
 	jp PrintItemUseTextAndRemoveItem
 
 ItemUseGuardSpec: ; e0dc (3:60dc)
@@ -1727,7 +1727,7 @@ PlayedFluteHadEffectText: ; e215 (3:6215)
 	ld a,[wc028]
 	cp a,$b8
 	jr z,.musicWaitLoop
-	call Func_2307 ; start playing normal music again
+	call PlayDefaultMusic ; start playing normal music again
 .done
 	jp TextScriptEnd ; end text
 
@@ -1796,7 +1796,7 @@ RodResponse: ; e28d (3:628d)
 	ld [W_CUROPPONENT], a
 
 .next
-	ld hl, wd700
+	ld hl, wWalkBikeSurfState
 	ld a, [hl] ; store the value in a
 	push af
 	push hl
@@ -1818,7 +1818,7 @@ FishingInit: ; e2b4 (3:62b4)
 .notInBattle
 	call IsNextTileShoreOrWater
 	ret c
-	ld a,[wd700]
+	ld a,[wWalkBikeSurfState]
 	cp a,2 ; Surfing?
 	jr z,.surfing
 	call ItemUseReloadOverworldData
@@ -1877,7 +1877,7 @@ ItemUsePPRestore: ; e31e (3:631e)
 	ld [wWhichTrade],a
 .chooseMon
 	xor a
-	ld [wcfcb],a
+	ld [wUpdateSpritesEnabled],a
 	ld a,$01 ; item use party menu
 	ld [wd07d],a
 	call DisplayPartyMenu
@@ -2117,7 +2117,7 @@ ItemUseTMHM: ; e479 (3:6479)
 	ld bc,14
 	call CopyData
 	ld a,$ff
-	ld [wcfcb],a
+	ld [wUpdateSpritesEnabled],a
 	ld a,$03 ; teach TM/HM party menu
 	ld [wd07d],a
 	call DisplayPartyMenu
@@ -2744,7 +2744,7 @@ IsNextTileShoreOrWater: ; e8b8 (3:68b8)
 	jr nc, .notShoreOrWater
 	ld a, [W_CURMAPTILESET]
 	cp SHIP_PORT ; Vermilion Dock tileset
-	ld a, [wcfc6] ; tile in front of player
+	ld a, [wTileInFrontOfPlayer] ; tile in front of player
 	jr z, .skipShoreTiles ; if it's the Vermilion Dock tileset
 	cp $48 ; eastern shore tile in Safari Zone
 	jr z, .shoreOrWater

engine/menu/bills_pc.asm

@@ -320,7 +320,7 @@ Func_21673: ; 21673 (8:5673)
 	jp Func_214e8
 
 Func_216b3: ; 216b3 (8:56b3)
-	callba Func_738a1
+	callba ChangeBox
 	jp Func_214e8
 
 Func_216be: ; 216be (8:56be)

engine/menu/diploma.asm

@@ -3,7 +3,7 @@ DisplayDiploma: ; 566e2 (15:66e2)
 	call GBPalWhiteOutWithDelay3
 	call ClearScreen
 	xor a
-	ld [wcfcb], a
+	ld [wUpdateSpritesEnabled], a
 	ld hl, wd730
 	set 6, [hl]
 	call DisableLCD
@@ -61,7 +61,7 @@ DisplayDiploma: ; 566e2 (15:66e2)
 	ld hl, wd730
 	res 6, [hl]
 	call GBPalWhiteOutWithDelay3
-	call Func_3dbe
+	call RestoreScreenTilesAndReloadTilePatterns
 	call Delay3
 	jp GBPalNormal
 

engine/menu/league_pc.asm

@@ -4,14 +4,14 @@ PKMNLeaguePC: ; 0x7657e
 	ld hl, wd730
 	set 6, [hl]
 	push hl
-	ld a, [wcfcb]
+	ld a, [wUpdateSpritesEnabled]
 	push af
-	ld a, [$ffD7]
+	ld a, [hTilesetType]
 	push af
 	xor a
-	ld [$ffD7], a
+	ld [hTilesetType], a
 	ld [W_SPRITEFLIPPED], a
-	ld [wcfcb], a
+	ld [wUpdateSpritesEnabled], a
 	ld [wTrainerScreenX], a
 	ld [wcd42], a
 	ld a, [wd5a2]
@@ -38,9 +38,9 @@ PKMNLeaguePC: ; 0x7657e
 	jr nz, .first
 .second
 	pop af
-	ld [$ffD7], a
+	ld [hTilesetType], a
 	pop af
-	ld [wcfcb], a
+	ld [wUpdateSpritesEnabled], a
 	pop hl
 	res 6, [hl]
 	call GBPalWhiteOutWithDelay3

engine/menu/main_menu.asm

@@ -111,16 +111,16 @@ MainMenu: ; 5af2 (1:5af2)
 	call DelayFrames
 	ld a,[wd5a2]
 	and a
-	jp z,Func_5d5f
+	jp z,SpecialEnterMap
 	ld a,[W_CURMAP] ; map ID
 	cp a,HALL_OF_FAME
-	jp nz,Func_5d5f
+	jp nz,SpecialEnterMap
 	xor a
-	ld [wd71a],a
+	ld [wDestinationMap],a
 	ld hl,wd732
-	set 2,[hl]
-	call Func_62ce
-	jp Func_5d5f
+	set 2,[hl] ; fly warp or dungeon warp
+	call SpecialWarpIn
+	jp SpecialEnterMap
 Func_5bff: ; 5bff (1:5bff)
 	ld a,1
 	ld [wd358],a
@@ -247,7 +247,7 @@ LinkMenu: ; 5c0a (1:5c0a)
 	cp $2
 	jr z, .asm_5d2d
 	xor a
-	ld [wd700], a
+	ld [wWalkBikeSurfState], a
 	ld a, [wCurrentMenuItem] ; wCurrentMenuItem
 	and a
 	ld a, TRADE_CENTER
@@ -262,8 +262,8 @@ LinkMenu: ; 5c0a (1:5c0a)
 	ld hl, wd732
 	res 1, [hl]
 	ld a, [W_ANIMATIONID] ; W_ANIMATIONID
-	ld [wd71a], a
-	call Func_62ce
+	ld [wDestinationMap], a
+	call SpecialWarpIn
 	ld c, $14
 	call DelayFrames
 	xor a
@@ -272,7 +272,7 @@ LinkMenu: ; 5c0a (1:5c0a)
 	inc a
 	ld [W_ISLINKBATTLE], a ; W_ISLINKBATTLE
 	ld [wcc47], a
-	jr Func_5d5f
+	jr SpecialEnterMap
 .asm_5d2d
 	xor a
 	ld [wMenuJoypadPollCount], a ; wMenuJoypadPollCount
@@ -303,16 +303,17 @@ Func_5d52: ; 5d52 (1:5d52)
 	ld c, $14
 	call DelayFrames
 
-Func_5d5f: ; 5d5f (1:5d5f)
+; enter map after using a special warp or loading the game from the main menu
+SpecialEnterMap: ; 5d5f (1:5d5f)
 	xor a
 	ld [hJoyPressed], a
 	ld [hJoyHeld], a
 	ld [hJoy5], a
 	ld [wd72d], a
 	ld hl, wd732
-	set 0, [hl]
+	set 0, [hl] ; count play time
 	call ResetPlayerSpriteData
-	ld c, $14
+	ld c, 20
 	call DelayFrames
 	ld a, [wcc47]
 	and a

engine/menu/naming_screen.asm

@@ -22,10 +22,10 @@ AskName: ; 64eb (1:64eb)
 	ld a, [wCurrentMenuItem] ; wCurrentMenuItem
 	and a
 	jr nz, .asm_654c
-	ld a, [wcfcb]
+	ld a, [wUpdateSpritesEnabled]
 	push af
 	xor a
-	ld [wcfcb], a
+	ld [wUpdateSpritesEnabled], a
 	push hl
 	ld a, $2
 	ld [wd07d], a
@@ -33,12 +33,12 @@ AskName: ; 64eb (1:64eb)
 	ld a, [W_ISINBATTLE] ; W_ISINBATTLE
 	and a
 	jr nz, .asm_653e
-	call Func_3e08
+	call ReloadMapSpriteTilePatterns
 .asm_653e
 	call LoadScreenTilesFromBuffer1
 	pop hl
 	pop af
-	ld [wcfcb], a
+	ld [wUpdateSpritesEnabled], a
 	ld a, [wcf4b]
 	cp $50
 	ret nz
@@ -56,12 +56,12 @@ DoYouWantToNicknameText: ; 0x6557
 Func_655c: ; 655c (1:655c)
 	ld hl, wHPBarMaxHP
 	xor a
-	ld [wcfcb], a
+	ld [wUpdateSpritesEnabled], a
 	ld a, $2
 	ld [wd07d], a
 	call DisplayNamingScreen
 	call GBPalWhiteOutWithDelay3
-	call Func_3dbe
+	call RestoreScreenTilesAndReloadTilePatterns
 	call LoadGBPal
 	ld a, [wcf4b]
 	cp $50
@@ -171,8 +171,8 @@ DisplayNamingScreen: ; 6596 (1:6596)
 	ld a, [W_ISINBATTLE] ; W_ISINBATTLE
 	and a
 	jp z, LoadTextBoxTilePatterns
-	ld hl, Func_3ee5b
-	ld b, BANK(Func_3ee5b)
+	ld hl, LoadHudTilePatterns
+	ld b, BANK(LoadHudTilePatterns)
 	jp Bankswitch
 
 .unknownPointerTable_665e: ; 665e (1:665e)

engine/menu/party_menu.asm

@@ -57,7 +57,7 @@ RedrawPartyMenu_: ; 12ce3 (4:6ce3)
 	call LoadMonData
 	pop hl
 	push hl
-	ld a,[wcc35]
+	ld a,[wMenuItemToSwap]
 	and a ; is the player swapping pokemon positions?
 	jr z,.skipUnfilledRightArrow
 ; if the player is swapping pokemon positions

engine/menu/pc.asm

@@ -86,7 +86,7 @@ BillsPC: ; 17ee4 (5:7ee4)
 	callba BillsPC_
 ReloadMainMenu: ; 17f06 (5:7f06)
 	xor a
-	ld [wcc3c], a
+	ld [wDoNotWaitForButtonPressAfterDisplayingText], a
 	call ReloadMapData
 	call UpdateSprites  ;XXX: moves sprites
 	jp PCMainMenu

engine/menu/players_pc.asm

@@ -78,7 +78,7 @@ Func_796d: ; 796d (1:796d)
 	ld hl, wd730
 	res 6, [hl]
 	xor a
-	ld [wcc3c], a
+	ld [wDoNotWaitForButtonPressAfterDisplayingText], a
 	ret
 
 Func_7995: ; 7995 (1:7995)

engine/menu/pokedex.asm

@@ -36,8 +36,8 @@ ShowPokedexMenu: ; 40000 (10:4000)
 	ld [wCurrentMenuItem],a
 	ld [wLastMenuItem],a
 	ld [hJoy7],a
-	ld [wcd3a],a
-	ld [wcd3b],a
+	ld [wWastedByteCD3A],a
+	ld [wOverrideSimulatedJoypadStatesMask],a
 	pop af
 	ld [wListScrollOffset],a
 	call GBPalWhiteOutWithDelay3
@@ -404,10 +404,10 @@ ShowPokedexDataInternal: ; 402e2 (10:42e2)
 	call GoPAL_SET
 	pop af
 	ld [wd11e],a
-	ld a,[$ffd7]
+	ld a,[hTilesetType]
 	push af
 	xor a
-	ld [$ffd7],a
+	ld [hTilesetType],a
 	hlCoord 0, 0
 	ld de,1
 	ld bc,$6414
@@ -554,7 +554,7 @@ ShowPokedexDataInternal: ; 402e2 (10:42e2)
 	and a,%00000011 ; A button and B button
 	jr z,.waitForButtonPress
 	pop af
-	ld [$ffd7],a
+	ld [hTilesetType],a
 	call GBPalWhiteOut
 	call ClearScreen
 	call GoPAL_SET_CF1C

engine/menu/pokedex.asm.orig

@@ -0,0 +1,647 @@
+ShowPokedexMenu: ; 40000 (10:4000)
+	call GBPalWhiteOut
+	call ClearScreen
+	call UpdateSprites ; move sprites
+	ld a,[wListScrollOffset]
+	push af
+	xor a
+	ld [wCurrentMenuItem],a
+	ld [wListScrollOffset],a
+	ld [wLastMenuItem],a
+	inc a
+	ld [wd11e],a
+	ld [hJoy7],a
+.setUpGraphics
+	ld b,$08
+	call GoPAL_SET
+	callab LoadPokedexTilePatterns
+.doPokemonListMenu
+	ld hl,wTopMenuItemY
+	ld a,3
+	ld [hli],a ; top menu item Y
+	xor a
+	ld [hli],a ; top menu item X
+	inc a
+	ld [wcc37],a
+	inc hl
+	inc hl
+	ld a,6
+	ld [hli],a ; max menu item ID
+	ld [hl],%00110011 ; menu watched keys (Left, Right, B button, A  button)
+	call HandlePokedexListMenu
+	jr c,.goToSideMenu ; if the player chose a pokemon from the list
+.exitPokedex
+	xor a
+	ld [wcc37],a
+	ld [wCurrentMenuItem],a
+	ld [wLastMenuItem],a
+<<<<<<< HEAD
+	ld [hJoy7],a
+	ld [wcd3a],a
+	ld [wcd3b],a
+=======
+	ld [$ffb7],a
+	ld [wWastedByteCD3A],a
+	ld [wOverrideSimulatedJoypadStatesMask],a
+>>>>>>> yama/master
+	pop af
+	ld [wListScrollOffset],a
+	call GBPalWhiteOutWithDelay3
+	call GoPAL_SET_CF1C
+	jp ReloadMapData
+.goToSideMenu
+	call HandlePokedexSideMenu
+	dec b
+	jr z,.exitPokedex ; if the player chose Quit
+	dec b
+	jr z,.doPokemonListMenu ; if pokemon not seen or player pressed B button
+	jp .setUpGraphics ; if pokemon data or area was shown
+
+; handles the menu on the lower right in the pokedex screen
+; OUTPUT:
+; b = reason for exiting menu
+; 00: showed pokemon data or area
+; 01: the player chose Quit
+; 02: the pokemon has not been seen yet or the player pressed the B button
+HandlePokedexSideMenu: ; 4006d (10:406d)
+	call PlaceUnfilledArrowMenuCursor
+	ld a,[wCurrentMenuItem]
+	push af
+	ld b,a
+	ld a,[wLastMenuItem]
+	push af
+	ld a,[wListScrollOffset]
+	push af
+	add b
+	inc a
+	ld [wd11e],a
+	ld a,[wd11e]
+	push af
+	ld a,[wWhichTrade]
+	push af
+	ld hl,wPokedexSeen
+	call IsPokemonBitSet
+	ld b,2
+	jr z,.exitSideMenu
+	call PokedexToIndex
+	ld hl,wTopMenuItemY
+	ld a,10
+	ld [hli],a ; top menu item Y
+	ld a,15
+	ld [hli],a ; top menu item X
+	xor a
+	ld [hli],a ; current menu item ID
+	inc hl
+	ld a,3
+	ld [hli],a ; max menu item ID
+	ld [hli],a ; menu watched keys (A button and B button)
+	xor a
+	ld [hli],a ; old menu item ID
+	ld [wcc37],a
+.handleMenuInput
+	call HandleMenuInput
+	bit 1,a ; was the B button pressed?
+	ld b,2
+	jr nz,.buttonBPressed
+	ld a,[wCurrentMenuItem]
+	and a
+	jr z,.choseData
+	dec a
+	jr z,.choseCry
+	dec a
+	jr z,.choseArea
+.choseQuit
+	ld b,1
+.exitSideMenu
+	pop af
+	ld [wWhichTrade],a
+	pop af
+	ld [wd11e],a
+	pop af
+	ld [wListScrollOffset],a
+	pop af
+	ld [wLastMenuItem],a
+	pop af
+	ld [wCurrentMenuItem],a
+	push bc
+	hlCoord 0, 3
+	ld de,20
+	ld bc,$7f0d ; 13 blank tiles
+	call DrawTileLine ; cover up the menu cursor in the pokemon list
+	pop bc
+	ret
+.buttonBPressed
+	push bc
+	hlCoord 15, 10
+	ld de,20
+	ld bc,$7f07 ; 7 blank tiles
+	call DrawTileLine ; cover up the menu cursor in the side menu
+	pop bc
+	jr .exitSideMenu
+.choseData
+	call ShowPokedexDataInternal
+	ld b,0
+	jr .exitSideMenu
+; play pokemon cry
+.choseCry
+	ld a,[wd11e]
+	call GetCryData ; get cry data
+	call PlaySound ; play sound
+	jr .handleMenuInput
+.choseArea
+	predef LoadTownMap_Nest ; display pokemon areas
+	ld b,0
+	jr .exitSideMenu
+
+; handles the list of pokemon on the left of the pokedex screen
+; sets carry flag if player presses A, unsets carry flag if player presses B
+HandlePokedexListMenu: ; 40111 (10:4111)
+	xor a
+	ld [H_AUTOBGTRANSFERENABLED],a
+; draw the horizontal line separating the seen and owned amounts from the menu
+	hlCoord 15, 8
+	ld a,$7a ; horizontal line tile
+	ld [hli],a
+	ld [hli],a
+	ld [hli],a
+	ld [hli],a
+	ld [hli],a
+	hlCoord 14, 0
+	ld [hl],$71 ; vertical line tile
+	hlCoord 14, 1
+	call DrawPokedexVerticalLine
+	hlCoord 14, 9
+	call DrawPokedexVerticalLine
+	ld hl,wPokedexSeen
+	ld b,wPokedexSeenEnd - wPokedexSeen
+	call CountSetBits
+	ld de,wd11e
+	hlCoord 16, 3
+	ld bc,$0103
+	call PrintNumber ; print number of seen pokemon
+	ld hl,wPokedexOwned
+	ld b,wPokedexOwnedEnd - wPokedexOwned
+	call CountSetBits
+	ld de,wd11e
+	hlCoord 16, 6
+	ld bc,$0103
+	call PrintNumber ; print number of owned pokemon
+	hlCoord 16, 2
+	ld de,PokedexSeenText
+	call PlaceString
+	hlCoord 16, 5
+	ld de,PokedexOwnText
+	call PlaceString
+	hlCoord 1, 1
+	ld de,PokedexContentsText
+	call PlaceString
+	hlCoord 16, 10
+	ld de,PokedexMenuItemsText
+	call PlaceString
+; find the highest pokedex number among the pokemon the player has seen
+	ld hl,wPokedexSeenEnd - 1
+	ld b,153
+.maxSeenPokemonLoop
+	ld a,[hld]
+	ld c,8
+.maxSeenPokemonInnerLoop
+	dec b
+	sla a
+	jr c,.storeMaxSeenPokemon
+	dec c
+	jr nz,.maxSeenPokemonInnerLoop
+	jr .maxSeenPokemonLoop
+.storeMaxSeenPokemon
+	ld a,b
+	ld [wWhichTrade],a ; max seen pokemon
+.loop
+	xor a
+	ld [H_AUTOBGTRANSFERENABLED],a
+	hlCoord 4, 2
+	ld bc,$0e0a
+	call ClearScreenArea
+	hlCoord 1, 3
+	ld a,[wListScrollOffset]
+	ld [wd11e],a
+	ld d,7
+	ld a,[wWhichTrade]
+	cp a,7
+	jr nc,.printPokemonLoop
+	ld d,a
+	dec a
+	ld [wMaxMenuItem],a
+; loop to print pokemon pokedex numbers and names
+; if the player has owned the pokemon, it puts a pokeball beside the name
+.printPokemonLoop
+	ld a,[wd11e]
+	inc a
+	ld [wd11e],a
+	push af
+	push de
+	push hl
+	ld de,-20
+	add hl,de
+	ld de,wd11e
+	ld bc,$8103
+	call PrintNumber ; print the pokedex number
+	ld de,20
+	add hl,de
+	dec hl
+	push hl
+	ld hl,wPokedexOwned
+	call IsPokemonBitSet
+	pop hl
+	ld a," "
+	jr z,.writeTile
+	ld a,$72 ; pokeball tile
+.writeTile
+	ld [hl],a ; put a pokeball next to pokemon that the player has owned
+	push hl
+	ld hl,wPokedexSeen
+	call IsPokemonBitSet
+	jr nz,.getPokemonName ; if the player has seen the pokemon
+	ld de,.dashedLine ; print a dashed line in place of the name if the player hasn't seen the pokemon
+	jr .skipGettingName
+.dashedLine ; for unseen pokemon in the list
+	db "----------@"
+.getPokemonName
+	call PokedexToIndex
+	call GetMonName
+.skipGettingName
+	pop hl
+	inc hl
+	call PlaceString
+	pop hl
+	ld bc,2 * 20
+	add hl,bc
+	pop de
+	pop af
+	ld [wd11e],a
+	dec d
+	jr nz,.printPokemonLoop
+	ld a,01
+	ld [H_AUTOBGTRANSFERENABLED],a
+	call Delay3
+	call GBPalNormal
+	call HandleMenuInput
+	bit 1,a ; was the B button pressed?
+	jp nz,.buttonBPressed
+.checkIfUpPressed
+	bit 6,a ; was Up pressed?
+	jr z,.checkIfDownPressed
+.upPressed ; scroll up one row
+	ld a,[wListScrollOffset]
+	and a
+	jp z,.loop
+	dec a
+	ld [wListScrollOffset],a
+	jp .loop
+.checkIfDownPressed
+	bit 7,a ; was Down pressed?
+	jr z,.checkIfRightPressed
+.downPressed ; scroll down one row
+	ld a,[wWhichTrade]
+	cp a,7
+	jp c,.loop
+	sub a,7
+	ld b,a
+	ld a,[wListScrollOffset]
+	cp b
+	jp z,.loop
+	inc a
+	ld [wListScrollOffset],a
+	jp .loop
+.checkIfRightPressed
+	bit 4,a ; was Right pressed?
+	jr z,.checkIfLeftPressed
+.rightPressed ; scroll down 7 rows
+	ld a,[wWhichTrade]
+	cp a,7
+	jp c,.loop
+	sub a,6
+	ld b,a
+	ld a,[wListScrollOffset]
+	add a,7
+	ld [wListScrollOffset],a
+	cp b
+	jp c,.loop
+	dec b
+	ld a,b
+	ld [wListScrollOffset],a
+	jp .loop
+.checkIfLeftPressed ; scroll up 7 rows
+	bit 5,a ; was Left pressed?
+	jr z,.buttonAPressed
+.leftPressed
+	ld a,[wListScrollOffset]
+	sub a,7
+	ld [wListScrollOffset],a
+	jp nc,.loop
+	xor a
+	ld [wListScrollOffset],a
+	jp .loop
+.buttonAPressed
+	scf
+	ret
+.buttonBPressed
+	and a
+	ret
+
+DrawPokedexVerticalLine: ; 4028e (10:428e)
+	ld c,9 ; height of line
+	ld de,20 ; width of screen
+	ld a,$71 ; vertical line tile
+.loop
+	ld [hl],a
+	add hl,de
+	xor a,1 ; toggle between vertical line tile and box tile
+	dec c
+	jr nz,.loop
+	ret
+
+PokedexSeenText: ; 4029d (10:429d)
+	db "SEEN@"
+
+PokedexOwnText: ; 402a2 (10:42a2)
+	db "OWN@"
+
+PokedexContentsText: ; 402a6 (10:42a6)
+	db "CONTENTS@"
+
+PokedexMenuItemsText: ; 402af (10:42af)
+	db   "DATA"
+	next "CRY"
+	next "AREA"
+	next "QUIT@"
+
+; tests if a pokemon's bit is set in the seen or owned pokemon bit fields
+; INPUT:
+; [wd11e] = pokedex number
+; hl = address of bit field
+IsPokemonBitSet: ; 402c2 (10:42c2)
+	ld a,[wd11e]
+	dec a
+	ld c,a
+	ld b,2
+	predef FlagActionPredef
+	ld a,c
+	and a
+	ret
+
+; function to display pokedex data from outside the pokedex
+ShowPokedexData: ; 402d1 (10:42d1)
+	call GBPalWhiteOutWithDelay3
+	call ClearScreen
+	call UpdateSprites
+	callab LoadPokedexTilePatterns ; load pokedex tiles
+
+; function to display pokedex data from inside the pokedex
+ShowPokedexDataInternal: ; 402e2 (10:42e2)
+	ld hl,wd72c
+	set 1,[hl]
+	ld a,$33 ; 3/7 volume
+	ld [$ff24],a
+	call GBPalWhiteOut ; zero all palettes
+	call ClearScreen
+	ld a,[wd11e] ; pokemon ID
+	ld [wcf91],a
+	push af
+	ld b,04
+	call GoPAL_SET
+	pop af
+	ld [wd11e],a
+	ld a,[hTilesetType]
+	push af
+	xor a
+	ld [hTilesetType],a
+	hlCoord 0, 0
+	ld de,1
+	ld bc,$6414
+	call DrawTileLine ; draw top border
+	hlCoord 0, 17
+	ld b,$6f
+	call DrawTileLine ; draw bottom border
+	hlCoord 0, 1
+	ld de,20
+	ld bc,$6610
+	call DrawTileLine ; draw left border
+	hlCoord 19, 1
+	ld b,$67
+	call DrawTileLine ; draw right border
+	ld a,$63 ; upper left corner tile
+	Coorda 0, 0
+	ld a,$65 ; upper right corner tile
+	Coorda 19, 0
+	ld a,$6c ; lower left corner tile
+	Coorda 0, 17
+	ld a,$6e ; lower right corner tile
+	Coorda 19, 17
+	hlCoord 0, 9
+	ld de,PokedexDataDividerLine
+	call PlaceString ; draw horizontal divider line
+	hlCoord 9, 6
+	ld de,HeightWeightText
+	call PlaceString
+	call GetMonName
+	hlCoord 9, 2
+	call PlaceString
+	ld hl,PokedexEntryPointers
+	ld a,[wd11e]
+	dec a
+	ld e,a
+	ld d,0
+	add hl,de
+	add hl,de
+	ld a,[hli]
+	ld e,a
+	ld d,[hl] ; de = address of pokedex entry
+	hlCoord 9, 4
+	call PlaceString ; print species name
+	ld h,b
+	ld l,c
+	push de
+	ld a,[wd11e]
+	push af
+	call IndexToPokedex
+	hlCoord 2, 8
+	ld a, "№"
+	ld [hli],a
+	ld a,$f2
+	ld [hli],a
+	ld de,wd11e
+	ld bc,$8103
+	call PrintNumber ; print pokedex number
+	ld hl,wPokedexOwned
+	call IsPokemonBitSet
+	pop af
+	ld [wd11e],a
+	ld a,[wcf91]
+	ld [wd0b5],a
+	pop de
+	push af
+	push bc
+	push de
+	push hl
+	call Delay3
+	call GBPalNormal
+	call GetMonHeader ; load pokemon picture location
+	hlCoord 1, 1
+	call LoadFlippedFrontSpriteByMonIndex ; draw pokemon picture
+	ld a,[wcf91]
+	call PlayCry ; play pokemon cry
+	pop hl
+	pop de
+	pop bc
+	pop af
+	ld a,c
+	and a
+	jp z,.waitForButtonPress ; if the pokemon has not been owned, don't print the height, weight, or description
+	inc de ; de = address of feet (height)
+	ld a,[de] ; reads feet, but a is overwritten without being used
+	hlCoord 12, 6
+	ld bc,$0102
+	call PrintNumber ; print feet (height)
+	ld a,$60 ; feet symbol tile (one tick)
+	ld [hl],a
+	inc de
+	inc de ; de = address of inches (height)
+	hlCoord 15, 6
+	ld bc,$8102
+	call PrintNumber ; print inches (height)
+	ld a,$61 ; inches symbol tile (two ticks)
+	ld [hl],a
+; now print the weight (note that weight is stored in tenths of pounds internally)
+	inc de
+	inc de
+	inc de ; de = address of upper byte of weight
+	push de
+; put weight in big-endian order at $ff8b
+	ld hl,$ff8b
+	ld a,[hl] ; save existing value of [$ff8b]
+	push af
+	ld a,[de] ; a = upper byte of weight
+	ld [hli],a ; store upper byte of weight in [$ff8b]
+	ld a,[hl] ; save existing value of [$ff8c]
+	push af
+	dec de
+	ld a,[de] ; a = lower byte of weight
+	ld [hl],a ; store lower byte of weight in [$ff8c]
+	ld de,$ff8b
+	hlCoord 11, 8
+	ld bc,$0205 ; no leading zeroes, right-aligned, 2 bytes, 5 digits
+	call PrintNumber ; print weight
+	hlCoord 14, 8
+	ld a,[$ff8c]
+	sub a,10
+	ld a,[$ff8b]
+	sbc a,0
+	jr nc,.next
+	ld [hl],"0" ; if the weight is less than 10, put a 0 before the decimal point
+.next
+	inc hl
+	ld a,[hli]
+	ld [hld],a ; make space for the decimal point by moving the last digit forward one tile
+	ld [hl],$f2 ; decimal point tile
+	pop af
+	ld [$ff8c],a ; restore original value of [$ff8c]
+	pop af
+	ld [$ff8b],a ; restore original value of [$ff8b]
+	pop hl
+	inc hl ; hl = address of pokedex description text
+	bcCoord 1, 11
+	ld a,2
+	ld [$fff4],a
+	call TextCommandProcessor ; print pokedex description text
+	xor a
+	ld [$fff4],a
+.waitForButtonPress
+	call JoypadLowSensitivity
+	ld a,[hJoy5]
+	and a,%00000011 ; A button and B button
+	jr z,.waitForButtonPress
+	pop af
+	ld [hTilesetType],a
+	call GBPalWhiteOut
+	call ClearScreen
+	call GoPAL_SET_CF1C
+	call LoadTextBoxTilePatterns
+	call GBPalNormal
+	ld hl,wd72c
+	res 1,[hl]
+	ld a,$77 ; max volume
+	ld [$ff24],a
+	ret
+
+HeightWeightText: ; 40448 (10:4448)
+	db "HT  ?",$60,"??",$61,$4E,"WT   ???lb@"
+
+; XXX does anything point to this?
+Unknown_4045D: ; 4045d (10:445d)
+	db $54,$50
+
+; horizontal line that divides the pokedex text description from the rest of the data
+PokedexDataDividerLine: ; 4045f (10:445f)
+	db $68,$69,$6B,$69,$6B
+	db $69,$6B,$69,$6B,$6B
+	db $6B,$6B,$69,$6B,$69
+	db $6B,$69,$6B,$69,$6A
+	db $50
+
+; draws a line of tiles
+; INPUT:
+; b = tile ID
+; c = number of tile ID's to write
+; de = amount to destination address after each tile (1 for horizontal, 20 for vertical)
+; hl = destination address
+DrawTileLine: ; 40474 (10:4474)
+	push bc
+	push de
+.loop
+	ld [hl],b
+	add hl,de
+	dec c
+	jr nz,.loop
+	pop de
+	pop bc
+	ret
+
+INCLUDE "data/pokedex_entries.asm"
+
+PokedexToIndex: ; 40ff9 (10:4ff9)
+	; converts the Pokédex number at wd11e to an index
+	push bc
+	push hl
+	ld a,[wd11e]
+	ld b,a
+	ld c,0
+	ld hl,PokedexOrder
+
+.loop ; go through the list until we find an entry with a matching dex number
+	inc c
+	ld a,[hli]
+	cp b
+	jr nz,.loop
+
+	ld a,c
+	ld [wd11e],a
+	pop hl
+	pop bc
+	ret
+
+IndexToPokedex: ; 41010 (10:5010)
+	; converts the indexédex number at wd11e to a Pokédex number
+	push bc
+	push hl
+	ld a,[wd11e]
+	dec a
+	ld hl,PokedexOrder
+	ld b,0
+	ld c,a
+	add hl,bc
+	ld a,[hl]
+	ld [wd11e],a
+	pop hl
+	pop bc
+	ret
+
+INCLUDE "data/pokedex_order.asm"

engine/menu/start_menu.asm

@@ -2,8 +2,8 @@ DisplayStartMenu:: ; 2acd (0:2acd)
 	ld a,$04 ; hardcoded Bank, not sure what's it refers to
 	ld [H_LOADEDROMBANK],a
 	ld [$2000],a ; ROM bank 4
-	ld a,[wd700] ; walking/biking/surfing
-	ld [wd11a],a
+	ld a,[wWalkBikeSurfState] ; walking/biking/surfing
+	ld [wWalkBikeSurfStateCopy],a
 	ld a, (SFX_02_3f - SFX_Headers_02) / 3 ; Start menu sound
 	call PlaySound
 

engine/menu/start_sub_menus.asm

@@ -11,21 +11,21 @@ StartMenu_Pokemon: ; 130a9 (4:70a9)
 	and a
 	jp z,RedisplayStartMenu
 	xor a
-	ld [wcc35],a
+	ld [wMenuItemToSwap],a
 	ld [wd07d],a
-	ld [wcfcb],a
+	ld [wUpdateSpritesEnabled],a
 	call DisplayPartyMenu
 	jr .checkIfPokemonChosen
 .loop
 	xor a
-	ld [wcc35],a
+	ld [wMenuItemToSwap],a
 	ld [wd07d],a
 	call GoBackToPartyMenu
 .checkIfPokemonChosen
 	jr nc,.chosePokemon
 .exitMenu
 	call GBPalWhiteOutWithDelay3
-	call Func_3dbe
+	call RestoreScreenTilesAndReloadTilePatterns
 	call LoadGBPal
 	jp RedisplayStartMenu
 .chosePokemon
@@ -184,7 +184,7 @@ StartMenu_Pokemon: ; 130a9 (4:70a9)
 	bit 0,a ; does the player have the Boulder Badge?
 	jp z,.newBadgeRequired
 	xor a
-	ld [wd35d],a
+	ld [wMapPalOffset],a
 	ld hl,.flashLightsAreaText
 	call PrintText
 	call GBPalWhiteOutWithDelay3
@@ -273,7 +273,7 @@ StartMenu_Pokemon: ; 130a9 (4:70a9)
 	TX_FAR _NotHealthyEnoughText
 	db "@"
 .goBackToMap
-	call Func_3dbe
+	call RestoreScreenTilesAndReloadTilePatterns
 	jp CloseTextDisplay
 .newBadgeRequired
 	ld hl,.newBadgeRequiredText
@@ -336,7 +336,7 @@ StartMenu_Item: ; 13302 (4:7302)
 	Coorda 5, 10
 	call PlaceUnfilledArrowMenuCursor
 	xor a
-	ld [wcc35],a
+	ld [wMenuItemToSwap],a
 	ld a,[wcf91]
 	cp a,BICYCLE
 	jp z,.useOrTossItem
@@ -406,20 +406,20 @@ StartMenu_Item: ; 13302 (4:7302)
 	jp z,ItemMenuLoop
 	jp CloseStartMenu
 .useItem_partyMenu
-	ld a,[wcfcb]
+	ld a,[wUpdateSpritesEnabled]
 	push af
 	call UseItem
 	ld a,[wcd6a]
 	cp a,$02
 	jp z,.partyMenuNotDisplayed
 	call GBPalWhiteOutWithDelay3
-	call Func_3dbe
+	call RestoreScreenTilesAndReloadTilePatterns
 	pop af
-	ld [wcfcb],a
+	ld [wUpdateSpritesEnabled],a
 	jp StartMenu_Item
 .partyMenuNotDisplayed
 	pop af
-	ld [wcfcb],a
+	ld [wUpdateSpritesEnabled],a
 	jp ItemMenuLoop
 .tossItem
 	call IsKeyItem
@@ -500,10 +500,10 @@ StartMenu_TrainerInfo: ; 13460 (4:7460)
 	call GBPalWhiteOut
 	call ClearScreen
 	call UpdateSprites ; move sprites
-	ld a,[$ffd7]
+	ld a,[hTilesetType]
 	push af
 	xor a
-	ld [$ffd7],a
+	ld [hTilesetType],a
 	call DrawTrainerInfo
 	predef DrawBadges ; draw badges
 	ld b,$0d
@@ -517,7 +517,7 @@ StartMenu_TrainerInfo: ; 13460 (4:7460)
 	call ReloadMapData
 	call LoadGBPal
 	pop af
-	ld [$ffd7],a
+	ld [hTilesetType],a
 	jp RedisplayStartMenu
 
 ; loads tile patterns and draws everything except for gym leader faces / badges
@@ -738,17 +738,17 @@ SwitchPartyMon_OAM: ; 13625 (4:7625)
 	jp PlaySound
 
 SwitchPartyMon_Stats: ; 13653 (4:7653)
-	ld a, [wcc35]
+	ld a, [wMenuItemToSwap]
 	and a
 	jr nz, .asm_13661
 	ld a, [wWhichPokemon] ; wWhichPokemon
 	inc a
-	ld [wcc35], a
+	ld [wMenuItemToSwap], a
 	ret
 .asm_13661
 	xor a
 	ld [wd07d], a
-	ld a, [wcc35]
+	ld a, [wMenuItemToSwap]
 	dec a
 	ld b, a
 	ld a, [wCurrentMenuItem] ; wCurrentMenuItem
@@ -756,12 +756,12 @@ SwitchPartyMon_Stats: ; 13653 (4:7653)
 	cp b
 	jr nz, .asm_1367b
 	xor a
-	ld [wcc35], a
+	ld [wMenuItemToSwap], a
 	ld [wd07d], a
 	ret
 .asm_1367b
 	ld a, b
-	ld [wcc35], a
+	ld [wMenuItemToSwap], a
 	push hl
 	push de
 	ld hl, wPartySpecies
@@ -773,7 +773,7 @@ SwitchPartyMon_Stats: ; 13653 (4:7653)
 	jr nc, .asm_1368e
 	inc h
 .asm_1368e
-	ld a, [wcc35]
+	ld a, [wMenuItemToSwap]
 	add e
 	ld e, a
 	jr nc, .asm_13696
@@ -790,61 +790,61 @@ SwitchPartyMon_Stats: ; 13653 (4:7653)
 	ld a, [wCurrentMenuItem] ; wCurrentMenuItem
 	call AddNTimes
 	push hl
-	ld de, wcc97
+	ld de, wSwitchPartyMonTempBuffer
 	ld bc, $2c
 	call CopyData
 	ld hl, wPartyMons
 	ld bc, $2c
-	ld a, [wcc35]
+	ld a, [wMenuItemToSwap]
 	call AddNTimes
 	pop de
 	push hl
 	ld bc, $2c
 	call CopyData
 	pop de
-	ld hl, wcc97
+	ld hl, wSwitchPartyMonTempBuffer
 	ld bc, $2c
 	call CopyData
 	ld hl, wPartyMonOT ; wd273
 	ld a, [wCurrentMenuItem] ; wCurrentMenuItem
 	call SkipFixedLengthTextEntries
 	push hl
-	ld de, wcc97
+	ld de, wSwitchPartyMonTempBuffer
 	ld bc, $b
 	call CopyData
 	ld hl, wPartyMonOT ; wd273
-	ld a, [wcc35]
+	ld a, [wMenuItemToSwap]
 	call SkipFixedLengthTextEntries
 	pop de
 	push hl
 	ld bc, $b
 	call CopyData
 	pop de
-	ld hl, wcc97
+	ld hl, wSwitchPartyMonTempBuffer
 	ld bc, $b
 	call CopyData
 	ld hl, wPartyMonNicks ; wPartyMonNicks
 	ld a, [wCurrentMenuItem] ; wCurrentMenuItem
 	call SkipFixedLengthTextEntries
 	push hl
-	ld de, wcc97
+	ld de, wSwitchPartyMonTempBuffer
 	ld bc, $b
 	call CopyData
 	ld hl, wPartyMonNicks ; wPartyMonNicks
-	ld a, [wcc35]
+	ld a, [wMenuItemToSwap]
 	call SkipFixedLengthTextEntries
 	pop de
 	push hl
 	ld bc, $b
 	call CopyData
 	pop de
-	ld hl, wcc97
+	ld hl, wSwitchPartyMonTempBuffer
 	ld bc, $b
 	call CopyData
-	ld a, [wcc35]
+	ld a, [wMenuItemToSwap]
 	ld [wWhichTrade], a ; wWhichTrade
 	xor a
-	ld [wcc35], a
+	ld [wMenuItemToSwap], a
 	ld [wd07d], a
 	pop de
 	pop hl

engine/menu/status_screen.asm

@@ -36,10 +36,10 @@ StatusScreen: ; 12953 (4:6953)
 	ld hl, vChars2 + $720
 	ld bc,(BANK(PTile) << 8 | $01)
 	call CopyVideoDataDouble ; P (for PP), inline
-	ld a, [$ffd7]
+	ld a, [hTilesetType]
 	push af
 	xor a
-	ld [$ffd7], a
+	ld [hTilesetType], a
 	hlCoord 19, 1
 	ld bc, $060a
 	call DrawLineBox ; Draws the box around name, HP and status
@@ -109,7 +109,7 @@ StatusScreen: ; 12953 (4:6953)
 	call PlayCry ; play Pokémon cry
 	call WaitForTextScrollButtonPress ; wait for button
 	pop af
-	ld [$ffd7], a
+	ld [hTilesetType], a
 	ret
 .unk_12a7e ; 0x12a7e ; I don't know what this does, iterates over pointers?
 	ld a, [wcc49]
@@ -227,10 +227,10 @@ StatsText: ; 12b3a (4:6b3a)
 	next "SPECIAL@"
 
 StatusScreen2: ; 12b57 (4:6b57)
-	ld a, [$ffd7]
+	ld a, [hTilesetType]
 	push af
 	xor a
-	ld [$ffd7], a
+	ld [hTilesetType], a
 	ld [$ffba], a
 	ld bc, $0005
 	ld hl, wd0dc
@@ -360,7 +360,7 @@ StatusScreen2: ; 12b57 (4:6b57)
 	call Delay3
 	call WaitForTextScrollButtonPress ; wait for button
 	pop af
-	ld [$ffd7], a
+	ld [hTilesetType], a
 	ld hl, wd72c
 	res 1, [hl]
 	ld a, $77

engine/mon_party_sprites.asm

@@ -21,7 +21,7 @@ GetAnimationSpeed: ; 7170a (1c:570a)
 	ld c, a
 	ld hl, PartyMonSpeeds
 	add hl, bc
-	ld a, [wcf1b]
+	ld a, [wOnSGB]
 	xor $1
 	add [hl]
 	ld c, a

engine/oak_speech.asm

@@ -49,10 +49,10 @@ OakSpeech: ; 6115 (1:6115)
 	ld [wcf96],a
 	call AddItemToInventory  ; give one potion
 	ld a,[W_ANIMATIONID]
-	ld [wd71a],a
-	call Func_62ce
+	ld [wDestinationMap],a
+	call SpecialWarpIn
 	xor a
-	ld [$FFD7],a
+	ld [hTilesetType],a
 	ld a,[wd732]
 	bit 1,a ; XXX when is bit 1 set?
 	jp nz,Func_61bc ; easter egg: skip the intro
@@ -62,7 +62,7 @@ OakSpeech: ; 6115 (1:6115)
 	call FadeInIntroPic
 	ld hl,OakSpeechText1
 	call PrintText      ; prints text box
-	call GBFadeOut2
+	call GBFadeOutToWhite
 	call ClearScreen
 	ld a,NIDORINO
 	ld [wd0b5],a    ; pic displayed is stored at this location
@@ -73,7 +73,7 @@ OakSpeech: ; 6115 (1:6115)
 	call MovePicLeft
 	ld hl,OakSpeechText2
 	call PrintText      ; Prints text box
-	call GBFadeOut2
+	call GBFadeOutToWhite
 	call ClearScreen
 	ld de,RedPicFront
 	ld bc,(Bank(RedPicFront) << 8) | $00
@@ -82,7 +82,7 @@ OakSpeech: ; 6115 (1:6115)
 	ld hl,IntroducePlayerText
 	call PrintText
 	call LoadDefaultNamesPlayer ; brings up NewName/Red/etc menu
-	call GBFadeOut2
+	call GBFadeOutToWhite
 	call ClearScreen
 	ld de,Rival1Pic
 	ld bc,(Bank(Rival1Pic) << 8) | $00
@@ -93,12 +93,12 @@ OakSpeech: ; 6115 (1:6115)
 	call LoadDefaultNamesRival
 
 Func_61bc: ; 61bc (1:61bc)
-	call GBFadeOut2
+	call GBFadeOutToWhite
 	call ClearScreen
 	ld de,RedPicFront
 	ld bc,(Bank(RedPicFront) << 8) | $00
 	call IntroPredef3B
-	call GBFadeIn2
+	call GBFadeInFromWhite
 	ld a,[wd72d]
 	and a
 	jr nz,.next
@@ -148,10 +148,10 @@ Func_61bc: ; 61bc (1:61bc)
 	call ClearScreenArea
 	call LoadTextBoxTilePatterns
 	ld a,1
-	ld [wcfcb],a
+	ld [wUpdateSpritesEnabled],a
 	ld c,$32
 	call DelayFrames
-	call GBFadeOut2
+	call GBFadeOutToWhite
 	jp ClearScreen
 OakSpeechText1: ; 6253 (1:6253)
 	TX_FAR _OakSpeechText1

engine/overworld/cable_club_npc.asm

@@ -24,7 +24,7 @@ Func_71e1: ; 71e1 (1:71e1)
 	ld a, $ff
 	ld [$ffaa], a
 	ld a, $2
-	ld [$ff01], a
+	ld [rSB], a
 	xor a
 	ld [$ffad], a
 	ld a, $80
@@ -34,7 +34,7 @@ Func_71e1: ; 71e1 (1:71e1)
 	ld [wcc47], a
 	jr z, .asm_7287 ; 0x720b $7a
 	ld a, $1
-	ld [$ff01], a
+	ld [rSB], a
 	ld a, $81
 	ld [$ff02], a
 	call DelayFrame
@@ -148,7 +148,7 @@ Func_72d7: ; 72d7 (1:72d7)
 	ld a, $ff
 	ld [$ffaa], a
 	ld a, $2
-	ld [$ff01], a
+	ld [rSB], a
 	xor a
 	ld [$ffad], a
 	ld a, $80

engine/overworld/card_key.asm

@@ -2,18 +2,18 @@ PrintCardKeyText: ; 52673 (14:6673)
 	ld hl, SilphCoMapList
 	ld a, [W_CURMAP]
 	ld b, a
-.asm_5267a
+.silphCoMapListLoop
 	ld a, [hli]
 	cp $ff
 	ret z
 	cp b
-	jr nz, .asm_5267a
-	predef Func_c586
-	ld a, [wcfc6]
+	jr nz, .silphCoMapListLoop
+	predef GetTileAndCoordsInFrontOfPlayer
+	ld a, [wTileInFrontOfPlayer]
 	cp $18
-	jr z, .asm_5269c
+	jr z, .cardKeyDoorInFrontOfPlayer
 	cp $24
-	jr z, .asm_5269c
+	jr z, .cardKeyDoorInFrontOfPlayer
 	ld b, a
 	ld a, [W_CURMAP]
 	cp SILPH_CO_11F
@@ -21,41 +21,41 @@ PrintCardKeyText: ; 52673 (14:6673)
 	ld a, b
 	cp $5e
 	ret nz
-.asm_5269c
+.cardKeyDoorInFrontOfPlayer
 	ld b, CARD_KEY
 	call IsItemInBag
-	jr z, .asm_526dc
-	call Func_526fd
+	jr z, .noCardKey
+	call GetCoordsInFrontOfPlayer
 	push de
 	ld a, $1
-	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
+	ld [H_DOWNARROWBLINKCNT2], a
 	call PrintPredefTextID
 	pop de
 	srl d
 	ld a, d
 	ld b, a
-	ld [wd73f], a
+	ld [wCardKeyDoorY], a
 	srl e
 	ld a, e
 	ld c, a
-	ld [wd740], a
-	ld a, [W_CURMAP] ; W_CURMAP
+	ld [wCardKeyDoorX], a
+	ld a, [W_CURMAP]
 	cp SILPH_CO_11F
-	jr nz, .asm_526c8
+	jr nz, .notSilphCo11F
 	ld a, $3
-	jr .asm_526ca
-.asm_526c8
+	jr .replaceCardKeyDoorTileBlock
+.notSilphCo11F
 	ld a, $e
-.asm_526ca
+.replaceCardKeyDoorTileBlock
 	ld [wd09f], a
-	predef Func_ee9e
+	predef ReplaceTileBlock
 	ld hl, wd126
 	set 5, [hl]
 	ld a, (SFX_1f_57 - SFX_Headers_1f) / 3
 	jp PlaySound
-.asm_526dc
+.noCardKey
 	ld a, $2
-	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
+	ld [H_DOWNARROWBLINKCNT2], a
 	jp PrintPredefTextID
 
 SilphCoMapList: ; 526e3 (14:66e3)
@@ -81,26 +81,32 @@ CardKeyFailText: ; 526f8 (14:66f8)
 	TX_FAR _CardKeyFailText
 	db "@"
 
-Func_526fd: ; 526fd (14:66fd)
-	ld a, [W_YCOORD] ; wd361
+; d = Y
+; e = X
+GetCoordsInFrontOfPlayer: ; 526fd (14:66fd)
+	ld a, [W_YCOORD]
 	ld d, a
-	ld a, [W_XCOORD] ; wd362
+	ld a, [W_XCOORD]
 	ld e, a
-	ld a, [wSpriteStateData1 + 9]
+	ld a, [wSpriteStateData1 + 9] ; player's sprite facing direction
 	and a
-	jr nz, .asm_5270d
+	jr nz, .notFacingDown
+; facing down
 	inc d
 	ret
-.asm_5270d
-	cp $4
-	jr nz, .asm_52713
+.notFacingDown
+	cp SPRITE_FACING_UP
+	jr nz, .notFacingUp
+; facing up
 	dec d
 	ret
-.asm_52713
-	cp $8
-	jr nz, .asm_52719
+.notFacingUp
+	cp SPRITE_FACING_LEFT
+	jr nz, .notFacingLeft
+; facing left
 	dec e
 	ret
-.asm_52719
+.notFacingLeft
+; facing right
 	inc e
 	ret

engine/overworld/cut.asm

@@ -6,13 +6,13 @@ UsedCut: ; ef54 (3:6f54)
 	jr z, .asm_ef6b
 	cp GYM
 	jr nz, .asm_ef77
-	ld a, [wcfc6]
+	ld a, [wTileInFrontOfPlayer]
 	cp $50 ; gym cut tree
 	jr nz, .asm_ef77
 	jr asm_ef82
 .asm_ef6b
 	dec a
-	ld a, [wcfc6]
+	ld a, [wTileInFrontOfPlayer]
 	cp $3d ; cut tree
 	jr z, asm_ef82
 	cp $52 ; grass
@@ -36,36 +36,36 @@ asm_ef82: ; ef82 (3:6f82)
 	set 6, [hl]
 	call GBPalWhiteOutWithDelay3
 	call ClearSprites
-	call Func_3dbe
+	call RestoreScreenTilesAndReloadTilePatterns
 	ld a, $90
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	call Delay3
 	call LoadGBPal
 	call LoadCurrentMapView
 	call SaveScreenTilesToBuffer2
 	call Delay3
 	xor a
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	ld hl, UsedCutText
 	call PrintText
 	call LoadScreenTilesFromBuffer2
 	ld hl, wd730
 	res 6, [hl]
 	ld a, $ff
-	ld [wcfcb], a
+	ld [wUpdateSpritesEnabled], a
 	call AnimateCutTree
 	ld de, CutTreeBlockSwaps ; $7100
 	call Func_f09f
-	call Func_eedc
+	call RedrawMapView
 	callba Func_79e96
 	ld a, $1
-	ld [wcfcb], a
+	ld [wUpdateSpritesEnabled], a
 	ld a, (SFX_02_56 - SFX_Headers_02) / 3
 	call PlaySound
 	ld a, $90
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	call UpdateSprites
-	jp Func_eedc
+	jp RedrawMapView
 
 UsedCutText: ; eff2 (3:6ff2)
 	TX_FAR _UsedCutText
@@ -87,17 +87,17 @@ AnimateCutTree: ; eff7 (3:6ff7)
 	ld hl, vChars1 + $7e0
 	ld bc, (BANK(Overworld_GFX) << 8) + $02
 	call CopyVideoData
-	jr asm_f055
+	jr WriteCutTreeBoulderDustAnimationOAMBlock
 .asm_f020
 	ld hl, vChars1 + $7c0
-	call LoadCutTreeOAM
+	call LoadCutTreeAnimationTilePattern
 	ld hl, vChars1 + $7d0
-	call LoadCutTreeOAM
+	call LoadCutTreeAnimationTilePattern
 	ld hl, vChars1 + $7e0
-	call LoadCutTreeOAM
+	call LoadCutTreeAnimationTilePattern
 	ld hl, vChars1 + $7f0
-	call LoadCutTreeOAM
-	call asm_f055
+	call LoadCutTreeAnimationTilePattern
+	call WriteCutTreeBoulderDustAnimationOAMBlock
 	ld hl, wOAMBuffer + $93
 	ld de, $4
 	ld a, $30
@@ -110,26 +110,27 @@ AnimateCutTree: ; eff7 (3:6ff7)
 	jr nz, .asm_f044
 	ret
 
-LoadCutTreeOAM: ; f04c (3:704c)
+LoadCutTreeAnimationTilePattern: ; f04c (3:704c)
 	ld de, AnimationTileset2 + $60 ; $474e ; tile depicting a leaf
 	ld bc, (BANK(AnimationTileset2) << 8) + $01
 	jp CopyVideoData
-asm_f055: ; f055 (3:7055)
-	call Func_f068
+
+WriteCutTreeBoulderDustAnimationOAMBlock: ; f055 (3:7055)
+	call GetCutTreeBoulderDustAnimationOffsets
 	ld a, $9
-	ld de, CutTreeOAM ; $7060
+	ld de, CutTreeBoulderDustAnimationTilesAndAttributes
 	jp WriteOAMBlock
 
-CutTreeOAM: ; f060 (3:7060)
+CutTreeBoulderDustAnimationTilesAndAttributes: ; f060 (3:7060)
 	db $FC,$10,$FD,$10
 	db $FE,$10,$FF,$10
 
-Func_f068: ; f068 (3:7068)
+GetCutTreeBoulderDustAnimationOffsets: ; f068 (3:7068)
 	ld hl, wSpriteStateData1 + 4
-	ld a, [hli]
+	ld a, [hli] ; player's sprite screen Y position
 	ld b, a
 	inc hl
-	ld a, [hli]
+	ld a, [hli] ; player's sprite screen X position
 	ld c, a ; bc holds ypos/xpos of player's sprite
 	inc hl
 	inc hl
@@ -139,9 +140,9 @@ Func_f068: ; f068 (3:7068)
 	ld d, $0 ; de holds direction (00: down, 02: up, 04: left, 06: right)
 	ld a, [wcd50]
 	and a
-	ld hl, CutTreeAnimationOffsets ; $708f
+	ld hl, CutTreeAnimationOffsets
 	jr z, .asm_f084
-	ld hl, CutTreeAnimationOffsets2 ; $7097
+	ld hl, BoulderDustAnimationOffsets
 .asm_f084
 	add hl, de
 	ld e, [hl]
@@ -162,8 +163,7 @@ CutTreeAnimationOffsets: ; f08f (3:708f)
 	db -8, 20 ; player is facing left
 	db 24, 20 ; player is facing right
 
-CutTreeAnimationOffsets2: ; f097 (3:7097)
-; Not sure if these ever get used. CutTreeAnimationOffsets only seems to be used.
+BoulderDustAnimationOffsets: ; f097 (3:7097)
 ; Each pair represents the x and y pixels offsets from the player of where the cut tree animation should be drawn
 ; These offsets represent 2 blocks away from the player
 	db  8,  52 ; player is facing down
@@ -178,7 +178,7 @@ Func_f09f: ; f09f (3:709f)
 	ld c, a
 	ld b, $0
 	ld d, $0
-	ld hl, wd35f
+	ld hl, wCurrentTileBlockMapViewPointer
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a

engine/overworld/cut2.asm

@@ -9,12 +9,12 @@ Func_79e96: ; 79e96 (1e:5e96)
 	ld a, $1
 	ld [wd08a], a
 	ld c, $2
-	call Func_79339
+	call AdjustOAMBlockXPos2
 	ld hl, wOAMBuffer + $99
 	ld a, $ff
 	ld [wd08a], a
 	ld c, $2
-	call Func_79339
+	call AdjustOAMBlockXPos2
 	ld a, [rOBP1] ; $ff49
 	xor $64
 	ld [rOBP1], a ; $ff49
@@ -37,7 +37,7 @@ Func_79e96: ; 79e96 (1e:5e96)
 	ld a, $2
 	ld [wd08a], a
 	ld c, $4
-	call Func_79352
+	call AdjustOAMBlockYPos2
 	pop bc
 	dec c
 	jr nz, .asm_79eca
@@ -49,22 +49,22 @@ Func_79eed: ; 79eed (1e:5eed)
 	ld a, $1
 	ld [wd08a], a
 	ld c, $1
-	call Func_79339
+	call AdjustOAMBlockXPos2
 	ld hl, wOAMBuffer + $95
 	ld a, $2
 	ld [wd08a], a
 	ld c, $1
-	call Func_79339
+	call AdjustOAMBlockXPos2
 	ld hl, wOAMBuffer + $99
 	ld a, $fe
 	ld [wd08a], a
 	ld c, $1
-	call Func_79339
+	call AdjustOAMBlockXPos2
 	ld hl, wOAMBuffer + $9d
 	ld a, $ff
 	ld [wd08a], a
 	ld c, $1
-	call Func_79339
+	call AdjustOAMBlockXPos2
 	ld a, [rOBP1] ; $ff49
 	xor $64
 	ld [rOBP1], a ; $ff49

engine/overworld/doors.asm

@@ -1,26 +1,27 @@
-HandleDoors: ; 1a609 (6:6609)
+; returns whether the player is standing on a door tile in carry
+IsPlayerStandingOnDoorTile: ; 1a609 (6:6609)
 	push de
 	ld hl, DoorTileIDPointers ; $662c
 	ld a, [W_CURMAPTILESET] ; W_CURMAPTILESET
 	ld de, $3
 	call IsInArray
 	pop de
-	jr nc, .asm_1a62a
+	jr nc, .notStandingOnDoor
 	inc hl
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
-	aCoord 8, 9
+	aCoord 8, 9 ; a = lower left background tile under player's sprite
 	ld b, a
-.asm_1a621
+.loop
 	ld a, [hli]
 	and a
-	jr z, .asm_1a62a
+	jr z, .notStandingOnDoor
 	cp b
-	jr nz, .asm_1a621
+	jr nz, .loop
 	scf
 	ret
-.asm_1a62a
+.notStandingOnDoor
 	and a
 	ret
 

engine/overworld/elevator.asm

@@ -38,10 +38,10 @@ ShakeElevator: ; 7bf15 (1e:7f15)
 	cp $b9
 	jr z, .asm_7bf57
 	call UpdateSprites
-	jp Func_2307
+	jp PlayDefaultMusic
 
 Func_7bf64: ; 7bf64 (1e:7f64)
-	ld hl, wd527
+	ld hl, wMapViewVRAMPointer + 1
 	ld a, [hld]
 	push af
 	ld a, [hl]

engine/overworld/emotion_bubbles.asm

@@ -11,10 +11,10 @@ EmotionBubble: ; 17c47 (5:7c47)
 	ld hl, vChars1 + $780
 	ld bc, (BANK(EmotionBubblesPointerTable) << 8) + $04
 	call CopyVideoData
-	ld a, [wcfcb]
+	ld a, [wUpdateSpritesEnabled]
 	push af
 	ld a, $ff
-	ld [wcfcb], a
+	ld [wUpdateSpritesEnabled], a
 	ld a, [wd736]
 	bit 6, a
 	ld hl, wOAMBuffer + $8f
@@ -51,7 +51,7 @@ EmotionBubble: ; 17c47 (5:7c47)
 	ld c, $3c
 	call DelayFrames
 	pop af
-	ld [wcfcb], a
+	ld [wUpdateSpritesEnabled], a
 	call DelayFrame
 	jp UpdateSprites
 

engine/overworld/healing_machine.asm

@@ -3,7 +3,7 @@ AnimateHealingMachine: ; 70433 (1c:4433)
 	ld hl, vChars0 + $7c0
 	ld bc, (BANK(PokeCenterFlashingMonitorAndHealBall) << 8) + $03
 	call CopyVideoData
-	ld hl, wcfcb
+	ld hl, wUpdateSpritesEnabled
 	ld a, [hl]
 	push af
 	ld [hl], $ff

engine/overworld/hidden_items.asm

@@ -12,7 +12,7 @@ HiddenItems: ; 76688 (1d:6688)
 	ret nz
 	call EnableAutoTextBoxDrawing
 	ld a, $1
-	ld [wcc3c], a
+	ld [wDoNotWaitForButtonPressAfterDisplayingText], a
 	ld a, [wWhichTrade] ; item ID
 	ld [wd11e], a
 	call GetItemName
@@ -42,7 +42,7 @@ FoundHiddenItemText: ; 7675b (1d:675b)
 .BagFull
 	call WaitForTextScrollButtonPress ; wait for button press
 	xor a
-	ld [wcc3c], a
+	ld [wDoNotWaitForButtonPressAfterDisplayingText], a
 	ld hl, HiddenItemBagFullText
 	call PrintText
 	jp TextScriptEnd

engine/overworld/hidden_objects.asm

@@ -1,20 +1,21 @@
 Func_46981: ; 46981 (11:6981)
 	xor a
-	ld [wd71e], a
+	ld [wWhichDungeonWarp], a
 	ld a, [wd72d]
 	bit 4, a
 	ret nz
 	call ArePlayerCoordsInArray
 	ret nc
-	ld a, [wWhichTrade] ; wWhichTrade
-	ld [wd71e], a
+	ld a, [wWhichTrade]
+	ld [wWhichDungeonWarp], a
 	ld hl, wd72d
 	set 4, [hl]
 	ld hl, wd732
 	set 4, [hl]
 	ret
 
-Func_469a0: ; 469a0 (11:69a0)
+; if a hidden object was found, stores $00 in [$ffee], else stores $ff
+CheckForHiddenObject: ; 469a0 (11:69a0)
 	ld hl, $ffeb
 	xor a
 	ld [hli], a
@@ -22,107 +23,110 @@ Func_469a0: ; 469a0 (11:69a0)
 	ld [hli], a
 	ld [hl], a
 	ld de, $0
-	ld hl, HiddenObjectMaps ; $6a40
-.asm_469ae
+	ld hl, HiddenObjectMaps
+.hiddenMapLoop
 	ld a, [hli]
 	ld b, a
 	cp $ff
-	jr z, .asm_469fc
-	ld a, [W_CURMAP] ; W_CURMAP
+	jr z, .noMatch
+	ld a, [W_CURMAP]
 	cp b
-	jr z, .asm_469be
+	jr z, .foundMatchingMap
 	inc de
 	inc de
-	jr .asm_469ae
-.asm_469be
-	ld hl, HiddenObjectPointers ; $6a96
+	jr .hiddenMapLoop
+.foundMatchingMap
+	ld hl, HiddenObjectPointers
 	add hl, de
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
 	push hl
-	ld hl, wWhichTrade ; wWhichTrade
+	ld hl, wHiddenObjectFunctionArgument
 	xor a
 	ld [hli], a
 	ld [hli], a
 	ld [hl], a
 	pop hl
-.asm_469ce
+.hiddenObjectLoop
 	ld a, [hli]
 	cp $ff
-	jr z, .asm_469fc
-	ld [wTrainerScreenY], a
+	jr z, .noMatch
+	ld [wHiddenObjectY], a
 	ld b, a
 	ld a, [hli]
-	ld [wTrainerScreenX], a
+	ld [wHiddenObjectX], a
 	ld c, a
-	call Func_46a01
+	call CheckIfCoordsInFrontOfPlayerMatch
 	ld a, [$ffea]
 	and a
-	jr z, .asm_469f0
+	jr z, .foundMatchingObject
 	inc hl
 	inc hl
 	inc hl
 	inc hl
 	push hl
-	ld hl, wTrainerFacingDirection
+	ld hl, wHiddenObjectIndex
 	inc [hl]
 	pop hl
-	jr .asm_469ce
-.asm_469f0
+	jr .hiddenObjectLoop
+.foundMatchingObject
 	ld a, [hli]
-	ld [wWhichTrade], a ; wWhichTrade
+	ld [wHiddenObjectFunctionArgument], a
 	ld a, [hli]
-	ld [wTrainerEngageDistance], a
+	ld [wHiddenObjectFunctionRomBank], a
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
 	ret
-.asm_469fc
+.noMatch
 	ld a, $ff
 	ld [$ffee], a
 	ret
 
-Func_46a01: ; 46a01 (11:6a01)
-	ld a, [wSpriteStateData1 + 9]
-	cp $4
-	jr z, .asm_46a16
-	cp $8
-	jr z, .asm_46a25
-	cp $c
-	jr z, .asm_46a2b
-	ld a, [W_YCOORD] ; wd361
+; checks if the coordinates in front of the player's sprite match Y in b and X in c
+; [$ffea] = $00 if they match, $ff if they don't match
+CheckIfCoordsInFrontOfPlayerMatch: ; 46a01 (11:6a01)
+	ld a, [wSpriteStateData1 + 9] ; player's sprite facing direction
+	cp SPRITE_FACING_UP
+	jr z, .facingUp
+	cp SPRITE_FACING_LEFT
+	jr z, .facingLeft
+	cp SPRITE_FACING_RIGHT
+	jr z, .facingRight
+; facing down
+	ld a, [W_YCOORD]
 	inc a
-	jr .asm_46a1a
-.asm_46a16
-	ld a, [W_YCOORD] ; wd361
+	jr .upDownCommon
+.facingUp
+	ld a, [W_YCOORD]
 	dec a
-.asm_46a1a
+.upDownCommon
 	cp b
-	jr nz, .asm_46a3b
-	ld a, [W_XCOORD] ; wd362
+	jr nz, .didNotMatch
+	ld a, [W_XCOORD]
 	cp c
-	jr nz, .asm_46a3b
-	jr .asm_46a38
-.asm_46a25
-	ld a, [W_XCOORD] ; wd362
+	jr nz, .didNotMatch
+	jr .matched
+.facingLeft
+	ld a, [W_XCOORD]
 	dec a
-	jr .asm_46a2f
-.asm_46a2b
-	ld a, [W_XCOORD] ; wd362
+	jr .leftRightCommon
+.facingRight
+	ld a, [W_XCOORD]
 	inc a
-.asm_46a2f
+.leftRightCommon
 	cp c
-	jr nz, .asm_46a3b
-	ld a, [W_YCOORD] ; wd361
+	jr nz, .didNotMatch
+	ld a, [W_YCOORD]
 	cp b
-	jr nz, .asm_46a3b
-.asm_46a38
+	jr nz, .didNotMatch
+.matched
 	xor a
-	jr .asm_46a3d
-.asm_46a3b
+	jr .done
+.didNotMatch
 	ld a, $ff
-.asm_46a3d
+.done
 	ld [$ffea], a
 	ret
 

engine/overworld/item.asm

@@ -34,7 +34,7 @@ PickupItem:
 	ld [wcc4d], a
 	predef HideObject
 	ld a, 1
-	ld [wcc3c], a
+	ld [wDoNotWaitForButtonPressAfterDisplayingText], a
 	ld hl, FoundItemText
 	jr .print
 

engine/overworld/ledges.asm

@@ -1,54 +1,54 @@
 HandleLedges: ; 1a672 (6:6672)
 	ld a, [wd736]
-	bit 6, a
+	bit 6, a ; already jumping down ledge
 	ret nz
 	ld a, [W_CURMAPTILESET] ; W_CURMAPTILESET
 	and a ; OVERWORLD
 	ret nz
-	predef Func_c586
+	predef GetTileAndCoordsInFrontOfPlayer
 	ld a, [wSpriteStateData1 + 9]
 	ld b, a
 	aCoord 8, 9
 	ld c, a
-	ld a, [wcfc6]
+	ld a, [wTileInFrontOfPlayer]
 	ld d, a
-	ld hl, LedgeTiles ; $66cf
-.asm_1a691
+	ld hl, LedgeTiles
+.loop
 	ld a, [hli]
 	cp $ff
 	ret z
 	cp b
-	jr nz, .asm_1a6a4
+	jr nz, .nextLedgeTile1
 	ld a, [hli]
 	cp c
-	jr nz, .asm_1a6a5
+	jr nz, .nextLedgeTile2
 	ld a, [hli]
 	cp d
-	jr nz, .asm_1a6a6
+	jr nz, .nextLedgeTile3
 	ld a, [hl]
 	ld e, a
-	jr .asm_1a6a9
-.asm_1a6a4
+	jr .foundMatch
+.nextLedgeTile1
 	inc hl
-.asm_1a6a5
+.nextLedgeTile2
 	inc hl
-.asm_1a6a6
+.nextLedgeTile3
 	inc hl
-	jr .asm_1a691
-.asm_1a6a9
+	jr .loop
+.foundMatch
 	ld a, [hJoyHeld]
 	and e
 	ret z
 	ld a, $ff
 	ld [wJoyIgnore], a
 	ld hl, wd736
-	set 6, [hl]
-	call Func_3486
+	set 6, [hl] ; jumping down ledge
+	call StartSimulatingJoypadStates
 	ld a, e
-	ld [wccd3], a
-	ld [wccd4], a
+	ld [wSimulatedJoypadStatesEnd], a
+	ld [wSimulatedJoypadStatesEnd + 1], a
 	ld a, $2
-	ld [wcd38], a
+	ld [wSimulatedJoypadStatesIndex], a
 	call LoadHoppingShadowOAM
 	ld a, (SFX_02_4e - SFX_Headers_02) / 3
 	call PlaySound
@@ -56,24 +56,24 @@ HandleLedges: ; 1a672 (6:6672)
 
 	; (player direction) (tile player standing on) (ledge tile) (input required)
 LedgeTiles: ; 1a6cf (6:66cf)
-	db $00,$2C,$37,$80
-	db $00,$39,$36,$80
-	db $00,$39,$37,$80
-	db $08,$2C,$27,$20
-	db $08,$39,$27,$20
-	db $0C,$2C,$0D,$10
-	db $0C,$2C,$1D,$10
-	db $0C,$39,$0D,$10
+	db SPRITE_FACING_DOWN, $2C,$37,D_DOWN
+	db SPRITE_FACING_DOWN, $39,$36,D_DOWN
+	db SPRITE_FACING_DOWN, $39,$37,D_DOWN
+	db SPRITE_FACING_LEFT, $2C,$27,D_LEFT
+	db SPRITE_FACING_LEFT, $39,$27,D_LEFT
+	db SPRITE_FACING_RIGHT,$2C,$0D,D_RIGHT
+	db SPRITE_FACING_RIGHT,$2C,$1D,D_RIGHT
+	db SPRITE_FACING_RIGHT,$39,$0D,D_RIGHT
 	db $FF
 
 LoadHoppingShadowOAM: ; 1a6f0 (6:66f0)
 	ld hl, vChars1 + $7f0
-	ld de, LedgeHoppingShadow ; $6708
+	ld de, LedgeHoppingShadow
 	ld bc, (BANK(LedgeHoppingShadow) << 8) + $01
 	call CopyVideoDataDouble
 	ld a, $9
 	ld bc, $5448 ; b, c = y, x coordinates of shadow
-	ld de, LedgeHoppingShadowOAM ; $6710
+	ld de, LedgeHoppingShadowOAM
 	call WriteOAMBlock
 	ret
 

engine/overworld/movement.asm

@@ -1,23 +1,26 @@
 UpdatePlayerSprite: ; 4e31 (1:4e31)
 	ld a, [wSpriteStateData2]
 	and a
-	jr z, .asm_4e41
+	jr z, .checkIfTextBoxInFrontOfSprite
 	cp $ff
-	jr z, .asm_4e4a
+	jr z, .disableSprite
 	dec a
 	ld [wSpriteStateData2], a
-	jr .asm_4e4a
-.asm_4e41
+	jr .disableSprite
+; check if a text box is in front of the sprite by checking if the lower left
+; background tile the sprite is standing on is greater than $5F, which is
+; the maximum number for map tiles
+.checkIfTextBoxInFrontOfSprite
 	aCoord 8, 9
 	ld [$ff93], a
 	cp $60
-	jr c, .asm_4e50
-.asm_4e4a
+	jr c, .lowerLeftTileIsMapTile
+.disableSprite
 	ld a, $ff
 	ld [wSpriteStateData1 + 2], a
 	ret
-.asm_4e50
-	call Func_4c70
+.lowerLeftTileIsMapTile
+	call DetectCollisionBetweenSprites
 	ld h, $c1
 	ld a, [wWalkCounter] ; wcfc5
 	and a
@@ -165,8 +168,8 @@ Func_4ed1: ; 4ed1 (1:4ed1)
 	ld hl, wd730
 	res 0, [hl]
 	xor a
-	ld [wcd38], a
-	ld [wcd3a], a
+	ld [wSimulatedJoypadStatesIndex], a
+	ld [wWastedByteCD3A], a
 	ret
 .asm_4f4b
 	cp $fe
@@ -490,6 +493,8 @@ CheckSpriteAvailability: ; 50dc (1:50dc)
 	cp b
 	jr c, .spriteInvisible  ; right of screen region
 .skipXVisibilityTest
+; make the sprite invisible if a text box is in front of it
+; $5F is the maximum number for map tiles
 	call getTileSpriteStandsOn
 	ld d, $60
 	ld a, [hli]
@@ -604,16 +609,16 @@ CanWalkOntoTile: ; 516e (1:516e)
 	jr nc, .impassable ; don't walk off screen
 	push de
 	push bc
-	call Func_4c70
+	call DetectCollisionBetweenSprites
 	pop bc
 	pop de
 	ld h, $c1
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $c
 	ld l, a
-	ld a, [hl]         ; c1xc (forbidden directions flags(?))
+	ld a, [hl]         ; c1xc (directions in which sprite collision would occur)
 	and b              ; check against chosen direction (1,2,4 or 8)
-	jr nz, .impassable ; direction forbidden, don't go there
+	jr nz, .impassable ; collision between sprites, don't go there
 	ld h, $c2
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $2
@@ -716,8 +721,8 @@ Func_5236: ; 5236 (1:5236)
 	bit 7, [hl]
 	set 7, [hl]
 	jp z, Func_52a6
-	ld hl, wcc97
-	ld a, [wcd37]
+	ld hl, wNPCMovementDirections2
+	ld a, [wNPCMovementDirections2Index]
 	add l
 	ld l, a
 	jr nc, .asm_5251
@@ -770,13 +775,13 @@ Func_5236: ; 5236 (1:5236)
 	ret nz
 	ld a, $8
 	ld [wcf18], a
-	ld hl, wcd37
+	ld hl, wNPCMovementDirections2Index
 	inc [hl]
 	ret
 
 Func_52a6: ; 52a6 (1:52a6)
 	xor a
-	ld [wcd37], a
+	ld [wNPCMovementDirections2Index], a
 	ld a, $8
 	ld [wcf18], a
 	jp Func_52c3

engine/overworld/npc_movement.asm

@@ -1,25 +1,25 @@
-Func_1a3e0: ; 1a3e0 (6:63e0)
+PlayerStepOutFromDoor: ; 1a3e0 (6:63e0)
 	ld hl, wd730
 	res 1, [hl]
-	call HandleDoors
-	jr nc, .asm_1a406
+	call IsPlayerStandingOnDoorTile
+	jr nc, .notStandingOnDoor
 	ld a, $fc
 	ld [wJoyIgnore], a
 	ld hl, wd736
 	set 1, [hl]
 	ld a, $1
-	ld [wcd38], a
-	ld a, $80
-	ld [wccd3], a
+	ld [wSimulatedJoypadStatesIndex], a
+	ld a, D_DOWN
+	ld [wSimulatedJoypadStatesEnd], a
 	xor a
 	ld [wSpriteStateData1 + 2], a
-	call Func_3486
+	call StartSimulatingJoypadStates
 	ret
-.asm_1a406
+.notStandingOnDoor
 	xor a
-	ld [wcd3a], a
-	ld [wcd38], a
-	ld [wccd3], a
+	ld [wWastedByteCD3A], a
+	ld [wSimulatedJoypadStatesIndex], a
+	ld [wSimulatedJoypadStatesEnd], a
 	ld hl, wd736
 	res 0, [hl]
 	res 1, [hl]
@@ -27,7 +27,7 @@ Func_1a3e0: ; 1a3e0 (6:63e0)
 	res 7, [hl]
 	ret
 
-Func_1a41d: ; 1a41d (6:641d)
+_EndNPCMovementScript: ; 1a41d (6:641d)
 	ld hl, wd730
 	res 7, [hl]
 	ld hl, wd72e
@@ -36,15 +36,15 @@ Func_1a41d: ; 1a41d (6:641d)
 	res 0, [hl]
 	res 1, [hl]
 	xor a
-	ld [wcf17], a
-	ld [wcc57], a
-	ld [wcf10], a
-	ld [wcd3a], a
-	ld [wcd38], a
-	ld [wccd3], a
+	ld [wNPCMovementScriptSpriteOffset], a
+	ld [wNPCMovementScriptPointerTableNum], a
+	ld [wNPCMovementScriptFunctionNum], a
+	ld [wWastedByteCD3A], a
+	ld [wSimulatedJoypadStatesIndex], a
+	ld [wSimulatedJoypadStatesEnd], a
 	ret
 
-PointerTable_1a442: ; 1a442 (6:6442)
+ProfOakMovementScriptPointerTable: ; 1a442 (6:6442)
 	dw Func_1a44c
 	dw Func_1a485
 	dw Func_1a4a1
@@ -58,20 +58,20 @@ Func_1a44c: ; 1a44c (6:644c)
 	jr z, .asm_1a475
 	ld b, $0
 	ld c, a
-	ld hl, wcc97
+	ld hl, wNPCMovementDirections2
 	ld a, $80
 	call FillMemory
 	ld [hl], $ff
-	ld a, [wcf13]
+	ld a, [wSpriteIndex]
 	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
-	ld de, wcc97
+	ld de, wNPCMovementDirections2
 	call MoveSprite
 	ld a, $1
-	ld [wcf10], a
+	ld [wNPCMovementScriptFunctionNum], a
 	jr .asm_1a47a
 .asm_1a475
 	ld a, $3
-	ld [wcf10], a
+	ld [wNPCMovementScriptFunctionNum], a
 .asm_1a47a
 	ld hl, W_FLAGS_D733
 	set 1, [hl]
@@ -84,44 +84,44 @@ Func_1a485: ; 1a485 (6:6485)
 	bit 0, a
 	ret nz
 	ld a, [wcca1]
-	ld [wcd38], a
+	ld [wSimulatedJoypadStatesIndex], a
 	ld [$ff95], a
-	predef Func_f9a0
-	call Func_3486
+	predef ConvertNPCMovementDirectionsToJoypadMasks
+	call StartSimulatingJoypadStates
 	ld a, $2
-	ld [wcf10], a
+	ld [wNPCMovementScriptFunctionNum], a
 	ret
 
 Func_1a4a1: ; 1a4a1 (6:64a1)
-	ld a, [wcd38]
+	ld a, [wSimulatedJoypadStatesIndex]
 	and a
 	ret nz
 
 Func_1a4a6: ; 1a4a6 (6:64a6)
 	xor a
-	ld [wcd3b], a
-	ld a, [wcf13]
+	ld [wOverrideSimulatedJoypadStatesMask], a
+	ld a, [wSpriteIndex]
 	swap a
-	ld [wcf17], a
+	ld [wNPCMovementScriptSpriteOffset], a
 	xor a
 	ld [wSpriteStateData2 + $06], a
-	ld hl, wccd3
-	ld de, RLEList_1a4e9
+	ld hl, wSimulatedJoypadStatesEnd
+	ld de, RLEList_PlayerWalkToLab
 	call DecodeRLEList
 	dec a
-	ld [wcd38], a
-	ld hl, wcc97
-	ld de, RLEList_1a4dc
+	ld [wSimulatedJoypadStatesIndex], a
+	ld hl, wNPCMovementDirections2
+	ld de, RLEList_ProfOakWalkToLab
 	call DecodeRLEList
 	ld hl, wd72e
 	res 7, [hl]
 	ld hl, wd730
 	set 7, [hl]
 	ld a, $4
-	ld [wcf10], a
+	ld [wNPCMovementScriptFunctionNum], a
 	ret
 
-RLEList_1a4dc: ; 1a4dc (6:64dc)
+RLEList_ProfOakWalkToLab: ; 1a4dc (6:64dc)
 	db $00, $05
 	db $80, $01
 	db $00, $05
@@ -130,16 +130,16 @@ RLEList_1a4dc: ; 1a4dc (6:64dc)
 	db $E0, $01
 	db $FF
 
-RLEList_1a4e9: ; 1a4e9 (6:64e9)
-	db $40, $02
-	db $10, $03
-	db $80, $05
-	db $20, $01
-	db $80, $06
+RLEList_PlayerWalkToLab: ; 1a4e9 (6:64e9)
+	db D_UP, $02
+	db D_RIGHT, $03
+	db D_DOWN, $05
+	db D_LEFT, $01
+	db D_DOWN, $06
 	db $FF
 
 Func_1a4f4: ; 1a4f4 (6:64f4)
-	ld a, [wcd38]
+	ld a, [wSimulatedJoypadStatesIndex]
 	and a
 	ret nz
 	ld a, $0
@@ -149,11 +149,11 @@ Func_1a4f4: ; 1a4f4 (6:64f4)
 	res 7, [hl]
 	ld hl, wd72e
 	res 7, [hl]
-	jp Func_314e
+	jp EndNPCMovementScript
 
-PointerTable_1a510: ; 1a510 (6:6510)
+PewterMuseumGuyMovementScriptPointerTable: ; 1a510 (6:6510)
 	dw Func_1a514
-	dw Func_1a56b
+	dw PewterMovementScriptDone
 
 Func_1a514: ; 1a514 (6:6514)
 	ld a, BANK(Music_MuseumGuy)
@@ -162,32 +162,32 @@ Func_1a514: ; 1a514 (6:6514)
 	ld a, MUSIC_MUSEUM_GUY
 	ld [wc0ee], a
 	call PlaySound
-	ld a, [wcf13]
+	ld a, [wSpriteIndex]
 	swap a
-	ld [wcf17], a
-	call Func_3486
-	ld hl, wccd3
+	ld [wNPCMovementScriptSpriteOffset], a
+	call StartSimulatingJoypadStates
+	ld hl, wSimulatedJoypadStatesEnd
 	ld de, RLEList_PewterMuseumPlayer
 	call DecodeRLEList
 	dec a
-	ld [wcd38], a
+	ld [wSimulatedJoypadStatesIndex], a
 	xor a
 	ld [wd12f], a
 	predef PewterGuys
-	ld hl, wcc97
+	ld hl, wNPCMovementDirections2
 	ld de, RLEList_PewterMuseumGuy
 	call DecodeRLEList
 	ld hl, wd72e
 	res 7, [hl]
 	ld a, $1
-	ld [wcf10], a
+	ld [wNPCMovementScriptFunctionNum], a
 	ret
 
 RLEList_PewterMuseumPlayer: ; 1a559 (6:6559)
-	db $00, $01
-	db $40, $03
-	db $20, $0D
-	db $40, $06
+	db 0, $01
+	db D_UP, $03
+	db D_LEFT, $0D
+	db D_UP, $06
 	db $FF
 
 RLEList_PewterMuseumGuy: ; 1a562 (6:6562)
@@ -197,19 +197,19 @@ RLEList_PewterMuseumGuy: ; 1a562 (6:6562)
 	db $80, $01
 	db $FF
 
-Func_1a56b: ; 1a56b (6:656b)
-	ld a, [wcd38]
+PewterMovementScriptDone: ; 1a56b (6:656b)
+	ld a, [wSimulatedJoypadStatesIndex]
 	and a
 	ret nz
 	ld hl, wd730
 	res 7, [hl]
 	ld hl, wd72e
 	res 7, [hl]
-	jp Func_314e
+	jp EndNPCMovementScript
 
-PointerTable_1a57d: ; 1a57d (6:657d)
+PewterGymGuyMovementScriptPointerTable: ; 1a57d (6:657d)
 	dw Func_1a581
-	dw Func_1a56b
+	dw PewterMovementScriptDone
 
 Func_1a581: ; 1a581 (6:6581)
 	ld a, BANK(Music_MuseumGuy)
@@ -218,20 +218,20 @@ Func_1a581: ; 1a581 (6:6581)
 	ld a, MUSIC_MUSEUM_GUY
 	ld [wc0ee], a
 	call PlaySound
-	ld a, [wcf13]
+	ld a, [wSpriteIndex]
 	swap a
-	ld [wcf17], a
+	ld [wNPCMovementScriptSpriteOffset], a
 	xor a
 	ld [wSpriteStateData2 + $06], a
-	ld hl, wccd3
+	ld hl, wSimulatedJoypadStatesEnd
 	ld de, RLEList_PewterGymPlayer
 	call DecodeRLEList
 	dec a
-	ld [wcd38], a
+	ld [wSimulatedJoypadStatesIndex], a
 	ld a, $1
 	ld [wd12f], a
 	predef PewterGuys
-	ld hl, wcc97
+	ld hl, wNPCMovementDirections2
 	ld de, RLEList_PewterGymGuy
 	call DecodeRLEList
 	ld hl, wd72e
@@ -239,16 +239,16 @@ Func_1a581: ; 1a581 (6:6581)
 	ld hl, wd730
 	set 7, [hl]
 	ld a, $1
-	ld [wcf10], a
+	ld [wNPCMovementScriptFunctionNum], a
 	ret
 
 RLEList_PewterGymPlayer: ; 1a5cd (6:65cd)
-	db $00, $01
-	db $10, $02
-	db $80, $05
-	db $20, $0B
-	db $40, $05
-	db $20, $0F
+	db 0, $01
+	db D_RIGHT, $02
+	db D_DOWN, $05
+	db D_LEFT, $0B
+	db D_UP, $05
+	db D_LEFT, $0F
 	db $FF
 
 RLEList_PewterGymGuy: ; 1a5da (6:65da)
@@ -260,12 +260,11 @@ RLEList_PewterGymGuy: ; 1a5da (6:65da)
 	db $C0, $03
 	db $FF
 
-; XXX why would this function want to return on POKEMONTOWER_7?
-Func_1a5e7: ; 1a5e7 (6:65e7)
-	ld a, [W_CURMAP] ; W_CURMAP
+FreezeEnemyTrainerSprite: ; 1a5e7 (6:65e7)
+	ld a, [W_CURMAP]
 	cp POKEMONTOWER_7
-	ret z
-	ld hl, RivalIDs ; $6605
+	ret z ; the Rockets on Pokemon Tower 7F leave after battling, so don't freeze them
+	ld hl, RivalIDs
 	ld a, [wEngagedTrainerClass]
 	ld b, a
 .loop
@@ -273,11 +272,11 @@ Func_1a5e7: ; 1a5e7 (6:65e7)
 	cp $ff
 	jr z, .notRival
 	cp b
-	ret z
+	ret z ; the rival leaves after battling, so don't freeze him
 	jr .loop
 .notRival
-	ld a, [wcf13]
-	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
+	ld a, [wSpriteIndex]
+	ld [H_SPRITEINDEX], a
 	jp SetSpriteMovementBytesToFF
 
 RivalIDs: ; 1a605 (6:6605)

engine/overworld/oam.asm

@@ -2,13 +2,13 @@ PrepareOAMData:
 ; Determine OAM data for currently visible
 ; sprites and write it to wOAMBuffer.
 
-	ld a, [wcfcb]
+	ld a, [wUpdateSpritesEnabled]
 	dec a
 	jr z, .asm_4b1e
 
 	cp 0 - 1
 	ret nz
-	ld [wcfcb], a
+	ld [wUpdateSpritesEnabled], a
 	jp HideSprites
 
 .asm_4b1e

engine/overworld/pewter_guys.asm

@@ -1,8 +1,8 @@
 PewterGuys: ; 37ca1 (d:7ca1)
-	ld hl, wccd3
-	ld a, [wcd38]
-	dec a
-	ld [wcd38], a
+	ld hl, wSimulatedJoypadStatesEnd
+	ld a, [wSimulatedJoypadStatesIndex]
+	dec a ; this decrement causes it to overwrite the last byte before $FF in the list
+	ld [wSimulatedJoypadStatesIndex], a
 	ld d, 0
 	ld e, a
 	add hl, de
@@ -37,9 +37,9 @@ PewterGuys: ; 37ca1 (d:7ca1)
 	ret z
 	ld [de], a
 	inc de
-	ld a, [wcd38]
+	ld a, [wSimulatedJoypadStatesIndex]
 	inc a
-	ld [wcd38], a
+	ld [wSimulatedJoypadStatesIndex], a
 	jr .asm_37cd2
 .asm_37ce1
 	inc hl

engine/overworld/player_animations.asm

@@ -1,66 +1,67 @@
-Func_70510: ; 70510 (1c:4510)
-	call Func_706ef
+EnterMapAnim: ; 70510 (1c:4510)
+	call InitFacingDirectionBuffer
 	ld a, $ec
-	ld [wSpriteStateData1 + 4], a
+	ld [wSpriteStateData1 + 4], a ; player's sprite Y screen position
 	call Delay3
 	push hl
-	call GBFadeIn2
+	call GBFadeInFromWhite
 	ld hl, W_FLAGS_D733
-	bit 7, [hl]
+	bit 7, [hl] ; used fly out of battle?
 	res 7, [hl]
-	jr nz, .asm_70568
+	jr nz, .flyAnimation
 	ld a, (SFX_02_4c - SFX_Headers_02) / 3
 	call PlaySound
 	ld hl, wd732
-	bit 4, [hl]
+	bit 4, [hl] ; used dungeon warp?
 	res 4, [hl]
 	pop hl
-	jr nz, .asm_7055e
-	call Func_705aa
+	jr nz, .dungeonWarpAnimation
+	call PlayerSpinWhileMovingDown
 	ld a, (SFX_02_4f - SFX_Headers_02) / 3
 	call PlaySound
-	call Func_70787
+	call IsPlayerStandingOnWarpPadOrHole
 	ld a, b
 	and a
-	jr nz, .asm_7055b
-	ld hl, wWhichTrade ; wWhichTrade
+	jr nz, .done
+; if the player is not standing on a warp pad or hole
+	ld hl, wPlayerSpinInPlaceAnimFrameDelay
 	xor a
-	ld [hli], a
+	ld [hli], a ; wPlayerSpinInPlaceAnimFrameDelay
 	inc a
-	ld [hli], a
+	ld [hli], a ; wPlayerSpinInPlaceAnimFrameDelayDelta
 	ld a, $8
-	ld [hli], a
-	ld [hl], $ff
+	ld [hli], a ; wPlayerSpinInPlaceAnimFrameDelayEndValue
+	ld [hl], $ff ; wPlayerSpinInPlaceAnimSoundID
 	ld hl, wcd48
-	call Func_70730
-.asm_70558
-	call Func_2307
-.asm_7055b
-	jp Func_70772
-.asm_7055e
-	ld c, $32
+	call PlayerSpinInPlace
+.restoreDefaultMusic
+	call PlayDefaultMusic
+.done
+	jp RestoreFacingDirectionAndYScreenPos
+.dungeonWarpAnimation
+	ld c, 50
 	call DelayFrames
-	call Func_705aa
-	jr .asm_7055b
-.asm_70568
+	call PlayerSpinWhileMovingDown
+	jr .done
+.flyAnimation
 	pop hl
-	ld de, BirdSprite ; $4d80
+	ld de, BirdSprite
 	ld hl, vNPCSprites
 	ld bc, (BANK(BirdSprite) << 8) + $0c
 	call CopyVideoData
-	call Func_706d7
+	call LoadBirdSpriteGraphics
 	ld a, (SFX_02_50 - SFX_Headers_02) / 3
 	call PlaySound
-	ld hl, wWhichTrade ; wWhichTrade
-	xor a
-	ld [hli], a
-	ld a, $c
-	ld [hli], a
-	ld [hl], $8
+	ld hl, wFlyAnimUsingCoordList
+	xor a ; is using coord list
+	ld [hli], a ; wFlyAnimUsingCoordList
+	ld a, 12
+	ld [hli], a ; wFlyAnimCounter
+	ld [hl], $8 ; wFlyAnimBirdSpriteImageIndex (facing right)
 	ld de, FlyAnimationEnterScreenCoords ; $4592
-	call Func_706ae
+	call DoFlyAnimation
 	call LoadPlayerSpriteGraphics
-	jr .asm_70558
+	jr .restoreDefaultMusic
 
 FlyAnimationEnterScreenCoords: ; 70592 (1c:4592)
 ; y, x pairs
@@ -79,90 +80,92 @@ FlyAnimationEnterScreenCoords: ; 70592 (1c:4592)
 	db $3C, $48
 	db $3C, $40
 
-Func_705aa: ; 705aa (1c:45aa)
-	ld hl, wWhichTrade ; wWhichTrade
+PlayerSpinWhileMovingDown: ; 705aa (1c:45aa)
+	ld hl, wPlayerSpinWhileMovingUpOrDownAnimDeltaY
 	ld a, $10
-	ld [hli], a
+	ld [hli], a ; wPlayerSpinWhileMovingUpOrDownAnimDeltaY
 	ld a, $3c
-	ld [hli], a
-	call Func_7077f
-	ld [hl], a
-	jp Func_70755
+	ld [hli], a ; wPlayerSpinWhileMovingUpOrDownAnimMaxY
+	call GetPlayerTeleportAnimFrameDelay
+	ld [hl], a ; wPlayerSpinWhileMovingUpOrDownAnimFrameDelay
+	jp PlayerSpinWhileMovingUpOrDown
 
 _LeaveMapAnim: ; 705ba (1c:45ba)
-	call Func_706ef
-	call Func_70787
+	call InitFacingDirectionBuffer
+	call IsPlayerStandingOnWarpPadOrHole
 	ld a, b
 	and a
-	jr z, .asm_705ef
+	jr z, .playerNotStandingOnWarpPadOrHole
 	dec a
-	jp nz, Func_7067d
-.asm_705c8
+	jp nz, LeaveMapThroughHoleAnim
+.spinWhileMovingUp
 	ld a, (SFX_02_4b - SFX_Headers_02) / 3
 	call PlaySound
-	ld hl, wWhichTrade ; wWhichTrade
-	ld a, $f0
-	ld [hli], a
+	ld hl, wPlayerSpinWhileMovingUpOrDownAnimDeltaY
+	ld a, -$10
+	ld [hli], a ; wPlayerSpinWhileMovingUpOrDownAnimDeltaY
 	ld a, $ec
-	ld [hli], a
-	call Func_7077f
-	ld [hl], a
-	call Func_70755
-	call Func_70787
+	ld [hli], a ; wPlayerSpinWhileMovingUpOrDownAnimMaxY
+	call GetPlayerTeleportAnimFrameDelay
+	ld [hl], a ; wPlayerSpinWhileMovingUpOrDownAnimFrameDelay
+	call PlayerSpinWhileMovingUpOrDown
+	call IsPlayerStandingOnWarpPadOrHole
 	ld a, b
 	dec a
-	jr z, .asm_705e9
-	ld c, $a
+	jr z, .playerStandingOnWarpPad
+; if not standing on a warp pad, there is an extra delay
+	ld c, 10
 	call DelayFrames
-.asm_705e9
-	call GBFadeOut2
-	jp Func_70772
-.asm_705ef
+.playerStandingOnWarpPad
+	call GBFadeOutToWhite
+	jp RestoreFacingDirectionAndYScreenPos
+.playerNotStandingOnWarpPadOrHole
 	ld a, $4
 	call StopMusic
 	ld a, [wd732]
-	bit 6, a
-	jr z, .asm_70610
-	ld hl, wWhichTrade ; wWhichTrade
-	ld a, $10
-	ld [hli], a
-	ld a, $ff
-	ld [hli], a
+	bit 6, a ; is the last used pokemon center the destination?
+	jr z, .flyAnimation
+; if going to the last used pokemon center
+	ld hl, wPlayerSpinInPlaceAnimFrameDelay
+	ld a, 16
+	ld [hli], a ; wPlayerSpinInPlaceAnimFrameDelay
+	ld a, -1
+	ld [hli], a ; wPlayerSpinInPlaceAnimFrameDelayDelta
 	xor a
-	ld [hli], a
-	ld [hl], $a1
+	ld [hli], a ; wPlayerSpinInPlaceAnimFrameDelayEndValue
+	ld [hl], $a1 ; wPlayerSpinInPlaceAnimSoundID
 	ld hl, wcd48
-	call Func_70730
-	jr .asm_705c8
-.asm_70610
-	call Func_706d7
-	ld hl, wWhichTrade ; wWhichTrade
-	ld a, $ff
-	ld [hli], a
-	ld a, $8
-	ld [hli], a
-	ld [hl], $c
-	call Func_706ae
+	call PlayerSpinInPlace
+	jr .spinWhileMovingUp
+.flyAnimation
+	call LoadBirdSpriteGraphics
+	ld hl, wFlyAnimUsingCoordList
+	ld a, $ff ; is not using coord list (flap in place)
+	ld [hli], a ; wFlyAnimUsingCoordList
+	ld a, 8
+	ld [hli], a ; wFlyAnimCounter
+	ld [hl], $c ; wFlyAnimBirdSpriteImageIndex
+	call DoFlyAnimation
 	ld a, (SFX_02_50 - SFX_Headers_02) / 3
 	call PlaySound
-	ld hl, wWhichTrade ; wWhichTrade
-	xor a
-	ld [hli], a
+	ld hl, wFlyAnimUsingCoordList
+	xor a ; is using coord list
+	ld [hli], a ; wFlyAnimUsingCoordList
 	ld a, $c
-	ld [hli], a
-	ld [hl], $c
+	ld [hli], a ; wFlyAnimCounter
+	ld [hl], $c ; wFlyAnimBirdSpriteImageIndex (facing right)
 	ld de, FlyAnimationScreenCoords1 ; $464f
-	call Func_706ae
-	ld c, $28
+	call DoFlyAnimation
+	ld c, 40
 	call DelayFrames
-	ld hl, wTrainerEngageDistance
-	ld a, $b
-	ld [hli], a
-	ld [hl], $8
+	ld hl, wFlyAnimCounter
+	ld a, 11
+	ld [hli], a ; wFlyAnimCounter
+	ld [hl], $8 ; wFlyAnimBirdSpriteImageIndex (facing left)
 	ld de, FlyAnimationScreenCoords2 ; $4667
-	call Func_706ae
-	call GBFadeOut2
-	jp Func_70772
+	call DoFlyAnimation
+	call GBFadeOutToWhite
+	jp RestoreFacingDirectionAndYScreenPos
 
 FlyAnimationScreenCoords1: ; 7064f (1c:464f)
 ; y, x pairs
@@ -198,33 +201,35 @@ FlyAnimationScreenCoords2: ; 70667 (1c:4667)
 
 	db $F0, $00
 
-Func_7067d: ; 7067d (1c:467d)
+LeaveMapThroughHoleAnim: ; 7067d (1c:467d)
 	ld a, $ff
-	ld [wcfcb], a
-	ld a, [wOAMBuffer + $02]
-	ld [wOAMBuffer + $0a], a
-	ld a, [wOAMBuffer + $06]
-	ld [wOAMBuffer + $0e], a
+	ld [wUpdateSpritesEnabled], a ; disable UpdateSprites
+	; shift upper half of player's sprite down 8 pixels and hide lower half
+	ld a, [wOAMBuffer + 0 * 4 + 2]
+	ld [wOAMBuffer + 2 * 4 + 2], a
+	ld a, [wOAMBuffer + 1 * 4 + 2]
+	ld [wOAMBuffer + 3 * 4 + 2], a
 	ld a, $a0
-	ld [wOAMBuffer], a
-	ld [wOAMBuffer + $04], a
-	ld c, $2
+	ld [wOAMBuffer + 0 * 4], a
+	ld [wOAMBuffer + 1 * 4], a
+	ld c, 2
 	call DelayFrames
+	; hide lower half of player's sprite
 	ld a, $a0
-	ld [wOAMBuffer + $08], a
-	ld [wOAMBuffer + $0c], a
-	call GBFadeOut2
+	ld [wOAMBuffer + 2 * 4], a
+	ld [wOAMBuffer + 3 * 4], a
+	call GBFadeOutToWhite
 	ld a, $1
-	ld [wcfcb], a
-	jp Func_70772
+	ld [wUpdateSpritesEnabled], a ; enable UpdateSprites
+	jp RestoreFacingDirectionAndYScreenPos
 
-Func_706ae: ; 706ae (1c:46ae)
-	ld a, [wTrainerFacingDirection]
-	xor $1
-	ld [wTrainerFacingDirection], a
+DoFlyAnimation: ; 706ae (1c:46ae)
+	ld a, [wFlyAnimBirdSpriteImageIndex]
+	xor $1 ; make the bird flap its wings
+	ld [wFlyAnimBirdSpriteImageIndex], a
 	ld [wSpriteStateData1 + 2], a
 	call Delay3
-	ld a, [wWhichTrade] ; wWhichTrade
+	ld a, [wFlyAnimUsingCoordList]
 	cp $ff
 	jr z, .asm_706cd
 	ld hl, wSpriteStateData1 + 4
@@ -236,13 +241,13 @@ Func_706ae: ; 706ae (1c:46ae)
 	inc de
 	ld [hl], a
 .asm_706cd
-	ld a, [wTrainerEngageDistance]
+	ld a, [wFlyAnimCounter]
 	dec a
-	ld [wTrainerEngageDistance], a
-	jr nz, Func_706ae
+	ld [wFlyAnimCounter], a
+	jr nz, DoFlyAnimation
 	ret
 
-Func_706d7: ; 706d7 (1c:46d7)
+LoadBirdSpriteGraphics: ; 706d7 (1c:46d7)
 	ld de, BirdSprite ; $4d80
 	ld hl, vNPCSprites
 	ld bc, (BANK(BirdSprite) << 8) + $0c
@@ -252,32 +257,32 @@ Func_706d7: ; 706d7 (1c:46d7)
 	ld bc, (BANK(BirdSprite) << 8) + $0c
 	jp CopyVideoData
 
-Func_706ef: ; 706ef (1c:46ef)
-	ld a, [wSpriteStateData1 + 2]
+InitFacingDirectionBuffer: ; 706ef (1c:46ef)
+	ld a, [wSpriteStateData1 + 2] ; player's sprite facing direction (image index is locked to standing images)
 	ld [wcd50], a
-	ld a, [wSpriteStateData1 + 4]
+	ld a, [wSpriteStateData1 + 4] ; player's sprite Y screen position
 	ld [wcd4f], a
-	ld hl, PlayerSpinningFacingOrder ; $4713
+	ld hl, PlayerSpinningFacingOrder
 	ld de, wcd48
 	ld bc, $4
 	call CopyData
-	ld a, [wSpriteStateData1 + 2]
+	ld a, [wSpriteStateData1 + 2] ; player's sprite facing direction (image index is locked to standing images)
 	ld hl, wcd48
-.asm_7070d
+.loop
 	cp [hl]
 	inc hl
-	jr nz, .asm_7070d
+	jr nz, .loop
 	dec hl
 	ret
 
 PlayerSpinningFacingOrder: ; 70713 (1c:4713)
 ; The order of the direction the player's sprite is facing when teleporting
 ; away. Creates a spinning effect.
-	db $00, $08, $04, $0C ; down, left, up, right
+	db SPRITE_FACING_DOWN, SPRITE_FACING_LEFT, SPRITE_FACING_UP, SPRITE_FACING_RIGHT
 
-Func_70717: ; 70717 (1c:4717)
+SpinPlayerSprite: ; 70717 (1c:4717)
 	ld a, [hl]
-	ld [wSpriteStateData1 + 2], a
+	ld [wSpriteStateData1 + 2], a ; player's sprite facing direction (image index is locked to standing images)
 	push hl
 	ld hl, wcd48
 	ld de, wcd47
@@ -288,84 +293,85 @@ Func_70717: ; 70717 (1c:4717)
 	pop hl
 	ret
 
-Func_70730: ; 70730 (1c:4730)
-	call Func_70717
-	ld a, [wWhichTrade] ; wWhichTrade
+PlayerSpinInPlace: ; 70730 (1c:4730)
+	call SpinPlayerSprite
+	ld a, [wPlayerSpinInPlaceAnimFrameDelay]
 	ld c, a
 	and $3
 	jr nz, .asm_70743
-	ld a, [wTrainerScreenY]
+	ld a, [wPlayerSpinInPlaceAnimSoundID]
 	cp $ff
 	call nz, PlaySound
 .asm_70743
-	ld a, [wTrainerEngageDistance]
+	ld a, [wPlayerSpinInPlaceAnimFrameDelayDelta]
 	add c
-	ld [wWhichTrade], a ; wWhichTrade
+	ld [wPlayerSpinInPlaceAnimFrameDelay], a
 	ld c, a
-	ld a, [wTrainerFacingDirection]
+	ld a, [wPlayerSpinInPlaceAnimFrameDelayEndValue]
 	cp c
 	ret z
 	call DelayFrames
-	jr Func_70730
+	jr PlayerSpinInPlace
 
-Func_70755: ; 70755 (1c:4755)
-	call Func_70717
-	ld a, [wWhichTrade] ; wWhichTrade
+PlayerSpinWhileMovingUpOrDown: ; 70755 (1c:4755)
+	call SpinPlayerSprite
+	ld a, [wPlayerSpinWhileMovingUpOrDownAnimDeltaY]
 	ld c, a
-	ld a, [wSpriteStateData1 + 4]
+	ld a, [wSpriteStateData1 + 4] ; player's sprite Y screen position
 	add c
 	ld [wSpriteStateData1 + 4], a
 	ld c, a
-	ld a, [wTrainerEngageDistance]
+	ld a, [wPlayerSpinWhileMovingUpOrDownAnimMaxY]
 	cp c
 	ret z
-	ld a, [wTrainerFacingDirection]
+	ld a, [wPlayerSpinWhileMovingUpOrDownAnimFrameDelay]
 	ld c, a
 	call DelayFrames
-	jr Func_70755
+	jr PlayerSpinWhileMovingUpOrDown
 
-Func_70772: ; 70772 (1c:4772)
+RestoreFacingDirectionAndYScreenPos: ; 70772 (1c:4772)
 	ld a, [wcd4f]
 	ld [wSpriteStateData1 + 4], a
 	ld a, [wcd50]
 	ld [wSpriteStateData1 + 2], a
 	ret
 
-Func_7077f: ; 7077f (1c:477f)
-	ld a, [wcf1b]
+; if SGB, 2 frames, else 3 frames
+GetPlayerTeleportAnimFrameDelay: ; 7077f (1c:477f)
+	ld a, [wOnSGB]
 	xor $1
 	inc a
 	inc a
 	ret
 
-Func_70787: ; 70787 (1c:4787)
+IsPlayerStandingOnWarpPadOrHole: ; 70787 (1c:4787)
 	ld b, 0
-	ld hl, DataTable_707a9 ; $47a9
-	ld a, [W_CURMAPTILESET] ; W_CURMAPTILESET
+	ld hl, .warpPadAndHoleData
+	ld a, [W_CURMAPTILESET]
 	ld c, a
-.asm_70790
+.loop
 	ld a, [hli]
 	cp $ff
-	jr z, .asm_707a4
+	jr z, .done
 	cp c
-	jr nz, .asm_7079e
+	jr nz, .nextEntry
 	aCoord 8, 9
 	cp [hl]
-	jr z, .asm_707a2
-.asm_7079e
+	jr z, .foundMatch
+.nextEntry
 	inc hl
 	inc hl
-	jr .asm_70790
-.asm_707a2
+	jr .loop
+.foundMatch
 	inc hl
 	ld b, [hl]
-.asm_707a4
+.done
 	ld a, b
 	ld [wcd5b], a
 	ret
 
 ; format: db tileset id, tile id, value to be put in wcd5b
-DataTable_707a9: ; 707a9 (1c:47a9)
+.warpPadAndHoleData: ; 707a9 (1c:47a9)
 	db FACILITY, $20, 1 ; warp pad
 	db FACILITY, $11, 2 ; hole
 	db CAVERN,   $22, 2 ; hole
@@ -454,7 +460,7 @@ ItsABiteText: ; 70851 (1c:4851)
 	db "@"
 
 FishingRodGfxProperties: ; 70856 (1c:4856)
-; specicies how the fishing rod should be drawn on the screen
+; specifies how the fishing rod should be drawn on the screen
 ; first byte = screen y coordinate
 ; second byte = screen x coordinate
 ; third byte = tile number
@@ -482,21 +488,21 @@ RedFishingTiles: ; 70866 (1c:4866)
 	dw vNPCSprites2 + $7d0
 
 _HandleMidJump: ; 7087e (1c:487e)
-	ld a, [wd714]
+	ld a, [wPlayerJumpingYScreenCoordsIndex]
 	ld c, a
 	inc a
 	cp $10
-	jr nc, .asm_70895
-	ld [wd714], a
-	ld b, $0
-	ld hl, PlayerJumpingYScreenCoords ; $48ba
+	jr nc, .finishedJump
+	ld [wPlayerJumpingYScreenCoordsIndex], a
+	ld b, 0
+	ld hl, PlayerJumpingYScreenCoords
 	add hl, bc
 	ld a, [hl]
 	ld [wSpriteStateData1 + 4], a ; player's sprite y coordinate
 	ret
-.asm_70895
-	ld a, [wWalkCounter] ; wcfc5
-	cp $0
+.finishedJump
+	ld a, [wWalkCounter]
+	cp 0
 	ret nz
 	call UpdateSprites
 	call Delay3
@@ -504,11 +510,11 @@ _HandleMidJump: ; 7087e (1c:487e)
 	ld [hJoyHeld], a
 	ld [hJoyPressed], a
 	ld [hJoyReleased], a
-	ld [wd714], a
+	ld [wPlayerJumpingYScreenCoordsIndex], a
 	ld hl, wd736
-	res 6, [hl]
+	res 6, [hl] ; not jumping down a ledge any more
 	ld hl, wd730
-	res 7, [hl]
+	res 7, [hl] ; not simulating joypad states any more
 	xor a
 	ld [wJoyIgnore], a
 	ret

engine/overworld/pokemart.asm

@@ -173,13 +173,13 @@ DisplayPokemartDialogue_: ; 6c20 (1:6c20)
 	ld [wcf0a],a
 .skipSettingFlag2
 	ld a,(SFX_02_5a - SFX_Headers_02) / 3
-	call PlaySoundWaitForCurrent ; play sound
-	call WaitForSoundToFinish ; wait until sound is done playing
+	call PlaySoundWaitForCurrent
+	call WaitForSoundToFinish
 	ld hl,PokemartBoughtItemText
 	call PrintText
 	jp .buyMenuLoop
 .returnToMainPokemartMenu
-	call LoadScreenTilesFromBuffer1 ; restore save screen
+	call LoadScreenTilesFromBuffer1
 	ld a,$13
 	ld [wd125],a
 	call DisplayTextBoxID ; draw money text box
@@ -203,7 +203,7 @@ DisplayPokemartDialogue_: ; 6c20 (1:6c20)
 	ld hl,PokemartThankYouText
 	call PrintText
 	ld a,$01
-	ld [wcfcb],a
+	ld [wUpdateSpritesEnabled],a
 	call UpdateSprites ; move sprites
 	ld a,[wd07e]
 	ld [wListScrollOffset],a

engine/overworld/ssanne.asm

@@ -1,37 +1,37 @@
-Func_79f54: ; 79f54 (1e:5f54)
+AnimateBoulderDust: ; 79f54 (1e:5f54)
 	ld a, $1
-	ld [wcd50], a
-	ld a, [wcfcb]
+	ld [wcd50], a ; select the boulder dust offsets
+	ld a, [wUpdateSpritesEnabled]
 	push af
 	ld a, $ff
-	ld [wcfcb], a
-	ld a, $e4
-	ld [rOBP1], a ; $ff49
+	ld [wUpdateSpritesEnabled], a
+	ld a, %11100100
+	ld [rOBP1], a
 	call LoadSmokeTileFourTimes
-	callba asm_f055
-	ld c, $8
-.asm_79f73
+	callba WriteCutTreeBoulderDustAnimationOAMBlock
+	ld c, 8 ; number of steps in animation
+.loop
 	push bc
-	call Func_79f92
-	ld bc, .asm_79f7e
+	call GetMoveBoulderDustFunctionPointer
+	ld bc, .returnAddress
 	push bc
 	ld c, $4
 	jp [hl]
-.asm_79f7e
-	ld a, [rOBP1] ; $ff49
-	xor $64
-	ld [rOBP1], a ; $ff49
+.returnAddress
+	ld a, [rOBP1]
+	xor %01100100
+	ld [rOBP1], a
 	call Delay3
 	pop bc
 	dec c
-	jr nz, .asm_79f73
+	jr nz, .loop
 	pop af
-	ld [wcfcb], a
+	ld [wUpdateSpritesEnabled], a
 	jp LoadPlayerSpriteGraphics
 
-Func_79f92: ; 79f92 (1e:5f92)
-	ld a, [wSpriteStateData1 + 9]
-	ld hl, PointerTable_79fb0 ; $5fb0
+GetMoveBoulderDustFunctionPointer: ; 79f92 (1e:5f92)
+	ld a, [wSpriteStateData1 + 9] ; player's sprite facing direction
+	ld hl, MoveBoulderDustFunctionPointerTable
 	ld c, a
 	ld b, $0
 	add hl, bc
@@ -51,18 +51,22 @@ Func_79f92: ; 79f92 (1e:5f92)
 	pop hl
 	ret
 
-PointerTable_79fb0: ; 79fb0 (1e:5fb0)
+MoveBoulderDustFunctionPointerTable: ; 79fb0 (1e:5fb0)
+; facing down
 	db $FF,$00
-	dw Func_79350
+	dw AdjustOAMBlockYPos
 
+; facing up
 	db $01,$00
-	dw Func_79350
+	dw AdjustOAMBlockYPos
 
+; facing left
 	db $01,$01
-	dw Func_79337
+	dw AdjustOAMBlockXPos
 
+; facing right
 	db $FF,$01
-	dw Func_79337
+	dw AdjustOAMBlockXPos
 
 LoadSmokeTileFourTimes: ; 79fc0 (1e:5fc0)
 	ld hl, vChars1 + $7c0

engine/overworld/trainers.asm

@@ -1,9 +1,9 @@
-Func_567f9: ; 567f9 (15:67f9)
+_GetSpritePosition1: ; 567f9 (15:67f9)
 	ld hl, wSpriteStateData1
 	ld de, $4
-	ld a, [wcf13]
-	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
-	call Func_56903
+	ld a, [wSpriteIndex]
+	ld [H_SPRITEINDEX], a
+	call GetSpriteDataPointer
 	ld a, [hli]
 	ld [$ffeb], a
 	inc hl
@@ -17,50 +17,50 @@ Func_567f9: ; 567f9 (15:67f9)
 	ld [$ffee], a
 	ret
 
-Func_56819: ; 56819 (15:6819)
+_GetSpritePosition2: ; 56819 (15:6819)
 	ld hl, wSpriteStateData1
-	ld de, $0004
-	ld a, [wcf13]
-	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
-	call Func_56903
-	ld a, [hli]
+	ld de, $4
+	ld a, [wSpriteIndex]
+	ld [H_SPRITEINDEX], a
+	call GetSpriteDataPointer
+	ld a, [hli] ; c1x4 (screen Y pos)
 	ld [wd130], a
 	inc hl
-	ld a, [hl]
+	ld a, [hl] ; c1x6 (screen X pos)
 	ld [wd131], a
-	ld de, $00fe
+	ld de, $104 - $6
 	add hl, de
-	ld a, [hli]
+	ld a, [hli] ; c2x4 (map Y pos)
 	ld [wd132], a
-	ld a, [hl]
+	ld a, [hl] ; c2x5 (map X pos)
 	ld [wd133], a
 	ret
 
-Func_5683d: ; 5683d (15:683d)
+_SetSpritePosition1: ; 5683d (15:683d)
 	ld hl, wSpriteStateData1
 	ld de, $4
-	ld a, [wcf13]
-	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
-	call Func_56903
-	ld a, [$ffeb]
+	ld a, [wSpriteIndex]
+	ld [H_SPRITEINDEX], a
+	call GetSpriteDataPointer
+	ld a, [$ffeb] ; c1x4 (screen Y pos)
 	ld [hli], a
 	inc hl
-	ld a, [$ffec]
+	ld a, [$ffec] ; c1x6 (screen X pos)
 	ld [hl], a
-	ld de, $fe
+	ld de, $104 - $6
 	add hl, de
-	ld a, [$ffed]
+	ld a, [$ffed] ; c2x4 (map Y pos)
 	ld [hli], a
-	ld a, [$ffee]
+	ld a, [$ffee] ; c2x5 (map X pos)
 	ld [hl], a
 	ret
 
-Func_5685d: ; 5685d (15:685d)
+_SetSpritePosition2: ; 5685d (15:685d)
 	ld hl, wSpriteStateData1
 	ld de, $0004
-	ld a, [wcf13]
-	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
-	call Func_56903
+	ld a, [wSpriteIndex]
+	ld [H_SPRITEINDEX], a
+	call GetSpriteDataPointer
 	ld a, [wd130]
 	ld [hli], a
 	inc hl
@@ -75,7 +75,7 @@ Func_5685d: ; 5685d (15:685d)
 	ret
 
 TrainerWalkUpToPlayer: ; 56881 (15:6881)
-	ld a, [wcf13]
+	ld a, [wSpriteIndex]
 	swap a
 	ld [wTrainerSpriteOffset], a ; wWhichTrade
 	call ReadTrainerScreenPosition
@@ -139,18 +139,20 @@ TrainerWalkUpToPlayer: ; 56881 (15:6881)
 	ld b, $0
 	ld a, $80           ; a = direction to go to
 .writeWalkScript
-	ld hl, wcc97
-	ld de, wcc97
+	ld hl, wNPCMovementDirections2
+	ld de, wNPCMovementDirections2
 	call FillMemory     ; write the necessary steps to reach player
 	ld [hl], $ff        ; write end of list sentinel
-	ld a, [wcf13]
-	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
+	ld a, [wSpriteIndex]
+	ld [H_SPRITEINDEX], a
 	jp MoveSprite_
 
-Func_56903: ; 56903 (15:6903)
+; input: de = offset within sprite entry
+; output: de = pointer to sprite data
+GetSpriteDataPointer: ; 56903 (15:6903)
 	push de
 	add hl, de
-	ld a, [H_DOWNARROWBLINKCNT2] ; $ff8c
+	ld a, [H_SPRITEINDEX]
 	swap a
 	ld d, $0
 	ld e, a

engine/palettes.asm

@@ -380,11 +380,11 @@ SendSGBPacket: ; 71feb (1c:5feb)
 
 LoadSGB: ; 7202b (1c:602b)
 	xor a
-	ld [wcf1b], a
+	ld [wOnSGB], a
 	call Func_7209b
 	ret nc
 	ld a, $1
-	ld [wcf1b], a
+	ld [wOnSGB], a
 	ld a, [wGBC]
 	and a
 	jr z, .asm_7203f

engine/play_time.asm

@@ -1,25 +1,25 @@
-Func_18dee: ; 18dee (6:4dee)
-	call Func_18e36
+TrackPlayTime: ; 18dee (6:4dee)
+	call CountDownIgnoreInputBitReset
 	ld a, [wd732]
 	bit 0, a
 	ret z
-	ld a, [W_PLAYTIMEMINUTES] ; wda42
+	ld a, [W_PLAYTIMEMINUTES]
 	and a
 	ret nz
-	ld a, [W_PLAYTIMEFRAMES] ; wda45
+	ld a, [W_PLAYTIMEFRAMES]
 	inc a
-	ld [W_PLAYTIMEFRAMES], a ; wda45
+	ld [W_PLAYTIMEFRAMES], a
 	cp 60
 	ret nz
 	xor a
-	ld [W_PLAYTIMEFRAMES], a ; wda45
-	ld a, [W_PLAYTIMESECONDS] ; wda44
+	ld [W_PLAYTIMEFRAMES], a
+	ld a, [W_PLAYTIMESECONDS]
 	inc a
-	ld [W_PLAYTIMESECONDS], a ; wda44
+	ld [W_PLAYTIMESECONDS], a
 	cp 60
 	ret nz
 	xor a
-	ld [W_PLAYTIMESECONDS], a ; wda44
+	ld [W_PLAYTIMESECONDS], a
 	ld a, [W_PLAYTIMEMINUTES + 1]
 	inc a
 	ld [W_PLAYTIMEMINUTES + 1], a
@@ -33,11 +33,11 @@ Func_18dee: ; 18dee (6:4dee)
 	cp $ff
 	ret nz
 	ld a, $ff
-	ld [W_PLAYTIMEMINUTES], a ; wda42
+	ld [W_PLAYTIMEMINUTES], a
 	ret
 
-Func_18e36: ; 18e36 (6:4e36)
-	ld a, [wd13a]
+CountDownIgnoreInputBitReset: ; 18e36 (6:4e36)
+	ld a, [wIgnoreInputCounter]
 	and a
 	jr nz, .asm_18e40
 	ld a, $ff
@@ -45,7 +45,7 @@ Func_18e36: ; 18e36 (6:4e36)
 .asm_18e40
 	dec a
 .asm_18e41
-	ld [wd13a], a
+	ld [wIgnoreInputCounter], a
 	and a
 	ret nz
 	ld a, [wd730]

engine/predefs.asm

@@ -52,13 +52,13 @@ GetPredefPointer:
 PredefPointers:: ; 4fe79 (13:7e79)
 ; these are pointers to ASM routines.
 ; they appear to be used in overworld map scripts.
-	add_predef Func_3cd60
+	add_predef DrawPlayerHUDAndHPBar
 	add_predef Func_3f0c6
 	add_predef Func_3f073
 	add_predef ScaleSpriteByTwo
 	add_predef LoadMonBackPic
 	add_predef Func_79aba
-	add_predef Func_f132
+	add_predef LoadMissableObjects
 	add_predef HealParty
 	add_predef MoveAnimation; 08 play move animation
 	add_predef DivideBCDPredef
@@ -71,30 +71,30 @@ PredefPointers:: ; 4fe79 (13:7e79)
 	add_predef FlagActionPredef
 	add_predef HideObject
 	add_predef IsObjectHidden
-	add_predef Func_c69c
+	add_predef ApplyOutOfBattlePoisonDamage
 	add_predef AnyPartyAlive
 	add_predef ShowObject
 	add_predef ShowObject2
-	add_predef Func_ee9e
+	add_predef ReplaceTileBlock
 	add_predef InitPlayerData2
-	add_predef Func_c754
-	add_predef Func_3af5b
+	add_predef LoadTilesetHeader
+	add_predef LearnMoveFromLevelUp
 	add_predef LearnMove
 	add_predef IsItemInBag_ ; 1C, used in Pokémon Tower
-	dbw $03,Func_3eb5 ; for these two, the bank number is actually 0
+	dbw $03,CheckForHiddenObjectOrBookshelfOrCardKeyDoor ; for these two, the bank number is actually 0
 	dbw $03,GiveItem
-	add_predef Func_480eb
-	add_predef Func_f8ba
+	add_predef ChangeBGPalColor0_4Frames
+	add_predef FindPathToPlayer
 	add_predef Func_480ff
-	add_predef Func_f929
-	add_predef Func_f9a0
+	add_predef CalcPositionOfPlayerRelativeToNPC
+	add_predef ConvertNPCMovementDirectionsToJoypadMasks
 	add_predef Func_48125
 	add_predef UpdateHPBar
 	add_predef HPBarLength
 	add_predef Func_5ab0
 	add_predef Func_3ed02
 	add_predef ShowPokedexMenu
-	add_predef Func_3ad1c
+	add_predef EvolutionAfterBattle
 	add_predef SaveSAVtoSRAM0
 	add_predef InitOpponent
 	add_predef Func_5a5f
@@ -105,7 +105,7 @@ PredefPointers:: ; 4fe79 (13:7e79)
 	add_predef PlayIntro
 	add_predef Func_79869
 	add_predef FlashScreen
-	add_predef Func_c586
+	add_predef GetTileAndCoordsInFrontOfPlayer
 	add_predef StatusScreen
 	add_predef StatusScreen2
 	add_predef Func_410e2
@@ -117,7 +117,7 @@ PredefPointers:: ; 4fe79 (13:7e79)
 	add_predef WriteMonMoves
 	add_predef SaveSAV
 	add_predef LoadSGB
-	add_predef Func_f113
+	add_predef MarkTownVisitedAndLoadMissableObjects
 	add_predef SetPartyMonTypes
 	add_predef CanLearnTM
 	add_predef TMToMove
@@ -125,7 +125,7 @@ PredefPointers:: ; 4fe79 (13:7e79)
 	add_predef StarterDex ; 46
 	add_predef _AddPartyMon
 	add_predef UpdateHPBar2
-	add_predef Func_3cdec
+	add_predef DrawEnemyHUDAndHPBar
 	add_predef LoadTownMap_Nest
 	add_predef Func_27d6b
 	add_predef EmotionBubble; 4C player exclamation
@@ -140,9 +140,9 @@ PredefPointers:: ; 4fe79 (13:7e79)
 	add_predef HallOfFamePC
 	add_predef DisplayDexRating
 	dbw $1E, _LeaveMapAnim ; wrong bank
-	dbw $1E, Func_70510 ; wrong bank
-	add_predef Func_c5be
-	add_predef Func_c60b
+	dbw $1E, EnterMapAnim ; wrong bank
+	add_predef GetTileTwoStepsInFrontOfPlayer
+	add_predef CheckForCollisionWhenPushingBoulder
 	add_predef PrintStrengthTxt
 	add_predef PickupItem
 	add_predef Func_27d98

engine/predefs12.asm

@@ -1,13 +1,14 @@
-Func_480eb: ; 480eb (12:40eb)
+; b = new colour for BG colour 0 (usually white) for 4 frames
+ChangeBGPalColor0_4Frames: ; 480eb (12:40eb)
 	call GetPredefRegisters
-	ld a, [rBGP] ; $ff47
+	ld a, [rBGP]
 	or b
-	ld [rBGP], a ; $ff47
+	ld [rBGP], a
 	ld c, $4
 	call DelayFrames
-	ld a, [rBGP] ; $ff47
-	and $fc
-	ld [rBGP], a ; $ff47
+	ld a, [rBGP]
+	and %11111100
+	ld [rBGP], a
 	ret
 
 Func_480ff: ; 480ff (12:40ff)

engine/predefs7.asm

@@ -31,7 +31,7 @@ Func_1c9c6: ; 1c9c6 (7:49c6)
 	ld b, a
 	ld a, [hl]
 	ld c, a
-	ld hl, wd3af
+	ld hl, wWarpEntries
 	call Func_1ca0d
 
 Func_1ca0d: ; 1ca0d (7:4a0d)

engine/save.asm

@@ -32,11 +32,11 @@ FileDataDestroyedText: ; 7361e (1c:761e)
 	db "@"
 
 LoadSAVCheckSum: ; 73623 (1c:7623)
-	ld a, $a
-	ld [$0], a
+	ld a, SRAM_ENABLE
+	ld [MBC1SRamEnable], a
 	ld a, $1
-	ld [$6000], a
-	ld [$4000], a
+	ld [MBC1SRamBankingMode], a
+	ld [MBC1SRamBank], a
 	ld hl, $a598 ; hero name located in SRAM
 	ld bc, $f8b ; but here checks the full SAV
 	call SAVCheckSum
@@ -58,30 +58,30 @@ LoadSAVCheckSum: ; 73623 (1c:7623)
 	ld bc, $b
 	call CopyData
 	ld hl, $a5a3
-	ld de, wPokedexOwned ; wPokedexOwned
+	ld de, wPokedexOwned
 	ld bc, $789
 	call CopyData
-	ld hl, W_CURMAPTILESET ; W_CURMAPTILESET
+	ld hl, W_CURMAPTILESET
 	set 7, [hl]
 	ld hl, $ad2c
 	ld de, wSpriteStateData1
 	ld bc, $200
 	call CopyData
 	ld a, [$b522]
-	ld [$ffd7], a
+	ld [hTilesetType], a
 	ld hl, $b0c0
-	ld de, W_NUMINBOX ; wda80
-	ld bc, $462
+	ld de, W_NUMINBOX
+	ld bc, wBoxMonNicksEnd - W_NUMINBOX
 	call CopyData
 	and a
 	jp SAVGoodChecksum
 
 LoadSAVCheckSum1: ; 73690 (1c:7690)
-	ld a, $a
-	ld [$0], a
+	ld a, SRAM_ENABLE
+	ld [MBC1SRamEnable], a
 	ld a, $1
-	ld [$6000], a
-	ld [$4000], a
+	ld [MBC1SRamBankingMode], a
+	ld [MBC1SRamBank], a
 	ld hl, $a598 ; hero name located in SRAM
 	ld bc, $f8b  ; but here checks the full SAV
 	call SAVCheckSum
@@ -90,18 +90,18 @@ LoadSAVCheckSum1: ; 73690 (1c:7690)
 	cp c
 	jr nz, SAVBadCheckSum
 	ld hl, $b0c0
-	ld de, W_NUMINBOX ; wda80
-	ld bc, $462
+	ld de, W_NUMINBOX
+	ld bc, wBoxMonNicksEnd - W_NUMINBOX
 	call CopyData
 	and a
 	jp SAVGoodChecksum
 
 LoadSAVCheckSum2: ; 736bd (1c:76bd)
-	ld a, $a
-	ld [$0], a
+	ld a, SRAM_ENABLE
+	ld [MBC1SRamEnable], a
 	ld a, $1
-	ld [$6000], a
-	ld [$4000], a
+	ld [MBC1SRamBankingMode], a
+	ld [MBC1SRamBank], a
 	ld hl, $a598 ; hero name located in SRAM
 	ld bc, $f8b  ; but here checks the full SAV
 	call SAVCheckSum
@@ -125,8 +125,8 @@ SAVBadCheckSum: ; 736f7 (1c:76f7)
 
 SAVGoodChecksum: ; 736f8 (1c:76f8)
 	ld a, $0
-	ld [$6000], a
-	ld [$0], a
+	ld [MBC1SRamBankingMode], a
+	ld [MBC1SRamEnable], a
 	ret
 
 Func_73701: ; 0x73701
@@ -193,67 +193,67 @@ OlderFileWillBeErasedText: ; 73787 (1c:7787)
 	db "@"
 
 SaveSAVtoSRAM0: ; 7378c (1c:778c)
-	ld a, $a
-	ld [$0], a
+	ld a, SRAM_ENABLE
+	ld [MBC1SRamEnable], a
 	ld a, $1
-	ld [$6000], a
-	ld [$4000], a
-	ld hl, wPlayerName ; wd158
+	ld [MBC1SRamBankingMode], a
+	ld [MBC1SRamBank], a
+	ld hl, wPlayerName
 	ld de, $a598
 	ld bc, $b
 	call CopyData
-	ld hl, wPokedexOwned ; wPokedexOwned
+	ld hl, wPokedexOwned
 	ld de, $a5a3
-	ld bc, $789
+	ld bc, W_NUMINBOX - wPokedexOwned
 	call CopyData
-	ld hl, wSpriteStateData1 ; OAM?
+	ld hl, wSpriteStateData1
 	ld de, $ad2c
 	ld bc, $200
 	call CopyData
-	ld hl, W_NUMINBOX ; wda80
+	ld hl, W_NUMINBOX
 	ld de, $b0c0
-	ld bc, $462
+	ld bc, wBoxMonNicksEnd - W_NUMINBOX
 	call CopyData
-	ld a, [$ffd7]
+	ld a, [hTilesetType]
 	ld [$b522], a
 	ld hl, $a598
 	ld bc, $f8b
 	call SAVCheckSum
 	ld [$b523], a
 	xor a
-	ld [$6000], a
-	ld [$0], a
+	ld [MBC1SRamBankingMode], a
+	ld [MBC1SRamEnable], a
 	ret
 
 SaveSAVtoSRAM1: ; 737e2 (1c:77e2)
 ; stored pokémon
-	ld a, $a
-	ld [$0], a
+	ld a, SRAM_ENABLE
+	ld [MBC1SRamEnable], a
 	ld a, $1
-	ld [$6000], a
-	ld [$4000], a
-	ld hl, W_NUMINBOX ; wda80
+	ld [MBC1SRamBankingMode], a
+	ld [MBC1SRamBank], a
+	ld hl, W_NUMINBOX
 	ld de, $b0c0
-	ld bc, $462
+	ld bc, wBoxMonNicksEnd - W_NUMINBOX
 	call CopyData
 	ld hl, $a598
 	ld bc, $f8b
 	call SAVCheckSum
 	ld [$b523], a
 	xor a
-	ld [$6000], a
-	ld [$0], a
+	ld [MBC1SRamBankingMode], a
+	ld [MBC1SRamEnable], a
 	ret
 
 SaveSAVtoSRAM2: ; 7380f (1c:780f)
-	ld a, $a
-	ld [$0], a
+	ld a, SRAM_ENABLE
+	ld [MBC1SRamEnable], a
 	ld a, $1
-	ld [$6000], a
-	ld [$4000], a
-	ld hl, wPartyCount ; wPartyCount
+	ld [MBC1SRamBankingMode], a
+	ld [MBC1SRamBank], a
+	ld hl, wPartyCount
 	ld de, $af2c
-	ld bc, $194
+	ld bc, wPokedexOwned - wPartyCount
 	call CopyData
 	ld hl, wPokedexOwned ; pokédex only
 	ld de, $a5a3
@@ -264,8 +264,8 @@ SaveSAVtoSRAM2: ; 7380f (1c:780f)
 	call SAVCheckSum
 	ld [$b523], a
 	xor a
-	ld [$6000], a
-	ld [$0], a
+	ld [MBC1SRamBankingMode], a
+	ld [MBC1SRamEnable], a
 	ret
 
 SaveSAVtoSRAM: ; 73848 (1c:7848)
@@ -334,13 +334,13 @@ PointerTable_73895: ; 73895 (1c:7895)
 	dw $B188
 	dw $B5EA
 
-Func_738a1:: ; 738a1 (1c:78a1)
+ChangeBox:: ; 738a1 (1c:78a1)
 	ld hl, WhenYouChangeBoxText
 	call PrintText
 	call YesNoChoice
-	ld a, [wCurrentMenuItem] ; wCurrentMenuItem
+	ld a, [wCurrentMenuItem]
 	and a
-	ret nz
+	ret nz ; return if No was chosen
 	ld hl, wd5a0
 	bit 7, [hl]
 	call z, Func_73a29
@@ -356,25 +356,25 @@ Func_738a1:: ; 738a1 (1c:78a1)
 	call Func_7387b
 	ld e, l
 	ld d, h
-	ld hl, W_NUMINBOX ; wda80
+	ld hl, W_NUMINBOX
 	call Func_7390e
-	ld a, [wCurrentMenuItem] ; wCurrentMenuItem
+	ld a, [wCurrentMenuItem]
 	set 7, a
 	ld [wd5a0], a
 	call Func_7387b
-	ld de, W_NUMINBOX ; wda80
+	ld de, W_NUMINBOX
 	call Func_7390e
-	ld hl, W_MAPTEXTPTR ; wd36c
-	ld de, wWhichTrade ; wWhichTrade
+	ld hl, W_MAPTEXTPTR
+	ld de, wChangeBoxSavedMapTextPointer
 	ld a, [hli]
 	ld [de], a
 	inc de
 	ld a, [hl]
 	ld [de], a
-	call Func_3f05
+	call RestoreMapTextPointer
 	call SaveSAVtoSRAM
-	ld hl, wWhichTrade ; wWhichTrade
-	call Func_3f0f
+	ld hl, wChangeBoxSavedMapTextPointer
+	call SetMapTextPointer
 	ld a, (SFX_02_5d - SFX_Headers_02) / 3
 	call PlaySoundWaitForCurrent
 	call WaitForSoundToFinish
@@ -386,12 +386,12 @@ WhenYouChangeBoxText: ; 73909 (1c:7909)
 
 Func_7390e: ; 7390e (1c:790e)
 	push hl
-	ld a, $a
-	ld [$0], a
+	ld a, SRAM_ENABLE
+	ld [MBC1SRamEnable], a
 	ld a, $1
-	ld [$6000], a
+	ld [MBC1SRamBankingMode], a
 	ld a, b
-	ld [$4000], a
+	ld [MBC1SRamBank], a
 	ld bc, $462
 	call CopyData
 	pop hl
@@ -405,8 +405,8 @@ Func_7390e: ; 7390e (1c:790e)
 	ld [$ba4c], a
 	call Func_73863
 	xor a
-	ld [$6000], a
-	ld [$0], a
+	ld [MBC1SRamBankingMode], a
+	ld [MBC1SRamEnable], a
 	ret
 
 Func_7393f: ; 7393f (1c:793f)
@@ -502,19 +502,19 @@ BoxNoText: ; 73a21 (1c:7a21)
 	db "BOX No.@"
 
 Func_73a29: ; 73a29 (1c:7a29)
-	ld a, $a
-	ld [$0], a
+	ld a, SRAM_ENABLE
+	ld [MBC1SRamEnable], a
 	ld a, $1
-	ld [$6000], a
+	ld [MBC1SRamBankingMode], a
 	ld a, $2
-	ld [$4000], a
+	ld [MBC1SRamBank], a
 	call Func_73a4b
 	ld a, $3
-	ld [$4000], a
+	ld [MBC1SRamBank], a
 	call Func_73a4b
 	xor a
-	ld [$6000], a
-	ld [$0], a
+	ld [MBC1SRamBankingMode], a
+	ld [MBC1SRamEnable], a
 	ret
 
 Func_73a4b: ; 73a4b (1c:7a4b)
@@ -547,19 +547,19 @@ Func_73a7f: ; 73a7f (1c:7a7f)
 Func_73a84: ; 73a84 (1c:7a84)
 	ld hl, wWhichTrade ; wWhichTrade
 	push hl
-	ld a, $a
-	ld [$0], a
+	ld a, SRAM_ENABLE
+	ld [MBC1SRamEnable], a
 	ld a, $1
-	ld [$6000], a
+	ld [MBC1SRamBankingMode], a
 	ld a, $2
-	ld [$4000], a
+	ld [MBC1SRamBank], a
 	call Func_73ab8
 	ld a, $3
-	ld [$4000], a
+	ld [MBC1SRamBank], a
 	call Func_73ab8
 	xor a
-	ld [$6000], a
-	ld [$0], a
+	ld [MBC1SRamBankingMode], a
+	ld [MBC1SRamEnable], a
 	pop hl
 	ld a, [wd5a0]
 	and $7f
@@ -592,8 +592,8 @@ SAVCheckRandomID: ;$7ad1
 	ld a,$0a
 	ld [$0000],a
 	ld a,$01
-	ld [$6000],a
-	ld [$4000],a
+	ld [MBC1SRamBankingMode],a
+	ld [MBC1SRamBank],a
 	ld a,[$a598]
 	and a
 	jr z,.next
@@ -615,7 +615,7 @@ SAVCheckRandomID: ;$7ad1
 	cp h
 .next
 	ld a,$00
-	ld [$6000],a
+	ld [MBC1SRamBankingMode],a
 	ld [$0000],a
 	ret
 
@@ -653,23 +653,23 @@ LoadHallOfFameTeams: ; 73b3f (1c:7b3f)
 	; fallthrough
 
 HallOfFame_Copy: ; 73b51 (1c:7b51)
-	ld a, $a
-	ld [$0], a
+	ld a, SRAM_ENABLE
+	ld [MBC1SRamEnable], a
 	ld a, $1
-	ld [$6000], a
+	ld [MBC1SRamBankingMode], a
 	xor a
-	ld [$4000], a
+	ld [MBC1SRamBank], a
 	call CopyData
 	xor a
-	ld [$6000], a
-	ld [$0], a
+	ld [MBC1SRamBankingMode], a
+	ld [MBC1SRamEnable], a
 	ret
 
 Func_73b6a: ; 73b6a (1c:7b6a)
-	ld a, $a
-	ld [$0], a
+	ld a, SRAM_ENABLE
+	ld [MBC1SRamEnable], a
 	ld a, $1
-	ld [$6000], a
+	ld [MBC1SRamBankingMode], a
 	xor a
 	call PadSRAM_FF
 	ld a, $1
@@ -679,12 +679,12 @@ Func_73b6a: ; 73b6a (1c:7b6a)
 	ld a, $3
 	call PadSRAM_FF
 	xor a
-	ld [$6000], a
-	ld [$0], a
+	ld [MBC1SRamBankingMode], a
+	ld [MBC1SRamEnable], a
 	ret
 
 PadSRAM_FF: ; 73b8f (1c:7b8f)
-	ld [$4000], a
+	ld [MBC1SRamBank], a
 	ld hl, $a000
 	ld bc, $2000
 	ld a, $ff

engine/slot_machine.asm

@@ -1,7 +1,7 @@
 PromptUserToPlaySlots: ; 3730e (d:730e)
 	call SaveScreenTilesToBuffer2
 	ld a, BANK(DisplayTextIDInit)
-	ld [wcf0c], a
+	ld [wAutoTextBoxDrawingControl], a
 	ld b, a
 	ld hl, DisplayTextIDInit
 	call Bankswitch
@@ -12,7 +12,7 @@ PromptUserToPlaySlots: ; 3730e (d:730e)
 	and a
 	jr nz, .skip
 	dec a
-	ld [wcfcb], a
+	ld [wUpdateSpritesEnabled], a
 	ld hl, wcd4f
 	xor a
 	ld [hli], a
@@ -40,9 +40,9 @@ PromptUserToPlaySlots: ; 3730e (d:730e)
 	ld [W_SUBANIMSUBENTRYADDR], a
 	call GBPalWhiteOutWithDelay3
 	ld a, $1
-	ld [wcfcb], a
+	ld [wUpdateSpritesEnabled], a
 	call GoPAL_SET_CF1C
-	call Func_3e08
+	call ReloadMapSpriteTilePatterns
 	call ReloadTilesetTilePatterns
 .skip
 	call LoadScreenTilesFromBuffer2
@@ -221,7 +221,7 @@ SlotMachine_374ad: ; 374ad (d:74ad)
 	call SlotMachine_374fb
 	call SlotMachine_37517
 	ret c
-	ld a, [wcf1b]
+	ld a, [wOnSGB]
 	xor $1
 	inc a
 	ld c, a

engine/titlescreen.asm

@@ -11,7 +11,7 @@ SetDefaultNamesBeforeTitlescreen: ; 42b7 (1:42b7)
 	ld de, W_RIVALNAME ; wd34a
 	call CopyFixedLengthText
 	xor a
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	ld [wd358], a
 	ld hl, wd732
 	ld [hli], a
@@ -26,12 +26,12 @@ LoadTitlescreenGraphics: ; 42dd (1:42dd)
 	ld a, $1
 	ld [H_AUTOBGTRANSFERENABLED], a ; $ffba
 	xor a
-	ld [$ffd7], a
+	ld [hTilesetType], a
 	ld [$ffae], a
 	ld a, $40
 	ld [$ffaf], a
 	ld a, $90
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	call ClearScreen
 	call DisableLCD
 	call LoadFontTilePatterns
@@ -127,7 +127,7 @@ ENDC
 	call Func_4533
 	call SaveScreenTilesToBuffer1
 	ld a, $40
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	call LoadScreenTilesFromBuffer2
 	ld a, $98
 	call Func_4533
@@ -182,7 +182,7 @@ ENDC
 	call PlaySound
 	call PrintGameVersionOnTitleScreen
 	ld a, $90
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	ld d, $90
 .asm_440a
 	ld h, d
@@ -225,7 +225,7 @@ ENDC
 	call GBPalWhiteOutWithDelay3
 	call ClearSprites
 	xor a
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	inc a
 	ld [H_AUTOBGTRANSFERENABLED], a ; $ffba
 	call ClearScreen
@@ -270,7 +270,7 @@ Func_4496: ; 4496 (1:4496)
 	call Func_4524
 
 	ld a, $90
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	ld d, 1 ; scroll out
 	callba TitleScroll
 	ret
@@ -279,7 +279,7 @@ Func_44c1: ; 44c1 (1:44c1)
 	ld d, 0 ; scroll in
 	callba TitleScroll
 	xor a
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	ret
 
 Func_44cf: ; 44cf (1:44cf)
@@ -353,7 +353,7 @@ Func_4533: ; 4533 (1:4533)
 
 LoadCopyrightAndTextBoxTiles: ; 4538 (1:4538)
 	xor a
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	call ClearScreen
 	call LoadTextBoxTilePatterns
 

engine/town_map.asm

@@ -1,6 +1,6 @@
 DisplayTownMap: ; 70e3e (1c:4e3e)
 	call LoadTownMap
-	ld hl, wcfcb
+	ld hl, wUpdateSpritesEnabled
 	ld a, [hl]
 	push af
 	ld [hl], $ff
@@ -64,7 +64,7 @@ Func_70e92: ; 70e92 (1c:4e92)
 	ld bc, $10
 	call CopyData
 .asm_70ec8
-	call Func_716c6
+	call TownMapSpriteBlinkingAnimation
 	call JoypadLowSensitivity
 	ld a, [hJoy5]
 	ld b, a
@@ -77,9 +77,9 @@ Func_70e92: ; 70e92 (1c:4e92)
 	bit 7, b
 	jr nz, .asm_70f01
 	xor a
-	ld [wd09b], a
+	ld [wTownMapSpriteBlinkingEnabled], a
 	ld [hJoy7], a
-	ld [W_SUBANIMTRANSFORM], a ; W_SUBANIMTRANSFORM
+	ld [wTownMapSpriteBlinkingCounter], a
 	call Func_711ab
 	pop hl
 	pop af
@@ -111,7 +111,7 @@ TownMapCursor: ; 70f40 (1c:4f40)
 
 LoadTownMap_Nest: ; 70f60 (1c:4f60)
 	call LoadTownMap
-	ld hl, wcfcb
+	ld hl, wUpdateSpritesEnabled
 	ld a, [hl]
 	push af
 	ld [hl], $ff
@@ -148,7 +148,7 @@ LoadTownMap_Fly: ; 70f90 (1c:4f90)
 	ld bc, (BANK(TownMapUpArrow) << 8) + $01
 	call CopyVideoDataDouble
 	call Func_71070
-	ld hl, wcfcb
+	ld hl, wUpdateSpritesEnabled
 	ld a, [hl]
 	push af
 	ld [hl], $ff
@@ -206,14 +206,14 @@ LoadTownMap_Fly: ; 70f90 (1c:4f90)
 	ld a, (SFX_02_3e - SFX_Headers_02) / 3
 	call PlaySound
 	ld a, [hl]
-	ld [wd71a], a
+	ld [wDestinationMap], a
 	ld hl, wd732
 	set 3, [hl]
 	inc hl
 	set 7, [hl]
 .asm_71037
 	xor a
-	ld [wd09b], a
+	ld [wTownMapSpriteBlinkingEnabled], a
 	call GBPalWhiteOutWithDelay3
 	pop hl
 	pop af
@@ -319,9 +319,9 @@ LoadTownMap: ; 7109b (1c:509b)
 	call Delay3
 	call GBPalNormal
 	xor a
-	ld [W_SUBANIMTRANSFORM], a ; W_SUBANIMTRANSFORM
+	ld [wTownMapSpriteBlinkingCounter], a
 	inc a
-	ld [wd09b], a
+	ld [wTownMapSpriteBlinkingEnabled], a
 	ret
 
 CompressedMap: ; 71100 (1c:5100)
@@ -330,7 +330,7 @@ CompressedMap: ; 71100 (1c:5100)
 
 Func_711ab: ; 711ab (1c:51ab)
 	xor a
-	ld [wd09b], a
+	ld [wTownMapSpriteBlinkingEnabled], a
 	call GBPalWhiteOut
 	call ClearScreen
 	call ClearSprites
@@ -570,29 +570,30 @@ INCLUDE "text/map_names.asm"
 MonNestIcon: ; 716be (1c:56be)
 	INCBIN "gfx/mon_nest_icon.1bpp"
 
-Func_716c6: ; 716c6 (1c:56c6)
-	ld a, [W_SUBANIMTRANSFORM] ; W_SUBANIMTRANSFORM
+TownMapSpriteBlinkingAnimation: ; 716c6 (1c:56c6)
+	ld a, [wTownMapSpriteBlinkingCounter]
 	inc a
-	cp $19
-	jr z, .asm_716e1
-	cp $32
-	jr nz, .asm_716f1
+	cp 25
+	jr z, .hideSprites
+	cp 50
+	jr nz, .done
+; show sprites when the counter reaches 50
 	ld hl, wTileMapBackup
 	ld de, wOAMBuffer
 	ld bc, $90
 	call CopyData
 	xor a
-	jr .asm_716f1
-.asm_716e1
+	jr .done
+.hideSprites
 	ld hl, wOAMBuffer
 	ld b, $24
 	ld de, $4
-.asm_716e9
+.hideSpritesLoop
 	ld [hl], $a0
 	add hl, de
 	dec b
-	jr nz, .asm_716e9
-	ld a, $19
-.asm_716f1
-	ld [W_SUBANIMTRANSFORM], a ; W_SUBANIMTRANSFORM
+	jr nz, .hideSpritesLoop
+	ld a, 25
+.done
+	ld [wTownMapSpriteBlinkingCounter], a
 	jp DelayFrame

engine/town_map.asm.orig

@@ -0,0 +1,605 @@
+DisplayTownMap: ; 70e3e (1c:4e3e)
+	call LoadTownMap
+	ld hl, wUpdateSpritesEnabled
+	ld a, [hl]
+	push af
+	ld [hl], $ff
+	push hl
+	ld a, $1
+	ld [hJoy7], a
+	ld a, [W_CURMAP] ; W_CURMAP
+	push af
+	ld b, $0
+	call Func_711c4
+	hlCoord 1, 0
+	ld de, wcd6d
+	call PlaceString
+	ld hl, wOAMBuffer
+	ld de, wTileMapBackup
+	ld bc, $10
+	call CopyData
+	ld hl, vSprites + $40
+	ld de, TownMapCursor ; $4f40
+	ld bc, (BANK(TownMapCursor) << 8) + $04
+	call CopyVideoDataDouble
+	xor a
+	ld [wWhichTrade], a ; wWhichTrade
+	pop af
+	jr Func_70e92
+
+Func_70e7e: ; 70e7e (1c:4e7e)
+	ld hl, wTileMap
+	ld bc, $114
+	call ClearScreenArea
+	ld hl, TownMapOrder ; $4f11
+	ld a, [wWhichTrade] ; wWhichTrade
+	ld c, a
+	ld b, $0
+	add hl, bc
+	ld a, [hl]
+
+Func_70e92: ; 70e92 (1c:4e92)
+	ld de, wHPBarMaxHP
+	call Func_712f1
+	ld a, [de]
+	push hl
+	call Func_71258
+	ld a, $4
+	ld [wcd5b], a
+	ld hl, wOAMBuffer + $10
+	call Func_71279
+	pop hl
+	ld de, wcd6d
+.asm_70eac
+	ld a, [hli]
+	ld [de], a
+	inc de
+	cp $50
+	jr nz, .asm_70eac
+	hlCoord 1, 0
+	ld de, wcd6d
+	call PlaceString
+	ld hl, wOAMBuffer + $10
+	ld de, wTileMapBackup + 16
+	ld bc, $10
+	call CopyData
+.asm_70ec8
+	call TownMapSpriteBlinkingAnimation
+	call JoypadLowSensitivity
+	ld a, [hJoy5]
+	ld b, a
+	and $c3
+	jr z, .asm_70ec8
+	ld a, (SFX_02_3c - SFX_Headers_02) / 3
+	call PlaySound
+	bit 6, b
+	jr nz, .asm_70ef2
+	bit 7, b
+	jr nz, .asm_70f01
+	xor a
+<<<<<<< HEAD
+	ld [wd09b], a
+	ld [hJoy7], a
+	ld [W_SUBANIMTRANSFORM], a ; W_SUBANIMTRANSFORM
+=======
+	ld [wTownMapSpriteBlinkingEnabled], a
+	ld [$ffb7], a
+	ld [wTownMapSpriteBlinkingCounter], a
+>>>>>>> yama/master
+	call Func_711ab
+	pop hl
+	pop af
+	ld [hl], a
+	ret
+.asm_70ef2
+	ld a, [wWhichTrade] ; wWhichTrade
+	inc a
+	cp $2f
+	jr nz, .asm_70efb
+	xor a
+.asm_70efb
+	ld [wWhichTrade], a ; wWhichTrade
+	jp Func_70e7e
+.asm_70f01
+	ld a, [wWhichTrade] ; wWhichTrade
+	dec a
+	cp $ff
+	jr nz, .asm_70f0b
+	ld a, $2e
+.asm_70f0b
+	ld [wWhichTrade], a ; wWhichTrade
+	jp Func_70e7e
+
+INCLUDE "data/town_map_order.asm"
+
+TownMapCursor: ; 70f40 (1c:4f40)
+	INCBIN "gfx/town_map_cursor.1bpp"
+
+LoadTownMap_Nest: ; 70f60 (1c:4f60)
+	call LoadTownMap
+	ld hl, wUpdateSpritesEnabled
+	ld a, [hl]
+	push af
+	ld [hl], $ff
+	push hl
+	call Func_711ef
+	call GetMonName
+	hlCoord 1, 0
+	call PlaceString
+	ld h, b
+	ld l, c
+	ld de, MonsNestText
+	call PlaceString
+	call WaitForTextScrollButtonPress
+	call Func_711ab
+	pop hl
+	pop af
+	ld [hl], a
+	ret
+
+MonsNestText: ; 70f89 (1c:4f89)
+	db "'s NEST@"
+
+LoadTownMap_Fly: ; 70f90 (1c:4f90)
+	call ClearSprites
+	call LoadTownMap
+	call LoadPlayerSpriteGraphics
+	call LoadFontTilePatterns
+	ld de, BirdSprite ; $4d80
+	ld hl, vSprites + $40
+	ld bc, (BANK(BirdSprite) << 8) + $0c
+	call CopyVideoData
+	ld de, TownMapUpArrow ; $5093
+	ld hl, vChars1 + $6d0
+	ld bc, (BANK(TownMapUpArrow) << 8) + $01
+	call CopyVideoDataDouble
+	call Func_71070
+	ld hl, wUpdateSpritesEnabled
+	ld a, [hl]
+	push af
+	ld [hl], $ff
+	push hl
+	ld hl, wTileMap
+	ld de, ToText
+	call PlaceString
+	ld a, [W_CURMAP] ; W_CURMAP
+	ld b, $0
+	call Func_711c4
+	ld hl, wTrainerEngageDistance
+	deCoord 18, 0
+
+.townMapFlyLoop
+	ld a, $7f
+	ld [de], a
+	push hl
+	push hl
+	hlCoord 3, 0
+	ld bc, $10f
+	call ClearScreenArea
+	pop hl
+	ld a, [hl]
+	ld b, $4
+	call Func_711c4
+	hlCoord 3, 0
+	ld de, wcd6d
+	call PlaceString
+	ld c, $f
+	call DelayFrames
+	hlCoord 18, 0
+	ld [hl], $ed
+	hlCoord 19, 0
+	ld [hl], $ee
+	pop hl
+.asm_71004
+	push hl
+	call DelayFrame
+	call JoypadLowSensitivity
+	ld a, [hJoy5]
+	ld b, a
+	pop hl
+	and $c3
+	jr z, .asm_71004
+	bit 0, b
+	jr nz, .asm_71026
+	ld a, (SFX_02_3c - SFX_Headers_02) / 3
+	call PlaySound
+	bit 6, b
+	jr nz, .asm_71042
+	bit 7, b
+	jr nz, .asm_71058
+	jr .asm_71037
+.asm_71026
+	ld a, (SFX_02_3e - SFX_Headers_02) / 3
+	call PlaySound
+	ld a, [hl]
+	ld [wDestinationMap], a
+	ld hl, wd732
+	set 3, [hl]
+	inc hl
+	set 7, [hl]
+.asm_71037
+	xor a
+	ld [wTownMapSpriteBlinkingEnabled], a
+	call GBPalWhiteOutWithDelay3
+	pop hl
+	pop af
+	ld [hl], a
+	ret
+.asm_71042
+	deCoord 18, 0
+	inc hl
+	ld a, [hl]
+	cp $ff
+	jr z, .asm_71052
+	cp $fe
+	jr z, .asm_71042
+	jp .townMapFlyLoop
+.asm_71052
+	ld hl, wTrainerEngageDistance
+	jp .townMapFlyLoop
+.asm_71058
+	deCoord 19, 0
+	dec hl
+	ld a, [hl]
+	cp $ff
+	jr z, .asm_71068
+	cp $fe
+	jr z, .asm_71058
+	jp .townMapFlyLoop
+.asm_71068
+	ld hl, wcd49
+	jr .asm_71058
+
+ToText: ; 7106d (1c:506d)
+	db "To@"
+
+Func_71070: ; 71070 (1c:5070)
+	ld hl, wWhichTrade ; wWhichTrade
+	ld [hl], $ff
+	inc hl
+	ld a, [W_TOWNVISITEDFLAG]
+	ld e, a
+	ld a, [W_TOWNVISITEDFLAG + 1]
+	ld d, a
+	ld bc, $b
+.asm_71081
+	srl d
+	rr e
+	ld a, $fe
+	jr nc, .asm_7108a
+	ld a, b
+.asm_7108a
+	ld [hl], a
+	inc hl
+	inc b
+	dec c
+	jr nz, .asm_71081
+	ld [hl], $ff
+	ret
+
+TownMapUpArrow: ; 71093 (1c:5093)
+	INCBIN "gfx/up_arrow.1bpp"
+
+LoadTownMap: ; 7109b (1c:509b)
+	call GBPalWhiteOutWithDelay3
+	call ClearScreen
+	call UpdateSprites
+	ld hl, wTileMap
+	ld b, $12
+	ld c, $12
+	call TextBoxBorder
+	call DisableLCD
+	ld hl, WorldMapTileGraphics ; $65a8
+	ld de, vChars2 + $600
+	ld bc, $100
+	ld a, BANK(WorldMapTileGraphics)
+	call FarCopyData2
+	ld hl, MonNestIcon ; $56be
+	ld de, vSprites + $40
+	ld bc, $8
+	ld a, BANK(MonNestIcon)
+	call FarCopyDataDouble
+	ld hl, wTileMap
+	ld de, CompressedMap ; $5100
+.asm_710d3
+	ld a, [de]
+	and a
+	jr z, .asm_710e9
+	ld b, a
+	and $f
+	ld c, a
+	ld a, b
+	swap a
+	and $f
+	add $60
+.asm_710e2
+	ld [hli], a
+	dec c
+	jr nz, .asm_710e2
+	inc de
+	jr .asm_710d3
+.asm_710e9
+	call EnableLCD
+	ld b, $2
+	call GoPAL_SET
+	call Delay3
+	call GBPalNormal
+	xor a
+	ld [wTownMapSpriteBlinkingCounter], a
+	inc a
+	ld [wTownMapSpriteBlinkingEnabled], a
+	ret
+
+CompressedMap: ; 71100 (1c:5100)
+; you can decompress this file with the redrle program in the extras/ dir
+	INCBIN "gfx/town_map.rle"
+
+Func_711ab: ; 711ab (1c:51ab)
+	xor a
+	ld [wTownMapSpriteBlinkingEnabled], a
+	call GBPalWhiteOut
+	call ClearScreen
+	call ClearSprites
+	call LoadPlayerSpriteGraphics
+	call LoadFontTilePatterns
+	call UpdateSprites
+	jp GoPAL_SET_CF1C
+
+Func_711c4: ; 711c4 (1c:51c4)
+	push af
+	ld a, b
+	ld [wcd5b], a
+	pop af
+	ld de, wHPBarMaxHP
+	call Func_712f1
+	ld a, [de]
+	push hl
+	call Func_71258
+	call Func_7126d
+	pop hl
+	ld de, wcd6d
+.asm_711dc
+	ld a, [hli]
+	ld [de], a
+	inc de
+	cp $50
+	jr nz, .asm_711dc
+	ld hl, wOAMBuffer
+	ld de, wTileMapBackup
+	ld bc, $a0
+	jp CopyData
+
+Func_711ef: ; 711ef (1c:51ef)
+	callba Func_e9cb
+	call Func_712d9
+	ld hl, wOAMBuffer
+	ld de, wHPBarMaxHP
+.asm_71200
+	ld a, [de]
+	cp $ff
+	jr z, .asm_7121d
+	and a
+	jr z, .asm_7121a
+	push hl
+	call Func_712f1
+	pop hl
+	ld a, [de]
+	cp $19
+	jr z, .asm_7121a
+	call Func_71258
+	ld a, $4
+	ld [hli], a
+	xor a
+	ld [hli], a
+.asm_7121a
+	inc de
+	jr .asm_71200
+.asm_7121d
+	ld a, l
+	and a
+	jr nz, .asm_71236
+	hlCoord 1, 7
+	ld b, $2
+	ld c, $f
+	call TextBoxBorder
+	hlCoord 2, 9
+	ld de, AreaUnknownText
+	call PlaceString
+	jr .asm_7123e
+.asm_71236
+	ld a, [W_CURMAP] ; W_CURMAP
+	ld b, $0
+	call Func_711c4
+.asm_7123e
+	ld hl, wOAMBuffer
+	ld de, wTileMapBackup
+	ld bc, $a0
+	jp CopyData
+
+AreaUnknownText: ; 7124a (1c:524a)
+	db " AREA UNKNOWN@"
+
+Func_71258: ; 71258 (1c:5258)
+	push af
+	and $f0
+	srl a
+	add $18
+	ld b, a
+	ld [hli], a
+	pop af
+	and $f
+	swap a
+	srl a
+	add $18
+	ld c, a
+	ld [hli], a
+	ret
+
+Func_7126d: ; 7126d (1c:526d)
+	ld a, [wcd5b]
+	and a
+	ld hl, wOAMBuffer + $90
+	jr z, Func_71279
+	ld hl, wOAMBuffer + $80
+
+Func_71279: ; 71279 (1c:5279)
+	push hl
+	ld hl, $fcfc
+	add hl, bc
+	ld b, h
+	ld c, l
+	pop hl
+
+Func_71281: ; 71281 (1c:5281)
+	ld de, $202
+.asm_71284
+	push de
+	push bc
+.asm_71286
+	ld a, b
+	ld [hli], a
+	ld a, c
+	ld [hli], a
+	ld a, [wcd5b]
+	ld [hli], a
+	inc a
+	ld [wcd5b], a
+	xor a
+	ld [hli], a
+	inc d
+	ld a, $8
+	add c
+	ld c, a
+	dec e
+	jr nz, .asm_71286
+	pop bc
+	pop de
+	ld a, $8
+	add b
+	ld b, a
+	dec d
+	jr nz, .asm_71284
+	ret
+
+Func_712a6: ; 712a6 (1c:52a6)
+	xor a
+	ld [wcd5c], a
+	ld de, $202
+.asm_712ad
+	push de
+	push bc
+.asm_712af
+	ld a, b
+	ld [hli], a
+	ld a, c
+	ld [hli], a
+	ld a, [wcd5b]
+	ld [hli], a
+	ld a, [wcd5c]
+	ld [hli], a
+	xor $20
+	ld [wcd5c], a
+	inc d
+	ld a, $8
+	add c
+	ld c, a
+	dec e
+	jr nz, .asm_712af
+	pop bc
+	pop de
+	push hl
+	ld hl, wcd5b
+	inc [hl]
+	inc [hl]
+	pop hl
+	ld a, $8
+	add b
+	ld b, a
+	dec d
+	jr nz, .asm_712ad
+	ret
+
+Func_712d9: ; 712d9 (1c:52d9)
+	ld de, wHPBarMaxHP
+.asm_712dc
+	ld a, [de]
+	inc de
+	cp $ff
+	ret z
+	ld c, a
+	ld l, e
+	ld h, d
+.asm_712e4
+	ld a, [hl]
+	cp $ff
+	jr z, .asm_712dc
+	cp c
+	jr nz, .asm_712ee
+	xor a
+	ld [hl], a
+.asm_712ee
+	inc hl
+	jr .asm_712e4
+
+Func_712f1: ; 712f1 (1c:52f1)
+	cp REDS_HOUSE_1F
+	jr c, .asm_71304
+	ld bc, $4
+	ld hl, InternalMapEntries ; $5382
+.asm_712fb
+	cp [hl]
+	jr c, .asm_71301
+	add hl, bc
+	jr .asm_712fb
+.asm_71301
+	inc hl
+	jr .asm_7130d
+.asm_71304
+	ld hl, ExternalMapEntries ; $5313
+	ld c, a
+	ld b, $0
+	add hl, bc
+	add hl, bc
+	add hl, bc
+.asm_7130d
+	ld a, [hli]
+	ld [de], a
+	ld a, [hli]
+	ld h, [hl]
+	ld l, a
+	ret
+
+INCLUDE "data/town_map_entries.asm"
+
+INCLUDE "text/map_names.asm"
+
+MonNestIcon: ; 716be (1c:56be)
+	INCBIN "gfx/mon_nest_icon.1bpp"
+
+TownMapSpriteBlinkingAnimation: ; 716c6 (1c:56c6)
+	ld a, [wTownMapSpriteBlinkingCounter]
+	inc a
+	cp 25
+	jr z, .hideSprites
+	cp 50
+	jr nz, .done
+; show sprites when the counter reaches 50
+	ld hl, wTileMapBackup
+	ld de, wOAMBuffer
+	ld bc, $90
+	call CopyData
+	xor a
+	jr .done
+.hideSprites
+	ld hl, wOAMBuffer
+	ld b, $24
+	ld de, $4
+.hideSpritesLoop
+	ld [hl], $a0
+	add hl, de
+	dec b
+	jr nz, .hideSpritesLoop
+	ld a, 25
+.done
+	ld [wTownMapSpriteBlinkingCounter], a
+	jp DelayFrame

engine/trade.asm

@@ -119,10 +119,10 @@ LoadTradingGFXAndMonNames: ; 411a1 (10:51a1)
 	call FillMemory
 	call ClearSprites
 	ld a, $ff
-	ld [wcfcb], a
+	ld [wUpdateSpritesEnabled], a
 	ld hl, wd730
 	set 6, [hl]
-	ld a, [wcf1b]
+	ld a, [wOnSGB]
 	and a
 	ld a, $e4
 	jr z, .asm_411e5
@@ -175,7 +175,7 @@ Func_41245: ; 41245 (10:5245)
 	ld a, $ab
 	ld [rLCDC], a ; $ff40
 	ld a, $50
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	ld a, $86
 	ld [rWX], a ; $ff4b
 	ld [$ffae], a
@@ -397,7 +397,7 @@ Func_41411: ; 41411 (10:5411)
 	xor a
 	ld [$ffae], a
 	ld a, $90
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	ret
 
 Func_4142d: ; 4142d (10:542d)
@@ -475,7 +475,7 @@ Func_4149f: ; 4149f (10:549f)
 Func_414ae: ; 414ae (10:54ae)
 	push hl
 	hlCoord 0, 4
-	call ScheduleRowRedrawHelper
+	call CopyToScreenEdgeTiles
 	pop hl
 	ld a, h
 	ld [H_SCREENEDGEREDRAWADDR + 1], a
@@ -655,7 +655,7 @@ Func_415c8: ; 415c8 (10:55c8)
 	ld a, $7
 	ld [rWX], a ; $ff4b
 	xor a
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	ld a, $90
 	ld [$ffae], a
 	ret

engine/turn_sprite.asm

@@ -1,25 +1,25 @@
-Func_13074: ; 13074 (4:7074)
+UpdateSpriteFacingOffsetAndDelayMovement: ; 13074 (4:7074)
 	ld h, $c2
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $8
 	ld l, a
-	ld a, $7f
-	ld [hl], a
+	ld a, $7f ; maximum movement delay
+	ld [hl], a ; c2x8 (movement delay)
 	dec h
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $9
 	ld l, a
-	ld a, [hld]
+	ld a, [hld] ; c1x9 (facing direction)
 	ld b, a
 	xor a
 	ld [hld], a
-	ld [hl], a
+	ld [hl], a ; c1x8 (walk animation frame)
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $2
 	ld l, a
-	ld a, [hl]
-	or b
+	ld a, [hl] ; c1x2 (facing and animation table offset)
+	or b ; or in the facing direction
 	ld [hld], a
-	ld a, $2
-	ld [hl], a
+	ld a, $2 ; delayed movement status
+	ld [hl], a ; c1x1 (movement status)
 	ret

home.asm

@@ -162,7 +162,7 @@ LoadDestinationWarpPosition:: ; 1313 (0:1313)
 	ld b,0
 	add hl,bc
 	ld bc,4
-	ld de,wd35f
+	ld de,wCurrentTileBlockMapViewPointer
 	call CopyData
 	pop af
 	ld [H_LOADEDROMBANK],a
@@ -257,8 +257,9 @@ LoadMonData:: ; 1372 (0:1372)
 	ld b, BANK(LoadMonData_)
 	jp Bankswitch
 
-; writes c to wd0dc+b
+
 Func_137a:: ; 137a (0:137a)
+; Write c to [wd0dc + b]. Unused.
 	ld hl, wd0dc
 	ld e, b
 	ld d, 0
@@ -350,10 +351,10 @@ GetCryData:: ; 13d9 (0:13d9)
 
 
 DisplayPartyMenu:: ; 13fc (0:13fc)
-	ld a,[$ffd7]
+	ld a,[hTilesetType]
 	push af
 	xor a
-	ld [$ffd7],a
+	ld [hTilesetType],a
 	call GBPalWhiteOutWithDelay3
 	call ClearSprites
 	call PartyMenuInit
@@ -361,10 +362,10 @@ DisplayPartyMenu:: ; 13fc (0:13fc)
 	jp HandlePartyMenuInput
 
 GoBackToPartyMenu:: ; 1411 (0:1411)
-	ld a,[$ffd7]
+	ld a,[hTilesetType]
 	push af
 	xor a
-	ld [$ffd7],a
+	ld [hTilesetType],a
 	call PartyMenuInit
 	call RedrawPartyMenu
 	jp HandlePartyMenuInput
@@ -422,11 +423,11 @@ HandlePartyMenuInput:: ; 145a (0:145a)
 	ld [wcc2b],a
 	ld hl,wd730
 	res 6,[hl] ; turn on letter printing delay
-	ld a,[wcc35]
+	ld a,[wMenuItemToSwap]
 	and a
 	jp nz,.swappingPokemon
 	pop af
-	ld [$ffd7],a
+	ld [hTilesetType],a
 	bit 1,b
 	jr nz,.noPokemonChosen
 	ld a,[wPartyCount]
@@ -454,7 +455,7 @@ HandlePartyMenuInput:: ; 145a (0:145a)
 .cancelSwap ; if the B button was pressed
 	callba ErasePartyMenuCursors
 	xor a
-	ld [wcc35],a
+	ld [wMenuItemToSwap],a
 	ld [wd07d],a
 	call RedrawPartyMenu
 	jr HandlePartyMenuInput
@@ -544,6 +545,7 @@ PrintLevelCommon:: ; 1523 (0:1523)
 	jp PrintNumber
 
 Func_152e:: ; 152e (0:152e)
+; Unused.
 	ld hl,wd0dc
 	ld c,a
 	ld b,0
@@ -925,7 +927,7 @@ INCLUDE "home/audio.asm"
 
 
 UpdateSprites:: ; 2429 (0:2429)
-	ld a, [wcfcb]
+	ld a, [wUpdateSpritesEnabled]
 	dec a
 	ret nz
 	ld a, [H_LOADEDROMBANK]
@@ -1068,18 +1070,18 @@ DisplayTextID:: ; 2920 (0:2920)
 	ld l,a ; hl = map text pointer
 	ld d,$00
 	ld a,[$ff8c] ; text ID
-	ld [wcf13],a
+	ld [wSpriteIndex],a
 	and a
 	jp z,DisplayStartMenu
-	cp a,$d3 ; safari game over
+	cp a,$d3
 	jp z,DisplaySafariGameOverText
-	cp a,$d0 ; fainted
+	cp a,$d0
 	jp z,DisplayPokemonFaintedText
-	cp a,$d1 ; blacked out
+	cp a,$d1
 	jp z,DisplayPlayerBlackedOutText
-	cp a,$d2 ; repel wore off
+	cp a,$d2
 	jp z,DisplayRepelWoreOffText
-	ld a,[W_NUMSPRITES] ; number of sprites
+	ld a,[W_NUMSPRITES]
 	ld e,a
 	ld a,[$ff8c] ; sprite ID
 	cp e
@@ -1090,7 +1092,7 @@ DisplayTextID:: ; 2920 (0:2920)
 	push hl
 	push de
 	push bc
-	callba Func_13074 ; update the graphics of the sprite the player is talking to (to face the right direction)
+	callba UpdateSpriteFacingOffsetAndDelayMovement ; update the graphics of the sprite the player is talking to (to face the right direction)
 	pop bc
 	pop de
 	ld hl,W_MAPSPRITEDATA ; NPC text entries
@@ -1139,7 +1141,7 @@ DisplayTextID:: ; 2920 (0:2920)
 	jr AfterDisplayingTextID
 .notSpecialCase
 	call Func_3c59 ; display the text
-	ld a,[wcc3c]
+	ld a,[wDoNotWaitForButtonPressAfterDisplayingText]
 	and a
 	jr nz,HoldTextDisplayOpen
 
@@ -1160,7 +1162,7 @@ CloseTextDisplay:: ; 29e8 (0:29e8)
 	ld a,[W_CURMAP]
 	call SwitchToMapRomBank
 	ld a,$90
-	ld [$ffb0],a ; move the window off the screen
+	ld [hVBlankWY],a ; move the window off the screen
 	call DelayFrame
 	call LoadGBPal
 	xor a
@@ -1184,13 +1186,13 @@ CloseTextDisplay:: ; 29e8 (0:29e8)
 	ld hl,wcfc4
 	res 0,[hl]
 	ld a,[wd732]
-	bit 3,a
+	bit 3,a ; used fly warp
 	call z,LoadPlayerSpriteGraphics
 	call LoadCurrentMapView
 	pop af
 	ld [H_LOADEDROMBANK],a
 	ld [$2000],a
-	jp UpdateSprites ; move sprites
+	jp UpdateSprites
 
 DisplayPokemartDialogue:: ; 2a2e (0:2a2e)
 	push hl
@@ -1218,7 +1220,7 @@ PokemartGreetingText:: ; 2a55 (0:2a55)
 
 LoadItemList:: ; 2a5a (0:2a5a)
 	ld a,$01
-	ld [wcfcb],a
+	ld [wUpdateSpritesEnabled],a
 	ld a,h
 	ld [wd128],a
 	ld a,l
@@ -1266,7 +1268,7 @@ DisplayPlayerBlackedOutText:: ; 2aa9 (0:2aa9)
 	ld hl,PlayerBlackedOutText
 	call PrintText
 	ld a,[wd732]
-	res 5,a
+	res 5,a ; reset forced to use bike bit
 	ld [wd732],a
 	jp HoldTextDisplayOpen
 
@@ -1382,13 +1384,13 @@ DisplayListMenuID:: ; 2be6 (0:2be6)
 	ld a,$01 ; hardcoded bank
 	jr .bankswitch
 .specialBattleType ; Old Man battle
-	ld a, Bank(OldManItemList)
+	ld a, Bank(DisplayBattleMenu)
 .bankswitch
 	call BankswitchHome
 	ld hl,wd730
 	set 6,[hl] ; turn off letter printing delay
 	xor a
-	ld [wcc35],a ; 0 means no item is currently being swapped
+	ld [wMenuItemToSwap],a ; 0 means no item is currently being swapped
 	ld [wd12a],a
 	ld a,[wcf8b]
 	ld l,a
@@ -1399,7 +1401,8 @@ DisplayListMenuID:: ; 2be6 (0:2be6)
 	ld a,$0d ; list menu text box ID
 	ld [wd125],a
 	call DisplayTextBoxID ; draw the menu text box
-	call UpdateSprites ; move sprites
+	call UpdateSprites ; disable sprites behind the text box
+; the code up to .skipMovingSprites appears to be useless
 	hlCoord 4, 2 ; coordinates of upper left corner of menu text box
 	ld de,$090e ; height and width of menu text box
 	ld a,[wListMenuID]
@@ -1669,11 +1672,11 @@ DisplayChooseQuantityMenu:: ; 2d57 (0:2d57)
 	jp .waitForKeyPressLoop
 .buttonAPressed ; the player chose to make the transaction
 	xor a
-	ld [wcc35],a ; 0 means no item is currently being swapped
+	ld [wMenuItemToSwap],a ; 0 means no item is currently being swapped
 	ret
 .buttonBPressed ; the player chose to cancel the transaction
 	xor a
-	ld [wcc35],a ; 0 means no item is currently being swapped
+	ld [wMenuItemToSwap],a ; 0 means no item is currently being swapped
 	ld a,$ff
 	ret
 
@@ -1695,7 +1698,7 @@ ExitListMenu:: ; 2e3b (0:2e3b)
 	res 6,[hl]
 	call BankswitchBack
 	xor a
-	ld [wcc35],a ; 0 means no item is currently being swapped
+	ld [wMenuItemToSwap],a ; 0 means no item is currently being swapped
 	scf
 	ret
 
@@ -1863,7 +1866,7 @@ PrintListMenuEntries:: ; 2e5a (0:2e5a)
 	inc c
 	push bc
 	inc c
-	ld a,[wcc35] ; ID of item chosen for swapping (counts from 1)
+	ld a,[wMenuItemToSwap] ; ID of item chosen for swapping (counts from 1)
 	and a ; is an item being swapped?
 	jr z,.nextListEntry
 	sla a
@@ -2073,10 +2076,10 @@ ChooseFlyDestination:: ; 30a9 (0:30a9)
 	ld hl, LoadTownMap_Fly
 	jp Bankswitch
 
-; causes the text box to close waithout waiting for a button press after displaying text
+; causes the text box to close without waiting for a button press after displaying text
 DisableWaitingAfterTextDisplay:: ; 30b6 (0:30b6)
 	ld a,$01
-	ld [wcc3c],a
+	ld [wDoNotWaitForButtonPressAfterDisplayingText],a
 	ret
 
 ; uses an item
@@ -2147,60 +2150,62 @@ DisplayTextBoxID:: ; 30e8 (0:30e8)
 	ld [$2000],a
 	ret
 
-Func_30fd:: ; 30fd (0:30fd)
-	ld a, [wcc57]
+; not zero if an NPC movement script is running, the player character is
+; automatically stepping down from a door, or joypad states are being simulated
+IsPlayerCharacterBeingControlledByGame:: ; 30fd (0:30fd)
+	ld a, [wNPCMovementScriptPointerTableNum]
 	and a
 	ret nz
 	ld a, [wd736]
-	bit 1, a
+	bit 1, a ; currently stepping down from door bit
 	ret nz
 	ld a, [wd730]
 	and $80
 	ret
 
-Func_310e:: ; 310e (0:310e)
+RunNPCMovementScript:: ; 310e (0:310e)
 	ld hl, wd736
 	bit 0, [hl]
 	res 0, [hl]
-	jr nz, .asm_3146
-	ld a, [wcc57]
+	jr nz, .playerStepOutFromDoor
+	ld a, [wNPCMovementScriptPointerTableNum]
 	and a
 	ret z
 	dec a
 	add a
-	ld d, $0
+	ld d, 0
 	ld e, a
-	ld hl, .pointerTable_3140
+	ld hl, .NPCMovementScriptPointerTables
 	add hl, de
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
 	ld a, [H_LOADEDROMBANK]
 	push af
-	ld a, [wcc58]
+	ld a, [wNPCMovementScriptBank]
 	ld [H_LOADEDROMBANK], a
 	ld [$2000], a
-	ld a, [wcf10]
+	ld a, [wNPCMovementScriptFunctionNum]
 	call CallFunctionInTable
 	pop af
 	ld [H_LOADEDROMBANK], a
 	ld [$2000], a
 	ret
-.pointerTable_3140
-	dw PointerTable_1a442
-	dw PointerTable_1a510
-	dw PointerTable_1a57d
-.asm_3146
-	ld b, BANK(Func_1a3e0)
-	ld hl, Func_1a3e0
+.NPCMovementScriptPointerTables
+	dw ProfOakMovementScriptPointerTable
+	dw PewterMuseumGuyMovementScriptPointerTable
+	dw PewterGymGuyMovementScriptPointerTable
+.playerStepOutFromDoor
+	ld b, BANK(PlayerStepOutFromDoor)
+	ld hl, PlayerStepOutFromDoor
 	jp Bankswitch
 
-Func_314e:: ; 314e (0:314e)
-	ld b, BANK(Func_1a41d)
-	ld hl, Func_1a41d
+EndNPCMovementScript:: ; 314e (0:314e)
+	ld b, BANK(_EndNPCMovementScript)
+	ld hl, _EndNPCMovementScript
 	jp Bankswitch
 
-Func_3156:: ; 3156 (0:3156)
+EmptyFunc2:: ; 3156 (0:3156)
 	ret
 
 ; stores hl in [W_TRAINERHEADERPTR]
@@ -2291,7 +2296,6 @@ ReadTrainerHeaderInfo:: ; 3193 (0:3193)
 TrainerFlagAction::
 	predef_jump FlagActionPredef
 
-; direct talking to a trainer (rather than getting seen by one)
 TalkToTrainer:: ; 31cc (0:31cc)
 	call StoreTrainerHeaderPointer
 	xor a
@@ -2318,25 +2322,26 @@ TalkToTrainer:: ; 31cc (0:31cc)
 	ld a, $8
 	call ReadTrainerHeaderInfo     ; read end battle text
 	pop de
-	call PreBattleSaveRegisters
+	call SaveEndBattleTextPointers
 	ld hl, W_FLAGS_D733
 	set 4, [hl]                    ; activate map script index override (index is set below)
 	ld hl, wFlags_0xcd60
-	bit 0, [hl]                    ; test if player is already being engaged by another trainer
+	bit 0, [hl]                    ; test if player is already engaging the trainer (because the trainer saw the player)
 	ret nz
+; if the player talked to the trainer of his own volition
 	call EngageMapTrainer
 	ld hl, W_CURMAPSCRIPT
-	inc [hl]      ; progress map script index (assuming it was 0 before) to start pre-battle routines
-	jp Func_325d
+	inc [hl]      ; increment map script index before StartTrainerBattle increments it again (next script function is usually EndTrainerBattle)
+	jp StartTrainerBattle
 
 ; checks if any trainers are seeing the player and wanting to fight
 CheckFightingMapTrainers:: ; 3219 (0:3219)
 	call CheckForEngagingTrainers
-	ld a, [wcf13]
+	ld a, [wSpriteIndex]
 	cp $ff
 	jr nz, .trainerEngaging
 	xor a
-	ld [wcf13], a
+	ld [wSpriteIndex], a
 	ld [wTrainerHeaderFlagBit], a
 	ret
 .trainerEngaging
@@ -2352,19 +2357,21 @@ CheckFightingMapTrainers:: ; 3219 (0:3219)
 	ldh [$b4], a
 	call TrainerWalkUpToPlayer_Bank0
 	ld hl, W_CURMAPSCRIPT
-	inc [hl]      ; progress to battle phase 1 (engaging)
+	inc [hl]      ; increment map script index (next script function is usually DisplayEnemyTrainerTextAndStartBattle)
 	ret
 
-Func_324c:: ; 324c (0:324c)
+; display the before battle text after the enemy trainer has walked up to the player's sprite
+DisplayEnemyTrainerTextAndStartBattle:: ; 324c (0:324c)
 	ld a, [wd730]
 	and $1
-	ret nz
+	ret nz ; return if the enemy trainer hasn't finished walking to the player's sprite
 	ld [wJoyIgnore], a
-	ld a, [wcf13]
-	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
+	ld a, [wSpriteIndex]
+	ld [hSpriteIndexOrTextID], a
 	call DisplayTextID
+	; fall through
 
-Func_325d:: ; 325d (0:325d)
+StartTrainerBattle:: ; 325d (0:325d)
 	xor a
 	ld [wJoyIgnore], a
 	call InitBattleEnemyParameters
@@ -2374,7 +2381,7 @@ Func_325d:: ; 325d (0:325d)
 	ld hl, wd72e
 	set 1, [hl]
 	ld hl, W_CURMAPSCRIPT
-	inc [hl]        ; progress to battle phase 2 (battling)
+	inc [hl]        ; increment map script index (next script function is usually EndTrainerBattle)
 	ret
 
 EndTrainerBattle:: ; 3275 (0:3275)
@@ -2399,7 +2406,7 @@ EndTrainerBattle:: ; 3275 (0:3275)
 	jr nc, .skipRemoveSprite    ; test if trainer was fought (in that case skip removing the corresponding sprite)
 	ld hl, W_MISSABLEOBJECTLIST
 	ld de, $2
-	ld a, [wcf13]
+	ld a, [wSpriteIndex]
 	call IsInArray              ; search for sprite ID
 	inc hl
 	ld a, [hl]
@@ -2440,22 +2447,22 @@ InitBattleEnemyParameters:: ; 32d7 (0:32d7)
 	ld [W_CURENEMYLVL], a ; W_CURENEMYLVL
 	ret
 
-Func_32ef:: ; 32ef (0:32ef)
-	ld hl, Func_567f9
+GetSpritePosition1:: ; 32ef (0:32ef)
+	ld hl, _GetSpritePosition1
 	jr asm_3301
 
-Func_32f4:: ; 32f4 (0:32f4)
-	ld hl, Func_56819
+GetSpritePosition2:: ; 32f4 (0:32f4)
+	ld hl, _GetSpritePosition2
 	jr asm_3301 ; 0x32f7 $8
 
-Func_32f9:: ; 32f9 (0:32f9)
-	ld hl, Func_5683d
+SetSpritePosition1:: ; 32f9 (0:32f9)
+	ld hl, _SetSpritePosition1
 	jr asm_3301
 
-Func_32fe:: ; 32fe (0:32fe)
-	ld hl, Func_5685d
+SetSpritePosition2:: ; 32fe (0:32fe)
+	ld hl, _SetSpritePosition2
 asm_3301:: ; 3301 (0:3301)
-	ld b, BANK(Func_567f9) ; BANK(Func_56819), BANK(Func_5683d), BANK(Func_5685d)
+	ld b, BANK(_GetSpritePosition1) ; BANK(_GetSpritePosition2), BANK(_SetSpritePosition1), BANK(_SetSpritePosition2)
 	jp Bankswitch ; indirect jump to one of the four functions
 
 CheckForEngagingTrainers:: ; 3306 (0:3306)
@@ -2466,7 +2473,7 @@ CheckForEngagingTrainers:: ; 3306 (0:3306)
 .trainerLoop
 	call StoreTrainerHeaderPointer   ; set trainer header pointer to current trainer
 	ld a, [de]
-	ld [wcf13], a                     ; store trainer flag's bit
+	ld [wSpriteIndex], a                     ; store trainer flag's bit
 	ld [wTrainerHeaderFlagBit], a
 	cp $ff
 	ret z
@@ -2488,7 +2495,7 @@ CheckForEngagingTrainers:: ; 3306 (0:3306)
 	ld a, [hl]                       ; read trainer engage distance
 	pop hl
 	ld [wTrainerEngageDistance], a
-	ld a, [wcf13]
+	ld a, [wSpriteIndex]
 	swap a
 	ld [wTrainerSpriteOffset], a ; wWhichTrade
 	predef TrainerEngage
@@ -2504,26 +2511,27 @@ CheckForEngagingTrainers:: ; 3306 (0:3306)
 	ld e, l
 	jr .trainerLoop
 
-; saves loaded rom bank and hl as well as de registers
-PreBattleSaveRegisters:: ; 3354 (0:3354)
+; hl = text if the player wins
+; de = text if the player loses
+SaveEndBattleTextPointers:: ; 3354 (0:3354)
 	ld a, [H_LOADEDROMBANK]
-	ld [W_PBSTOREDROMBANK], a
+	ld [wEndBattleTextRomBank], a
 	ld a, h
-	ld [W_PBSTOREDREGISTERH], a
+	ld [wEndBattleWinTextPointer], a
 	ld a, l
-	ld [W_PBSTOREDREGISTERL], a
+	ld [wEndBattleWinTextPointer + 1], a
 	ld a, d
-	ld [W_PBSTOREDREGISTERD], a
+	ld [wEndBattleLoseTextPointer], a
 	ld a, e
-	ld [W_PBSTOREDREGISTERE], a
+	ld [wEndBattleLoseTextPointer + 1], a
 	ret
 
 ; loads data of some trainer on the current map and plays pre-battle music
-; [wcf13]: sprite ID of trainer who is engaged
+; [wSpriteIndex]: sprite ID of trainer who is engaged
 EngageMapTrainer:: ; 336a (0:336a)
 	ld hl, W_MAPSPRITEEXTRADATA
 	ld d, $0
-	ld a, [wcf13]
+	ld a, [wSpriteIndex]
 	dec a
 	add a
 	ld e, a
@@ -2534,7 +2542,7 @@ EngageMapTrainer:: ; 336a (0:336a)
 	ld [wEnemyMonAttackMod], a ; wcd2e
 	jp PlayTrainerMusic
 
-Func_3381:: ; 3381 (0:3381)
+PrintEndBattleText:: ; 3381 (0:3381)
 	push hl
 	ld hl, wd72d
 	bit 7, [hl]
@@ -2543,45 +2551,45 @@ Func_3381:: ; 3381 (0:3381)
 	ret z
 	ld a, [H_LOADEDROMBANK]
 	push af
-	ld a, [W_PBSTOREDROMBANK]
+	ld a, [wEndBattleTextRomBank]
 	ld [H_LOADEDROMBANK], a
-	ld [$2000], a
+	ld [MBC1RomBank], a
 	push hl
 	callba SaveTrainerName
-	ld hl, TrainerNameText
+	ld hl, TrainerEndBattleText
 	call PrintText
 	pop hl
 	pop af
 	ld [H_LOADEDROMBANK], a
-	ld [$2000], a
-	callba Func_1a5e7
+	ld [MBC1RomBank], a
+	callba FreezeEnemyTrainerSprite
 	jp WaitForSoundToFinish
 
-Func_33b7:: ; 33b7 (0:33b7)
-	ld a, [wcf0b]
+GetSavedEndBattleTextPointer:: ; 33b7 (0:33b7)
+	ld a, [wBattleResult]
 	and a
-	jr nz, .asm_33c6
-	ld a, [W_PBSTOREDREGISTERH]
+; won battle
+	jr nz, .lostBattle
+	ld a, [wEndBattleWinTextPointer]
 	ld h, a
-	ld a, [W_PBSTOREDREGISTERL]
+	ld a, [wEndBattleWinTextPointer + 1]
 	ld l, a
 	ret
-.asm_33c6
-	ld a, [W_PBSTOREDREGISTERD]
+.lostBattle
+	ld a, [wEndBattleLoseTextPointer]
 	ld h, a
-	ld a, [W_PBSTOREDREGISTERE]
+	ld a, [wEndBattleLoseTextPointer + 1]
 	ld l, a
 	ret
 
-TrainerNameText:: ; 33cf (0:33cf)
+TrainerEndBattleText:: ; 33cf (0:33cf)
 	TX_FAR _TrainerNameText
 	db $08
-
-Func_33d4:: ; 33d4 (0:33d4)
-	call Func_33b7
+	call GetSavedEndBattleTextPointer
 	call TextCommandProcessor
 	jp TextScriptEnd
 
+; XXX unused?
 Func_33dd:: ; 33dd (0:33dd)
 	ld a, [wFlags_0xcd60]
 	bit 0, a
@@ -2637,29 +2645,33 @@ PlayTrainerMusic:: ; 33e8 (0:33e8)
 
 INCLUDE "data/trainer_types.asm"
 
-Func_3442:: ; 3442 (0:3442)
+; checks if the player's coordinates match an arrow movement tile's coordinates
+; and if so, decodes the RLE movement data
+; b = player Y
+; c = player X
+DecodeArrowMovementRLE:: ; 3442 (0:3442)
 	ld a, [hli]
 	cp $ff
-	ret z
+	ret z ; no match in the list
 	cp b
-	jr nz, .asm_345b
+	jr nz, .nextArrowMovementTileEntry1
 	ld a, [hli]
 	cp c
-	jr nz, .asm_345c
+	jr nz, .nextArrowMovementTileEntry2
 	ld a, [hli]
 	ld d, [hl]
 	ld e, a
-	ld hl, wccd3
+	ld hl, wSimulatedJoypadStatesEnd
 	call DecodeRLEList
 	dec a
-	ld [wcd38], a
+	ld [wSimulatedJoypadStatesIndex], a
 	ret
-.asm_345b
+.nextArrowMovementTileEntry1
 	inc hl
-.asm_345c
+.nextArrowMovementTileEntry2
 	inc hl
 	inc hl
-	jr Func_3442
+	jr DecodeArrowMovementRLE
 
 FuncTX_ItemStoragePC:: ; 3460 (0:3460)
 	call SaveScreenTilesToBuffer2
@@ -2687,10 +2699,10 @@ FuncTX_PokemonCenterPC:: ; 347f (0:347f)
 	ld hl, ActivatePC
 	jr bankswitchAndContinue
 
-Func_3486:: ; 3486 (0:3486)
+StartSimulatingJoypadStates:: ; 3486 (0:3486)
 	xor a
-	ld [wcd3b], a
-	ld [wSpriteStateData2 + $06], a
+	ld [wOverrideSimulatedJoypadStatesMask], a
+	ld [wSpriteStateData2 + $06], a ; player's sprite movement byte 1
 	ld hl, wd730
 	set 7, [hl]
 	ret
@@ -2711,21 +2723,21 @@ DisplayPokedex:: ; 349b (0:349b)
 	ld hl, Func_7c18
 	jp Bankswitch
 
-Func_34a6:: ; 34a6 (0:34a6)
-	call Func_34ae
+SetSpriteFacingDirectionAndDelay:: ; 34a6 (0:34a6)
+	call SetSpriteFacingDirection
 	ld c, $6
 	jp DelayFrames
 
-Func_34ae:: ; 34ae (0:34ae)
+SetSpriteFacingDirection:: ; 34ae (0:34ae)
 	ld a, $9
-	ld [H_DOWNARROWBLINKCNT1], a ; $ff8b
-	call Func_34fc
+	ld [H_SPRITEDATAOFFSET], a
+	call GetPointerWithinSpriteStateData1
 	ld a, [$ff8d]
 	ld [hl], a
 	ret
 
-Func_34b9:: ; 34b9 (0:34b9)
-	ld de, $fff9
+SetSpriteImageIndexAfterSettingFacingDirection:: ; 34b9 (0:34b9)
+	ld de, -7
 	add hl, de
 	ld [hl], a
 	ret
@@ -2773,14 +2785,14 @@ CheckCoords:: ; 34c7 (0:34c7)
 ; tests if a boulder's coordinates are in a specified array
 ; INPUT:
 ; hl = address of array
-; ff8c = which boulder to check? XXX
+; [H_SPRITEINDEX] = index of boulder sprite
 ; OUTPUT:
 ; [wWhichTrade] = if there is match, the matching array index
 ; sets carry if the coordinates are in the array, clears carry if not
 CheckBoulderCoords:: ; 34e4 (0:34e4)
 	push hl
 	ld hl, wSpriteStateData2 + $04
-	ld a, [$ff8c]
+	ld a, [H_SPRITEINDEX]
 	swap a
 	ld d, $0
 	ld e, a
@@ -2794,16 +2806,17 @@ CheckBoulderCoords:: ; 34e4 (0:34e4)
 	pop hl
 	jp CheckCoords
 
-Func_34fc:: ; 34fc (0:34fc)
+GetPointerWithinSpriteStateData1:: ; 34fc (0:34fc)
 	ld h, $c1
-	jr asm_3502
+	jr _GetPointerWithinSpriteStateData
 
-Func_3500:: ; 3500 (0:3500)
+GetPointerWithinSpriteStateData2:: ; 3500 (0:3500)
 	ld h, $c2
-asm_3502:: ; 3502 (0:3502)
-	ld a, [H_DOWNARROWBLINKCNT1] ; $ff8b
+
+_GetPointerWithinSpriteStateData:
+	ld a, [H_SPRITEDATAOFFSET]
 	ld b, a
-	ld a, [H_DOWNARROWBLINKCNT2] ; $ff8c
+	ld a, [H_SPRITEINDEX]
 	swap a
 	add b
 	ld l, a
@@ -2864,7 +2877,7 @@ SetSpriteMovementBytesToFF:: ; 3541 (0:3541)
 ; returns the sprite movement byte 1 pointer for sprite [$FF8C] in hl
 GetSpriteMovementByte1Pointer:: ; 354e (0:354e)
 	ld h,$C2
-	ld a,[$FF8C] ; the sprite to move
+	ld a,[H_SPRITEINDEX] ; the sprite to move
 	swap a
 	add a,6
 	ld l,a
@@ -3053,30 +3066,31 @@ MoveSprite_:: ; 363d (0:363d)
 	set 0,[hl]
 	pop hl
 	xor a
-	ld [wcd3b],a
-	ld [wccd3],a
+	ld [wOverrideSimulatedJoypadStatesMask],a
+	ld [wSimulatedJoypadStatesEnd],a
 	dec a
 	ld [wJoyIgnore],a
-	ld [wcd3a],a
+	ld [wWastedByteCD3A],a
 	ret
 
-Func_366b:: ; 366b (0:366b)
+; divides [$ffe5] by [$ffe6] and stores the quotient in [$ffe7]
+DivideBytes:: ; 366b (0:366b)
 	push hl
 	ld hl, $ffe7
 	xor a
 	ld [hld], a
 	ld a, [hld]
 	and a
-	jr z, .asm_367e
+	jr z, .done
 	ld a, [hli]
-.asm_3676
+.loop
 	sub [hl]
-	jr c, .asm_367e
+	jr c, .done
 	inc hl
 	inc [hl]
 	dec hl
-	jr .asm_3676
-.asm_367e
+	jr .loop
+.done
 	pop hl
 	ret
 
@@ -3432,21 +3446,21 @@ JoypadLowSensitivity:: ; 3831 (0:3831)
 	ret
 
 WaitForTextScrollButtonPress:: ; 3865 (0:3865)
-	ld a, [H_DOWNARROWBLINKCNT1] ; $ff8b
+	ld a, [H_DOWNARROWBLINKCNT1]
 	push af
-	ld a, [H_DOWNARROWBLINKCNT2] ; $ff8c
+	ld a, [H_DOWNARROWBLINKCNT2]
 	push af
 	xor a
-	ld [H_DOWNARROWBLINKCNT1], a ; $ff8b
+	ld [H_DOWNARROWBLINKCNT1], a
 	ld a, $6
-	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
-.asm_3872
+	ld [H_DOWNARROWBLINKCNT2], a
+.loop
 	push hl
-	ld a, [wd09b]
+	ld a, [wTownMapSpriteBlinkingEnabled]
 	and a
-	jr z, .asm_387c
-	call Func_716c6
-.asm_387c
+	jr z, .skipAnimation
+	call TownMapSpriteBlinkingAnimation
+.skipAnimation
 	hlCoord 18, 16
 	call HandleDownArrowBlinkTiming
 	pop hl
@@ -3454,16 +3468,16 @@ WaitForTextScrollButtonPress:: ; 3865 (0:3865)
 	predef Func_5a5f
 	ld a, [hJoy5]
 	and A_BUTTON | B_BUTTON
-	jr z, .asm_3872
+	jr z, .loop
 	pop af
-	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
+	ld [H_DOWNARROWBLINKCNT2], a
 	pop af
-	ld [H_DOWNARROWBLINKCNT1], a ; $ff8b
+	ld [H_DOWNARROWBLINKCNT1], a
 	ret
 
-; (unlass in link battle) waits for A or B being pressed and outputs the scrolling sound effect
+; (unless in link battle) waits for A or B being pressed and outputs the scrolling sound effect
 ManualTextScroll:: ; 3898 (0:3898)
-	ld a, [W_ISLINKBATTLE] ; W_ISLINKBATTLE
+	ld a, [W_ISLINKBATTLE]
 	cp $4
 	jr z, .inLinkBattle
 	call WaitForTextScrollButtonPress
@@ -4169,9 +4183,9 @@ DisableAutoTextBoxDrawing:: ; 3c3f (0:3c3f)
 	ld a,$01
 
 AutoTextBoxDrawingCommon:: ; 3c41 (0:3c41)
-	ld [wcf0c],a ; control text box drawing
+	ld [wAutoTextBoxDrawingControl],a
 	xor a
-	ld [wcc3c],a ; make DisplayTextID wait for button press
+	ld [wDoNotWaitForButtonPressAfterDisplayingText],a ; make DisplayTextID wait for button press
 	ret
 
 PrintText:: ; 3c49 (0:3c49)
@@ -4461,11 +4475,11 @@ IsInRestOfArray::
 	ret
 
 
-Func_3dbe:: ; 3dbe (0:3dbe)
+RestoreScreenTilesAndReloadTilePatterns:: ; 3dbe (0:3dbe)
 	call ClearSprites
 	ld a, $1
-	ld [wcfcb], a
-	call Func_3e08
+	ld [wUpdateSpritesEnabled], a
+	call ReloadMapSpriteTilePatterns
 	call LoadScreenTilesFromBuffer2
 	call LoadTextBoxTilePatterns
 	call GoPAL_SET_CF1C
@@ -4501,7 +4515,7 @@ GBPalWhiteOut::
 GoPAL_SET_CF1C:: ; 3ded (0:3ded)
 	ld b,$ff
 GoPAL_SET:: ; 3def (0:3def)
-	ld a,[wcf1b]
+	ld a,[wOnSGB]
 	and a
 	ret z
 	predef_jump Func_71ddf
@@ -4521,14 +4535,16 @@ GetHealthBarColor::
 	ld [hl], d
 	ret
 
-Func_3e08:: ; 3e08 (0:3e08)
+; Copy the current map's sprites' tile patterns to VRAM again after they have
+; been overwritten by other tile patterns.
+ReloadMapSpriteTilePatterns:: ; 3e08 (0:3e08)
 	ld hl, wcfc4
 	ld a, [hl]
 	push af
 	res 0, [hl]
 	push hl
 	xor a
-	ld [W_SPRITESETID], a ; W_SPRITESETID
+	ld [W_SPRITESETID], a
 	call DisableLCD
 	callba InitMapSprites
 	call EnableLCD
@@ -4592,51 +4608,52 @@ Func_3ead:: ; 3ead (0:3ead)
 	ld hl, CinnabarGymQuiz_1eb0a
 	jp Bankswitch
 
-Func_3eb5:: ; 3eb5 (0:3eb5)
+CheckForHiddenObjectOrBookshelfOrCardKeyDoor:: ; 3eb5 (0:3eb5)
 	ld a, [H_LOADEDROMBANK]
 	push af
 	ld a, [hJoyHeld]
-	bit 0, a
-	jr z, .asm_3eea
-	ld a, Bank(Func_469a0)
-	ld [$2000], a
+	bit 0, a ; A button
+	jr z, .nothingFound
+; A button is pressed
+	ld a, Bank(CheckForHiddenObject)
+	ld [MBC1RomBank], a
 	ld [H_LOADEDROMBANK], a
-	call Func_469a0
+	call CheckForHiddenObject
 	ld a, [$ffee]
 	and a
-	jr nz, .asm_3edd
-	ld a, [wTrainerEngageDistance]
-	ld [$2000], a
+	jr nz, .hiddenObjectNotFound
+	ld a, [wHiddenObjectFunctionRomBank]
+	ld [MBC1RomBank], a
 	ld [H_LOADEDROMBANK], a
-	ld de, .asm_3eda
+	ld de, .returnAddress
 	push de
 	jp [hl]
-.asm_3eda
+.returnAddress
 	xor a
-	jr .asm_3eec
-.asm_3edd
+	jr .done
+.hiddenObjectNotFound
 	callba PrintBookshelfText
 	ld a, [$ffdb]
 	and a
-	jr z, .asm_3eec
-.asm_3eea
+	jr z, .done
+.nothingFound
 	ld a, $ff
-.asm_3eec
+.done
 	ld [$ffeb], a
 	pop af
-	ld [$2000], a
+	ld [MBC1RomBank], a
 	ld [H_LOADEDROMBANK], a
 	ret
 
 PrintPredefTextID:: ; 3ef5 (0:3ef5)
 	ld [H_DOWNARROWBLINKCNT2], a ; $ff8c
 	ld hl, TextPredefs
-	call Func_3f0f
+	call SetMapTextPointer
 	ld hl, wcf11
 	set 0, [hl]
 	call DisplayTextID
 
-Func_3f05:: ; 3f05 (0:3f05)
+RestoreMapTextPointer:: ; 3f05 (0:3f05)
 	ld hl, W_MAPTEXTPTR
 	ld a, [$ffec]
 	ld [hli], a
@@ -4644,7 +4661,7 @@ Func_3f05:: ; 3f05 (0:3f05)
 	ld [hl], a
 	ret
 
-Func_3f0f:: ; 3f0f (0:3f0f)
+SetMapTextPointer:: ; 3f0f (0:3f0f)
 	ld a, [W_MAPTEXTPTR]
 	ld [$ffec], a
 	ld a, [W_MAPTEXTPTR + 1]

home/audio.asm

@@ -1,4 +1,4 @@
-Func_2307:: ; 2307 (0:2307)
+PlayDefaultMusic:: ; 2307 (0:2307)
 	call WaitForSoundToFinish
 	xor a
 	ld c, a
@@ -17,7 +17,7 @@ Func_2312:: ; 2312 (0:2312)
 	ld c, $8
 	ld d, c
 asm_2324:: ; 2324 (0:2324)
-	ld a, [wd700]
+	ld a, [wWalkBikeSurfState]
 	and a
 	jr z, .asm_2343
 	cp $2

home/copy.asm

@@ -5,11 +5,11 @@ FarCopyData::
 	push af
 	ld a, [wBuffer]
 	ld [H_LOADEDROMBANK], a
-	ld [MBC3RomBank], a
+	ld [MBC1RomBank], a
 	call CopyData
 	pop af
 	ld [H_LOADEDROMBANK], a
-	ld [MBC3RomBank], a
+	ld [MBC1RomBank], a
 	ret
 
 CopyData::

home/copy2.asm

@@ -6,11 +6,11 @@ FarCopyData2::
 	push af
 	ld a,[$ff8b]
 	ld [H_LOADEDROMBANK],a
-	ld [MBC3RomBank],a
+	ld [MBC1RomBank],a
 	call CopyData
 	pop af
 	ld [H_LOADEDROMBANK],a
-	ld [MBC3RomBank],a
+	ld [MBC1RomBank],a
 	ret
 
 FarCopyData3::
@@ -20,7 +20,7 @@ FarCopyData3::
 	push af
 	ld a,[$ff8b]
 	ld [H_LOADEDROMBANK],a
-	ld [MBC3RomBank],a
+	ld [MBC1RomBank],a
 	push hl
 	push de
 	push de
@@ -32,7 +32,7 @@ FarCopyData3::
 	pop hl
 	pop af
 	ld [H_LOADEDROMBANK],a
-	ld [MBC3RomBank],a
+	ld [MBC1RomBank],a
 	ret
 
 FarCopyDataDouble::
@@ -43,7 +43,7 @@ FarCopyDataDouble::
 	push af
 	ld a,[$ff8b]
 	ld [H_LOADEDROMBANK],a
-	ld [MBC3RomBank],a
+	ld [MBC1RomBank],a
 .loop
 	ld a,[hli]
 	ld [de],a
@@ -56,7 +56,7 @@ FarCopyDataDouble::
 	jr nz,.loop
 	pop af
 	ld [H_LOADEDROMBANK],a
-	ld [MBC3RomBank],a
+	ld [MBC1RomBank],a
 	ret
 
 CopyVideoData::
@@ -74,7 +74,7 @@ CopyVideoData::
 
 	ld a, b
 	ld [H_LOADEDROMBANK], a
-	ld [MBC3RomBank], a
+	ld [MBC1RomBank], a
 
 	ld a, e
 	ld [H_VBCOPYSRC], a
@@ -96,7 +96,7 @@ CopyVideoData::
 	call DelayFrame
 	ld a, [$ff8b]
 	ld [H_LOADEDROMBANK], a
-	ld [MBC3RomBank], a
+	ld [MBC1RomBank], a
 	pop af
 	ld [H_AUTOBGTRANSFERENABLED], a
 	ret
@@ -123,7 +123,7 @@ CopyVideoDataDouble::
 
 	ld a, b
 	ld [H_LOADEDROMBANK], a
-	ld [MBC3RomBank], a
+	ld [MBC1RomBank], a
 
 	ld a, e
 	ld [H_VBCOPYDOUBLESRC], a
@@ -145,7 +145,7 @@ CopyVideoDataDouble::
 	call DelayFrame
 	ld a, [$ff8b]
 	ld [H_LOADEDROMBANK], a
-	ld [MBC3RomBank], a
+	ld [MBC1RomBank], a
 	pop af
 	ld [H_AUTOBGTRANSFERENABLED], a
 	ret

home/fade.asm

@@ -1,7 +1,7 @@
 ; These routines manage gradual fading
 ; (e.g., entering a doorway)
 LoadGBPal::
-	ld a, [wd35d] ;tells if cur.map is dark (requires HM5_FLASH?)
+	ld a, [wMapPalOffset] ;tells if cur.map is dark (requires HM5_FLASH?)
 	ld b, a
 	ld hl, FadePal4
 	ld a, l
@@ -18,16 +18,16 @@ LoadGBPal::
 	ld [rOBP1], a
 	ret
 
-GBFadeOut1::
+GBFadeInFromBlack::
 	ld hl, FadePal1
 	ld b, 4
-	jr GBFadeOutCommon
+	jr GBFadeIncCommon
 
-GBFadeOut2::
+GBFadeOutToWhite::
 	ld hl, FadePal6
 	ld b, 3
 
-GBFadeOutCommon::
+GBFadeIncCommon:
 	ld a, [hli]
 	ld [rBGP], a
 	ld a, [hli]
@@ -37,19 +37,19 @@ GBFadeOutCommon::
 	ld c, 8
 	call DelayFrames
 	dec b
-	jr nz, GBFadeOutCommon
+	jr nz, GBFadeIncCommon
 	ret
 
-GBFadeIn1::
+GBFadeOutToBlack::
 	ld hl, FadePal4 + 2
 	ld b, 4
-	jr GBFadeInCommon
+	jr GBFadeDecCommon
 
-GBFadeIn2::
+GBFadeInFromWhite::
 	ld hl, FadePal7 + 2
 	ld b, 3
 
-GBFadeInCommon::
+GBFadeDecCommon:
 	ld a, [hld]
 	ld [rOBP1], a
 	ld a, [hld]
@@ -59,7 +59,7 @@ GBFadeInCommon::
 	ld c, 8
 	call DelayFrames
 	dec b
-	jr nz, GBFadeInCommon
+	jr nz, GBFadeDecCommon
 	ret
 
 FadePal1:: db %11111111, %11111111, %11111111

home/init.asm

@@ -25,7 +25,7 @@ rLCDC_DEFAULT EQU %11100011
 	ld [rIE], a
 	ld [$ff43], a
 	ld [$ff42], a
-	ld [$ff01], a
+	ld [rSB], a
 	ld [$ff02], a
 	ld [$ff4b], a
 	ld [$ff4a], a
@@ -61,11 +61,11 @@ rLCDC_DEFAULT EQU %11100011
 
 	ld a, Bank(WriteDMACodeToHRAM)
 	ld [H_LOADEDROMBANK], a
-	ld [MBC3RomBank], a
+	ld [MBC1RomBank], a
 	call WriteDMACodeToHRAM
 
 	xor a
-	ld [$ffd7], a
+	ld [hTilesetType], a
 	ld [$ff41], a
 	ld [$ffae], a
 	ld [$ffaf], a
@@ -74,7 +74,7 @@ rLCDC_DEFAULT EQU %11100011
 	ld [rIE], a
 
 	ld a, 144 ; move the window off-screen
-	ld [$ffb0], a
+	ld [hVBlankWY], a
 	ld [rWY], a
 	ld a, 7
 	ld [rWX], a
@@ -105,7 +105,7 @@ rLCDC_DEFAULT EQU %11100011
 	xor a
 	ld [$ffbc], a
 	dec a
-	ld [wcfcb], a
+	ld [wUpdateSpritesEnabled], a
 
 	predef PlayIntro
 

home/overworld.asm

@@ -10,26 +10,26 @@ EnterMap::
 	ld a, $ff
 	ld [wJoyIgnore], a
 	call LoadMapData
-	callba Func_c335 ; initialize map variables
+	callba ClearVariablesAfterLoadingMapData
 	ld hl, wd72c
-	bit 0, [hl]
-	jr z, .doNotCountSteps
-	ld a, 3
-	ld [wd13c], a ; some kind of step counter (counts up to 3 steps?)
-.doNotCountSteps
+	bit 0, [hl] ; has the player already made 3 steps since the last battle?
+	jr z, .skipGivingThreeStepsOfNoRandomBattles
+	ld a, 3 ; minimum number of steps between battles
+	ld [wNumberOfNoRandomBattleStepsLeft], a
+.skipGivingThreeStepsOfNoRandomBattles
 	ld hl, wd72e
 	bit 5, [hl] ; did a battle happen immediately before this?
 	res 5, [hl] ; unset the "battle just happened" flag
-	call z, Func_12e7
+	call z, ResetUsingStrengthOutOfBattleBit
 	call nz, MapEntryAfterBattle
 	ld hl, wd732
 	ld a, [hl]
-	and 1 << 4 | 1 << 3
-	jr z, .didNotFlyOrTeleportIn
+	and 1 << 4 | 1 << 3 ; fly warp or dungeon warp
+	jr z, .didNotEnterUsingFlyWarpOrDungeonWarp
 	res 3, [hl]
-	callba Func_70510 ; display fly/teleport in graphical effect
+	callba EnterMapAnim
 	call UpdateSprites
-.didNotFlyOrTeleportIn
+.didNotEnterUsingFlyWarpOrDungeonWarp
 	callba CheckForceBikeOrSurf ; handle currents in SF islands and forced bike riding in cycling road
 	ld hl, wd72d
 	res 5, [hl]
@@ -53,7 +53,7 @@ OverworldLoopLessDelay::
 	jp nz,.moveAhead ; if the player sprite has not yet completed the walking animation
 	call JoypadOverworld ; get joypad state (which is possibly simulated)
 	callba SafariZoneCheck
-	ld a,[wda46]
+	ld a,[wSafariZoneGameOver]
 	and a
 	jp nz,WarpFound2
 	ld hl,wd72d
@@ -61,8 +61,8 @@ OverworldLoopLessDelay::
 	res 3,[hl]
 	jp nz,WarpFound2
 	ld a,[wd732]
-	and a,$18
-	jp nz,HandleFlyOrTeleportAway
+	and a,1 << 4 | 1 << 3 ; fly warp or dungeon warp
+	jp nz,HandleFlyWarpOrDungeonWarp
 	ld a,[W_CUROPPONENT]
 	and a
 	jp nz,.newBattle
@@ -78,7 +78,7 @@ OverworldLoopLessDelay::
 	jr z,.startButtonNotPressed
 ; if START is pressed
 	xor a
-	ld [$ff8c],a ; the $2920 ID for the start menu is 0
+	ld [hSpriteIndexOrTextID],a ; start menu text ID
 	jp .displayDialogue
 .startButtonNotPressed
 	bit 0,a ; A button
@@ -87,19 +87,19 @@ OverworldLoopLessDelay::
 	ld a,[wd730]
 	bit 2,a
 	jp nz,.noDirectionButtonsPressed
-	call Func_30fd
+	call IsPlayerCharacterBeingControlledByGame
 	jr nz,.checkForOpponent
-	call Func_3eb5 ; check for hidden items, PC's, etc.
+	call CheckForHiddenObjectOrBookshelfOrCardKeyDoor
 	ld a,[$ffeb]
 	and a
-	jp z,OverworldLoop
-	call IsSpriteOrSignInFrontOfPlayer ; check for sign or sprite in front of the player
-	ld a,[$ff8c] ; $2920 ID for NPC/sign text, if any
+	jp z,OverworldLoop ; jump if a hidden object or bookshelf was found, but not if a card key door was found
+	call IsSpriteOrSignInFrontOfPlayer
+	ld a,[hSpriteIndexOrTextID]
 	and a
 	jp z,OverworldLoop
 .displayDialogue
-	predef Func_c586 ; check what is in front of the player
-	call UpdateSprites ; move sprites
+	predef GetTileAndCoordsInFrontOfPlayer
+	call UpdateSprites
 	ld a,[wFlags_0xcd60]
 	bit 2,a
 	jr nz,.checkForOpponent
@@ -117,8 +117,8 @@ OverworldLoopLessDelay::
 	jr z,.changeMap
 	predef LoadSAV
 	ld a,[W_CURMAP]
-	ld [wd71a],a
-	call Func_62ce
+	ld [wDestinationMap],a
+	call SpecialWarpIn
 	ld a,[W_CURMAP]
 	call SwitchToMapRomBank ; switch to the ROM bank of the current map
 	ld hl,W_CURMAPTILESET
@@ -133,7 +133,7 @@ OverworldLoopLessDelay::
 .noDirectionButtonsPressed
 	ld hl,wFlags_0xcd60
 	res 2,[hl]
-	call UpdateSprites ; move sprites
+	call UpdateSprites
 	ld a,$01
 	ld [wcc4b],a
 	ld a,[wd528] ; the direction that was pressed last time
@@ -225,18 +225,20 @@ OverworldLoopLessDelay::
 .noDirectionChange
 	ld a,[wd52a] ; current direction
 	ld [wd528],a ; save direction
-	call UpdateSprites ; move sprites
-	ld a,[wd700]
+	call UpdateSprites
+	ld a,[wWalkBikeSurfState]
 	cp a,$02 ; surfing
 	jr z,.surfing
 ; not surfing
 	call CollisionCheckOnLand
 	jr nc,.noCollision
+; collision occurred
 	push hl
 	ld hl,wd736
-	bit 2,[hl]
+	bit 2,[hl] ; standing on warp flag
 	pop hl
 	jp z,OverworldLoop
+; collision occurred while standing on a warp
 	push hl
 	call ExtraWarpCheck ; sets carry if there is a potential to warp
 	pop hl
@@ -259,7 +261,7 @@ OverworldLoopLessDelay::
 .moveAhead2
 	ld hl,wFlags_0xcd60
 	res 2,[hl]
-	ld a,[wd700]
+	ld a,[wWalkBikeSurfState]
 	dec a ; riding a bike?
 	jr nz,.normalPlayerSpriteAdvancement
 	ld a,[wd736]
@@ -276,36 +278,36 @@ OverworldLoopLessDelay::
 	bit 7,a
 	jr nz,.doneStepCounting ; if button presses are being simulated, don't count steps
 ; step counting
-	ld hl,wd13b ; step counter
+	ld hl,wStepCounter
 	dec [hl]
 	ld a,[wd72c]
 	bit 0,a
 	jr z,.doneStepCounting
-	ld hl,wd13c
+	ld hl,wNumberOfNoRandomBattleStepsLeft
 	dec [hl]
 	jr nz,.doneStepCounting
 	ld hl,wd72c
-	res 0,[hl]
+	res 0,[hl] ; indicate that the player has stepped thrice since the last battle
 .doneStepCounting
 	ld a,[wd790]
 	bit 7,a ; in the safari zone?
 	jr z,.notSafariZone
 	callba SafariZoneCheckSteps
-	ld a,[wda46]
+	ld a,[wSafariZoneGameOver]
 	and a
 	jp nz,WarpFound2
 .notSafariZone
 	ld a,[W_ISINBATTLE]
 	and a
 	jp nz,CheckWarpsNoCollision
-	predef Func_c69c ; decrement HP of poisoned pokemon
+	predef ApplyOutOfBattlePoisonDamage ; also increment daycare mon exp
 	ld a,[wd12d]
 	and a
 	jp nz,HandleBlackOut ; if all pokemon fainted
 .newBattle
 	call NewBattle
 	ld hl,wd736
-	res 2,[hl]
+	res 2,[hl] ; standing on warp flag
 	jp nc,CheckWarpsNoCollision ; check for warps if there was no battle
 .battleOccurred
 	ld hl,wd72d
@@ -316,7 +318,7 @@ OverworldLoopLessDelay::
 	set 5,[hl]
 	set 6,[hl]
 	xor a
-	ld [hJoyHeld],a ; clear joypad state
+	ld [hJoyHeld],a
 	ld a,[W_CURMAP]
 	cp a,CINNABAR_GYM
 	jr nz,.notCinnabarGym
@@ -327,8 +329,8 @@ OverworldLoopLessDelay::
 	set 5,[hl]
 	ld a,[W_CURMAP]
 	cp a,OAKS_LAB
-	jp z,.noFaintCheck
-	callab AnyPartyAlive ; check if all the player's pokemon fainted
+	jp z,.noFaintCheck ; no blacking out if the player lost to the rival in Oak's lab
+	callab AnyPartyAlive
 	ld a,d
 	and a
 	jr z,.allPokemonFainted
@@ -348,45 +350,45 @@ NewBattle:: ; 0683 (0:0683)
 	ld a,[wd72d]
 	bit 4,a
 	jr nz,.noBattle
-	call Func_30fd
-	jr nz,.noBattle
+	call IsPlayerCharacterBeingControlledByGame
+	jr nz,.noBattle ; no battle if the player character is under the game's control
 	ld a,[wd72e]
 	bit 4,a
 	jr nz,.noBattle
 	ld b, BANK(InitBattle)
 	ld hl, InitBattle
-	jp Bankswitch ; determines if a battle will occur and runs the battle if so
+	jp Bankswitch
 .noBattle
 	and a
 	ret
 
 ; function to make bikes twice as fast as walking
 BikeSpeedup:: ; 06a0 (0:06a0)
-	ld a,[wcc57]
+	ld a,[wNPCMovementScriptPointerTableNum]
 	and a
 	ret nz
 	ld a,[W_CURMAP]
 	cp a,ROUTE_17 ; Cycling Road
 	jr nz,.goFaster
-	ld a,[hJoyHeld] ; current joypad state
-	and a,%01110000 ; bit mask for up, left, right buttons
+	ld a,[hJoyHeld]
+	and a,D_UP | D_LEFT | D_RIGHT
 	ret nz
 .goFaster
 	jp AdvancePlayerSprite
 
 ; check if the player has stepped onto a warp after having not collided
 CheckWarpsNoCollision:: ; 06b4 (0:06b4)
-	ld a,[wd3ae] ; number of warps
+	ld a,[wNumberOfWarps]
 	and a
 	jp z,CheckMapConnections
-	ld a,[wd3ae] ; number of warps
-	ld b,$00
+	ld a,[wNumberOfWarps]
+	ld b,0
 	ld c,a
 	ld a,[W_YCOORD]
 	ld d,a
 	ld a,[W_XCOORD]
 	ld e,a
-	ld hl,wd3af ; start of warp entries
+	ld hl,wWarpEntries
 CheckWarpsNoCollisionLoop:: ; 06cc (0:06cc)
 	ld a,[hli] ; check if the warp's Y position matches
 	cp d
@@ -398,14 +400,14 @@ CheckWarpsNoCollisionLoop:: ; 06cc (0:06cc)
 	push hl
 	push bc
 	ld hl,wd736
-	set 2,[hl]
-	callba Func_c49d ; check if the player sprite is standing on a "door" tile
+	set 2,[hl] ; standing on warp flag
+	callba IsPlayerStandingOnDoorTileOrWarpTile
 	pop bc
 	pop hl
-	jr c,WarpFound1 ; if it is, go to 0735
+	jr c,WarpFound1 ; jump if standing on door or warp
 	push hl
 	push bc
-	call ExtraWarpCheck ; sets carry if the warp is confirmed
+	call ExtraWarpCheck
 	pop bc
 	pop hl
 	jr nc,CheckWarpsNoCollisionRetry2
@@ -418,16 +420,16 @@ CheckWarpsNoCollisionLoop:: ; 06cc (0:06cc)
 	call Joypad
 	pop bc
 	pop de
-	ld a,[hJoyHeld] ; current joypad state
-	and a,%11110000 ; bit mask for directional buttons
+	ld a,[hJoyHeld]
+	and a,D_DOWN | D_UP | D_LEFT | D_RIGHT
 	jr z,CheckWarpsNoCollisionRetry2 ; if directional buttons aren't being pressed, do not pass through the warp
 	jr WarpFound1
 
 ; check if the player has stepped onto a warp after having collided
 CheckWarpsCollision:: ; 0706 (0:0706)
-	ld a,[wd3ae] ; number of warps
+	ld a,[wNumberOfWarps]
 	ld c,a
-	ld hl,wd3af ; start of warp entries
+	ld hl,wWarpEntries
 .loop
 	ld a,[hli] ; Y coordinate of warp
 	ld b,a
@@ -440,7 +442,7 @@ CheckWarpsCollision:: ; 0706 (0:0706)
 	cp b
 	jr nz,.retry2
 	ld a,[hli]
-	ld [wd42f],a ; save target warp ID
+	ld [wDestinationWarpID],a
 	ld a,[hl]
 	ld [$ff8b],a ; save target map
 	jr WarpFound2
@@ -462,12 +464,12 @@ CheckWarpsNoCollisionRetry2:: ; 0730 (0:0730)
 
 WarpFound1:: ; 0735 (0:0735)
 	ld a,[hli]
-	ld [wd42f],a ; save target warp ID
+	ld [wDestinationWarpID],a
 	ld a,[hli]
 	ld [$ff8b],a ; save target map
 
 WarpFound2:: ; 073c (0:073c)
-	ld a,[wd3ae] ; number of warps
+	ld a,[wNumberOfWarps]
 	sub c
 	ld [wd73b],a ; save ID of used warp
 	ld a,[W_CURMAP]
@@ -484,8 +486,8 @@ WarpFound2:: ; 073c (0:073c)
 	cp a,ROCK_TUNNEL_1
 	jr nz,.notRockTunnel
 	ld a,$06
-	ld [wd35d],a
-	call GBFadeIn1
+	ld [wMapPalOffset],a
+	call GBFadeOutToBlack
 .notRockTunnel
 	call PlayMapChangeSound
 	jr .done
@@ -496,16 +498,16 @@ WarpFound2:: ; 073c (0:073c)
 	jr z,.goBackOutside
 ; if not going back to the previous map
 	ld [W_CURMAP],a ; current map number
-	callba Func_70787 ; check if the warp was a Silph Co. teleporter
+	callba IsPlayerStandingOnWarpPadOrHole
 	ld a,[wcd5b]
-	dec a
-	jr nz,.notTeleporter
-; if it's a Silph Co. teleporter
+	dec a ; is the player on a warp pad?
+	jr nz,.notWarpPad
+; if the player is on a warp pad
 	ld hl,wd732
 	set 3,[hl]
 	call LeaveMapAnim
 	jr .skipMapChangeSound
-.notTeleporter
+.notWarpPad
 	call PlayMapChangeSound
 .skipMapChangeSound
 	ld hl,wd736
@@ -517,11 +519,11 @@ WarpFound2:: ; 073c (0:073c)
 	ld [W_CURMAP],a
 	call PlayMapChangeSound
 	xor a
-	ld [wd35d],a
+	ld [wMapPalOffset],a
 .done
 	ld hl,wd736
-	set 0,[hl]
-	call Func_12da
+	set 0,[hl] ; have the player's sprite step out from the door (if there is one)
+	call IgnoreInputForHalfSecond
 	jp EnterMap
 
 ContinueCheckWarpsNoCollisionLoop:: ; 07b5 (0:07b5)
@@ -562,9 +564,9 @@ CheckMapConnections:: ; 07ba (0:07ba)
 	jr nz,.pointerAdjustmentLoop1
 .savePointer1
 	ld a,l
-	ld [wd35f],a ; pointer to upper left corner of current tile block map section
+	ld [wCurrentTileBlockMapViewPointer],a ; pointer to upper left corner of current tile block map section
 	ld a,h
-	ld [wd360],a
+	ld [wCurrentTileBlockMapViewPointer + 1],a
 	jp .loadNewMap
 .checkEastMap
 	ld b,a
@@ -598,9 +600,9 @@ CheckMapConnections:: ; 07ba (0:07ba)
 	jr nz,.pointerAdjustmentLoop2
 .savePointer2
 	ld a,l
-	ld [wd35f],a ; pointer to upper left corner of current tile block map section
+	ld [wCurrentTileBlockMapViewPointer],a ; pointer to upper left corner of current tile block map section
 	ld a,h
-	ld [wd360],a
+	ld [wCurrentTileBlockMapViewPointer + 1],a
 	jp .loadNewMap
 .checkNorthMap
 	ld a,[W_YCOORD]
@@ -624,9 +626,9 @@ CheckMapConnections:: ; 07ba (0:07ba)
 	srl c
 	add hl,bc
 	ld a,l
-	ld [wd35f],a ; pointer to upper left corner of current tile block map section
+	ld [wCurrentTileBlockMapViewPointer],a ; pointer to upper left corner of current tile block map section
 	ld a,h
-	ld [wd360],a
+	ld [wCurrentTileBlockMapViewPointer + 1],a
 	jp .loadNewMap
 .checkSouthMap
 	ld b,a
@@ -651,9 +653,9 @@ CheckMapConnections:: ; 07ba (0:07ba)
 	srl c
 	add hl,bc
 	ld a,l
-	ld [wd35f],a ; pointer to upper left corner of current tile block map section
+	ld [wCurrentTileBlockMapViewPointer],a ; pointer to upper left corner of current tile block map section
 	ld a,h
-	ld [wd360],a
+	ld [wCurrentTileBlockMapViewPointer + 1],a
 .loadNewMap ; load the connected map that was entered
 	call LoadMapHeader
 	call Func_2312 ; music
@@ -678,10 +680,10 @@ PlayMapChangeSound:: ; 08c9 (0:08c9)
 	ld a,(SFX_02_5c - SFX_Headers_02) / 3
 .playSound
 	call PlaySound
-	ld a,[wd35d]
+	ld a,[wMapPalOffset]
 	and a
 	ret nz
-	jp GBFadeIn1
+	jp GBFadeOutToBlack
 
 CheckIfInOutsideMap:: ; 08e1 (0:08e1)
 ; If the player is in an outside map (a town or route), set the z flag
@@ -719,37 +721,37 @@ ExtraWarpCheck:: ; 08e9 (0:08e9)
 	cp PLATEAU ; Indigo Plateau tileset
 	jr z, .useFunction2
 .useFunction1
-	ld hl, Func_c3ff
+	ld hl, IsPlayerFacingEdgeOfMap
 	jr .doBankswitch
 .useFunction2
-	ld hl, Func_c44e
+	ld hl, IsWarpTileInFrontOfPlayer
 .doBankswitch
-	ld b, BANK(Func_c44e)
+	ld b, BANK(IsWarpTileInFrontOfPlayer)
 	jp Bankswitch
 
 MapEntryAfterBattle:: ; 091f (0:091f)
-	callba Func_c35f ; function that appears to disable warp testing after collisions if the player is standing on a warp
-	ld a,[wd35d]
+	callba IsPlayerStandingOnWarp ; for enabling warp testing after collisions
+	ld a,[wMapPalOffset]
 	and a
-	jp z,GBFadeIn2
+	jp z,GBFadeInFromWhite
 	jp LoadGBPal
 
 HandleBlackOut::
 ; For when all the player's pokemon faint.
 ; Does not print the "blacked out" message.
 
-	call GBFadeIn1
+	call GBFadeOutToBlack
 	ld a, $08
 	call StopMusic
 	ld hl, wd72e
 	res 5, [hl]
-	ld a, Bank(Func_40b0) ; also Bank(Func_62ce) and Bank(Func_5d5f)
+	ld a, Bank(ResetStatusAndHalveMoneyOnBlackout) ; also Bank(SpecialWarpIn) and Bank(SpecialEnterMap)
 	ld [H_LOADEDROMBANK], a
-	ld [MBC3RomBank], a
-	call Func_40b0
-	call Func_62ce
+	ld [MBC1RomBank], a
+	call ResetStatusAndHalveMoneyOnBlackout
+	call SpecialWarpIn
 	call Func_2312
-	jp Func_5d5f
+	jp SpecialEnterMap
 
 StopMusic::
 	ld [wMusicHeaderPointer], a
@@ -762,23 +764,23 @@ StopMusic::
 	jr nz, .wait
 	jp StopAllSounds
 
-HandleFlyOrTeleportAway::
+HandleFlyWarpOrDungeonWarp::
 	call UpdateSprites
 	call Delay3
 	xor a
-	ld [wcf0b], a
-	ld [wd700], a
+	ld [wBattleResult], a
+	ld [wWalkBikeSurfState], a
 	ld [W_ISINBATTLE], a
-	ld [wd35d], a
+	ld [wMapPalOffset], a
 	ld hl, wd732
-	set 2, [hl]
-	res 5, [hl]
+	set 2, [hl] ; fly warp or dungeon warp
+	res 5, [hl] ; forced to ride bike
 	call LeaveMapAnim
-	ld a, Bank(Func_62ce)
+	ld a, Bank(SpecialWarpIn)
 	ld [H_LOADEDROMBANK], a
 	ld [$2000], a
-	call Func_62ce
-	jp Func_5d5f
+	call SpecialWarpIn
+	jp SpecialEnterMap
 
 LeaveMapAnim::
 	ld b, BANK(_LeaveMapAnim)
@@ -792,11 +794,11 @@ LoadPlayerSpriteGraphics::
 	; 1: biking
 	; 2: surfing
 
-	ld a, [wd700]
+	ld a, [wWalkBikeSurfState]
 	dec a
 	jr z, .ridingBike
 
-	ld a, [$ffd7]
+	ld a, [hTilesetType]
 	and a
 	jr nz, .determineGraphics
 	jr .startWalking
@@ -809,12 +811,12 @@ LoadPlayerSpriteGraphics::
 
 .startWalking
 	xor a
-	ld [wd700], a
-	ld [wd11a], a
+	ld [wWalkBikeSurfState], a
+	ld [wWalkBikeSurfStateCopy], a
 	jp LoadWalkingPlayerSpriteGraphics
 
 .determineGraphics
-	ld a, [wd700]
+	ld a, [wWalkBikeSurfState]
 	and a
 	jp z, LoadWalkingPlayerSpriteGraphics
 	dec a
@@ -1056,16 +1058,16 @@ LoadEastWestConnectionsTileMap:: ; 0b02 (0:0b02)
 	ret
 
 ; function to check if there is a sign or sprite in front of the player
-; if so, it is stored in [$FF8C]
-; if not, [$FF8C] is set to 0
+; if so, it is stored in [hSpriteIndexOrTextID]
+; if not, [hSpriteIndexOrTextID] is set to 0
 IsSpriteOrSignInFrontOfPlayer:: ; 0b23 (0:0b23)
 	xor a
-	ld [$ff8c],a
+	ld [hSpriteIndexOrTextID],a
 	ld a,[wd4b0] ; number of signs in the map
 	and a
 	jr z,.extendRangeOverCounter
 ; if there are signs
-	predef Func_c586 ; get the coordinates in front of the player in de
+	predef GetTileAndCoordsInFrontOfPlayer ; get the coordinates in front of the player in de
 	ld hl,wd4b1 ; start of sign coordinates
 	ld a,[wd4b0] ; number of signs in the map
 	ld b,a
@@ -1090,7 +1092,7 @@ IsSpriteOrSignInFrontOfPlayer:: ; 0b23 (0:0b23)
 	dec c
 	add hl,bc
 	ld a,[hl]
-	ld [$ff8c],a ; store sign text ID
+	ld [hSpriteIndexOrTextID],a ; store sign text ID
 	pop bc
 	pop hl
 	ret
@@ -1099,7 +1101,7 @@ IsSpriteOrSignInFrontOfPlayer:: ; 0b23 (0:0b23)
 	jr nz,.signLoop
 ; check if the player is front of a counter in a pokemon center, pokemart, etc. and if so, extend the range at which he can talk to the NPC
 .extendRangeOverCounter
-	predef Func_c586 ; get the tile in front of the player in c
+	predef GetTileAndCoordsInFrontOfPlayer ; get the tile in front of the player in c
 	ld hl,W_TILESETTALKINGOVERTILES ; list of tiles that extend talking range (counter tiles)
 	ld b,$03
 	ld d,$20 ; talking range in pixels (long range)
@@ -1111,7 +1113,7 @@ IsSpriteOrSignInFrontOfPlayer:: ; 0b23 (0:0b23)
 	jr nz,.counterTilesLoop
 
 ; part of the above function, but sometimes its called on its own, when signs are irrelevant
-; the caller must zero [$FF8C]
+; the caller must zero [hSpriteIndexOrTextID]
 IsSpriteInFrontOfPlayer:: ; 0b6b (0:0b6b)
 	ld d,$10 ; talking range in pixels (normal range)
 IsSpriteInFrontOfPlayer2:: ; 0b6d (0:0b6d)
@@ -1193,7 +1195,7 @@ IsSpriteInFrontOfPlayer2:: ; 0b6d (0:0b6d)
 	ld l,a
 	set 7,[hl]
 	ld a,e
-	ld [$ff8c],a ; store sprite ID
+	ld [hSpriteIndexOrTextID],a
 	ret
 
 ; function to check if the player will jump down a ledge and check if the tile ahead is passable (when not surfing)
@@ -1203,18 +1205,18 @@ CollisionCheckOnLand:: ; 0bd1 (0:0bd1)
 	bit 6,a ; is the player jumping?
 	jr nz,.noCollision
 ; if not jumping a ledge
-	ld a,[wcd38]
+	ld a,[wSimulatedJoypadStatesIndex]
 	and a
-	jr nz,.noCollision
+	jr nz,.noCollision ; no collisions when the player's movements are being controlled by the game
 	ld a,[wd52a] ; the direction that the player is trying to go in
 	ld d,a
 	ld a,[wSpriteStateData1 + 12] ; the player sprite's collision data (bit field) (set in the sprite movement code)
 	and d ; check if a sprite is in the direction the player is trying to go
 	jr nz,.collision
 	xor a
-	ld [$ff8c],a
+	ld [hSpriteIndexOrTextID],a
 	call IsSpriteInFrontOfPlayer ; check for sprite collisions again? when does the above check fail to detect a sprite collision?
-	ld a,[$ff8c]
+	ld a,[hSpriteIndexOrTextID]
 	and a ; was there a sprite collision?
 	jr nz,.collision
 ; if no sprite collision
@@ -1239,8 +1241,8 @@ CollisionCheckOnLand:: ; 0bd1 (0:0bd1)
 ; function that checks if the tile in front of the player is passable
 ; clears carry if it is, sets carry if not
 CheckTilePassable:: ; 0c10 (0:0c10)
-	predef Func_c586 ; get tile in front of player
-	ld a,[wcfc6] ; tile in front of player
+	predef GetTileAndCoordsInFrontOfPlayer ; get tile in front of player
+	ld a,[wTileInFrontOfPlayer] ; tile in front of player
 	ld c,a
 	ld hl,W_TILESETCOLLISIONPTR ; pointer to list of passable tiles
 	ld a,[hli]
@@ -1263,7 +1265,7 @@ CheckTilePassable:: ; 0c10 (0:0c10)
 ; sets carry if there is a collision and unsets carry if not
 CheckForJumpingAndTilePairCollisions:: ; 0c2a (0:0c2a)
 	push hl
-	predef Func_c586 ; get the tile in front of the player
+	predef GetTileAndCoordsInFrontOfPlayer ; get the tile in front of the player
 	push de
 	push bc
 	callba HandleLedges ; check if the player is trying to jump a ledge
@@ -1276,12 +1278,12 @@ CheckForJumpingAndTilePairCollisions:: ; 0c2a (0:0c2a)
 	ret nz
 ; if not jumping
 
-Func_c44:: ; 0c44 (0:0c44)
+CheckForTilePairCollisions2:: ; 0c44 (0:0c44)
 	aCoord 8, 9 ; tile the player is on
 	ld [wcf0e],a
 
 CheckForTilePairCollisions:: ; 0c4a (0:0c4a)
-	ld a,[wcfc6] ; tile in front of the player
+	ld a,[wTileInFrontOfPlayer]
 	ld c,a
 .tilePairCollisionLoop
 	ld a,[W_CURMAPTILESET] ; tileset number
@@ -1357,9 +1359,9 @@ LoadCurrentMapView:: ; 0caa (0:0caa)
 	ld a,[W_TILESETBANK] ; tile data ROM bank
 	ld [H_LOADEDROMBANK],a
 	ld [$2000],a ; switch to ROM bank that contains tile data
-	ld a,[wd35f] ; address of upper left corner of current map view
+	ld a,[wCurrentTileBlockMapViewPointer] ; address of upper left corner of current map view
 	ld e,a
-	ld a,[wd360]
+	ld a,[wCurrentTileBlockMapViewPointer + 1]
 	ld d,a
 	ld hl,wTileMapBackup
 	ld b,$05
@@ -1465,7 +1467,7 @@ AdvancePlayerSprite:: ; 0d27 (0:0d27)
 	cp a,$01
 	jr nz,.checkIfMovingWest
 ; moving east
-	ld a,[wd526]
+	ld a,[wMapViewVRAMPointer]
 	ld e,a
 	and a,$e0
 	ld d,a
@@ -1473,13 +1475,13 @@ AdvancePlayerSprite:: ; 0d27 (0:0d27)
 	add a,$02
 	and a,$1f
 	or d
-	ld [wd526],a
+	ld [wMapViewVRAMPointer],a
 	jr .adjustXCoordWithinBlock
 .checkIfMovingWest
 	cp a,$ff
 	jr nz,.checkIfMovingSouth
 ; moving west
-	ld a,[wd526]
+	ld a,[wMapViewVRAMPointer]
 	ld e,a
 	and a,$e0
 	ld d,a
@@ -1487,36 +1489,36 @@ AdvancePlayerSprite:: ; 0d27 (0:0d27)
 	sub a,$02
 	and a,$1f
 	or d
-	ld [wd526],a
+	ld [wMapViewVRAMPointer],a
 	jr .adjustXCoordWithinBlock
 .checkIfMovingSouth
 	ld a,b
 	cp a,$01
 	jr nz,.checkIfMovingNorth
 ; moving south
-	ld a,[wd526]
+	ld a,[wMapViewVRAMPointer]
 	add a,$40
-	ld [wd526],a
+	ld [wMapViewVRAMPointer],a
 	jr nc,.adjustXCoordWithinBlock
-	ld a,[wd527]
+	ld a,[wMapViewVRAMPointer + 1]
 	inc a
 	and a,$03
 	or a,$98
-	ld [wd527],a
+	ld [wMapViewVRAMPointer + 1],a
 	jr .adjustXCoordWithinBlock
 .checkIfMovingNorth
 	cp a,$ff
 	jr nz,.adjustXCoordWithinBlock
 ; moving north
-	ld a,[wd526]
+	ld a,[wMapViewVRAMPointer]
 	sub a,$40
-	ld [wd526],a
+	ld [wMapViewVRAMPointer],a
 	jr nc,.adjustXCoordWithinBlock
-	ld a,[wd527]
+	ld a,[wMapViewVRAMPointer + 1]
 	dec a
 	and a,$03
 	or a,$98
-	ld [wd527],a
+	ld [wMapViewVRAMPointer + 1],a
 .adjustXCoordWithinBlock
 	ld a,c
 	and a
@@ -1531,9 +1533,9 @@ AdvancePlayerSprite:: ; 0d27 (0:0d27)
 ; moved into the tile block to the east
 	xor a
 	ld [hl],a
-	ld hl,wd4e3
+	ld hl,wXOffsetSinceLastSpecialWarp
 	inc [hl]
-	ld de,wd35f
+	ld de,wCurrentTileBlockMapViewPointer
 	call MoveTileBlockMapPointerEast
 	jr .updateMapView
 .checkForMoveToWestBlock
@@ -1542,9 +1544,9 @@ AdvancePlayerSprite:: ; 0d27 (0:0d27)
 ; moved into the tile block to the west
 	ld a,$01
 	ld [hl],a
-	ld hl,wd4e3
+	ld hl,wXOffsetSinceLastSpecialWarp
 	dec [hl]
-	ld de,wd35f
+	ld de,wCurrentTileBlockMapViewPointer
 	call MoveTileBlockMapPointerWest
 	jr .updateMapView
 .adjustYCoordWithinBlock
@@ -1557,9 +1559,9 @@ AdvancePlayerSprite:: ; 0d27 (0:0d27)
 ; moved into the tile block to the south
 	xor a
 	ld [hl],a
-	ld hl,wd4e2
+	ld hl,wYOffsetSinceLastSpecialWarp
 	inc [hl]
-	ld de,wd35f
+	ld de,wCurrentTileBlockMapViewPointer
 	ld a,[W_CURMAPWIDTH]
 	call MoveTileBlockMapPointerSouth
 	jr .updateMapView
@@ -1569,9 +1571,9 @@ AdvancePlayerSprite:: ; 0d27 (0:0d27)
 ; moved into the tile block to the north
 	ld a,$01
 	ld [hl],a
-	ld hl,wd4e2
+	ld hl,wYOffsetSinceLastSpecialWarp
 	dec [hl]
-	ld de,wd35f
+	ld de,wCurrentTileBlockMapViewPointer
 	ld a,[W_CURMAPWIDTH]
 	call MoveTileBlockMapPointerNorth
 .updateMapView
@@ -1692,18 +1694,18 @@ MoveTileBlockMapPointerNorth:: ; 0e85 (0:0e85)
 
 ScheduleNorthRowRedraw:: ; 0e91 (0:0e91)
 	hlCoord 0, 0
-	call ScheduleRowRedrawHelper
-	ld a,[wd526]
+	call CopyToScreenEdgeTiles
+	ld a,[wMapViewVRAMPointer]
 	ld [H_SCREENEDGEREDRAWADDR],a
-	ld a,[wd527]
+	ld a,[wMapViewVRAMPointer + 1]
 	ld [H_SCREENEDGEREDRAWADDR + 1],a
 	ld a,REDRAWROW
 	ld [H_SCREENEDGEREDRAW],a
 	ret
 
-ScheduleRowRedrawHelper:: ; 0ea6 (0:0ea6)
+CopyToScreenEdgeTiles:: ; 0ea6 (0:0ea6)
 	ld de,wScreenEdgeTiles
-	ld c,$28
+	ld c,2 * 20
 .loop
 	ld a,[hli]
 	ld [de],a
@@ -1714,10 +1716,10 @@ ScheduleRowRedrawHelper:: ; 0ea6 (0:0ea6)
 
 ScheduleSouthRowRedraw:: ; 0eb2 (0:0eb2)
 	hlCoord 0, 16
-	call ScheduleRowRedrawHelper
-	ld a,[wd526]
+	call CopyToScreenEdgeTiles
+	ld a,[wMapViewVRAMPointer]
 	ld l,a
-	ld a,[wd527]
+	ld a,[wMapViewVRAMPointer + 1]
 	ld h,a
 	ld bc,$0200
 	add hl,bc
@@ -1734,7 +1736,7 @@ ScheduleSouthRowRedraw:: ; 0eb2 (0:0eb2)
 ScheduleEastColumnRedraw:: ; 0ed3 (0:0ed3)
 	hlCoord 18, 0
 	call ScheduleColumnRedrawHelper
-	ld a,[wd526]
+	ld a,[wMapViewVRAMPointer]
 	ld c,a
 	and a,$e0
 	ld b,a
@@ -1743,7 +1745,7 @@ ScheduleEastColumnRedraw:: ; 0ed3 (0:0ed3)
 	and a,$1f
 	or b
 	ld [H_SCREENEDGEREDRAWADDR],a
-	ld a,[wd527]
+	ld a,[wMapViewVRAMPointer + 1]
 	ld [H_SCREENEDGEREDRAWADDR + 1],a
 	ld a,REDRAWCOL
 	ld [H_SCREENEDGEREDRAW],a
@@ -1772,9 +1774,9 @@ ScheduleColumnRedrawHelper:: ; 0ef2 (0:0ef2)
 ScheduleWestColumnRedraw:: ; 0f08 (0:0f08)
 	hlCoord 0, 0
 	call ScheduleColumnRedrawHelper
-	ld a,[wd526]
+	ld a,[wMapViewVRAMPointer]
 	ld [H_SCREENEDGEREDRAWADDR],a
-	ld a,[wd527]
+	ld a,[wMapViewVRAMPointer + 1]
 	ld [H_SCREENEDGEREDRAWADDR + 1],a
 	ld a,REDRAWCOL
 	ld [H_SCREENEDGEREDRAW],a
@@ -1835,28 +1837,27 @@ JoypadOverworld:: ; 0f4d (0:0f4d)
 	ld a,[W_CURMAP]
 	cp a,ROUTE_17 ; Cycling Road
 	jr nz,.notForcedDownwards
-	ld a,[hJoyHeld] ; current joypad state
-	and a,%11110011 ; bit mask for all directions and A/B
+	ld a,[hJoyHeld]
+	and a,D_DOWN | D_UP | D_LEFT | D_RIGHT | B_BUTTON | A_BUTTON
 	jr nz,.notForcedDownwards
-	ld a,%10000000 ; down pressed
+	ld a,D_DOWN
 	ld [hJoyHeld],a ; on the cycling road, if there isn't a trainer and the player isn't pressing buttons, simulate a down press
 .notForcedDownwards
 	ld a,[wd730]
 	bit 7,a
 	ret z
 ; if simulating button presses
-	ld a,[hJoyHeld] ; current joypad state
+	ld a,[hJoyHeld]
 	ld b,a
-	ld a,[wcd3b] ; bit mask for button presses that override simulated ones
+	ld a,[wOverrideSimulatedJoypadStatesMask] ; bit mask for button presses that override simulated ones
 	and b
 	ret nz ; return if the simulated button presses are overridden
-	ld hl,wcd38 ; index of current simulated button press
+	ld hl,wSimulatedJoypadStatesIndex
 	dec [hl]
 	ld a,[hl]
 	cp a,$ff
 	jr z,.doneSimulating ; if the end of the simulated button presses has been reached
-	ld hl,wccd3 ; base address of simulated button presses
-; add offset to base address
+	ld hl,wSimulatedJoypadStatesEnd
 	add l
 	ld l,a
 	jr nc,.noCarry
@@ -1872,9 +1873,9 @@ JoypadOverworld:: ; 0f4d (0:0f4d)
 ; if done simulating button presses
 .doneSimulating
 	xor a
-	ld [wcd3a],a
-	ld [wcd38],a
-	ld [wccd3],a
+	ld [wWastedByteCD3A],a
+	ld [wSimulatedJoypadStatesIndex],a
+	ld [wSimulatedJoypadStatesEnd],a
 	ld [wJoyIgnore],a
 	ld [hJoyHeld],a
 	ld hl,wd736
@@ -1906,8 +1907,8 @@ CollisionCheckOnWater:: ; 0fb7 (0:0fb7)
 	ld hl,TilePairCollisionsWater
 	call CheckForJumpingAndTilePairCollisions
 	jr c,.collision
-	predef Func_c586 ; get tile in front of player (puts it in c and [wcfc6])
-	ld a,[wcfc6] ; tile in front of player
+	predef GetTileAndCoordsInFrontOfPlayer ; get tile in front of player (puts it in c and [wTileInFrontOfPlayer])
+	ld a,[wTileInFrontOfPlayer] ; tile in front of player
 	cp a,$14 ; water tile
 	jr z,.noCollision ; keep surfing if it's a water tile
 	cp a,$32 ; either the left tile of the S.S. Anne boarding platform or the tile on eastern coastlines (depending on the current tileset)
@@ -1942,9 +1943,9 @@ CollisionCheckOnWater:: ; 0fb7 (0:0fb7)
 	ret
 .stopSurfing
 	xor a
-	ld [wd700],a
+	ld [wWalkBikeSurfState],a
 	call LoadPlayerSpriteGraphics
-	call Func_2307
+	call PlayDefaultMusic
 	jr .noCollision
 .checkIfVermilionDockTileset
 	ld a, [W_CURMAPTILESET] ; tileset
@@ -1957,16 +1958,16 @@ RunMapScript:: ; 101b (0:101b)
 	push hl
 	push de
 	push bc
-	callba Func_f225 ; check if the player is pushing a boulder
+	callba TryPushingBoulder
 	ld a,[wFlags_0xcd60]
-	bit 1,a ; is the player pushing a boulder?
+	bit 1,a ; play boulder dust animation
 	jr z,.afterBoulderEffect
-	callba Func_f2b5 ; displays dust effect when pushing a boulder
+	callba DoBoulderDustAnimation
 .afterBoulderEffect
 	pop bc
 	pop de
 	pop hl
-	call Func_310e
+	call RunNPCMovementScript
 	ld a,[W_CURMAP] ; current map number
 	call SwitchToMapRomBank ; change to the ROM bank the map's data is in
 	ld hl,W_MAPSCRIPTPTR
@@ -2012,7 +2013,7 @@ LoadPlayerSpriteGraphicsCommon:: ; 1063 (0:1063)
 
 ; function to load data from the map header
 LoadMapHeader:: ; 107c (0:107c)
-	callba Func_f113
+	callba MarkTownVisitedAndLoadMissableObjects
 	ld a,[W_CURMAPTILESET]
 	ld [wd119],a
 	ld a,[W_CURMAP]
@@ -2090,12 +2091,12 @@ LoadMapHeader:: ; 107c (0:107c)
 	ld a,[hli]
 	ld [de],a ; save background tile ID
 .loadWarpData
-	ld a,[hli] ; number of warps
-	ld [wd3ae],a ; save the number of warps
-	and a ; are there any warps?
-	jr z,.loadSignData ; if not, skip this
+	ld a,[hli]
+	ld [wNumberOfWarps],a
+	and a
+	jr z,.loadSignData
 	ld c,a
-	ld de,wd3af ; base address of warps
+	ld de,wWarpEntries
 .warpLoop ; one warp per loop iteration
 	ld b,$04
 .warpInnerLoop
@@ -2259,8 +2260,8 @@ LoadMapHeader:: ; 107c (0:107c)
 	dec b
 	jp nz,.loadSpriteLoop
 .finishUp
-	predef Func_c754 ; load tileset data
-	callab LoadWildData ; load wild pokemon data
+	predef LoadTilesetHeader
+	callab LoadWildData
 	pop hl ; restore hl from before going to the warp/sign/sprite data (this value was saved for seemingly no purpose)
 	ld a,[W_CURMAPHEIGHT] ; map height in 4x4 tile blocks
 	add a ; double it
@@ -2306,14 +2307,14 @@ LoadMapData:: ; 1241 (0:1241)
 	push af
 	call DisableLCD
 	ld a,$98
-	ld [wd527],a
+	ld [wMapViewVRAMPointer + 1],a
 	xor a
-	ld [wd526],a
+	ld [wMapViewVRAMPointer],a
 	ld [$ffaf],a
 	ld [$ffae],a
 	ld [wWalkCounter],a
 	ld [wd119],a
-	ld [wd11a],a
+	ld [wWalkBikeSurfStateCopy],a
 	ld [W_SPRITESETID],a
 	call LoadTextBoxTilePatterns
 	call LoadMapHeader
@@ -2342,13 +2343,13 @@ LoadMapData:: ; 1241 (0:1241)
 	dec b
 	jr nz,.vramCopyLoop
 	ld a,$01
-	ld [wcfcb],a
+	ld [wUpdateSpritesEnabled],a
 	call EnableLCD
 	ld b,$09
 	call GoPAL_SET
 	call LoadPlayerSpriteGraphics
 	ld a,[wd732]
-	and a,$18 ; did the player fly or teleport in?
+	and a,1 << 4 | 1 << 3 ; fly warp or dungeon warp
 	jr nz,.restoreRomBank
 	ld a,[W_FLAGS_D733]
 	bit 1,a
@@ -2382,16 +2383,16 @@ SwitchToMapRomBank:: ; 12bc (0:12bc)
 	pop hl
 	ret
 
-Func_12da:: ; 12da (0:12da)
-	ld a, $1e
-	ld [wd13a], a
+IgnoreInputForHalfSecond: ; 12da (0:12da)
+	ld a, 30
+	ld [wIgnoreInputCounter], a
 	ld hl, wd730
 	ld a, [hl]
 	or $26
-	ld [hl], a
+	ld [hl], a ; set ignore input bit
 	ret
 
-Func_12e7:: ; 12e7 (0:12e7)
+ResetUsingStrengthOutOfBattleBit: ; 12e7 (0:12e7)
 	ld hl, wd728
 	res 0, [hl]
 	ret
@@ -2400,4 +2401,4 @@ ForceBikeOrSurf:: ; 12ed (0:12ed)
 	ld b, BANK(RedSprite)
 	ld hl, LoadPlayerSpriteGraphics
 	call Bankswitch
-	jp Func_2307 ; update map/player state?
+	jp PlayDefaultMusic ; update map/player state?