From 43ec9ae7f74e745b7ccac7c34a253deeb9291c15 Mon Sep 17 00:00:00 2001
From: TiKevin83 <38826675+TiKevin83@users.noreply.github.com>
Date: Tue, 22 Jan 2019 14:30:41 -0500
Subject: Label functions, note cause of fast options

Some of the functions in here are unlabeled despite having decent labels in pokecrystal (GSC reused yellow's options code).  Updated the most relevant ones.
This code has a bug/feature called "fast options" that reappears due to its reuse in GSC, added some explanation of it in comments
---
 engine/menu/options.asm | 34 ++++++++++++++++++----------------
 1 file changed, 18 insertions(+), 16 deletions(-)

diff --git a/engine/menu/options.asm b/engine/menu/options.asm
index 7bed30ae..b6042ab9 100644
--- a/engine/menu/options.asm
+++ b/engine/menu/options.asm
@@ -1,16 +1,18 @@
 DisplayOptionMenu_:
-	call Func_41f06
+; executes each menu option's update function via GetOptionPointer, but the joypad isn't cleared until the ret back to optionMenuLoop
+; this results in the options each being shifted left or right if the respective button is pressed along with A while opening options
+	call InitOptions
 .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 +20,7 @@ DisplayOptionMenu_:
 .exitOptionMenu
 	ret
 
-Func_41c95:
+GetOptionPointer:
 	ld a, [wOptionsCursorLocation]
 	ld e, a
 	ld d, $0
@@ -28,7 +30,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 +43,7 @@ OptionMenuJumpTable:
 	dw OptionsMenu_Cancel
 
 OptionsMenu_TextSpeed:
-	call Func_41d07
+	call GetTextSpeed
 	ld a, [hJoy5]
 	bit 4, a ; right
 	jr nz, .pressedRight
@@ -96,7 +98,7 @@ MidText:
 SlowText:
 	db "SLOW@"
 
-Func_41d07:
+GetTextSpeed:
 	ld a, [wOptions]
 	and $f
 	cp $5
@@ -348,7 +350,7 @@ OptionsMenu_Cancel:
 	scf
 	ret
 
-Func_41eb7:
+OptionsControl:
 	ld hl, wOptionsCursorLocation
 	ld a, [hJoy5]
 	cp D_DOWN
@@ -388,7 +390,7 @@ Func_41eb7:
 	scf
 	ret
 
-Func_41ee9:
+OptionsMenu_UpdateCursorPosition:
 	coord hl, 1, 1
 	ld de, SCREEN_WIDTH
 	ld c, 16
@@ -404,7 +406,7 @@ Func_41ee9:
 	ld [hl], "▶"
 	ret
 
-Func_41f06:
+InitOptions:
 	coord hl, 0, 0
 	lb bc, SCREEN_HEIGHT - 2, SCREEN_WIDTH - 2
 	call TextBoxBorder
@@ -416,13 +418,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 options cursor
 	dec c
 	jr nz, .loop
 	xor a
-- 
cgit v1.2.3


From 3031dfab64772a44b6541114a3f15ae845390f4d Mon Sep 17 00:00:00 2001
From: TiKevin83 <38826675+TiKevin83@users.noreply.github.com>
Date: Wed, 23 Jan 2019 10:08:53 -0500
Subject: Note bug in Battle Transitions

---
 engine/battle/battle_transitions.asm | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/engine/battle/battle_transitions.asm b/engine/battle/battle_transitions.asm
index ec95a5d9..8f799867 100644
--- a/engine/battle/battle_transitions.asm
+++ b/engine/battle/battle_transitions.asm
@@ -91,6 +91,12 @@ GetBattleTransitionID_WildOrTrainer:
 	ret
 
 GetBattleTransitionID_CompareLevels:
+; no error handling to check if you have a Pokemon yet
+; this causes bugs with the transition in the Oak Pikachu catch
+; wPartyMon1HP reads from wRivalName+6
+; this causes the faster transition to be manipulable either by
+; using a default rival name or
+; setting and then deleting 6 characters in a custom Rival name
 	ld hl, wPartyMon1HP
 .faintedLoop
 	ld a, [hli]
-- 
cgit v1.2.3


From ec9072fed38f09cf0e035443608e0f060646a290 Mon Sep 17 00:00:00 2001
From: Travis McGeehan <tmcgeehan@macatawabank.com>
Date: Wed, 23 Jan 2019 13:22:30 -0500
Subject: Pull bug descriptions into documentation, add more relevant docs from
 pokecrystal

---
 docs/assembly_programming.md         | 25 ++++++++++++++++++++++
 docs/bugs_and_glitches.md            | 40 ++++++++++++++++++++++++++++++++++++
 engine/battle/battle_transitions.asm |  6 ------
 engine/menu/options.asm              |  4 +---
 4 files changed, 66 insertions(+), 9 deletions(-)
 create mode 100644 docs/assembly_programming.md
 create mode 100644 docs/bugs_and_glitches.md

diff --git a/docs/assembly_programming.md b/docs/assembly_programming.md
new file mode 100644
index 00000000..ca6cb9e3
--- /dev/null
+++ b/docs/assembly_programming.md
@@ -0,0 +1,25 @@
+# Assembly Programming
+
+- [**RGBDS documentation**][rgbds-doc]: Includes information on the RGBDS tools and the assembly language syntax.
+   - [**GBZ80 instructions**][gbz80-instructions]: List of CPU instructions and their effects.
+   - [**RGBASM features**][rgbasm-features]: How to use the assembler features: constants, labels, sections, macros, etc.
+   - [**RGBLINK features**][rgblink-features]: How to use the linker, including the [pokecrystal.link](/pokecrystal.link) linkerscript.
+- [**ASMSchool**][asmschool]: A gameboy assembly tutorial.
+- [**GB ASM Tutorial**][gb-asm-tutorial]: A newer but still in-progress asm tutorial.
+- [**Pan Docs**][pan-docs]: Everything You Always Wanted To Know About GAMEBOY (but were afraid to ask).
+- [**GameBoy Programming Manual**][gb-manual]: The official GameBoy programming and hardware manual by Nintendo.
+- [**GameBoy Opcode Summary**][gb-opcodes]: Describes the opcodes of GameBoy assembly language.
+- [**GameBoy Memory Map**][gb-memory-map]: Describes the GameBoy Color address space.
+- [**awesome-gbdev**][awesome-gbdev]: A curated list of Game Boy development resources such as tools, docs, emulators, related projects and open-source ROMs.
+
+[rgbds-doc]: https://rednex.github.io/rgbds/
+[rgbasm-features]: https://rednex.github.io/rgbds/rgbasm.5.html
+[rgblink-features]: https://rednex.github.io/rgbds/rgblink.5.html
+[gbz80-instructions]: https://rednex.github.io/rgbds/gbz80.7.html
+[asmschool]: http://gameboy.mongenel.com/asmschool.html
+[gb-asm-tutorial]: https://eldred.fr/gb-asm-tutorial/
+[pan-docs]: http://bgb.bircd.org/pandocs.htm
+[gb-manual]: https://ia801906.us.archive.org/19/items/GameBoyProgManVer1.1/GameBoyProgManVer1.1.pdf
+[gb-opcodes]: http://www.devrs.com/gb/files/opcodes.html
+[gb-memory-map]: http://gameboy.mongenel.com/dmg/asmmemmap.html
+[awesome-gbdev]: https://github.com/avivace/awesome-gbdev
\ No newline at end of file
diff --git a/docs/bugs_and_glitches.md b/docs/bugs_and_glitches.md
new file mode 100644
index 00000000..db564bda
--- /dev/null
+++ b/docs/bugs_and_glitches.md
@@ -0,0 +1,40 @@
+# Bugs and Glitches
+
+These are known bugs and glitches in the original Pokémon Yellow game: code that clearly does not work as intended, or that only works in limited circumstances but has the possibility to fail or crash.
+
+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)
+
+
+## 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 InitOptions
+```
+
+## 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](/engine/battle/battle_transitions.asm)
\ No newline at end of file
diff --git a/engine/battle/battle_transitions.asm b/engine/battle/battle_transitions.asm
index 8f799867..ec95a5d9 100644
--- a/engine/battle/battle_transitions.asm
+++ b/engine/battle/battle_transitions.asm
@@ -91,12 +91,6 @@ GetBattleTransitionID_WildOrTrainer:
 	ret
 
 GetBattleTransitionID_CompareLevels:
-; no error handling to check if you have a Pokemon yet
-; this causes bugs with the transition in the Oak Pikachu catch
-; wPartyMon1HP reads from wRivalName+6
-; this causes the faster transition to be manipulable either by
-; using a default rival name or
-; setting and then deleting 6 characters in a custom Rival name
 	ld hl, wPartyMon1HP
 .faintedLoop
 	ld a, [hli]
diff --git a/engine/menu/options.asm b/engine/menu/options.asm
index b6042ab9..e78ac2ee 100644
--- a/engine/menu/options.asm
+++ b/engine/menu/options.asm
@@ -1,6 +1,4 @@
 DisplayOptionMenu_:
-; executes each menu option's update function via GetOptionPointer, but the joypad isn't cleared until the ret back to optionMenuLoop
-; this results in the options each being shifted left or right if the respective button is pressed along with A while opening options
 	call InitOptions
 .optionMenuLoop
 	call JoypadLowSensitivity
@@ -424,7 +422,7 @@ InitOptions:
 	call GetOptionPointer ; updates the next option
 	pop bc
 	ld hl, wOptionsCursorLocation
-	inc [hl] ; moves the options cursor
+	inc [hl] ; moves the cursor for the highlighted option
 	dec c
 	jr nz, .loop
 	xor a
-- 
cgit v1.2.3


From 9c6657ec7c30820b2e536962ce891ebe6e570664 Mon Sep 17 00:00:00 2001
From: Travis McGeehan <tmcgeehan@macatawabank.com>
Date: Wed, 23 Jan 2019 13:27:22 -0500
Subject: tweak diff

---
 docs/bugs_and_glitches.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/bugs_and_glitches.md b/docs/bugs_and_glitches.md
index db564bda..5cda97f9 100644
--- a/docs/bugs_and_glitches.md
+++ b/docs/bugs_and_glitches.md
@@ -25,8 +25,9 @@ The bug also exists in pokegold and pokecrystal.
 **Fix:** Update [engine/menu/options.asm](/engine/menu/options.asm)
 
 ```diff
- DisplayOptionMenu_:
- +  call JoypadLowSensitivity
+  DisplayOptionMenu_:
++
++   call JoypadLowSensitivity
     call InitOptions
 ```
 
-- 
cgit v1.2.3


From 155521e3ab73cd9d8c78e40b2a0fb4cbefbf8b37 Mon Sep 17 00:00:00 2001
From: Travis McGeehan <tmcgeehan@macatawabank.com>
Date: Wed, 20 Feb 2019 13:54:13 -0500
Subject: Improve some labels in the Pikachu Follow code

---
 engine/pikachu_follow.asm | 6 +++---
 home/overworld.asm        | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

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
-- 
cgit v1.2.3


From 51780b586d45d1743eb73101c0923be9f232aa44 Mon Sep 17 00:00:00 2001
From: Travis McGeehan <tmcgeehan@macatawabank.com>
Date: Wed, 20 Feb 2019 13:54:45 -0500
Subject: Add descriptions of Pikawalk and Counter damage.  Move
 assembly_programming.md elsewhere

---
 docs/assembly_programming.md | 25 -------------------------
 docs/bugs_and_glitches.md    | 24 +++++++++++++++++++++---
 2 files changed, 21 insertions(+), 28 deletions(-)
 delete mode 100644 docs/assembly_programming.md

diff --git a/docs/assembly_programming.md b/docs/assembly_programming.md
deleted file mode 100644
index ca6cb9e3..00000000
--- a/docs/assembly_programming.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# Assembly Programming
-
-- [**RGBDS documentation**][rgbds-doc]: Includes information on the RGBDS tools and the assembly language syntax.
-   - [**GBZ80 instructions**][gbz80-instructions]: List of CPU instructions and their effects.
-   - [**RGBASM features**][rgbasm-features]: How to use the assembler features: constants, labels, sections, macros, etc.
-   - [**RGBLINK features**][rgblink-features]: How to use the linker, including the [pokecrystal.link](/pokecrystal.link) linkerscript.
-- [**ASMSchool**][asmschool]: A gameboy assembly tutorial.
-- [**GB ASM Tutorial**][gb-asm-tutorial]: A newer but still in-progress asm tutorial.
-- [**Pan Docs**][pan-docs]: Everything You Always Wanted To Know About GAMEBOY (but were afraid to ask).
-- [**GameBoy Programming Manual**][gb-manual]: The official GameBoy programming and hardware manual by Nintendo.
-- [**GameBoy Opcode Summary**][gb-opcodes]: Describes the opcodes of GameBoy assembly language.
-- [**GameBoy Memory Map**][gb-memory-map]: Describes the GameBoy Color address space.
-- [**awesome-gbdev**][awesome-gbdev]: A curated list of Game Boy development resources such as tools, docs, emulators, related projects and open-source ROMs.
-
-[rgbds-doc]: https://rednex.github.io/rgbds/
-[rgbasm-features]: https://rednex.github.io/rgbds/rgbasm.5.html
-[rgblink-features]: https://rednex.github.io/rgbds/rgblink.5.html
-[gbz80-instructions]: https://rednex.github.io/rgbds/gbz80.7.html
-[asmschool]: http://gameboy.mongenel.com/asmschool.html
-[gb-asm-tutorial]: https://eldred.fr/gb-asm-tutorial/
-[pan-docs]: http://bgb.bircd.org/pandocs.htm
-[gb-manual]: https://ia801906.us.archive.org/19/items/GameBoyProgManVer1.1/GameBoyProgManVer1.1.pdf
-[gb-opcodes]: http://www.devrs.com/gb/files/opcodes.html
-[gb-memory-map]: http://gameboy.mongenel.com/dmg/asmmemmap.html
-[awesome-gbdev]: https://github.com/avivace/awesome-gbdev
\ No newline at end of file
diff --git a/docs/bugs_and_glitches.md b/docs/bugs_and_glitches.md
index 5cda97f9..e1c0527a 100644
--- a/docs/bugs_and_glitches.md
+++ b/docs/bugs_and_glitches.md
@@ -1,6 +1,6 @@
 # Bugs and Glitches
 
-These are known bugs and glitches in the original Pokémon Yellow game: code that clearly does not work as intended, or that only works in limited circumstances but has the possibility to fail or crash.
+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:
 
@@ -15,7 +15,8 @@ Fixes are written in the `diff` format. If you've used Git before, this should l
 
 - [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
 
@@ -38,4 +39,21 @@ The Battle Transitions code has no error handling for this and reads wPartyMon1H
 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](/engine/battle/battle_transitions.asm)
\ No newline at end of file
+**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)
\ No newline at end of file
-- 
cgit v1.2.3


From 08733d85ff358f38f80909b053e9adea6c3f1baa Mon Sep 17 00:00:00 2001
From: TiKevin83 <travismcgeehan@gmail.com>
Date: Mon, 18 May 2020 01:54:54 -0400
Subject: Fix duplicate label

---
 engine/menu/options.asm | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/engine/menu/options.asm b/engine/menu/options.asm
index e78ac2ee..da89ad82 100644
--- a/engine/menu/options.asm
+++ b/engine/menu/options.asm
@@ -1,5 +1,5 @@
 DisplayOptionMenu_:
-	call InitOptions
+	call InitOptionsMenu
 .optionMenuLoop
 	call JoypadLowSensitivity
 	ld a, [hJoy5]
@@ -404,7 +404,7 @@ OptionsMenu_UpdateCursorPosition:
 	ld [hl], "▶"
 	ret
 
-InitOptions:
+InitOptionsMenu:
 	coord hl, 0, 0
 	lb bc, SCREEN_HEIGHT - 2, SCREEN_WIDTH - 2
 	call TextBoxBorder
-- 
cgit v1.2.3


From 45576fef167039b9a26d48b93c54d77275957874 Mon Sep 17 00:00:00 2001
From: TiKevin83 <38826675+TiKevin83@users.noreply.github.com>
Date: Mon, 18 May 2020 12:26:11 -0400
Subject: Update bugs_and_glitches.md

Sync with fixed duplicate label
---
 docs/bugs_and_glitches.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/bugs_and_glitches.md b/docs/bugs_and_glitches.md
index e1c0527a..a82a52a8 100644
--- a/docs/bugs_and_glitches.md
+++ b/docs/bugs_and_glitches.md
@@ -29,7 +29,7 @@ The bug also exists in pokegold and pokecrystal.
   DisplayOptionMenu_:
 +
 +   call JoypadLowSensitivity
-    call InitOptions
+    call InitOptionsMenu
 ```
 
 ## Battle Transitions Fail to Account for Scripted Battles
@@ -56,4 +56,4 @@ A typical use for this would be to force the in game time to 255:59.
 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)
\ No newline at end of file
+**Fix:** TBD in [engine/battle/core.asm#L4960](/engine/battle/core.asm#L4960)
-- 
cgit v1.2.3