Merge pull request #39 from TiKevin83/master

Label functions, note causes of bugs

4 files changed, 81 insertions, 22 deletions

diff --git a/docs/bugs_and_glitches.md b/docs/bugs_and_glitches.md
new file mode 100644
index 00000000..a82a52a8
--- /dev/null
+++ b/docs/bugs_and_glitches.md
@@ -0,0 +1,59 @@
+# Bugs and Glitches
+
+These are sections of the original Pokémon Yellow game code that clearly do not work as intended or only work in limited circumstances.
+
+Fixes are written in the `diff` format. If you've used Git before, this should look familiar:
+
+```diff
+ this is some code
+-delete red - lines
++add green + lines
+```
+
+
+## Contents
+
+- [Options Menu Code Fails to Clear Joypad State on Initialization](#options-menu-code-fails-to-clear-joypad-state-on-initialization)
+- [Battle Transitions Fail to Account for Scripted Battles](#battle-transitions-fail-to-account-for-scripted-battles)
+- [wPikachuFollowCommandBuffer can Overflow](#wpikachufollowcommandbuffer-can-overflow)
+- [Unexpected Counter Damage](#unexpected-counter-damage)
+
+## Options Menu Code Fails to Clear Joypad State on Initialization
+
+This bug (or feature!) results in all options being shifted left or right if the respective direction is pressed on the same frame the options menu is opened.
+The bug also exists in pokegold and pokecrystal.
+
+**Fix:** Update [engine/menu/options.asm](/engine/menu/options.asm)
+
+```diff
+  DisplayOptionMenu_:
++
++   call JoypadLowSensitivity
+    call InitOptionsMenu
+```
+
+## Battle Transitions Fail to Account for Scripted Battles
+
+When Oak Catches Pikachu in the Pallet Town cutscenes you don't yet have any Pokemon in Party.
+The Battle Transitions code has no error handling for this and reads wPartyMon1HP from wRivalName+6.
+This means you can manipulate this first transition to be faster by choosing a default rival name or writing and deleting 6 characters in a custom rival name.
+A similar series of bugs appears to exist in pokecrystal.
+
+**Fix:** TBD in [engine/battle/battle_transitions.asm#L93](/engine/battle/battle_transitions.asm#L93)
+
+## wPikachuFollowCommandBuffer can Overflow
+
+AppendPikachuFollowCommandToBuffer doesn't have any length checking for the buffer of Pikachu commands.
+This can be abused to write data into any address past d437, typically by putting pikachu to sleep in the Pewter Center with Jigglypuff.
+While in this state, walking down writes 01, up 02, left 03, and right 04.
+This bug is generally known as "Pikawalk."
+A typical use for this would be to force the in game time to 255:59.
+
+**Fix:** TBD in [engine/pikachu_follow.asm#1165](/engine/pikachu_follow.asm#1165)
+
+## Unexpected Counter Damage
+
+Counter simply doubles the value of wDamage which can hold the last value of damage dealt whether it was from you, your opponent, a switched out opponent, or a player in another battle.
+This is because wDamage is used for both the player's damage and opponent's damage, and is not cleared out between switching or battles.
+
+**Fix:** TBD in [engine/battle/core.asm#L4960](/engine/battle/core.asm#L4960)
diff --git a/engine/menu/options.asm b/engine/menu/options.asm
index 7bed30ae..da89ad82 100644
--- a/engine/menu/options.asm
+++ b/engine/menu/options.asm
@@ -1,16 +1,16 @@
 DisplayOptionMenu_:
-	call Func_41f06
+	call InitOptionsMenu
 .optionMenuLoop
 	call JoypadLowSensitivity
 	ld a, [hJoy5]
 	and START | B_BUTTON
 	jr nz, .exitOptionMenu
-	call Func_41eb7
-	jr c, .asm_41c86
-	call Func_41c95
+	call OptionsControl
+	jr c, .dpadDelay
+	call GetOptionPointer
 	jr c, .exitOptionMenu
-.asm_41c86
-	call Func_41ee9
+.dpadDelay
+	call OptionsMenu_UpdateCursorPosition
 	call DelayFrame
 	call DelayFrame
 	call DelayFrame
@@ -18,7 +18,7 @@ DisplayOptionMenu_:
 .exitOptionMenu
 	ret
 
-Func_41c95:
+GetOptionPointer:
 	ld a, [wOptionsCursorLocation]
 	ld e, a
 	ld d, $0
@@ -28,7 +28,7 @@ Func_41c95:
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
-	jp hl
+	jp hl ; jump to the function for the current highlighted option
 
 OptionMenuJumpTable:
 	dw OptionsMenu_TextSpeed
@@ -41,7 +41,7 @@ OptionMenuJumpTable:
 	dw OptionsMenu_Cancel
 
 OptionsMenu_TextSpeed:
-	call Func_41d07
+	call GetTextSpeed
 	ld a, [hJoy5]
 	bit 4, a ; right
 	jr nz, .pressedRight
@@ -96,7 +96,7 @@ MidText:
 SlowText:
 	db "SLOW@"
 
-Func_41d07:
+GetTextSpeed:
 	ld a, [wOptions]
 	and $f
 	cp $5
@@ -348,7 +348,7 @@ OptionsMenu_Cancel:
 	scf
 	ret
 
-Func_41eb7:
+OptionsControl:
 	ld hl, wOptionsCursorLocation
 	ld a, [hJoy5]
 	cp D_DOWN
@@ -388,7 +388,7 @@ Func_41eb7:
 	scf
 	ret
 
-Func_41ee9:
+OptionsMenu_UpdateCursorPosition:
 	coord hl, 1, 1
 	ld de, SCREEN_WIDTH
 	ld c, 16
@@ -404,7 +404,7 @@ Func_41ee9:
 	ld [hl], "▶"
 	ret
 
-Func_41f06:
+InitOptionsMenu:
 	coord hl, 0, 0
 	lb bc, SCREEN_HEIGHT - 2, SCREEN_WIDTH - 2
 	call TextBoxBorder
@@ -416,13 +416,13 @@ Func_41f06:
 	call PlaceString
 	xor a
 	ld [wOptionsCursorLocation], a
-	ld c, 5
+	ld c, 5 ; the number of options to loop through
 .loop
 	push bc
-	call Func_41c95
+	call GetOptionPointer ; updates the next option
 	pop bc
 	ld hl, wOptionsCursorLocation
-	inc [hl]
+	inc [hl] ; moves the cursor for the highlighted option
 	dec c
 	jr nz, .loop
 	xor a
diff --git a/engine/pikachu_follow.asm b/engine/pikachu_follow.asm
index 6092eabe..db5fa0ee 100755
--- a/engine/pikachu_follow.asm
+++ b/engine/pikachu_follow.asm
@@ -182,7 +182,7 @@ CalculatePikachuFacingDirection::
 	ld [wSpritePikachuStateData1FacingDirection], a
 	ret
 
-CalculatePikachuSpawnState1::
+SetPikachuSpawnOutside::
 	ld a, [wCurMap]
 	cp OAKS_LAB
 	jr z, .oaks_lab
@@ -254,7 +254,7 @@ Pointer_fc653::
 	db FUCHSIA_HOUSE_3
 	db $ff
 
-CalculatePikachuSpawnState2::
+SetPikachuSpawnWarpPad::
 	ld a, [wCurMap]
 	cp VIRIDIAN_FOREST_EXIT
 	jr z, .viridian_forest_exit
@@ -302,7 +302,7 @@ Pointer_fc68e::
 	db CINNABAR_LAB_4
 	db $ff
 
-CalculatePikachuSpawnState3::
+SetPikachuSpawnBackOutside::
 	ld a, [wCurMap]
 	cp ROUTE_22_GATE
 	jr z, .asm_fc6a7
diff --git a/home/overworld.asm b/home/overworld.asm
index 9c53a3be..8b635aa5 100644
--- a/home/overworld.asm
+++ b/home/overworld.asm
@@ -473,7 +473,7 @@ WarpFound2::
 	ld [wMapPalOffset], a
 	call GBFadeOutToBlack
 .notRockTunnel
-	callab CalculatePikachuSpawnState1
+	callab SetPikachuSpawnOutside
 	call PlayMapChangeSound
 	jr .done
 
@@ -500,11 +500,11 @@ WarpFound2::
 	ld hl, wd736
 	res 0, [hl]
 	res 1, [hl]
-	callab CalculatePikachuSpawnState2
+	callab SetPikachuSpawnWarpPad
 	jr .done
 
 .goBackOutside
-	callab CalculatePikachuSpawnState3
+	callab SetPikachuSpawnBackOutside
 	ld a, [wLastMap]
 	ld [wCurMap], a
 	call PlayMapChangeSound