Merge remote-tracking branch 'origin/master' into chaos_requests-tppfork

32 files changed, 147 insertions, 121 deletions

diff --git a/constants.asm b/constants.asm
index f91532d..b4349bc 100644
--- a/constants.asm
+++ b/constants.asm
@@ -3,6 +3,7 @@ INCLUDE "vram.asm"
 INCLUDE "gbhw.asm"
 
 INCLUDE "constants/ball_types.asm"
+INCLUDE "constants/bonus_stage_order_constants.asm"
 INCLUDE "constants/diglett_stage_constants.asm"
 INCLUDE "constants/evolution_line_constants.asm"
 INCLUDE "constants/evolution_type_constants.asm"
diff --git a/constants/bonus_stage_order_constants.asm b/constants/bonus_stage_order_constants.asm
new file mode 100755
index 0000000..dd226a5
--- /dev/null
+++ b/constants/bonus_stage_order_constants.asm
@@ -0,0 +1,6 @@
+; See wNextBonusStage

+BONUS_STAGE_ORDER_GENGAR  EQU 0

+BONUS_STAGE_ORDER_MEWTWO  EQU 1

+BONUS_STAGE_ORDER_MEOWTH  EQU 2

+BONUS_STAGE_ORDER_DIGLETT EQU 3

+BONUS_STAGE_ORDER_SEEL    EQU 4

diff --git a/constants/stage_constants.asm b/constants/stage_constants.asm
index 600abf9..7f4cd73 100644
--- a/constants/stage_constants.asm
+++ b/constants/stage_constants.asm
@@ -4,6 +4,8 @@ STAGE_RED_FIELD_BOTTOM   EQU $1
 ; XXX EQU $3
 STAGE_BLUE_FIELD_TOP     EQU $4
 STAGE_BLUE_FIELD_BOTTOM  EQU $5
+
+FIRST_BONUS_STAGE        EQU $6
 ; STAGE_GENGAR_BONUS     EQU $6  ; buggy
 STAGE_GENGAR_BONUS       EQU $7
 ; STAGE_MEWTWO_BONUS     EQU $8  ; buggy
diff --git a/engine/high_scores_screen.asm b/engine/high_scores_screen.asm
index 1aa3bb2..3d867c6 100644
--- a/engine/high_scores_screen.asm
+++ b/engine/high_scores_screen.asm
@@ -356,7 +356,7 @@ Func_ccb6: ; 0xccb6
 	ld de, wBlueHighScore5Id + $3

 	call Func_d361

 	ld hl, wRedHighScore1Points

-	ld de, $a000

+	ld de, sHighScores

 	ld bc, $0082

 	call SaveData

 	ret

@@ -523,7 +523,7 @@ Func_cdce: ; 0xcdce
 	ld de, wBlueHighScore5Id + $3

 	call Func_d361

 	ld hl, wRedHighScore1Points

-	ld de, $a000

+	ld de, sHighScores

 	ld bc, $0082

 	call SaveData

 	and a

@@ -1016,7 +1016,7 @@ Func_d1d2: ; 0xd1d2
 	ld hl, wScreenState

 	inc [hl]

 	ld hl, wRedHighScore1Points

-	ld de, $a000

+	ld de, sHighScores

 	ld bc, $0082

 	call SaveData

 	ret

diff --git a/engine/pinball_game.asm b/engine/pinball_game.asm
index 66ff1de..466a01f 100644
--- a/engine/pinball_game.asm
+++ b/engine/pinball_game.asm
@@ -224,12 +224,12 @@ GameScreenFunction_EndBall: ; 0xdab2
 	ld a, [wGameOver]

 	and a

 	jp nz, TransitionToHighScoresScreen

-	ld a, [wd495]

+	ld a, [wGoingToBonusStage]

 	and a

-	jr nz, .asm_dae6

-	ld a, [wd496]

+	jr nz, .goingToBonusStage

+	ld a, [wReturningFromBonusStage]

 	and a

-	jr nz, .asm_db28

+	jr nz, .returningFromBonusStage

 	call FadeOut

 	ld a, [wUpdateAudioEngineUsingTimerInterrupt]

 	and a

@@ -243,7 +243,7 @@ GameScreenFunction_EndBall: ; 0xdab2
 	ld [wScreenState], a

 	ret

 

-.asm_dae6

+.goingToBonusStage

 	ld de, $0000

 	call PlaySong

 	ld bc, $0004

@@ -264,13 +264,13 @@ GameScreenFunction_EndBall: ; 0xdab2
 	ld a, [wNextStage]

 	ld [wCurrentStage], a

 	xor a

-	ld [wd496], a

-	ld [wd495], a

+	ld [wReturningFromBonusStage], a

+	ld [wGoingToBonusStage], a

 	ld a, $0

 	ld [wScreenState], a

 	ret

 

-.asm_db28

+.returningFromBonusStage

 	ld de, $0000

 	call PlaySong

 	ld bc, $0004

diff --git a/engine/pinball_game/ball_init/ball_init_blue_field.asm b/engine/pinball_game/ball_init/ball_init_blue_field.asm
index c2142e2..9728be0 100644
--- a/engine/pinball_game/ball_init/ball_init_blue_field.asm
+++ b/engine/pinball_game/ball_init/ball_init_blue_field.asm
@@ -1,5 +1,5 @@
 InitBallBlueField: ; 0x1c08d

-	ld a, [wd496]

+	ld a, [wReturningFromBonusStage]

 	and a

 	jp nz, StartBallAfterBonusStageBlueField

 	ld a, $0

@@ -78,7 +78,7 @@ StartBallAfterBonusStageBlueField: ; 0x1c129
 	ld [wBallYVelocity + 1], a

 	ld [wBallXVelocity], a

 	ld [wBallXVelocity + 1], a

-	ld [wd496], a

+	ld [wReturningFromBonusStage], a

 	ld [wSCX], a

 	ld [wd7be], a

 	ld a, [wBallTypeBackup]

diff --git a/engine/pinball_game/ball_init/ball_init_red_field.asm b/engine/pinball_game/ball_init/ball_init_red_field.asm
index 34d94b5..c37e21c 100644
--- a/engine/pinball_game/ball_init/ball_init_red_field.asm
+++ b/engine/pinball_game/ball_init/ball_init_red_field.asm
@@ -1,5 +1,5 @@
 InitBallRedField: ; 0x3007d

-	ld a, [wd496]

+	ld a, [wReturningFromBonusStage]

 	and a

 	jp nz, StartBallAfterBonusStageRedField

 	ld a, $0

@@ -83,7 +83,7 @@ StartBallAfterBonusStageRedField: ; 0x30128
 	ld [wBallYVelocity + 1], a

 	ld [wBallXVelocity], a

 	ld [wBallXVelocity + 1], a

-	ld [wd496], a

+	ld [wReturningFromBonusStage], a

 	ld [wSCX], a

 	ld [wd7be], a

 	ld a, [wBallTypeBackup]

diff --git a/engine/pinball_game/ball_loss/ball_loss_diglett_bonus.asm b/engine/pinball_game/ball_loss/ball_loss_diglett_bonus.asm
index 6827c19..b4e341f 100644
--- a/engine/pinball_game/ball_loss/ball_loss_diglett_bonus.asm
+++ b/engine/pinball_game/ball_loss/ball_loss_diglett_bonus.asm
@@ -6,9 +6,9 @@ HandleBallLossDiglettBonus: ; 0xe056
 	lb de, $00, $0b

 	call PlaySoundEffect

 	xor a

-	ld [wd495], a

+	ld [wGoingToBonusStage], a

 	ld a, $1

-	ld [wd496], a

+	ld [wReturningFromBonusStage], a

 	ld a, $2

 	ld [wd4c8], a

 	xor a

diff --git a/engine/pinball_game/ball_loss/ball_loss_gengar_bonus.asm b/engine/pinball_game/ball_loss/ball_loss_gengar_bonus.asm
index 4c37222..59bc3d3 100644
--- a/engine/pinball_game/ball_loss/ball_loss_gengar_bonus.asm
+++ b/engine/pinball_game/ball_loss/ball_loss_gengar_bonus.asm
@@ -32,9 +32,9 @@ HandleBallLossGengarBonus: ; 0xdf1a
 

 .asm_df57

 	xor a

-	ld [wd495], a

+	ld [wGoingToBonusStage], a

 	ld a, $1

-	ld [wd496], a

+	ld [wReturningFromBonusStage], a

 	ld a, $2

 	ld [wd4c8], a

 	xor a

diff --git a/engine/pinball_game/ball_loss/ball_loss_meowth_bonus.asm b/engine/pinball_game/ball_loss/ball_loss_meowth_bonus.asm
index 1bc7035..05d731b 100644
--- a/engine/pinball_game/ball_loss/ball_loss_meowth_bonus.asm
+++ b/engine/pinball_game/ball_loss/ball_loss_meowth_bonus.asm
@@ -38,9 +38,9 @@ HandleBallLossMeowthBonus: ; 0xdfe2
 	ld [wTimeRanOut], a

 	ld [wTimerActive], a

 	xor a

-	ld [wd495], a

+	ld [wGoingToBonusStage], a

 	ld a, $1

-	ld [wd496], a

+	ld [wReturningFromBonusStage], a

 	ld a, $2

 	ld [wd4c8], a

 	xor a

diff --git a/engine/pinball_game/ball_loss/ball_loss_mewtwo_bonus.asm b/engine/pinball_game/ball_loss/ball_loss_mewtwo_bonus.asm
index 07a51f0..949f8a8 100644
--- a/engine/pinball_game/ball_loss/ball_loss_mewtwo_bonus.asm
+++ b/engine/pinball_game/ball_loss/ball_loss_mewtwo_bonus.asm
@@ -32,9 +32,9 @@ HandleBallLossMewtwoBonus: ; 0xdf7e
 

 .asm_dfbb

 	xor a

-	ld [wd495], a

+	ld [wGoingToBonusStage], a

 	ld a, $1

-	ld [wd496], a

+	ld [wReturningFromBonusStage], a

 	ld a, $2

 	ld [wd4c8], a

 	xor a

diff --git a/engine/pinball_game/ball_loss/ball_loss_seel_bonus.asm b/engine/pinball_game/ball_loss/ball_loss_seel_bonus.asm
index 59d4bd7..ee2e41a 100644
--- a/engine/pinball_game/ball_loss/ball_loss_seel_bonus.asm
+++ b/engine/pinball_game/ball_loss/ball_loss_seel_bonus.asm
@@ -37,9 +37,9 @@ HandleBallLossSeelBonus: ; 0xe08b
 	xor a

 	ld [wTimerActive], a

 	ld [wTimerActive], a ; duplicate instruction

-	ld [wd495], a

+	ld [wGoingToBonusStage], a

 	ld a, $1

-	ld [wd496], a

+	ld [wReturningFromBonusStage], a

 	ld a, $2

 	ld [wd4c8], a

 	xor a

diff --git a/engine/pinball_game/draw_sprites/draw_red_field_sprites.asm b/engine/pinball_game/draw_sprites/draw_red_field_sprites.asm
index cc57f8d..17f1d2c 100644
--- a/engine/pinball_game/draw_sprites/draw_red_field_sprites.asm
+++ b/engine/pinball_game/draw_sprites/draw_red_field_sprites.asm
@@ -102,7 +102,7 @@ DrawTimerDigit: ; 0x17627
 Func_1762f: ; 0x1762f

 	lb de, $60, $0c

 	ld a, [wCurrentStage]

-	cp STAGE_BLUE_FIELD_BOTTOM + 1

+	cp FIRST_BONUS_STAGE

 	ret nc

 	lb de, $00, $00

 	bit 0, a

diff --git a/engine/pinball_game/evolution_mode.asm b/engine/pinball_game/evolution_mode.asm
index 226ba48..d6db1a8 100755
--- a/engine/pinball_game/evolution_mode.asm
+++ b/engine/pinball_game/evolution_mode.asm
@@ -443,7 +443,7 @@ InitEvolutionModeForMon: ; 0x10d1d
 	jr nz, .asm_10d8a

 	xor a

 .asm_10d8a

-	call Func_a21

+	call RandomRange

 	sla a

 	ld c, a

 	pop hl

@@ -478,7 +478,7 @@ InitEvolutionModeForMon: ; 0x10d1d
 .asm_10dc0

 	push bc

 	ld a, c

-	call Func_a21

+	call RandomRange

 	ld c, a

 	ld b, $0

 	ld hl, wd55c

diff --git a/engine/pinball_game/evolution_mode/evolution_mode_blue_field.asm b/engine/pinball_game/evolution_mode/evolution_mode_blue_field.asm
index afcb9ea..5dac074 100644
--- a/engine/pinball_game/evolution_mode/evolution_mode_blue_field.asm
+++ b/engine/pinball_game/evolution_mode/evolution_mode_blue_field.asm
@@ -638,7 +638,7 @@ asm_210c7:
 

 Func_2111d: ; 0x2111d

 	ld a, $11

-	call Func_a21

+	call RandomRange

 	ld c, a

 	ld b, $0

 	ld hl, wd566

diff --git a/engine/pinball_game/evolution_mode/evolution_mode_red_field.asm b/engine/pinball_game/evolution_mode/evolution_mode_red_field.asm
index 5bbf336..018ea91 100644
--- a/engine/pinball_game/evolution_mode/evolution_mode_red_field.asm
+++ b/engine/pinball_game/evolution_mode/evolution_mode_red_field.asm
@@ -640,7 +640,7 @@ asm_20a9f:
 

 Func_20af5: ; 0x20af5

 	ld a, $11

-	call Func_a21

+	call RandomRange

 	ld c, a

 	ld b, $0

 	ld hl, wd566

diff --git a/engine/pinball_game/load_stage_data/load_blue_field.asm b/engine/pinball_game/load_stage_data/load_blue_field.asm
index de5c455..f9eb138 100644
--- a/engine/pinball_game/load_stage_data/load_blue_field.asm
+++ b/engine/pinball_game/load_stage_data/load_blue_field.asm
@@ -435,7 +435,7 @@ Func_1c4b6: ; 0x1c4b6
 	ld a, [wOpenedSlotByGetting3Pokeballs]

 	and a

 	jr z, .asm_1c4d2

-	ld a, [wd498]

+	ld a, [wNextBonusStage]

 	add $15

 	callba LoadBillboardTileData

 	ret

diff --git a/engine/pinball_game/load_stage_data/load_red_field.asm b/engine/pinball_game/load_stage_data/load_red_field.asm
index 51a00c9..f195f92 100644
--- a/engine/pinball_game/load_stage_data/load_red_field.asm
+++ b/engine/pinball_game/load_stage_data/load_red_field.asm
@@ -441,7 +441,7 @@ Func_14377: ; 0x14377
 	ld a, [wOpenedSlotByGetting3Pokeballs]

 	and a

 	jr z, .asm_14393

-	ld a, [wd498]

+	ld a, [wNextBonusStage]

 	add $15

 	callba LoadBillboardTileData

 	ret

diff --git a/engine/pinball_game/object_collision/blue_stage_resolve_collision.asm b/engine/pinball_game/object_collision/blue_stage_resolve_collision.asm
index e2ac723..8d80360 100644
--- a/engine/pinball_game/object_collision/blue_stage_resolve_collision.asm
+++ b/engine/pinball_game/object_collision/blue_stage_resolve_collision.asm
@@ -2620,9 +2620,9 @@ DoSlotLogic_BlueField: ; 0x1e830
 	xor a

 	ld [wBonusStageSlotRewardActive], a

 	ld a, $1

-	ld [wd495], a

+	ld [wGoingToBonusStage], a

 	ld [wMoveToNextScreenState], a

-	ld a, [wd498]

+	ld a, [wNextBonusStage]

 	ld c, a

 	ld b, $0

 	ld hl, BonusStages_BlueField

@@ -2726,7 +2726,7 @@ OpenSlotCave_BlueField: ; 0x1e9c0
 	ld a, [wOpenedSlotByGetting3Pokeballs]

 	and a

 	jr z, .asm_1e9dc

-	ld a, [wd498]

+	ld a, [wNextBonusStage]

 	add $15

 	jr .asm_1e9e3

 

diff --git a/engine/pinball_game/object_collision/diglett_bonus_resolve_collision.asm b/engine/pinball_game/object_collision/diglett_bonus_resolve_collision.asm
index 738010d..bf48d71 100644
--- a/engine/pinball_game/object_collision/diglett_bonus_resolve_collision.asm
+++ b/engine/pinball_game/object_collision/diglett_bonus_resolve_collision.asm
@@ -672,7 +672,7 @@ Func_1ab30: ; 0x1ab30
 	call InitAnimation

 	xor a

 	ld [wDugrioState], a

-	ld [wd498], a

+	ld [wNextBonusStage], a ; BONUS_STAGE_ORDER_GENGAR

 	ld a, $1

 	ld [wCompletedBonusStage], a

 	call FillBottomMessageBufferWithBlackTile

diff --git a/engine/pinball_game/object_collision/gengar_bonus_resolve_collision.asm b/engine/pinball_game/object_collision/gengar_bonus_resolve_collision.asm
index 10afcd3..0ddb3c4 100644
--- a/engine/pinball_game/object_collision/gengar_bonus_resolve_collision.asm
+++ b/engine/pinball_game/object_collision/gengar_bonus_resolve_collision.asm
@@ -999,8 +999,8 @@ Func_189af: ; 0x189af
 	ret nz

 	ld a, $1

 	ld [wd6a8], a

-	ld a, $1

-	ld [wd498], a

+	ld a, BONUS_STAGE_ORDER_MEWTWO

+	ld [wNextBonusStage], a

 	ld a, $1

 	ld [wCompletedBonusStage], a

 	call FillBottomMessageBufferWithBlackTile

diff --git a/engine/pinball_game/object_collision/meowth_bonus_resolve_collision.asm b/engine/pinball_game/object_collision/meowth_bonus_resolve_collision.asm
index 85b4598..95cd4b5 100644
--- a/engine/pinball_game/object_collision/meowth_bonus_resolve_collision.asm
+++ b/engine/pinball_game/object_collision/meowth_bonus_resolve_collision.asm
@@ -188,12 +188,12 @@ ResolveMeowthBonusGameObjectCollisions: ; 0x2442a
 	ld a, [wd712]

 	cp $2

 	jr nc, .asm_24498

-	ld a, [wd498]

-	cp $4

+	ld a, [wNextBonusStage]

+	cp BONUS_STAGE_ORDER_SEEL

 	ret z

-	ld a, $4

+	ld a, BONUS_STAGE_ORDER_SEEL

 	ld [wd712], a

-	ld [wd498], a

+	ld [wNextBonusStage], a

 	ld a, $96

 	ld [wd739], a

 	ld de, $0000

diff --git a/engine/pinball_game/object_collision/mewtwo_bonus_resolve_collision.asm b/engine/pinball_game/object_collision/mewtwo_bonus_resolve_collision.asm
index 17e0b0b..119ffa3 100644
--- a/engine/pinball_game/object_collision/mewtwo_bonus_resolve_collision.asm
+++ b/engine/pinball_game/object_collision/mewtwo_bonus_resolve_collision.asm
@@ -339,8 +339,8 @@ Func_19638: ; 0x19638
 	ret nz

 	ld a, $1

 	ld [wd6b3], a

-	ld a, [wd499]

-	ld [wd498], a

+	ld a, [wInitialNextBonusStage]

+	ld [wNextBonusStage], a

 	ld a, [wNumMewtwoBonusCompletions]

 	cp $2  ; only counts up to 2. Gets reset to 0 when Mew is encountered in Catch 'Em Mode.

 	jr z, .asm_1965e

diff --git a/engine/pinball_game/object_collision/red_stage_resolve_collision.asm b/engine/pinball_game/object_collision/red_stage_resolve_collision.asm
index 7d9774e..8134d0e 100644
--- a/engine/pinball_game/object_collision/red_stage_resolve_collision.asm
+++ b/engine/pinball_game/object_collision/red_stage_resolve_collision.asm
@@ -2066,9 +2066,9 @@ DoSlotLogic_RedField: ; 0x16352
 	xor a

 	ld [wBonusStageSlotRewardActive], a

 	ld a, $1

-	ld [wd495], a

+	ld [wGoingToBonusStage], a

 	ld [wMoveToNextScreenState], a

-	ld a, [wd498]

+	ld a, [wNextBonusStage]

 	ld c, a

 	ld b, $0

 	ld hl, BonusStages_RedField

@@ -2178,7 +2178,7 @@ OpenSlotCave_RedField: ; 0x164e3
 	ld a, [wOpenedSlotByGetting3Pokeballs]

 	and a

 	jr z, .asm_164ff

-	ld a, [wd498]

+	ld a, [wNextBonusStage]

 	add $15

 	jr .asm_16506

 

diff --git a/engine/pinball_game/object_collision/seel_bonus_resolve_collision.asm b/engine/pinball_game/object_collision/seel_bonus_resolve_collision.asm
index 39e8044..df40da0 100644
--- a/engine/pinball_game/object_collision/seel_bonus_resolve_collision.asm
+++ b/engine/pinball_game/object_collision/seel_bonus_resolve_collision.asm
@@ -7,8 +7,8 @@ ResolveSeelBonusGameObjectCollisions: ; 0x25c5a
 	ld a, [wd794]

 	cp $2

 	jr nc, .asm_25c98

-	ld a, $1

-	ld [wd498], a

+	ld a, BONUS_STAGE_ORDER_MEWTWO

+	ld [wNextBonusStage], a

 	ld de, $0000

 	call PlaySong

 	ld a, $1

diff --git a/engine/pinball_game/slot.asm b/engine/pinball_game/slot.asm
index a81fc14..0cf52d2 100644
--- a/engine/pinball_game/slot.asm
+++ b/engine/pinball_game/slot.asm
@@ -219,7 +219,7 @@ Func_eef9: ; 0xeef9
 	cp $d

 	ret nz

 	push hl

-	ld hl, wd498

+	ld hl, wNextBonusStage

 	add [hl]

 	pop hl

 	ret

@@ -269,7 +269,7 @@ SlotRewardBonusMultiplier: ; 0xefa7
 

 SlotRewardSmallPoints: ; 0xefb2

 	ld a, $8

-	call Func_a21

+	call RandomRange

 	ld [wCurSlotBonus], a

 	ld b, $80

 .asm_efbc

@@ -308,7 +308,7 @@ SlotRewardSmallPoints: ; 0xefb2
 

 SlotRewardBigPoints: ; 0xeff3

 	ld a, $8

-	call Func_a21

+	call RandomRange

 	ld [wCurSlotBonus], a

 	ld b, $80

 .asm_effd

@@ -417,7 +417,7 @@ BallTypeProgressionBlueField: ; 0xf0bb
 

 SlotBonusMultiplier: ; 0xf0c1

 	ld a, $4

-	call Func_a21

+	call RandomRange

 	ld [wCurSlotBonus], a

 	ld b, $80

 .asm_f0cb

diff --git a/engine/pinball_game/stage_init/init_blue_field.asm b/engine/pinball_game/stage_init/init_blue_field.asm
index 0200f2d..ed624c5 100644
--- a/engine/pinball_game/stage_init/init_blue_field.asm
+++ b/engine/pinball_game/stage_init/init_blue_field.asm
@@ -30,9 +30,9 @@ InitBlueField: ; 0x1c000
 	ld a, $3

 	ld [wd49e], a

 	ld [wd610], a

-	ld a, $2

-	ld [wd498], a

-	ld [wd499], a

+	ld a, BONUS_STAGE_ORDER_MEOWTH

+	ld [wNextBonusStage], a

+	ld [wInitialNextBonusStage], a

 	ld a, $80

 	ld [wIndicatorStates], a

 	ld [wIndicatorStates + 3], a

diff --git a/engine/pinball_game/stage_init/init_red_field.asm b/engine/pinball_game/stage_init/init_red_field.asm
index a40ace1..82778c3 100644
--- a/engine/pinball_game/stage_init/init_red_field.asm
+++ b/engine/pinball_game/stage_init/init_red_field.asm
@@ -30,8 +30,8 @@ InitRedField: ; 0x30000
 	ld a, $3

 	ld [wd49e], a

 	ld [wd610], a

-	ld [wd498], a

-	ld [wd499], a

+	ld [wNextBonusStage], a ; BONUS_STAGE_ORDER_DIGLETT

+	ld [wInitialNextBonusStage], a ; BONUS_STAGE_ORDER_DIGLETT

 	ld a, $4

 	ld [wStageCollisionState], a

 	ld [wd7ad], a

diff --git a/engine/pinball_game/stage_init/init_stages.asm b/engine/pinball_game/stage_init/init_stages.asm
index 5e26639..621a828 100644
--- a/engine/pinball_game/stage_init/init_stages.asm
+++ b/engine/pinball_game/stage_init/init_stages.asm
@@ -53,7 +53,7 @@ ResetDataForStageInitialization: ; 0x8388
 	ret

 .asm_8398

 	ld a, [wCurrentStage]

-	cp STAGE_BLUE_FIELD_BOTTOM + 1

+	cp FIRST_BONUS_STAGE

 	ret nc  ; Check if bonus stage

 	ld hl, wPartyMons

 	ld bc, $0170

diff --git a/home.asm b/home.asm
index 1f1e6fa..645ec20 100644
--- a/home.asm
+++ b/home.asm
@@ -147,8 +147,8 @@ Start: ; 0x150
 	ld [rIE], a  ; Only enable LCD Status interrupt
 	ei
 	ld a, $ff
-	ld [wd810], a
-	call Func_97a
+	ld [wRNGModulus], a
+	call ResetRNG
 	xor a
 	ld [wBootCheck], a
 	ld a, BANK(Func_1ffc)
@@ -236,8 +236,8 @@ SoftReset:
 	ld [rIE], a
 	ei
 	ld a, $ff
-	ld [wd810], a
-	call Func_97a
+	ld [wRNGModulus], a
+	call ResetRNG
 	ld a, [hGameBoyColorFlag]
 	ld [$fffd], a
 	xor a
@@ -785,7 +785,7 @@ INCLUDE "home/random.asm"
 INCLUDE "home/joypad.asm"
 INCLUDE "home/palettes.asm"
 
-Func_dd4: ; 0xdd4
+HorrendousMultiplyAbyL: ; 0xdd4
 ; Return a * l to hl
 ; Stupid waste of space
 	push bc
@@ -2930,7 +2930,7 @@ Func_248a: ; 0x248a
 	sub $e0
 	ld b, a
 	ld a, [wCurrentStage]
-	cp $6  ; gengar stage buggy?
+	cp FIRST_BONUS_STAGE
 	jr nc, .bonusStage
 	bit 4, b
 	ld hl, BottomLeftCollisionMasks
diff --git a/home/random.asm b/home/random.asm
index e2b8c32..ce34f69 100644
--- a/home/random.asm
+++ b/home/random.asm
@@ -2,18 +2,18 @@ GenRandom: ; 0x959
 	push bc
 	push de
 	push hl
-	ld a, [wd811]
+	ld a, [wRNGPointer]
 	ld c, a
 	ld b, $0 ;load ??? into c
 	inc a
 	cp 54 + 1 ;inc ???, if ??? is 55 do alot of subtraction and make ??? 0
 	jr nz, .asm_96e
-	call Func_9fa
+	call UpdateRNG
 	xor a
 	ld bc, $0000
 .asm_96e
-	ld [wd811], a ;place wd811 + 1 back in
-	ld hl, wd812 ;choose number generated based on wd811 and all the subtraction
+	ld [wRNGPointer], a ;place wRNGPointer + 1 back in
+	ld hl, wRNGValues ;choose number generated based on wRNGPointer and all the subtraction
 	add hl, bc
 	ld a, [hl]
 	pop hl
@@ -21,53 +21,55 @@ GenRandom: ; 0x959
 	pop bc
 	ret
 
-Func_97a: ; 0x97a
-	ld a, [wd810]
+ResetRNG: ; 0x97a
+	ld a, [wRNGModulus]
 	ld d, a
-	ld a, $0
+	ld a, $0 ; wasted instruction (debug that was never commented out?)
+	; [wRNGSub] = [sRNGMod] % [wRNGModulus]
 	ld a, [sRNGMod]
-.asm_983
+.modulo
 	cp d
-	jr c, .asm_989
+	jr c, .okay
 	sub d
-	jr .asm_983
+	jr .modulo
 
-.asm_989
-	ld [wd80f], a
-	ld [wd848], a
+.okay
+	ld [wRNGSub], a
+	ld [wRNGSub2], a
 	ld e, $1
-	ld hl, Data_9c4
-	ld a, $36
-.asm_996
+	ld hl, .Data
+	ld a, 54
+.copy_prng
 	push af
 	ld c, [hl]
 	inc hl
 	ld b, $0
 	push hl
-	ld hl, wd812
+	ld hl, wRNGValues
 	add hl, bc
 	ld [hl], e
-	ld a, [wd80f]
+	ld a, [wRNGSub]
 	sub e
-	jr nc, .asm_9a8
+	jr nc, .next
 	add d
-.asm_9a8
+.next
 	ld e, a
 	ld a, [hl]
-	ld [wd80f], a
+	ld [wRNGSub], a
 	pop hl
 	pop af
 	dec a
-	jr nz, .asm_996
-	call Func_9fa
-	call Func_9fa
-	call Func_9fa
-	ld a, $0
+	jr nz, .copy_prng
+	call UpdateRNG
+	call UpdateRNG
+	call UpdateRNG
+	ld a, $0 ; wasted instruction (debug that was never commented out?)
 	call GenRandom
 	ld [sRNGMod], a
 	ret
 
-Data_9c4:
+.Data
+; offsets from wRNGValues
 	db $14, $29, $07, $1c, $31, $0f, $24, $02, $17
 	db $2c, $0a, $1f, $34, $12, $27, $05, $1a, $2f
 	db $0d, $22, $00, $15, $2a, $08, $1d, $32, $10
@@ -75,45 +77,49 @@ Data_9c4:
 	db $06, $1b, $30, $0e, $23, $01, $16, $2b, $09
 	db $1e, $33, $11, $26, $04, $19, $2e, $0c, $21
 
-Func_9fa: ; 0x9fa
-	ld a, [wd810]
+UpdateRNG: ; 0x9fa
+; Adjusts two RNG values using wRNGModulus
+	ld a, [wRNGModulus]
 	ld d, a
-	ld bc, wd812
-	ld hl, wd812 + $1f ;d831
+ ; [d812] = ([d812] - 24 * [d831]) % [d810]
+	ld bc, wRNGValues
+	ld hl, wRNGValues + $1f
 	ld e, $18
-.asm_a06
+.loop
 	ld a, [bc]
-	sub [hl] ;sub d831 from wd812, add wd810 if it does not carry, put result in wd812. repeat 24 times
-	jr nc, .asm_a0b
+	sub [hl]
+	jr nc, .no_carry
 	add d
-.asm_a0b
+.no_carry
 	ld [bc], a
 	dec e
-	jr nz, .asm_a06
-	ld bc, wd812 + $18
-	ld hl, wd812
+	jr nz, .loop
+ ; [d82a] = ([d82a] - 31 * [d812]) % [d810]
+	ld bc, wRNGValues + $18 ; d82a
+	ld hl, wRNGValues
 	ld e, $1f
-.asm_a17
+.loop2
 	ld a, [bc]
 	sub [hl]
-	jr nc, .asm_a1c
+	jr nc, .no_carry2
 	add d
-.asm_a1c
+.no_carry2
 	ld [bc], a
 	dec e
-	jr nz, .asm_a17
+	jr nz, .loop2
 	ret
 
-Func_a21: ; 0xa21
+RandomRange: ; 0xa21
+; Random value 0 <= x < a
 	push bc
 	push hl
 	ld c, a
 	ld b, $0
-	ld hl, Data_a38 ;jump to c in table, load (twice c?) into l
+	ld hl, EvensAndOdds
 	add hl, bc
 	ld l, [hl]
-	call GenRandom ;a = a psuedo random number
-	call Func_dd4 ;a * l
+	call GenRandom
+	call HorrendousMultiplyAbyL
 	inc h
 	srl h
 	ld a, h
@@ -121,7 +127,10 @@ Func_a21: ; 0xa21
 	pop bc
 	ret
 
-Data_a38: ;starting from 0, go up 2 each byte
+EvensAndOdds:
+; The first 128 bytes are the first 128 even numbers starting at 0.
+; The next 128 bytes are the first 128 odd numbers starting at 1.
+; The (a)th element is essentially what you'd get from rlca.
 x = 0
 REPT 128
 	db x | ((x >> 7) & 1)
diff --git a/wram.asm b/wram.asm
index a753245..8e80515 100644
--- a/wram.asm
+++ b/wram.asm
@@ -159,20 +159,28 @@ wd489:: ; 0xd489
 wd48f:: ; 0xd48f
 	ds $6
 
-wd495:: ; 0xd495
+wGoingToBonusStage:: ; 0xd495
+; Set to 1 when the player's pinball enters the Slot cave to go to a Bonus Stage.
 	ds $1
 
-wd496:: ; 0xd496
+wReturningFromBonusStage:: ; 0xd496
+; Set to 1 when a bonus stage is is finished. This is used when the main field logic is determining
+; where to start the ball, since it falls out of the Slot cave after a bonus stage.
 	ds $1
 
 wNextStage:: ; 0xd497
 ; Holds the id of the next stage to go to. Used for transitioning between bonus stage and the main red/blue field.
 	ds $1
 
-wd498:: ; 0xd498
+wNextBonusStage:: ; 0xd498
+; Holds id of the next Bonus Stage the player is eligible to go to.
+; This is not the raw stage id (e.g. STAGE_MEOWTH_BONUS), rather, its the id in the order the STAGE constants are defined.
+; See constants/bonus_stage_order_constants.asm for list of values.
 	ds $1
 
-wd499:: ; 0xd499
+wInitialNextBonusStage:: ; 0xd499
+; Holds the id of the first Bonus Stage for the current field. This is used to "wrap around" back to the start of the bonus stages
+; after defeating the Mewtwo stage.  See wNextBonusStage.
 	ds $1
 
 wCompletedBonusStage:: ; 0xd49a
@@ -1921,19 +1929,19 @@ wOBP0:: ; 0xd80d
 wOBP1:: ; 0xd80e
 	ds $1
 
-wd80f:: ; 0xd80f
+wRNGSub:: ; 0xd80f
 	ds $1
 
-wd810:: ; 0xd810 loaded by Func_9fa, RNG related
+wRNGModulus:: ; 0xd810 loaded by UpdateRNG, RNG related
 	ds $1
 
-wd811:: ; 0xd811
+wRNGPointer:: ; 0xd811
 	ds $1
 
-wd812:: ; 0xd812
+wRNGValues:: ; 0xd812
 	ds $36
 
-wd848:: ; 0xd848
+wRNGSub2:: ; 0xd848
 	ds $1
 
 wUpdateAudioEngineUsingTimerInterrupt:: ; 0xd849