Comment some bank 0 functions, and add wram labels for Predef.

engine/battle/4.asm

@@ -16,12 +16,12 @@ Func_128ea: ; 128ea (4:68ea)
 	ret
 
 Func_128ef: ; 128ef (4:68ef)
-	call Load16BitRegisters
+	call GetPredefRegisters
 	ld a, $1
 	jr asm_128fb
 
 Func_128f6: ; 128f6 (4:68f6)
-	call Load16BitRegisters
+	call GetPredefRegisters
 	ld a, $2
 asm_128fb: ; 128fb (4:68fb)
 	ld [wListMenuID], a ; $cf94

engine/battle/9.asm

@@ -1,5 +1,5 @@
 Func_27d6b: ; 27d6b (9:7d6b)
-	call Load16BitRegisters
+	call GetPredefRegisters
 	push hl
 	call GetMonHeader
 	pop hl
@@ -26,7 +26,7 @@ asm_27d8c: ; 27d8c (9:7d8c)
 	jp FillMemory
 
 Func_27d98: ; 27d98 (9:7d98)
-	call Load16BitRegisters
+	call GetPredefRegisters
 	push hl
 	ld a, [W_PLAYERMOVETYPE] ; $cfd5
 asm_27d9f: ; 27d9f (9:7d9f)

engine/battle/animations.asm

@@ -2509,7 +2509,7 @@ Func_79aae: ; 79aae (1e:5aae)
 	jr asm_79acb
 
 Func_79aba: ; 79aba (1e:5aba)
-	call Load16BitRegisters
+	call GetPredefRegisters
 	ld a, [$cd6c]
 	and a
 	jr nz, .asm_79ac8
@@ -2790,7 +2790,7 @@ AnimationShakeEnemyHUD: ; 79d77 (1e:5d77)
 	jp Func_79e0d
 
 Func_79dda: ; 79dda (1e:5dda)
-	call Load16BitRegisters
+	call GetPredefRegisters
 	ld a, c
 	ld [H_DOWNARROWBLINKCNT1], a ; $ff8b
 	ld a, b

engine/cable_club.asm

@@ -919,7 +919,7 @@ Func_5aaf: ; 5aaf (1:5aaf)
 	ret
 
 Func_5ab0:
-	call Load16BitRegisters
+	call GetPredefRegisters
 
 Func_5ab3: ; 5ab3 (1:5ab3)
 	push hl

engine/evos_moves.asm

@@ -372,7 +372,7 @@ Func_3af5b: ; 3af5b (e:6f5b)
 ; move slots are being filled up sequentially and shifted if all slots are full
 ; [$cee9]: (?)
 WriteMonMoves: ; 3afb8 (e:6fb8)
-	call Load16BitRegisters
+	call GetPredefRegisters
 	push hl
 	push de
 	push bc

engine/hp_bar.asm

@@ -1,5 +1,5 @@
 UpdateHPBar_LoadRegisters: ; f9dc (3:79dc)
-	call Load16BitRegisters
+	call GetPredefRegisters
 
 ; calculates bc * 48 / de, the number of pixels the HP bar has
 ; the result is always at least 1
@@ -72,7 +72,7 @@ UpdateHPBar: ; fa1d (3:7a1d)
 	ld a, $1
 .HPdecrease
 	ld [wHPBarDelta], a
-	call Load16BitRegisters
+	call GetPredefRegisters
 	ld a, [wHPBarNewHP]
 	ld e, a
 	ld a, [wHPBarNewHP+1]

engine/items/itemfinder.asm

@@ -4,7 +4,7 @@ HiddenItemNear: ; 7481f (1d:481f)
 .asm_74824
 	ld de, $0003
 	ld a, [W_CURMAP]
-	call IsInArrayCummulativeCount
+	call IsInRestOfArray
 	ret nc ; return if current map has no hidden items
 	push bc
 	push hl

engine/menu/naming_screen.asm

@@ -1,6 +1,6 @@
 AskForMonNickname: ; 64eb (1:64eb)
 	call SaveScreenTilesToBuffer1
-	call Load16BitRegisters
+	call GetPredefRegisters
 	push hl
 	ld a, [W_ISINBATTLE] ; $d057
 	dec a

engine/oak_speech.asm

@@ -211,7 +211,7 @@ MovePicLeft: ; 6288 (1:6288)
 	jr .next
 
 Predef3B: ; 62a1 (1:62a1)
-	call Load16BitRegisters
+	call GetPredefRegisters
 IntroPredef3B: ; 62a4 (1:62a4)
 ; bank of sprite given in b
 	push bc

engine/palettes.asm

@@ -1,5 +1,5 @@
 Func_71ddf: ; 71ddf (1c:5ddf)
-	call Load16BitRegisters
+	call GetPredefRegisters
 	ld a, b
 	cp $ff
 	jr nz, .asm_71dea

engine/predefs12.asm

@@ -1,5 +1,5 @@
 Func_480eb: ; 480eb (12:40eb)
-	call Load16BitRegisters
+	call GetPredefRegisters
 	ld a, [rBGP] ; $ff47
 	or b
 	ld [rBGP], a ; $ff47
@@ -11,7 +11,7 @@ Func_480eb: ; 480eb (12:40eb)
 	ret
 
 Func_480ff: ; 480ff (12:40ff)
-	call Load16BitRegisters
+	call GetPredefRegisters
 	ld a, $1
 	ld [$d0a0], a
 	xor a
@@ -35,7 +35,7 @@ Func_48119: ; 48119 (12:4119)
 	jp DelayFrames
 
 Func_48125: ; 48125 (12:4125)
-	call Load16BitRegisters
+	call GetPredefRegisters
 	xor a
 .asm_48129
 	ld [$ff97], a

engine/predefs17_2.asm

@@ -1,6 +1,6 @@
 ; updates the types of a party mon (pointed to in hl) to the ones of the mon specified in $d11e
 SetPartyMonTypes: ; 5db5e (17:5b5e)
-	call Load16BitRegisters
+	call GetPredefRegisters
 	ld bc, W_PARTYMON1_TYPE1 - W_PARTYMON1DATA ; $5
 	add hl, bc
 	ld a, [$d11e]

main.asm

@@ -926,9 +926,10 @@ MapEntryAfterBattle:: ; 091f (0:091f)
 	jp z,GBFadeIn2
 	jp LoadGBPal
 
-; for when all the player's pokemon faint
+HandleBlackOut::
-; other code prints the "you blacked out" message before this is called
+; For when all the player's pokemon faint.
-HandleBlackOut:: ; 0931 (0:0931)
+; Does not print the "blacked out" message.
+
 	call GBFadeIn1
 	ld a, $08
 	call StopMusic
@@ -942,19 +943,19 @@ HandleBlackOut:: ; 0931 (0:0931)
 	call Func_2312
 	jp Func_5d5f
 
-StopMusic:: ; 0951 (0:0951)
+StopMusic::
 	ld [wMusicHeaderPointer], a
 	ld a, $ff
 	ld [$c0ee], a
 	call PlaySound
-.waitLoop
+.wait
 	ld a, [wMusicHeaderPointer]
 	and a
-	jr nz,.waitLoop
+	jr nz, .wait
 	jp StopAllSounds
 
-HandleFlyOrTeleportAway:: ; 0965 (0:0965)
+HandleFlyOrTeleportAway::
-	call UpdateSprites ; move sprites
+	call UpdateSprites
 	call Delay3
 	xor a
 	ld [$cf0b], a
@@ -971,29 +972,39 @@ HandleFlyOrTeleportAway:: ; 0965 (0:0965)
 	call Func_62ce
 	jp Func_5d5f
 
-; function that calls a function to do fly away or teleport away graphics
+DoFlyOrTeleportAwayGraphics::
-DoFlyOrTeleportAwayGraphics:: ; 098f (0:098f)
 	ld b, BANK(_DoFlyOrTeleportAwayGraphics)
 	ld hl, _DoFlyOrTeleportAwayGraphics
 	jp Bankswitch
 
-; load sprite graphics based on whether the player is standing, biking, or surfing
+LoadPlayerSpriteGraphics::
-LoadPlayerSpriteGraphics:: ; 0997 (0:0997)
+; Load sprite graphics based on whether the player is standing, biking, or surfing.
+
+	; 0: standing
+	; 1: biking
+	; 2: surfing
+
 	ld a, [$d700]
 	dec a
 	jr z, .ridingBike
+
 	ld a, [$ffd7]
 	and a
 	jr nz, .determineGraphics
 	jr .startWalking
+
 .ridingBike
+	; If the bike can't be used,
+	; start walking instead.
 	call IsBikeRidingAllowed
-	jr c,.determineGraphics ; don't start walking if bike riding is allowed
+	jr c, .determineGraphics
+
 .startWalking
 	xor a
 	ld [$d700], a
 	ld [$d11a], a
 	jp LoadWalkingPlayerSpriteGraphics
+
 .determineGraphics
 	ld a, [$d700]
 	and a
@@ -1004,14 +1015,17 @@ LoadPlayerSpriteGraphics:: ; 0997 (0:0997)
 	jp z, LoadSurfingPlayerSpriteGraphics
 	jp LoadWalkingPlayerSpriteGraphics
 
-; function to check if bike riding is allowed on the current map
+IsBikeRidingAllowed::
-; sets carry if bike is allowed, clears carry otherwise
+; The bike can be used on Route 23 and Indigo Plateau,
-IsBikeRidingAllowed:: ; 09c5 (0:09c5)
+; or maps with tilesets in BikeRidingTilesets.
+; Return carry if biking is allowed.
+
 	ld a, [W_CURMAP]
-	cp a,ROUTE_23
+	cp ROUTE_23
 	jr z, .allowed
-	cp a,INDIGO_PLATEAU
+	cp INDIGO_PLATEAU
 	jr z, .allowed
+
 	ld a, [W_CURMAPTILESET]
 	ld b, a
 	ld hl, BikeRidingTilesets
@@ -1023,6 +1037,7 @@ IsBikeRidingAllowed:: ; 09c5 (0:09c5)
 	jr nz, .loop
 	and a
 	ret
+
 .allowed
 	scf
 	ret
@@ -2584,13 +2599,10 @@ Func_12e7:: ; 12e7 (0:12e7)
 	res 0, [hl]
 	ret
 
-;appears to be called twice inside function $C38B
-;if $d700,$d11a == $1 then biking
-;if $d700,$d11a == $2 then surfing
 ForceBikeOrSurf:: ; 12ed (0:12ed)
-	ld b,5 ;graphics bank 5
+	ld b, BANK(RedSprite)
-	ld hl,LoadPlayerSpriteGraphics ;load player sprite graphics
+	ld hl, LoadPlayerSpriteGraphics
-	call Bankswitch ;loads bank 5 and then calls LoadPlayerSpriteGraphics
+	call Bankswitch
 	jp Func_2307 ; update map/player state?
 
 ; this is used to check if the player wants to interrupt the opening sequence at several points
@@ -2626,7 +2638,7 @@ LoadDestinationWarpPosition:: ; 1313 (0:1313)
 	ld b,a
 	ld a,[H_LOADEDROMBANK]
 	push af
-	ld a,[$cf12]
+	ld a,[wPredefParentBank]
 	ld [H_LOADEDROMBANK],a
 	ld [$2000],a
 	ld a,b
@@ -9804,31 +9816,34 @@ CallFunctionInTable:: ; 3d97 (0:3d97)
 	pop hl
 	ret
 
-; searches an array at hl for the value in a.
-; skips (de − 1) bytes between reads, so to check every byte, de should be 1.
-; if found, returns count in b and sets carry.
-IsInArray:: ; 3dab (0:3dab)
-	ld b,0
-	; fall through
 
-IsInArrayCummulativeCount:: ; 3dad (0:3dad)
+IsInArray::
+; Search an array at hl for the value in a.
+; Entry size is de bytes.
+; Return count b and carry if found.
+	ld b, 0
+
+IsInRestOfArray::
 	ld c, a
 .loop
 	ld a, [hl]
-	cp a,$FF
+	cp -1
-	jr z,.NotInArray
+	jr z, .notfound
 	cp c
-	jr z,.InArray
+	jr z, .found
 	inc b
 	add hl, de
 	jr .loop
-.NotInArray
+
+.notfound
 	and a
 	ret
-.InArray
+
+.found
 	scf
 	ret
 
+
 Func_3dbe:: ; 3dbe (0:3dbe)
 	call CleanLCD_OAM
 	ld a, $1
@@ -9839,31 +9854,33 @@ Func_3dbe:: ; 3dbe (0:3dbe)
 	call GoPAL_SET_CF1C
 	jr Delay3
 
-; calls GBPalWhiteOut and then Delay3
+
-GBPalWhiteOutWithDelay3:: ; 3dd4 (0:3dd4)
+GBPalWhiteOutWithDelay3::
 	call GBPalWhiteOut
 
-Delay3:: ; 3dd7 (0:3dd7)
+Delay3::
-; call Delay with a parameter of 3
+; The bg map is updated each frame in thirds.
+; Wait three frames to let the bg map fully update.
 	ld c, 3
 	jp DelayFrames
 
-; resets BGP and OBP0 to their usual colors
+GBPalNormal::
-GBPalNormal:: ; 3ddc (0:3ddc)
+; Reset BGP and OBP0.
-	ld a,%11100100
+	ld a, %11100100 ; 3210
 	ld [rBGP], a
-	ld a,%11010000
+	ld a, %11010000 ; 3100
 	ld [rOBP0], a
 	ret
 
-; makes all palette colors white
+GBPalWhiteOut::
-GBPalWhiteOut:: ; 3de5 (0:3de5)
+; White out all palettes.
 	xor a
 	ld [rBGP],a
 	ld [rOBP0],a
 	ld [rOBP1],a
 	ret
 
+
 GoPAL_SET_CF1C:: ; 3ded (0:3ded)
 	ld b,$ff
 GoPAL_SET:: ; 3def (0:3def)
@@ -9945,54 +9962,59 @@ GenRandom:: ; 3e5c (0:3e5c)
 	pop hl
 	ret
 
-Predef:: ; 3e6d (0:3e6d)
-; runs a predefined ASM command, where the command ID is read from $D0B7
-; $3E6D grabs the ath pointer from PredefPointers and executes it
 
-	ld [$CC4E],a ; save the predef routine's ID for later
+Predef::
+; Call predefined function a.
+; To preserve other registers, have the
+; destination call GetPredefRegisters.
 
+	; Save the predef id for GetPredefPointer.
+	ld [wPredefID], a
+
+	; A hack for LoadDestinationWarpPosition.
+	; See Func_c754 (predef $19).
 	ld a, [H_LOADEDROMBANK]
-	ld [$CF12],a
+	ld [wPredefParentBank], a
 
-	; save bank and call 13:7E49
 	push af
 	ld a, BANK(GetPredefPointer)
 	ld [H_LOADEDROMBANK], a
 	ld [$2000], a
+
 	call GetPredefPointer
 
-	; call the predef function
+	ld a, [wPredefBank]
-	; ($D0B7 has the bank of the predef routine)
-	ld a,[$D0B7]
 	ld [H_LOADEDROMBANK], a
 	ld [$2000], a
-	ld de,.Return
+
+	ld de, .done
 	push de
 	jp [hl]
-	; after the predefined function finishes it returns here
+.done
-.Return
+
 	pop af
 	ld [H_LOADEDROMBANK], a
 	ld [$2000], a
 	ret
 
-;loads hl from cc4f, de from cc51, and bc from cc53
+GetPredefRegisters::
-
+; Restore the contents of register pairs
-Load16BitRegisters:: ; 3e94 (0:3e94)
+; when GetPredefPointer was called.
-	ld a, [$cc4f]
+	ld a, [wPredefRegisters + 0]
 	ld h, a
-	ld a, [$cc50]
+	ld a, [wPredefRegisters + 1]
 	ld l, a
-	ld a, [$cc51]
+	ld a, [wPredefRegisters + 2]
 	ld d, a
-	ld a, [$cc52]
+	ld a, [wPredefRegisters + 3]
 	ld e, a
-	ld a, [$cc53]
+	ld a, [wPredefRegisters + 4]
 	ld b, a
-	ld a, [$cc54]
+	ld a, [wPredefRegisters + 5]
 	ld c, a
 	ret
 
+
 Func_3ead:: ; 3ead (0:3ead)
 	ld b, BANK(CinnabarGymQuiz_1eb0a)
 	ld hl, CinnabarGymQuiz_1eb0a
@@ -13514,7 +13536,7 @@ SafariBallText: ; c57e (3:457e)
 	db "BALL×× @"
 
 Func_c586: ; c586 (3:4586)
-	call Load16BitRegisters
+	call GetPredefRegisters
 
 Func_c589: ; c589 (3:4589)
 	ld a, [W_YCOORD] ; $d361
@@ -13814,7 +13836,7 @@ Func_c69c: ; c69c (3:469c)
 	ret
 
 Func_c754: ; c754 (3:4754)
-	call Load16BitRegisters
+	call GetPredefRegisters
 	push hl
 	ld d, $0
 	ld a, [W_CURMAPTILESET] ; $d367
@@ -14265,7 +14287,7 @@ GymLeaderFaceAndBadgeTileGraphics: ; ea9e (3:6a9e)
 	INCBIN "gfx/badges.w16.2bpp"
 
 Func_ee9e: ; ee9e (3:6e9e)
-	call Load16BitRegisters
+	call GetPredefRegisters
 	ld hl, $c6e8
 	ld a, [W_CURMAPWIDTH] ; $d369
 	add $6
@@ -14942,7 +14964,7 @@ _AddPokemonToParty: ; f2e5 (3:72e5)
 	ret
 
 LoadMovePPs: ; f473 (3:7473)
-	call Load16BitRegisters
+	call GetPredefRegisters
 	; fallthrough
 AddPokemonToParty_WriteMovePP: ; f476 (3:7476)
 	ld b, $4
@@ -15216,7 +15238,7 @@ Func_f51e: ; f51e (3:751e)
 ; hl: base address
 ; c: bit index
 HandleBitArray: ; f666 (3:7666)
-	call Load16BitRegisters
+	call GetPredefRegisters
 
 _HandleBitArray: ; f669 (3:7669)
 	push hl
@@ -15359,7 +15381,7 @@ HealParty: ; f6a5 (3:76a5)
 ; predef $d
 ; predef $e
 Func_f71e: ; f71e (3:771e)
-	call Load16BitRegisters
+	call GetPredefRegisters
 	xor a
 	ld [$ffa5], a
 	ld [$ffa6], a
@@ -15512,7 +15534,7 @@ Func_f800: ; f800 (3:7800)
 	jr .asm_f803
 
 Func_f81d: ; f81d (3:781d)
-	call Load16BitRegisters
+	call GetPredefRegisters
 	and a
 	ld b, c
 .asm_f822
@@ -15536,7 +15558,7 @@ Func_f81d: ; f81d (3:781d)
 	ret
 
 Func_f836: ; f836 (3:7836)
-	call Load16BitRegisters
+	call GetPredefRegisters
 
 Func_f839: ; f839 (3:7839)
 	and a
@@ -15607,7 +15629,7 @@ InitializeEmptyList: ; f8a0 (3:78a0)
 	ret
 
 IsItemInBag_: ; f8a5 (3:78a5)
-	call Load16BitRegisters
+	call GetPredefRegisters
 	ld hl, wNumBagItems ; $d31d
 .asm_f8ab
 	inc hl

wram.asm

@@ -140,7 +140,12 @@ wMenuWrappingEnabled:: ; cc4a
 ; set to 0 if you can't go past the top or bottom of the menu
 	ds 1
 
-	ds 10
+	ds 3
+
+wPredefID:: ; cc4e
+	ds 1
+wPredefRegisters:: ; cc4f
+	ds 6
 
 wTrainerHeaderFlagBit:: ; cc55
 	ds 1
@@ -288,7 +293,12 @@ wAnimSoundID:: ; cf07
 ; sound ID during battle animations
 	ds 1
 
-	ds 12
+	ds 10
+
+wPredefParentBank:: ; cf12
+	ds 1
+
+	ds 1
 
 wCurSpriteMovement2:: ; cf14
 ; movement byte 2 of current sprite
@@ -707,6 +717,7 @@ W_SPRITEDECODETABLE1PTR:: ; d0b3
 W_LISTTYPE:: ; d0b6
 	ds 1
 
+wPredefBank:: ; d0b7
 	ds 1
 
 W_MONHEADER:: ; d0b8