Finish labeling vertical_screen_transition.asm and related

29 files changed, 109 insertions, 91 deletions

diff --git a/engine/pinball_game.asm b/engine/pinball_game.asm
index 9c1c847..d4148ff 100644
--- a/engine/pinball_game.asm
+++ b/engine/pinball_game.asm
@@ -49,7 +49,7 @@ GameScreenFunction_StartBall: ; 0xd87f
 	callba InitBallForStage

 	callba LoadStageCollisionAttributes

 	callba LoadStageData

-	callba Func_ed5e

+	callba ScrollScreenToShowPinball

 	call ClearOAMBuffer

 	callba DrawSpritesForStage

 	ld a, [wUpdateAudioEngineUsingTimerInterrupt]

@@ -145,25 +145,25 @@ GameScreenFunction_HandleBallPhysics: ; 0xd909
 	call MoveBallPosition

 	callba CheckStageTransition

 	callba DrawSpritesForStage

-	call Func_33e3

-	ld a, [wd5cb]

+	call UpdateBottomText

+	ld a, [wDisableDrawScoreboardInfo]

 	and a

-	jr nz, .asm_d9e9

+	jr nz, .skipDrawingScoreboard

 	callba Func_85c7

 	callba HideScoreIfBallLow

 	callba Func_8645

 	call Func_dba9

 	call DrawNumPartyMonsIcon

 	call DrawPikachuSaverLightningBoltIcon

-.asm_d9e9

+.skipDrawingScoreboard

 	ld a, [wTimerActive]

 	and a

 	callba nz, Func_86a4

-	ld a, [wd4ae]

+	ld a, [wMoveToNextScreenState]

 	and a

 	ret z

 	xor a

-	ld [wd4ae], a

+	ld [wMoveToNextScreenState], a

 	ld hl, wScreenState

 	inc [hl]

 	ret

@@ -186,9 +186,9 @@ GameScreenFunction_HandleBallLoss: ; 0xda36
 	bit 0, a

 	callba nz, HandleFlippers

 	callba DrawSpritesForStage

-	call Func_33e3

+	call UpdateBottomText

 	callba Func_85c7

-	ld a, [wd5ca]

+	ld a, [wBottomTextEnabled]

 	and a

 	ret nz

 	ld a, [wd4c9]

diff --git a/engine/pinball_game/ball_init/ball_init_meowth_bonus.asm b/engine/pinball_game/ball_init/ball_init_meowth_bonus.asm
index e452ecb..48f8077 100644
--- a/engine/pinball_game/ball_init/ball_init_meowth_bonus.asm
+++ b/engine/pinball_game/ball_init/ball_init_meowth_bonus.asm
@@ -26,7 +26,7 @@ InitBallMeowthBonusStage: ; 0x24059
 	dec b

 	jr nz, .asm_24081

 	ld a, $1

-	ld [wd7ac], a

+	ld [wDisableHorizontalScrollForBallStart], a

 	ld a, $40

 	ld [wMeowthXPosition], a

 	ld a, $20

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 2dd8117..6827c19 100644
--- a/engine/pinball_game/ball_loss/ball_loss_diglett_bonus.asm
+++ b/engine/pinball_game/ball_loss/ball_loss_diglett_bonus.asm
@@ -12,7 +12,7 @@ HandleBallLossDiglettBonus: ; 0xe056
 	ld a, $2

 	ld [wd4c8], a

 	xor a

-	ld [wd7ac], a

+	ld [wDisableHorizontalScrollForBallStart], a

 	ld a, [wCompletedBonusStage]

 	and a

 	ret nz

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 59a40da..4c37222 100644
--- a/engine/pinball_game/ball_loss/ball_loss_gengar_bonus.asm
+++ b/engine/pinball_game/ball_loss/ball_loss_gengar_bonus.asm
@@ -10,7 +10,7 @@ HandleBallLossGengarBonus: ; 0xdf1a
 	cp $5

 	jr c, .asm_df50

 	xor a

-	ld [wd4ae], a

+	ld [wMoveToNextScreenState], a

 	ld a, [wd6a7]

 	and a

 	ret nz

@@ -38,7 +38,7 @@ HandleBallLossGengarBonus: ; 0xdf1a
 	ld a, $2

 	ld [wd4c8], a

 	xor a

-	ld [wd7ac], a

+	ld [wDisableHorizontalScrollForBallStart], a

 	ld a, [wCompletedBonusStage]

 	and a

 	ret nz

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 f80e758..cf84910 100644
--- a/engine/pinball_game/ball_loss/ball_loss_meowth_bonus.asm
+++ b/engine/pinball_game/ball_loss/ball_loss_meowth_bonus.asm
@@ -44,7 +44,7 @@ HandleBallLossMeowthBonus: ; 0xdfe2
 	ld a, $2

 	ld [wd4c8], a

 	xor a

-	ld [wd7ac], a

+	ld [wDisableHorizontalScrollForBallStart], a

 	ld [wd712], a

 	ld a, [wCompletedBonusStage]

 	and 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 2cd165e..07a51f0 100644
--- a/engine/pinball_game/ball_loss/ball_loss_mewtwo_bonus.asm
+++ b/engine/pinball_game/ball_loss/ball_loss_mewtwo_bonus.asm
@@ -10,7 +10,7 @@ HandleBallLossMewtwoBonus: ; 0xdf7e
 	cp $8

 	jr c, .asm_dfb4

 	xor a

-	ld [wd4ae], a

+	ld [wMoveToNextScreenState], a

 	ld a, [wd6b2]

 	and a

 	ret nz

@@ -38,7 +38,7 @@ HandleBallLossMewtwoBonus: ; 0xdf7e
 	ld a, $2

 	ld [wd4c8], a

 	xor a

-	ld [wd7ac], a

+	ld [wDisableHorizontalScrollForBallStart], a

 	ld a, [wCompletedBonusStage]

 	and a

 	ret nz

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 0c86084..59d4bd7 100644
--- a/engine/pinball_game/ball_loss/ball_loss_seel_bonus.asm
+++ b/engine/pinball_game/ball_loss/ball_loss_seel_bonus.asm
@@ -43,7 +43,7 @@ HandleBallLossSeelBonus: ; 0xe08b
 	ld a, $2

 	ld [wd4c8], a

 	xor a

-	ld [wd7ac], a

+	ld [wDisableHorizontalScrollForBallStart], a

 	ld [wd794], a

 	ld a, [wCompletedBonusStage]

 	and a

diff --git a/engine/pinball_game/catchem_mode/catchem_mode_blue_field.asm b/engine/pinball_game/catchem_mode/catchem_mode_blue_field.asm
index 8bdd4c3..897bafe 100644
--- a/engine/pinball_game/catchem_mode/catchem_mode_blue_field.asm
+++ b/engine/pinball_game/catchem_mode/catchem_mode_blue_field.asm
@@ -200,7 +200,7 @@ CapturePokemonBlueStage: ; 0x20483
 	ret

 

 Func_2048f: ; 0x2048f

-	ld a, [wd5ca]

+	ld a, [wBottomTextEnabled]

 	and a

 	ret nz

 	call FillBottomMessageBufferWithBlackTile

diff --git a/engine/pinball_game/catchem_mode/catchem_mode_red_field.asm b/engine/pinball_game/catchem_mode/catchem_mode_red_field.asm
index e6cd614..ee2c5ef 100644
--- a/engine/pinball_game/catchem_mode/catchem_mode_red_field.asm
+++ b/engine/pinball_game/catchem_mode/catchem_mode_red_field.asm
@@ -198,7 +198,7 @@ CapturePokemonRedStage: ; 0x201c2
 	ret

 

 Func_201ce: ; 0x201ce

-	ld a, [wd5ca]

+	ld a, [wBottomTextEnabled]

 	and a

 	ret nz

 	call FillBottomMessageBufferWithBlackTile

diff --git a/engine/pinball_game/evolution_mode.asm b/engine/pinball_game/evolution_mode.asm
index 541c5a4..19cf595 100755
--- a/engine/pinball_game/evolution_mode.asm
+++ b/engine/pinball_game/evolution_mode.asm
@@ -25,7 +25,7 @@ StartEvolutionMode_CallTable: ; 0x10abc
 

 ConcludeEvolutionMode: ; 0x10ac8

 	xor a

-	ld [wd5ca], a

+	ld [wBottomTextEnabled], a

 	call FillBottomMessageBufferWithBlackTile

 	xor a

 	ld [wInSpecialMode], a

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 c1e31c1..bb5042f 100644
--- a/engine/pinball_game/evolution_mode/evolution_mode_blue_field.asm
+++ b/engine/pinball_game/evolution_mode/evolution_mode_blue_field.asm
@@ -196,7 +196,7 @@ Func_20d30: ; 0x20d30
 	ret

 

 Func_20d7c: ; 0x20d7c

-	ld a, [wd5ca]

+	ld a, [wBottomTextEnabled]

 	and a

 	ret nz

 	call FillBottomMessageBufferWithBlackTile

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 ba3e372..e21d09f 100644
--- a/engine/pinball_game/evolution_mode/evolution_mode_red_field.asm
+++ b/engine/pinball_game/evolution_mode/evolution_mode_red_field.asm
@@ -199,7 +199,7 @@ Func_2070b: ; 0x2070b
 	ret

 

 Func_20757: ; 0x20757

-	ld a, [wd5ca]

+	ld a, [wBottomTextEnabled]

 	and a

 	ret nz

 	call FillBottomMessageBufferWithBlackTile

diff --git a/engine/pinball_game/extra_ball.asm b/engine/pinball_game/extra_ball.asm
index f753f5f..e0c99ae 100644
--- a/engine/pinball_game/extra_ball.asm
+++ b/engine/pinball_game/extra_ball.asm
@@ -1,6 +1,6 @@
 ShowExtraBallMessage: ; 0x30188

 ; Displays the extra ball scrolling message, if an extra ball has been granted.

-	ld a, [wd5ca]

+	ld a, [wBottomTextEnabled]

 	and a

 	ret nz

 	ld a, [wShowExtraBallText]

diff --git a/engine/pinball_game/map_move.asm b/engine/pinball_game/map_move.asm
index 5382259..a639108 100755
--- a/engine/pinball_game/map_move.asm
+++ b/engine/pinball_game/map_move.asm
@@ -40,7 +40,7 @@ CallTable_3021f: ; 0x3021f
 

 Func_3022b: ; 0x3022b

 	xor a

-	ld [wd5ca], a ;turn text off

+	ld [wBottomTextEnabled], a ;turn text off

 	call FillBottomMessageBufferWithBlackTile ;clear text

 	xor a

 	ld [wInSpecialMode], a

@@ -471,7 +471,7 @@ Func_314f3: ; 0x314f3
 	ret

 

 Func_31505: ; 0x31505

-	ld a, [wd5ca]

+	ld a, [wBottomTextEnabled]

 	and a

 	ret nz

 	call FillBottomMessageBufferWithBlackTile

@@ -564,9 +564,9 @@ Func_315d5: ; 0x315d5
 	ld bc, ArrivedAtMapText

 	callba LoadScrollingMapNameText

 .asm_31603

-	callba Func_33e3

+	callba UpdateBottomText

 	rst AdvanceFrame

-	ld a, [wd5ca]

+	ld a, [wBottomTextEnabled]

 	and a

 	jr nz, .asm_31603

 	ld a, $2

@@ -621,7 +621,7 @@ Func_31660: ; 0x31660
 	ret

 

 Func_31672: ; 0x31672

-	ld a, [wd5ca] ;if text is off

+	ld a, [wBottomTextEnabled] ;if text is off

 	and a

 	ret nz

 	call FillBottomMessageBufferWithBlackTile

@@ -718,9 +718,9 @@ Func_3174c: ; 0x3174c
 	ld bc, ArrivedAtMapText

 	callba LoadScrollingMapNameText

 .asm_3177a

-	callba Func_33e3

+	callba UpdateBottomText

 	rst AdvanceFrame

-	ld a, [wd5ca]

+	ld a, [wBottomTextEnabled]

 	and a

 	jr nz, .asm_3177a

 	ld a, $2

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 c9ac09d..835cf57 100644
--- a/engine/pinball_game/object_collision/blue_stage_resolve_collision.asm
+++ b/engine/pinball_game/object_collision/blue_stage_resolve_collision.asm
@@ -1334,7 +1334,7 @@ UpdateBonusMultiplierRailing_BlueField: ; 0x1d51b
 	ret

 

 ShowBonusMultiplierMessage_BlueField: ; 0x1d5bf

-	ld a, [wd5ca]

+	ld a, [wBottomTextEnabled]

 	and a

 	ret nz

 	ld a, [wd613]

@@ -2621,7 +2621,7 @@ DoSlotLogic_BlueField: ; 0x1e830
 	ld [wBonusStageSlotRewardActive], a

 	ld a, $1

 	ld [wd495], a

-	ld [wd4ae], a

+	ld [wMoveToNextScreenState], a

 	ld a, [wd498]

 	ld c, a

 	ld b, $0

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 c1c9f78..b89c105 100644
--- a/engine/pinball_game/object_collision/gengar_bonus_resolve_collision.asm
+++ b/engine/pinball_game/object_collision/gengar_bonus_resolve_collision.asm
@@ -885,9 +885,9 @@ Func_1894c: ; 0x1894c
 	inc a

 	ld [wBallYPos + 1], a

 .asm_18973

-	ld a, [wd7a0]

+	ld a, [wUpperTiltPixelsOffset]

 	dec a

-	ld [wd7a0], a

+	ld [wUpperTiltPixelsOffset], a

 	ld a, $1

 	ld [wUpperTiltPushing], a

 	ret

@@ -907,9 +907,9 @@ Func_1894c: ; 0x1894c
 	jr z, .asm_189a5

 	dec a

 	ld [wd6a5], a

-	ld a, [wd7a0]

+	ld a, [wUpperTiltPixelsOffset]

 	inc a

-	ld [wd7a0], a

+	ld [wUpperTiltPixelsOffset], a

 	ret

 

 .asm_189a5

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 dcd080b..3f9a248 100644
--- a/engine/pinball_game/object_collision/red_stage_resolve_collision.asm
+++ b/engine/pinball_game/object_collision/red_stage_resolve_collision.asm
@@ -2067,7 +2067,7 @@ DoSlotLogic_RedField: ; 0x16352
 	ld [wBonusStageSlotRewardActive], a

 	ld a, $1

 	ld [wd495], a

-	ld [wd4ae], a

+	ld [wMoveToNextScreenState], a

 	ld a, [wd498]

 	ld c, a

 	ld b, $0

@@ -2839,7 +2839,7 @@ UpdateBonusMultiplierRailing_RedField: ; 0x16e51
 	ret

 

 ShowBonusMultiplierMessage_RedField: ; 0x16ef5

-	ld a, [wd5ca]

+	ld a, [wBottomTextEnabled]

 	and a

 	ret nz

 	ld a, [wd613]

diff --git a/engine/pinball_game/slot.asm b/engine/pinball_game/slot.asm
index 01e3bef..a81fc14 100644
--- a/engine/pinball_game/slot.asm
+++ b/engine/pinball_game/slot.asm
@@ -25,7 +25,7 @@ Func_ed8e: ; 0xed8e
 	ld hl, HandleFlippers

 	call nz, BankSwitch

 	callba DrawSpritesForStage

-	call Func_33e3

+	call UpdateBottomText

 	call CleanOAMBuffer

 	rst AdvanceFrame

 	ld a, [wd7af]

diff --git a/engine/pinball_game/stage_init/init_blue_field.asm b/engine/pinball_game/stage_init/init_blue_field.asm
index 747d1af..03a93d6 100644
--- a/engine/pinball_game/stage_init/init_blue_field.asm
+++ b/engine/pinball_game/stage_init/init_blue_field.asm
@@ -19,7 +19,7 @@ InitBlueField: ; 0x1c000
 	ld [hli], a

 	ld [hli], a ; wNumPokeballs

 	ld [hli], a ; wPokeballBlinkingCounter

-	ld [wd7ac], a

+	ld [wDisableHorizontalScrollForBallStart], a

 	ld [wd7be], a

 	ld [wCurrentMap], a  ; PALLET_TOWN

 	ld a, $1

diff --git a/engine/pinball_game/stage_init/init_diglett_bonus.asm b/engine/pinball_game/stage_init/init_diglett_bonus.asm
index a04b201..26af2ca 100644
--- a/engine/pinball_game/stage_init/init_diglett_bonus.asm
+++ b/engine/pinball_game/stage_init/init_diglett_bonus.asm
@@ -5,7 +5,7 @@ InitDiglettBonusStage: ; 0x199f2
 	xor a

 	ld [wStageCollisionState], a

 	ld a, $1

-	ld [wd7ac], a

+	ld [wDisableHorizontalScrollForBallStart], a

 	ld a, [wBallType]

 	ld [wBallTypeBackup], a

 	xor a

diff --git a/engine/pinball_game/stage_init/init_gengar_bonus.asm b/engine/pinball_game/stage_init/init_gengar_bonus.asm
index 357de1c..65e313c 100644
--- a/engine/pinball_game/stage_init/init_gengar_bonus.asm
+++ b/engine/pinball_game/stage_init/init_gengar_bonus.asm
@@ -10,7 +10,7 @@ InitGengarBonusStage: ; 0x18099
 	ret

 .asm_180ac

 	ld a, $1

-	ld [wd7ac], a

+	ld [wDisableHorizontalScrollForBallStart], a

 	ld a, [wBallType]

 	ld [wBallTypeBackup], a

 	xor a

diff --git a/engine/pinball_game/stage_init/init_meowth_bonus.asm b/engine/pinball_game/stage_init/init_meowth_bonus.asm
index 178c90c..3e07fa6 100644
--- a/engine/pinball_game/stage_init/init_meowth_bonus.asm
+++ b/engine/pinball_game/stage_init/init_meowth_bonus.asm
@@ -12,7 +12,7 @@ InitMeowthBonusStage: ; 0x24000
 	ld [wBallType], a

 	ld [wCompletedBonusStage], a

 	ld a, $1

-	ld [wd7ac], a

+	ld [wDisableHorizontalScrollForBallStart], a

 	ld a, $40

 	ld [wMeowthXPosition], a

 	ld a, $20

diff --git a/engine/pinball_game/stage_init/init_mewtwo_bonus.asm b/engine/pinball_game/stage_init/init_mewtwo_bonus.asm
index 26410e3..1c26004 100644
--- a/engine/pinball_game/stage_init/init_mewtwo_bonus.asm
+++ b/engine/pinball_game/stage_init/init_mewtwo_bonus.asm
@@ -5,7 +5,7 @@ InitMewtwoBonusStage: ; 0x1924f
 	xor a

 	ld [wStageCollisionState], a

 	ld a, $1

-	ld [wd7ac], a

+	ld [wDisableHorizontalScrollForBallStart], a

 	ld a, [wBallType]

 	ld [wBallTypeBackup], a

 	xor a

diff --git a/engine/pinball_game/stage_init/init_red_field.asm b/engine/pinball_game/stage_init/init_red_field.asm
index ba8d1f8..a40ace1 100644
--- a/engine/pinball_game/stage_init/init_red_field.asm
+++ b/engine/pinball_game/stage_init/init_red_field.asm
@@ -19,7 +19,7 @@ InitRedField: ; 0x30000
 	ld [hli], a

 	ld [hli], a ; wNumPokeballs

 	ld [hli], a ; wPokeballBlinkingCounter

-	ld [wd7ac], a

+	ld [wDisableHorizontalScrollForBallStart], a

 	ld [wd7be], a

 	ld [wCurrentMap], a  ; PALLET_TOWN

 	ld a, $1

diff --git a/engine/pinball_game/stage_init/init_seel_bonus.asm b/engine/pinball_game/stage_init/init_seel_bonus.asm
index ee51417..2af90c9 100644
--- a/engine/pinball_game/stage_init/init_seel_bonus.asm
+++ b/engine/pinball_game/stage_init/init_seel_bonus.asm
@@ -6,7 +6,7 @@ InitSeelBonusStage: ; 0x25a7c
 	ld [wd4c8], a

 	ld [wStageCollisionState], a

 	ld a, $1

-	ld [wd7ac], a

+	ld [wDisableHorizontalScrollForBallStart], a

 	ld a, [wBallType]

 	ld [wBallTypeBackup], a

 	xor a

diff --git a/engine/pinball_game/vertical_screen_transition.asm b/engine/pinball_game/vertical_screen_transition.asm
index 59deb90..d534a21 100644
--- a/engine/pinball_game/vertical_screen_transition.asm
+++ b/engine/pinball_game/vertical_screen_transition.asm
@@ -37,13 +37,13 @@ LoadStageData: ; 0xe6c2
 	ld a, [wCurrentStage]

 	bit 0, a

 	ld a, $86

-	jr z, .asm_e6d5

-	ld a, [wd5ca]

+	jr z, .gotWindowYPos

+	ld a, [wBottomTextEnabled]

 	and a

 	ld a, $86

-	jr nz, .asm_e6d5

+	jr nz, .gotWindowYPos

 	ld a, $90

-.asm_e6d5

+.gotWindowYPos

 	ld [hWY], a

 	ld hl, StageGfxPointers_GameBoy

 	ld a, [hGameBoyColorFlag]

@@ -61,7 +61,7 @@ LoadStageData: ; 0xe6c2
 INCLUDE "data/stage_base_gfx.asm"

 

 CheckStageTransition: ; 0xece9

-	call Func_ed5e

+	call ScrollScreenToShowPinball

 	ld a, [wBallYPos + 1]

 	add $10

 	cp $18

@@ -99,7 +99,7 @@ CheckStageTransition: ; 0xece9
 

 .youLose

 	ld a, $1

-	ld [wd4ae], a

+	ld [wMoveToNextScreenState], a

 	callba HandleBallLoss

 	ret

 

@@ -143,9 +143,11 @@ BallMovingDownStageTransitions: ; 0xed4e
 	db $FF                      ; STAGE_SEEL_BONUS

 	db $FF                      ; STAGE_SEEL_BONUS

 

-Func_ed5e: ; 0xed5e

+ScrollScreenToShowPinball: ; 0xed5e

+; When the ball is launched on the Blue and Red Fields, the screen starts off scrolled to the right.

+; However, when the balls rolls in on Bonus Stages, the screen does NOT scroll.

 	ld hl, wSCX

-	ld a, [wd7ac]

+	ld a, [wDisableHorizontalScrollForBallStart]

 	and a

 	jr nz, .modify_scx_and_scy

 	ld a, [wBallXPos + 1]

@@ -154,7 +156,7 @@ Func_ed5e: ; 0xed5e
 	jr nc, .okay1

 	ld a, -2

 .okay1

-	ld [wd7aa], a

+	ld [wUnused_d7aa], a ; This is not used

 	add [hl]

 	cp $22

 	jr z, .modify_scx_and_scy

@@ -163,11 +165,11 @@ Func_ed5e: ; 0xed5e
 	ld [hl], a

 .modify_scx_and_scy

 	ld a, [hl]

-	ld hl, wd79f

+	ld hl, wLeftAndRightTiltPixelsOffset

 	sub [hl]

 	ld [hSCX], a

 	xor a

-	ld hl, wd7a0

+	ld hl, wUpperTiltPixelsOffset

 	sub [hl]

 	ld [hSCY], a

 	ret

diff --git a/home.asm b/home.asm
index 29c1420..817de2d 100644
--- a/home.asm
+++ b/home.asm
@@ -3872,9 +3872,9 @@ HandleLeftTilt: ; 0x358c
 	dec a  ; move ball's position to the left by 1 pixel
 	ld [wBallXPos + 1], a
 .skipBallMovement
-	ld a, [wd79f]
+	ld a, [wLeftAndRightTiltPixelsOffset]
 	inc a
-	ld [wd79f], a
+	ld [wLeftAndRightTiltPixelsOffset], a
 	ld a, $1
 	ld [wLeftTiltPushing], a
 	ret
@@ -3890,9 +3890,9 @@ HandleLeftTilt: ; 0x358c
 	jr z, .done
 	dec a
 	ld [wLeftTiltCounter], a
-	ld a, [wd79f]
+	ld a, [wLeftAndRightTiltPixelsOffset]
 	dec a
-	ld [wd79f], a
+	ld [wLeftAndRightTiltPixelsOffset], a
 	ret
 
 .done
@@ -3928,9 +3928,9 @@ HandleRightTilt: ; 0x35f3
 	inc a  ; move ball's position to the right by 1 pixel
 	ld [wBallXPos + 1], a
 .skipBallMovement
-	ld a, [wd79f]
+	ld a, [wLeftAndRightTiltPixelsOffset]
 	dec a
-	ld [wd79f], a
+	ld [wLeftAndRightTiltPixelsOffset], a
 	ld a, $1
 	ld [wRightTiltPushing], a
 	ret
@@ -3946,9 +3946,9 @@ HandleRightTilt: ; 0x35f3
 	jr z, .done
 	dec a
 	ld [wRightTiltCounter], a
-	ld a, [wd79f]
+	ld a, [wLeftAndRightTiltPixelsOffset]
 	inc a
-	ld [wd79f], a
+	ld [wLeftAndRightTiltPixelsOffset], a
 	ret
 
 .done
@@ -3984,9 +3984,9 @@ HandleUpperTilt: ; 0x365a
 	inc a  ; move ball's position down by 1 pixel
 	ld [wBallYPos + 1], a
 .skipBallMovement
-	ld a, [wd7a0]
+	ld a, [wUpperTiltPixelsOffset]
 	dec a
-	ld [wd7a0], a
+	ld [wUpperTiltPixelsOffset], a
 	ld a, $1
 	ld [wUpperTiltPushing], a
 	ret
@@ -4002,9 +4002,9 @@ HandleUpperTilt: ; 0x365a
 	jr z, .done
 	dec a
 	ld [wUpperTiltCounter], a
-	ld a, [wd7a0]
+	ld a, [wUpperTiltPixelsOffset]
 	inc a
-	ld [wd7a0], a
+	ld [wUpperTiltPixelsOffset], a
 	ret
 
 .done
diff --git a/home/text.asm b/home/text.asm
index b9bcea2..238af3a 100644
--- a/home/text.asm
+++ b/home/text.asm
@@ -4,8 +4,8 @@ Func_30db: ; 0x30db
 	ld a, $86
 	ld [hWY], a ;force text bar up
 	ld a, $1
-	ld [wd5ca], a ;place 1 in ???
-	ld [wd5cb], a
+	ld [wBottomTextEnabled], a
+	ld [wDisableDrawScoreboardInfo], a
 	ret
 
 FillBottomMessageBufferWithBlackTile: ; 0x30e8 wipes the message buffer and disables all text
@@ -445,7 +445,8 @@ Func_3309: ; 0x3309
 	inc de
 	ret
 
-HandleScrolling: ; 0x3325 activates while text is scrolling
+HandleScrollingText: ; 0x3325 activates while text is scrolling
+; Input: hl = pointer to scrolling_text struct
 	ld a, [hli] ;if scrolling set to off, ret.
 	and a
 	ret z
@@ -612,21 +613,22 @@ HandleStationaryText: ; 0x33c3 Handles stationary text
 	ld [hl], $0
 	ret
 
-Func_33e3: ; 0x33e3
-	ld a, [wd5ca]
+UpdateBottomText: ; 0x33e3
+; Updates the scrolling and/or stationary text messages in the bottom black bar.
+	ld a, [wBottomTextEnabled]
 	and a
-	jr nz, .asm_33ed ;if ??? = z, load 0 into ???, else jump
-	ld [wd5cb], a
+	jr nz, .textEnabled
+	ld [wDisableDrawScoreboardInfo], a
 	ret
 
-.asm_33ed
+.textEnabled
 	ld c, $0
 	ld a, [wScrollingText1Enabled]
 	and a
 	jr z, .Scrolling1Off ;if scrolling text is enabled, scroll text and inc c. repeat for each struct
 	push bc
 	ld hl, wScrollingText1
-	call HandleScrolling
+	call HandleScrollingText
 	pop bc
 	inc c
 .Scrolling1Off
@@ -635,7 +637,7 @@ Func_33e3: ; 0x33e3
 	jr z, .Scrolling2Off
 	push bc
 	ld hl, wScrollingText2
-	call HandleScrolling
+	call HandleScrollingText
 	pop bc
 	inc c
 .Scrolling2Off
@@ -644,7 +646,7 @@ Func_33e3: ; 0x33e3
 	jr z, .Scrolling3Off
 	push bc
 	ld hl, wScrollingText3
-	call HandleScrolling
+	call HandleScrollingText
 	pop bc
 	inc c
 .Scrolling3Off
@@ -678,7 +680,7 @@ Func_33e3: ; 0x33e3
 	ld a, c
 	and a
 	ret nz ;if text has displayed, we are done, else
-	ld [wd5ca], a ;place 0 in ???
+	ld [wBottomTextEnabled], a ; disable bottom text
 	call FillBottomMessageBufferWithBlackTile ;fill with default data?
 	ld a, [hGameBoyColorFlag]
 	and a
@@ -708,12 +710,12 @@ Func_3475: ; 0x3475
 	bit 0, a ;handle flippers if the stage has any
 	callba nz, HandleFlippers
 	callba DrawSpritesForStage
-	call Func_33e3
+	call UpdateBottomText
 	call CleanOAMBuffer
 	rst AdvanceFrame
-	ld a, [wd5ca]
+	ld a, [wBottomTextEnabled]
 	and a
-	jr nz, Func_3475 ;loops until wd5ca is zero
+	jr nz, Func_3475 ;loops until wBottomTextEnabled is zero
 	ret
 
 FivePoints:       ; 34a6
diff --git a/wram.asm b/wram.asm
index 64aa4f5..062907a 100644
--- a/wram.asm
+++ b/wram.asm
@@ -237,7 +237,8 @@ wCurrentStage:: ; 0xd4ac see constants/stage_constants.asm for list. bit 0 is 1
 wd4ad:: ; 0xd4ad
 	ds $1
 
-wd4ae:: ; 0xd4ae
+wMoveToNextScreenState:: ; 0xd4ae
+; This is set when the the screen state should advance, in the pinball game's core logic state.
 	ds $1
 
 wStageCollisionState:: ; 0xd4af
@@ -741,10 +742,15 @@ wWildMonCollision:: ; 0xd5c7
 
 	ds $1
 
-wd5ca:: ; 0xd5ca set to 1 by a commonly called text function that is called at the start of catch and raises the score bar. set off by text handler if no text is ready to run. Possibly toggles if text is running?
+wBottomTextEnabled:: ; 0xd5ca
+; 1 = text messages in the bottom black bar are enabled
+; 0 = disabled--the text won't appear even if LoadScrollingText is called
 	ds $1
 
-wd5cb:: ; 0xd5cb set to 0 if the above is 0 during Func_33e3
+wDisableDrawScoreboardInfo:: ; 0xd5cb
+; This is set when text messages are shown in the bottom black bar.
+; 1 = Skip drawing the scoreboard icons in the bottom black bar. (num pokemon caught, number of balls left, score)
+; 0 = Draw them.
 	ds $1
 
 scrolling_text: MACRO
@@ -1660,10 +1666,12 @@ wd79c:: ; 0xd79c
 wd79e:: ; 0xd79e
 	ds $1
 
-wd79f:: ; 0xd79f
+wLeftAndRightTiltPixelsOffset:: ; 0xd79f
+; Horizontal offset in pixels that the left and right tilt are currently moving the screen.
 	ds $1
 
-wd7a0:: ; 0xd7a0
+wUpperTiltPixelsOffset:: ; 0xd7a0
+; Vertical offset in pixels that the upper tilt is currently moving the screen.
 	ds $1
 
 wLeftTiltCounter:: ; 0xd7a1
@@ -1693,13 +1701,19 @@ wRightTiltPushing:: ; 0xd7a8
 wUpperTiltPushing:: ; 0xd7a9
 	ds $1
 
-wd7aa:: ; 0xd7aa
+wUnused_d7aa:: ; 0xd7aa
+; not actually used
 	ds $1
 
 wSCX:: ; 0xd7ab
 	ds $1
 
-wd7ac:: ; 0xd7ac
+wDisableHorizontalScrollForBallStart:: ; 0xd7ac
+; Controls whether or not the screen will scroll to accomodate the pinball when its off-screen.
+; When the ball is launched on the Blue and Red Fields, the screen starts off scrolled to the right.
+; However, when the balls rolls in on Bonus Stages, the screen does NOT scroll.
+; 1 = Disable the scrolling
+; 0 = Enable the scrolling
 	ds $1
 
 wd7ad:: ; 0xd7ad