Pull bug descriptions into documentation, add more relevant docs from pokecrystal

4 files changed, 66 insertions, 9 deletions

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