Merge branch 'chaos_requests'

engine/pinball_game.asm

@@ -150,7 +150,7 @@ GameScreenFunction_HandleBallPhysics: ; 0xd909
 	and a
 	jr nz, .asm_d9e9
 	callba Func_85c7
-	callba Func_8650
+	callba HideScoreIfBallLow
 	callba Func_8645
 	call Func_dba9
 	call Func_dc7c
@@ -206,7 +206,7 @@ GameScreenFunction_HandleBallLoss: ; 0xda36
 	ld [wDrawBottomMessageBox], a
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5dc
+	ld hl, wScrollingTextStruct3
 	ld de, ShootAgainText
 	call LoadTextHeader
 	ret

engine/pinball_game/ball_loss/ball_loss_diglett_bonus.asm

@@ -18,7 +18,7 @@ HandleBallLossDiglettBonus: ; 0xe056
 	ret nz
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5dc
+	ld hl, wScrollingTextStruct3
 	ld de, EndDiglettStageText
 	call LoadTextHeader
 	ret

engine/pinball_game/ball_loss/ball_loss_gengar_bonus.asm

@@ -44,7 +44,7 @@ HandleBallLossGengarBonus: ; 0xdf1a
 	ret nz
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5dc
+	ld hl, wScrollingTextStruct3
 	ld de, EndGengarStageText
 	call LoadTextHeader
 	ret

engine/pinball_game/ball_loss/ball_loss_meowth_bonus.asm

@@ -51,7 +51,7 @@ HandleBallLossMeowthBonus: ; 0xdfe2
 	ret nz
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5dc
+	ld hl, wScrollingTextStruct3
 	ld de, EndMeowthStageText
 	call LoadTextHeader
 	ret

engine/pinball_game/ball_loss/ball_loss_mewtwo_bonus.asm

@@ -44,7 +44,7 @@ HandleBallLossMewtwoBonus: ; 0xdf7e
 	ret nz
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5dc
+	ld hl, wScrollingTextStruct3
 	ld de, EndMewtwoStageText
 	call LoadTextHeader
 	ret

engine/pinball_game/ball_loss/ball_loss_seel_bonus.asm

@@ -50,7 +50,7 @@ HandleBallLossSeelBonus: ; 0xe08b
 	ret nz
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5dc
+	ld hl, wScrollingTextStruct3
 	ld de, EndSeelStageText
 	call LoadTextHeader
 	ret

engine/pinball_game/catchem_mode.asm

@@ -6,35 +6,35 @@ StartCatchEmMode: ; 0x1003f
 	ld [wInSpecialMode], a  ; set special mode flag
 	xor a
 	ld [wSpecialMode], a
-	ld [wd54d], a
+	ld [wd54d], a ;set ??? to 0
 	ld a, [wCurrentStage]
 	sla a
-	ld c, a
+	ld c, a ;store twice current stage to use a pointer offset
 	ld b, $0
 	push bc
 	ld hl, WildMonOffsetsPointers
 	add hl, bc
-	ld a, [hli]
+	ld a, [hli] ;hl = pointer to wild mon pointer table
 	ld h, [hl]
 	ld l, a
 	ld a, [wCurrentMap]
 	sla a
 	ld c, a
-	add hl, bc
+	add hl, bc ;go to correct location in table
 	ld a, [hli]
 	ld c, a
 	ld a, [hl]
-	ld b, a
+	ld b, a ;bc = offset needed to reach correct wild table
-	pop de
+	pop de ;pop current stage offset
 	ld hl, WildMonPointers
 	add hl, de
-	ld a, [hli]
+	ld a, [hli] ;fetch start od correct wilds table, place in hl
 	ld h, [hl]
 	ld l, a
 	add hl, bc
 	call GenRandom
 	and $f
-	call CheckForMew
+	call CheckForMew ;a = $10 if mew, else is less
 	ld c, a
 	ld b, $0
 	add hl, bc
@@ -42,20 +42,20 @@ StartCatchEmMode: ; 0x1003f
 	sla a
 	ld c, a
 	add hl, bc
-	ld a, [hl]  ; a contains mon id
+	ld a, [hl]  ; a contains mon id. overshoots by 1 if mew, causing mew to be loaded
 	dec a
-	ld [wCurrentCatchEmMon], a
+	ld [wCurrentCatchEmMon], a ;stores 1 less than ID
-	ld a, [wCurrentCatchEmMon]
+	ld a, [wCurrentCatchEmMon] ;wow gamefreak
 	ld c, a
 	ld b, $0
-	ld hl, EvolutionLineIds
+	ld hl, EvolutionLineIds ;fetch the mon's evolution line
 	add hl, bc
 	ld c, [hl]
 	ld h, b
 	ld l, c
 	add hl, bc
-	add hl, bc  ; multiply the evolution line id by 3
+	add hl, bc  ; multiply the evolution line id by 3, add it to pointer to ???
-	ld bc, Data_13685
+	ld bc, Data_13685 ;mystery data
 	add hl, bc
 	ld a, [hli]
 	ld [wd5c1], a
@@ -63,25 +63,25 @@ StartCatchEmMode: ; 0x1003f
 	ld a, [hli]
 	ld [wd5c2], a
 	ld a, [hli]
-	ld [wd5c3], a
+	ld [wd5c3], a ;load the 3 bytes into ????
 	ld hl, wd586
 	ld a, [wd5b6]
 	ld c, a
 	and a
 	ld b, $18
-	jr z, .asm_100c7
+	jr z, .asm_100c7 ;if ?? = 0, jump with b = 24 (2 seperate loops?
 .asm_100ba
 	ld a, $1
-	ld [hli], a
+	ld [hli], a ;load 1 then 0 into data from wd5b6 C times, where C is the contents of wd5b6
 	xor a
 	ld [hli], a
 	dec b
 	dec c
 	jr nz, .asm_100ba
-	ld a, b
+	ld a, b ;load 24 - times looped into a, if 0: skip
 	and a
 	jr z, .asm_100ce
-.asm_100c7
+.asm_100c7 ;loop 0 then 1 into the rest of the data from wd5b6
 	xor a
 	ld [hli], a
 	inc a
@@ -94,12 +94,12 @@ StartCatchEmMode: ; 0x1003f
 	ld b, $0
 	sla c
 	rl b
-	ld hl, CatchEmTimerData
+	ld hl, CatchEmTimerData ;contains how long each mon stays on screen, all are 2 minutes by default
 	add hl, bc
 	ld a, [hli]
 	ld c, a
 	ld a, [hl]
-	ld b, a
+	ld b, a ;bc = timer legnth. b = secons c = minutes
 	callba StartTimer
 	callba InitBallSaverForCatchEmMode
 	call Func_10696
@@ -136,27 +136,27 @@ CheckForMew:
 ;   3. The right alley has been hit three times
 ;   4. The Mewtwo Bonus Stage completion counter equals 2.
 	push af
-	cp $f  ; random number equals $f
+	cp $f  ; random number equals $f (1 in 16)
-	jr nz, .asm_10155
+	jr nz, .NotMew
 	ld a, c
 	cp (BlueStageIndigoPlateauWildMons - BlueStageWildMons) & $ff  ; check if low-byte of map mons offset is Indigo Plateau
-	jr nz, .asm_10155
+	jr nz, .NotMew
 	ld a, b
 	cp (BlueStageIndigoPlateauWildMons - BlueStageWildMons) >> 8  ; check if high-byte of map mons offset is Indigo Plateau
-	jr nz, .asm_10155
+	jr nz, .NotMew
 	ld a, [wRareMonsFlag]
 	cp $8
-	jr nz, .asm_10155
+	jr nz, .NotMew
 	ld a, [wNumMewtwoBonusCompletions]
 	cp NUM_MEWTWO_COMPLETIONS_FOR_MEW
-	jr nz, .asm_10155
+	jr nz, .NotMew
 	pop af
 	xor a
 	ld [wNumMewtwoBonusCompletions], a
 	ld a, $10
 	ret
 
-.asm_10155
+.NotMew
 	pop af
 	ret
 
@@ -930,7 +930,7 @@ ShowAnimatedWildMon: ; 0x10678
 Func_10696: ; 0x10696
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	ld de, LetsGetPokemonText
 	call LoadTextHeader
 	ret
@@ -938,7 +938,7 @@ Func_10696: ; 0x10696
 Func_106a6: ; 0x106a6
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	ld de, PokemonRanAwayText
 	call LoadTextHeader
 	ret
@@ -979,10 +979,10 @@ Func_106b6: ; 0x106b6
 	push de
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	pop de
 	call LoadTextHeader
-	ld hl, wd5d4
+	ld hl, wScrollingTextStruct2
 	pop de
 	call LoadTextHeader
 	pop hl
@@ -1178,10 +1178,10 @@ Func_10848: ; 0x10848
 	callba AddBigBCD6FromQueue
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5d4
+	ld hl, wScrollingTextStruct2
 	ld de, OneBillionText
 	call LoadTextHeader
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	ld de, PokemonCaughtSpecialBonusText
 	call LoadTextHeader
 	call Func_3475

engine/pinball_game/end_of_ball_bonus.asm

@@ -61,10 +61,10 @@ Func_f57f: ; 0xf57f
 ShowBallBonusSummary: ; 0xf5a0
 	ld de, wBottomMessageText + $40
 	ld hl, BonusPointsText
-	call PrintTextNoHeader
+	call PlaceTextAlphanumericOnly
 	ld de, wBottomMessageText + $80
 	ld hl, SubtotalPointsText
-	call PrintTextNoHeader
+	call PlaceTextAlphanumericOnly
 	ld hl, wd489
 	call ClearBCD6Buffer
 	ld hl, wd48f
@@ -90,7 +90,7 @@ ShowBallBonusSummary: ; 0xf5a0
 	call Func_f81b
 	ld de, wBottomMessageText + $20
 	ld hl, GameOverText
-	call PrintTextNoHeader
+	call PlaceTextAlphanumericOnly
 	ld bc, $0040
 	ld de, $0000
 	call Func_f80d
@@ -121,7 +121,7 @@ CallTable_f60d: ; 0xf60d
 HandleNumPokemonCaughtBallBonus: ; 0xf626
 	ld de, wBottomMessageText + $01
 	ld hl, NumPokemonCaughtText
-	call PrintTextNoHeader
+	call PlaceTextAlphanumericOnly
 	ld hl, wBottomMessageText + $01
 	ld a, [wNumPokemonCaughtInBallBonus]
 	call Func_f78e
@@ -137,7 +137,7 @@ HandleNumPokemonCaughtBallBonus: ; 0xf626
 HandleNumPokemonEvolvedBallBonus: ; 0xf64e
 	ld de, wBottomMessageText
 	ld hl, NumPokemonEvolvedText
-	call PrintTextNoHeader
+	call PlaceTextAlphanumericOnly
 	ld hl, wBottomMessageText
 	ld a, [wNumPokemonEvolvedInBallBonus]
 	call Func_f78e
@@ -176,10 +176,10 @@ Func_f676: ; 0xf676
 	jr nz, .asm_f678
 	ld de, wBottomMessageText + $40
 	ld hl, MultiplierPointsText
-	call PrintTextNoHeader
+	call PlaceTextAlphanumericOnly
 	ld de, wBottomMessageText + $80
 	ld hl, TotalPointsText
-	call PrintTextNoHeader
+	call PlaceTextAlphanumericOnly
 	ld hl, wBottomMessageText + $50
 	ld a, [wCurBonusMultiplier]
 	call Func_f78e
@@ -249,7 +249,7 @@ Func_f70d: ; 0xf70d
 	jr nz, .asm_f70f
 	ld de, wBottomMessageText + $60
 	ld hl, ScoreText
-	call PrintTextNoHeader
+	call PlaceTextAlphanumericOnly
 	ld hl, wScore + $5
 	ld de, wBottomMessageText + $66
 	call Func_f8bd
@@ -308,43 +308,43 @@ Func_f78e: ; 0xf78e
 	ld c, $0
 	ret
 
-PrintTextNoHeader: ; 0xf7b1
+PlaceTextAlphanumericOnly: ; 0xf7b1 seems to filter out punctuation and other misc characters
-	ld a, [wd805]
+	ld a, [wd805] ;id unusedTextFlag is set, take olther path
 	and a
-	jr nz, .asm_f7e0
+	jr nz, .UnusedBranch
 .loop
 	ld a, [hli]
 	and a
-	ret z
+	ret z ;if end of text, ret
 	cp "0"
-	jr c, .asm_f7c6
+	jr c, .NotADigit ;if a digit, add $56 and skip letter check
 	cp "9" + 1
-	jr nc, .asm_f7c6
+	jr nc, .NotADigit
 	add $56
-	jr .asm_f7dc
+	jr .IsValidChar
 
-.asm_f7c6
+.NotADigit
 	cp "A"
-	jr c, .asm_f7d2
+	jr c, .NotALetter ;if a letter, add $56 and skip letter check
 	cp "Z" + 1
-	jr nc, .asm_f7d2
+	jr nc, .NotALetter
 	add $bf
-	jr .asm_f7dc
+	jr .IsValidChar
 
-.asm_f7d2
+.NotALetter
-	cp "e"
+	cp "e" ;check if acute e
-	jr nz, .asm_f7da
+	jr nz, .NotAcuteE
 	ld a, $83
-	jr .asm_f7dc
+	jr .IsValidChar
 
-.asm_f7da
+.NotAcuteE
-	ld a, $81
+	ld a, $81 ;if none of the above groups, replace with a space
-.asm_f7dc
+.IsValidChar
-	ld [de], a
+	ld [de], a ;load result into de
 	inc de
 	jr .loop
 
-.asm_f7e0
+.UnusedBranch
 	ld a, [hli]
 	and a
 	ret z
@@ -376,7 +376,7 @@ PrintTextNoHeader: ; 0xf7b1
 .asm_f809
 	ld [de], a
 	inc de
-	jr .asm_f7e0
+	jr .UnusedBranch
 
 Func_f80d: ; 0xf80d
 	hlCoord 0, 0, vBGWin
@@ -590,7 +590,7 @@ HandleBallBonusRedField: ; 0xf945
 HandleBellsproutEntriesBallBonus: ; 0xf952
 	ld de, wBottomMessageText + $03
 	ld hl, BellsproutCounterText
-	call PrintTextNoHeader
+	call PlaceTextAlphanumericOnly
 	ld hl, wBottomMessageText + $03
 	ld a, [wNumBellsproutEntries]
 	call Func_f78e
@@ -606,7 +606,7 @@ HandleBellsproutEntriesBallBonus: ; 0xf952
 HandleDugtrioTriplesBallBonus: ; 0xf97a
 	ld de, wBottomMessageText + $04
 	ld hl, DugtrioCounterText
-	call PrintTextNoHeader
+	call PlaceTextAlphanumericOnly
 	ld hl, wBottomMessageText + $04
 	ld a, [wNumDugtrioTriples]
 	call Func_f78e
@@ -622,7 +622,7 @@ HandleDugtrioTriplesBallBonus: ; 0xf97a
 HandleCAVECompletionsBallBonus_RedField: ; 0xf9a2
 	ld de, wBottomMessageText + $03
 	ld hl, CaveShotCounterText
-	call PrintTextNoHeader
+	call PlaceTextAlphanumericOnly
 	ld hl, wBottomMessageText + $03
 	ld a, [wNumCAVECompletions]
 	call Func_f78e
@@ -638,7 +638,7 @@ HandleCAVECompletionsBallBonus_RedField: ; 0xf9a2
 HandleSpinnerTurnsBallBonus_RedField: ; 0xf9ca
 	ld de, wBottomMessageText + $01
 	ld hl, SpinnerTurnsCounterText
-	call PrintTextNoHeader
+	call PlaceTextAlphanumericOnly
 	ld hl, wBottomMessageText + $01
 	ld a, [wNumSpinnerTurns]
 	call Func_f78e
@@ -666,7 +666,7 @@ HandleBallBonusBlueField: ; 0xf9f3
 HandleCloysterEntriesBallBonus: ; 0xfa06
 	ld de, wBottomMessageText + $04
 	ld hl, CloysterCounterText
-	call PrintTextNoHeader
+	call PlaceTextAlphanumericOnly
 	ld hl, wBottomMessageText + $04
 	ld a, [wNumCloysterEntries]
 	call Func_f78e
@@ -682,7 +682,7 @@ HandleCloysterEntriesBallBonus: ; 0xfa06
 HandleSlowpokeEntriesBallBonus: ; 0xfa2e
 	ld de, wBottomMessageText + $04
 	ld hl, SlowpokeCounterText
-	call PrintTextNoHeader
+	call PlaceTextAlphanumericOnly
 	ld hl, wBottomMessageText + $04
 	ld a, [wNumSlowpokeEntries]
 	call Func_f78e
@@ -698,7 +698,7 @@ HandleSlowpokeEntriesBallBonus: ; 0xfa2e
 HandlePoliwagTriplesBallBonus: ; 0xfa56
 	ld de, wBottomMessageText + $04
 	ld hl, PoliwagCounterText
-	call PrintTextNoHeader
+	call PlaceTextAlphanumericOnly
 	ld hl, wBottomMessageText + $04
 	ld a, [wNumPoliwagTriples]
 	call Func_f78e
@@ -714,7 +714,7 @@ HandlePoliwagTriplesBallBonus: ; 0xfa56
 HandlePsyduckTriplesBallBonus: ; 0xfa7e
 	ld de, wBottomMessageText + $04
 	ld hl, PsyduckCounterText
-	call PrintTextNoHeader
+	call PlaceTextAlphanumericOnly
 	ld hl, wBottomMessageText + $04
 	ld a, [wNumPsyduckTriples]
 	call Func_f78e
@@ -730,7 +730,7 @@ HandlePsyduckTriplesBallBonus: ; 0xfa7e
 HandleCAVECompletionsBallBonus_BlueField: ; 0xfaa6
 	ld de, wBottomMessageText + $03
 	ld hl, CaveShotCounterText
-	call PrintTextNoHeader
+	call PlaceTextAlphanumericOnly
 	ld hl, wBottomMessageText + $03
 	ld a, [wNumCAVECompletions]
 	call Func_f78e
@@ -746,7 +746,7 @@ HandleCAVECompletionsBallBonus_BlueField: ; 0xfaa6
 HandleSpinnerTurnsBallBonus_BlueField: ; 0xface  :)
 	ld de, wBottomMessageText + $01
 	ld hl, SpinnerTurnsCounterText
-	call PrintTextNoHeader
+	call PlaceTextAlphanumericOnly
 	ld hl, wBottomMessageText + $01
 	ld a, [wNumSpinnerTurns]
 	call Func_f78e

engine/pinball_game/evolution_mode/evolution_mode_blue_field.asm

@@ -72,7 +72,7 @@ Func_20c08: ; 0x20c08
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
 	ld de, YeahYouGotItText
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	call LoadTextHeader
 	ld a, [hGameBoyColorFlag]
 	and a
@@ -257,7 +257,7 @@ Func_20da0: ; 0x20da0
 	callba StopTimer
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	ld de, EvolutionFailedText
 	call LoadTextHeader
 	ret
@@ -494,7 +494,7 @@ Func_20f75: ; 0x20f75
 	ld e, a
 	ld a, [hl]
 	ld d, a
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	call LoadTextHeader
 	scf
 	ret
@@ -527,7 +527,7 @@ Func_20fef: ; 0x20fef
 	callba AddBigBCD6FromQueue
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	ld a, [wCurrentEvolutionType]
 	cp EVO_EXPERIENCE
 	ld de, PokemonIsTiredText
@@ -631,7 +631,7 @@ asm_210c7:
 	jr z, .asm_21115
 	ld de, TryNextPlaceText
 .asm_21115
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	call LoadTextHeader
 	scf
 	ret

engine/pinball_game/evolution_mode/evolution_mode_red_field.asm

@@ -75,7 +75,7 @@ Func_205e0: ; 0x205e0
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
 	ld de, YeahYouGotItText
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	call LoadTextHeader
 	ld a, [hGameBoyColorFlag]
 	and a
@@ -260,7 +260,7 @@ Func_2077b: ; 0x2077b
 	callba StopTimer
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	ld de, EvolutionFailedText
 	call LoadTextHeader
 	ret
@@ -517,7 +517,7 @@ Func_20977: ; 0x20977
 	ld e, a
 	ld a, [hl]
 	ld d, a
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	call LoadTextHeader
 	scf
 	ret
@@ -549,7 +549,7 @@ Func_209eb: ; 0x209eb
 	callba AddBigBCD6FromQueue
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	ld a, [wCurrentEvolutionType]
 	cp EVO_EXPERIENCE
 	ld de, PokemonIsTiredText
@@ -633,7 +633,7 @@ asm_20a9f:
 	jr z, .asm_20aed
 	ld de, TryNextPlaceText
 .asm_20aed
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	call LoadTextHeader
 	scf
 	ret

engine/pinball_game/extra_ball.asm

@@ -10,7 +10,7 @@ HandleExtraBall: ; 0x30188
 	jr nz, .asm_301a7
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	ld de, ExtraBallText
 	call LoadTextHeader
 	jr .asm_301c9
@@ -22,12 +22,12 @@ HandleExtraBall: ; 0x30188
 	push de
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5d4
+	ld hl, wScrollingTextStruct2
 	ld de, DigitsText1to9
 	call Func_32cc
 	pop de
 	pop bc
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	ld de, ExtraBallSpecialBonusText
 	call LoadTextHeader
 .asm_301c9

engine/pinball_game/object_collision/blue_stage_resolve_collision.asm

@@ -1340,7 +1340,7 @@ ShowBonusMultiplierMessage_BlueField: ; 0x1d5bf
 	ld [wd613], a
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	ld de, BonusMultiplierText
 	call LoadTextHeader
 	ld hl, wBottomMessageText + $12
@@ -2081,7 +2081,7 @@ ResolveBlueStagePinballUpgradeTriggersCollision: ; 0x1e356
 	call PlaySoundEffect
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	ld de, FieldMultiplierText
 	call LoadTextHeader
 	ld a, [wBallType]
@@ -2106,12 +2106,12 @@ ResolveBlueStagePinballUpgradeTriggersCollision: ; 0x1e356
 	push de
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5d4
+	ld hl, wScrollingTextStruct2
 	ld de, DigitsText1to8
 	call Func_32cc
 	pop de
 	pop bc
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	ld de, FieldMultiplierSpecialBonusText
 	call LoadTextHeader
 .asm_1e465
@@ -2896,7 +2896,7 @@ Func_1e830: ; 0x1e830
 Func_1e8c3: ; 0x1e8c3
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5dc
+	ld hl, wScrollingTextStruct3
 	ld a, [wd497]
 	ld de, GoToMeowthStageText
 	cp STAGE_MEOWTH_BONUS

engine/pinball_game/object_collision/diglett_bonus_resolve_collision.asm

@@ -677,7 +677,7 @@ Func_1ab30: ; 0x1ab30
 	ld [wCompletedBonusStage], a
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5dc
+	ld hl, wScrollingTextStruct3
 	ld de, DiglettStageClearedText
 	call LoadTextHeader
 	lb de, $4b, $2a

engine/pinball_game/object_collision/gengar_bonus_resolve_collision.asm

@@ -1005,7 +1005,7 @@ Func_189af: ; 0x189af
 	ld [wCompletedBonusStage], a
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5dc
+	ld hl, wScrollingTextStruct3
 	ld de, GengarStageClearedText
 	call LoadTextHeader
 	lb de, $4b, $2a

engine/pinball_game/object_collision/meowth_bonus_resolve_collision.asm

@@ -202,7 +202,7 @@ ResolveMeowthBonusGameObjectCollisions: ; 0x2442a
 	ld [wCompletedBonusStage], a
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5dc
+	ld hl, wScrollingTextStruct3
 	ld de, MeowthStageClearedText
 	call LoadTextHeader
 	lb de, $4b, $2a

engine/pinball_game/object_collision/mewtwo_bonus_resolve_collision.asm

@@ -351,7 +351,7 @@ Func_19638: ; 0x19638
 	ld [wCompletedBonusStage], a
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5dc
+	ld hl, wScrollingTextStruct3
 .asm_1966b
 	ld de, MewtwoStageClearedText
 	call LoadTextHeader

engine/pinball_game/object_collision/red_stage_resolve_collision.asm

@@ -1141,7 +1141,7 @@ ResolveRedStagePinballUpgradeTriggersCollision: ; 0x1535d
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
 	ld de, FieldMultiplierText
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	call LoadTextHeader
 	ld a, [wBallType]
 	ld c, a
@@ -1165,12 +1165,12 @@ ResolveRedStagePinballUpgradeTriggersCollision: ; 0x1535d
 	push de
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5d4
+	ld hl, wScrollingTextStruct2
 	ld de, DigitsText1to8
 	call Func_32cc
 	pop de
 	pop bc
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	ld de, FieldMultiplierSpecialBonusText
 	call LoadTextHeader
 .asm_15447
@@ -3612,7 +3612,7 @@ Func_16352: ; 0x16352
 Func_163f2: ; 0x163f2
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5dc
+	ld hl, wScrollingTextStruct3
 	ld a, [wd497]
 	ld de, GoToDiglettStageText
 	cp STAGE_DIGLETT_BONUS
@@ -5596,7 +5596,7 @@ ShowBonusMultiplierMessage_RedField: ; 0x16ef5
 	ld [wd613], a
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	ld de, BonusMultiplierText
 	call LoadTextHeader
 	ld hl, wBottomMessageText + $12

engine/pinball_game/object_collision/seel_bonus_resolve_collision.asm

@@ -15,7 +15,7 @@ ResolveSeelBonusGameObjectCollisions: ; 0x25c5a
 	ld [wCompletedBonusStage], a
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5dc
+	ld hl, wScrollingTextStruct3
 	ld de, SeelStageClearedText
 	call LoadTextHeader
 	ld a, $2

engine/pinball_game/score.asm

@@ -214,10 +214,10 @@ Func_8645: ; 0x8645
 	call Func_8524
 	ret
 
-Func_8650: ; 0x8650
+HideScoreIfBallLow: ; 0x8650
 	ld a, [wCurrentStage]
 	bit 0, a
-	jr nz, .bottomStage
+	jr nz, .bottomStage ;if on upper stage, score is up
 	ld a, $86
 	ld [hWY], a
 	ret
@@ -225,22 +225,22 @@ Func_8650: ; 0x8650
 .bottomStage
 	ld a, [wBallYPos + 1]
 	cp $84
-	jr nc, .asm_8670
+	jr nc, .BallLow ;if ballY pos less than or equal to 132, raise score, else lower score
 	ld a, [hWY]
 	sub $3
 	cp $86
-	jr nc, .asm_866d
+	jr nc, .DontClampHigh ;if result is less than 132, clamp to 132, else just load it in
 	ld a, $86
-.asm_866d
+.DontClampHigh
 	ld [hWY], a
 	ret
 
-.asm_8670
+.BallLow
 	ld a, [hWY]
 	add $3
 	cp $90
-	jr c, .asm_867a
+	jr c, .DontClampLow ;if result is more than 144, clamp to 144, else just load it in
 	ld a, $90
-.asm_867a
+.DontClampLow
 	ld [hWY], a
 	ret

engine/pinball_game/slot.asm

@@ -369,7 +369,7 @@ SlotRewardUpgradeBall: ; 0xf040
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
 	ld de, FieldMultiplierText
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	call LoadTextHeader
 	; upgrade ball type
 	ld a, [wBallType]
@@ -394,12 +394,12 @@ SlotRewardUpgradeBall: ; 0xf040
 	push de
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5d4
+	ld hl, wScrollingTextStruct2
 	ld de, DigitsText1to8
 	call Func_32cc
 	pop de
 	pop bc
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	ld de, FieldMultiplierSpecialBonusText
 	call LoadTextHeader
 .asm_f0b0

home.asm

@@ -285,8 +285,8 @@ VBlank: ; 0x2f2
 	ld a, [hli]
 	ld [$ff00+c], a
 	inc c
-	ld a, [hli]
+	ld a, [hli] ;hWY
-	ld [$ff00+c], a
+	ld [$ff00+c], a ;into FF4A
 	inc c
 	ld a, [hli]
 	ld [$ff00+c], a
@@ -468,13 +468,13 @@ Serial: ; 0x445
 	push bc
 	push de
 	push hl
-	ld hl, Data_45d 
+	ld hl, Data_45d
 	push hl
 	ld a, [$ffb1]
 	sla a
 	ld c, a
 	ld b, $0
-	ld hl, Data_462 
+	ld hl, Data_462
 	add hl, bc
 	ld c, [hl]
 	inc hl
@@ -612,7 +612,7 @@ Func_504: ; 0x504
 	ld a, [wCurrentSongBank]
 	ld [hLoadedROMBank], a
 	ld [MBC5RomBank], a
-	call Func_3c180 
+	call Func_3c180
 	pop af
 	ld [hLoadedROMBank], a
 	ld [MBC5RomBank], a

home/text.asm

@@ -1,8 +1,8 @@
 Func_30db: ; 0x30db
 	ld a, $86
-	ld [hWY], a
+	ld [hWY], a ;force text bar up
 	ld a, $1
-	ld [wd5ca], a
+	ld [wd5ca], a ;place 1 in ???
 	ld [wd5cb], a
 	ret
 
@@ -18,9 +18,9 @@ FillBottomMessageBufferWithBlackTile: ; 0x30e8
 	dec b
 	jr nz, .loop
 	xor a
-	ld [wd5cc], a
+	ld [wScrollingTextStruct1], a
-	ld [wd5d4], a
+	ld [wScrollingTextStruct2], a
-	ld [wd5dc], a
+	ld [wScrollingTextStruct3], a
 	ld [wd5e4], a
 	ld [wd5e9], a
 	ld [wd5ee], a
@@ -48,16 +48,16 @@ Func_310a: ; 0x310a
 	jr nz, .asm_311d
 	ret
 
-LoadMonNameIntoBottomMessageBufferList: ; 0x3125 enables special loads
+LoadMonNameIntoBottomMessageBufferList: ; 0x3125 increases address to load into by 64
 	ld b, $1
-	jr asm_312b
+	jr JumpToPlaceText
 
-Func_3129: ; 0x3129 disables special loads
+PlaceTextLow: ; 0x3129 disables special loads PlaceTextLow
 	ld b, $0
-asm_312b: ; 0x312b loads e chars of text text into de
+JumpToPlaceText: ; 0x312b loads e chars of text text into de
 	ld a, [wd805]
 	and a
-	jp nz, Func_3268 ;if ??? = 0, then continue, else jump
+	jp nz, UnusedPlaceString ;unused alternate place string
 .next_char
 	ld a, [hli]
 	and a
@@ -86,10 +86,10 @@ asm_312b: ; 0x312b loads e chars of text text into de
 	cp ":"
 	jr z, .colon
 	cp "0"
-	jr c, .check_atoz
+	jr c, .check_AtoZ
 	cp "9" + 1
 	jr c, .digit
-.check_atoz
+.check_AtoZ
 	cp "A"
 	jr c, .invalid
 	cp "Z" + 1
@@ -104,7 +104,7 @@ asm_312b: ; 0x312b loads e chars of text text into de
 .comma
 	inc c ;$82 = , , goes back a space?
 	dec e
-	jr .check_special_load
+	jr .CheckLoadHieght
 
 .male
 	xor a
@@ -168,14 +168,14 @@ asm_312b: ; 0x312b loads e chars of text text into de
 	add $bf
 .load_char
 	ld [de], a ;load char into de
-.check_special_load
+.CheckLoadHieght
 	bit 0, b
-	jr nz, .no_special_load ;only load special if b is 1
+	jr nz, .LowLoad ;only load special if b is 1
-	set 7, e ;tempererally set 7 of e, adding  to pointer de or taking it away
+	set 7, e ;temporerally set 7 of e, adding  to pointer de or taking it away
 	ld a, c
 	ld [de], a
 	res 7, e
-.no_special_load
+.LowLoad
 	inc e ;move to next slot
 	jp .next_char
 
@@ -269,20 +269,20 @@ SpecialTextCharPointers:
 	dw vTilesSH tile 3 ;colon
 	dbw Bank(Colon_CharacterGfx_GameboyColor), Colon_CharacterGfx_GameboyColor
 
-Func_3268: ; 0x3268
+UnusedPlaceString: ; 0x3268 seems to place text based on different, confusing logic, but the enabling flag is never set above 0
 	ld a, [hli]
 	and a
 	ret z
-	ld c, $81
+	ld c, $81 ;special space?
-	cp $20
+	cp " "
-	jr z, .asm_3297
+	jr z, .Space ;space
-	cp $2c
+	cp ","
-	jr z, .asm_329a
+	jr z, .Comma ;comma
-	cp $30
+	cp "0"
-	jr c, .asm_327d
+	jr c, .Punctuation ;less than 0 is punctuation
-	cp $3a
+	cp "9" + 1
-	jr c, .asm_329e
+	jr c, .Digits ;less than colon is numbers, more than is a mix of punctuation and AtoZ
-.asm_327d
+.Punctuation
 	cp $a0
 	jr c, .asm_3285
 	cp $e0
@@ -293,7 +293,7 @@ Func_3268: ; 0x3268
 	cp $f4
 	jr c, .asm_3293
 .asm_328d
-	jr Func_3268
+	jr UnusedPlaceString
 
 .asm_328f
 	sub $80
@@ -303,16 +303,16 @@ Func_3268: ; 0x3268
 	sub $50
 	jr .asm_32a0
 
-.asm_3297
+.Space
 	ld a, c
 	jr .asm_32a0
 
-.asm_329a
+.Comma
 	inc c
 	dec e
 	jr .asm_32a1
 
-.asm_329e
+.Digits
 	add $56
 .asm_32a0
 	ld [de], a
@@ -322,7 +322,7 @@ Func_3268: ; 0x3268
 	ld [de], a
 	res 7, e
 	inc e
-	jr Func_3268
+	jr UnusedPlaceString
 
 LoadTextHeader: ; 0x32aa
 ; Loads scrolling text into the specified buffer.
@@ -443,51 +443,51 @@ Func_3309: ; 0x3309
 	inc de
 	ret
 
-Func_3325: ; 0x3325
+HandleScrolling: ; 0x3325 activates while text is scrolling
-	ld a, [hli]
+	ld a, [hli] ;if scrolling set to off, ret.
 	and a
 	ret z
 	ld a, [hl]
-	dec a
+	dec a ;decrement time until next scroll, if it is zero then process a scroll
 	ld [hli], a
 	ret nz
-	ld a, [hld]
+	ld a, [hld] ;reset the scroll timer
 	ld [hl], a
 	inc hl
 	inc hl
 	push hl
-	ld a, [hli]
+	ld a, [hli] ;retrieve current text start position from the struct, place in e for the PlaceText function
 	ld e, a
-	cp [hl]
+	cp [hl] ; check if in the stop position
 	inc hl
-	jr nz, .asm_333c
+	jr nz, .NotInStopPosition
-	ld a, [hl]
+	ld a, [hl] ;lower stop position timer
 	dec a
 	ld [hl], a
-	jr nz, .asm_333d
+	jr nz, .SkipScroll ;if stop timer not zero, prevent the scroll by setting e to the current position
-.asm_333c
+.NotInStopPosition
-	dec e
+	dec e ;decrement the text start position, causing the text to move 1 tile to the left
-.asm_333d
+.SkipScroll
 	push de
-	ld d, wBottomMessageBuffer / $100
+	ld d, wBottomMessageBuffer / $100 ;$c6
 	inc hl
 	push hl
-	ld l, [hl]
+	ld l, [hl] ;Retrieve text source pointer from Byte 7
 	ld h, wBottomMessageText / $100
-	call Func_3129
+	call PlaceTextLow ;load text into destination e in text RAM
 	pop hl
 	inc hl
 	ld a, [hl]
 	dec a
-	ld [hl], a
+	ld [hl], a ;dec Byte 8
 	pop de
-	pop hl
+	pop hl ;+3
-	ld [hl], e
+	ld [hl], e ;restore position into var 4
-	ret nz
+	ret nz ;if position = 0, switch scrolling off
 	dec hl
 	dec hl
 	dec hl
-	ld [hl], $0
+	ld [hl], $0 ;+0
 	ret
 
 Func_3357: ; 0x3357
@@ -592,7 +592,7 @@ Func_33c3: ; 0x33c3
 	push hl
 	ld l, [hl]
 	ld h, wBottomMessageText / $100
-	call Func_3129
+	call PlaceTextLow
 	pop hl
 	inc hl
 	ld a, [hl]
@@ -613,36 +613,36 @@ Func_33c3: ; 0x33c3
 Func_33e3: ; 0x33e3
 	ld a, [wd5ca]
 	and a
-	jr nz, .asm_33ed
+	jr nz, .asm_33ed ;if ??? = nz, load into ???, else jump
 	ld [wd5cb], a
 	ret
 
 .asm_33ed
 	ld c, $0
-	ld a, [wd5cc]
+	ld a, [wScrollingTextStruct1]
 	and a
-	jr z, .asm_33fe
+	jr z, .asm_33fe ;if ?? is 0
-	push bc
+	push bc ;store b and 0
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
-	call Func_3325
+	call HandleScrolling
 	pop bc
 	inc c
 .asm_33fe
-	ld a, [wd5d4]
+	ld a, [wScrollingTextStruct2]
 	and a
 	jr z, .asm_340d
 	push bc
-	ld hl, wd5d4
+	ld hl, wScrollingTextStruct2
-	call Func_3325
+	call HandleScrolling
 	pop bc
 	inc c
 .asm_340d
-	ld a, [wd5dc]
+	ld a, [wScrollingTextStruct3]
 	and a
 	jr z, .asm_341c
 	push bc
-	ld hl, wd5dc
+	ld hl, wScrollingTextStruct3
-	call Func_3325
+	call HandleScrolling
 	pop bc
 	inc c
 .asm_341c
@@ -744,4 +744,3 @@ TenMillionPoints: ; 34f4
 	bigBCD6 000010000000
 OneHundredMillionPoints: ; 34fa
 	bigBCD6 000100000000
-

hram.asm

@@ -20,7 +20,7 @@ hLYC EQU $FFA2
 hBGP EQU $FFA3
 hOBP0 EQU $FFA4
 hOBP1 EQU $FFA5
-hWY EQU $FFA6
+hWY EQU $FFA6 ;window y coord buffer
 hWX EQU $FFA7
 hLastLYC EQU $FFA8
 hNextLYCSub EQU $FFA9

main.asm

@@ -118,7 +118,7 @@ Func_dc6d: ; 0xdc6d
 	push de
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5dc
+	ld hl, wScrollingTextStruct3
 	pop de
 	call LoadTextHeader
 	ret
@@ -307,7 +307,7 @@ VideoData_10b2a: ; 0x10b2a
 Func_10b3f: ; 0x10b3f
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	ld a, [wCurrentEvolutionType]
 	cp EVO_EXPERIENCE
 	ld de, StartTrainingText
@@ -763,10 +763,10 @@ Func_10e0a: ; 0x10e0a
 	push de
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	pop de
 	call LoadTextHeader
-	ld hl, wd5d4
+	ld hl, wScrollingTextStruct2
 	pop de
 	call LoadTextHeader
 	pop hl
@@ -808,12 +808,12 @@ Func_10e8b: ; 0x10e8b
 	push de
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5d4
+	ld hl, wScrollingTextStruct2
 	ld de, Data_2b6b
 	call Func_32cc
 	pop de
 	pop bc
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	ld de, EvolutionSpecialBonusText
 	call LoadTextHeader
 	ret
@@ -1534,10 +1534,10 @@ LoadScrollingMapNameText: ; 0x3118f
 	ld e, a
 	ld a, [hli]
 	ld d, a
-	ld hl, wd5d4
+	ld hl, wScrollingTextStruct2
 	call LoadTextHeader
 	pop de
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	call LoadTextHeader
 	ret
 
@@ -1970,7 +1970,7 @@ Func_3151f: ; 0x3151f
 	callba StopTimer
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	ld de, MapMoveFailedText
 	call LoadTextHeader
 	ret
@@ -2124,7 +2124,7 @@ Func_3168c: ; 0x3168c
 	callba StopTimer
 	call FillBottomMessageBufferWithBlackTile
 	call Func_30db
-	ld hl, wd5cc
+	ld hl, wScrollingTextStruct1
 	ld de, MapMoveFailedText
 	call LoadTextHeader
 	ret

wram.asm

@@ -681,7 +681,7 @@ wTimerDigits:: ; 0xd582
 wd586:: ; 0xd586
 	ds $30
 
-wd5b6:: ; 0xd5b6
+wd5b6:: ; 0xd5b6 a 24 wide block starts here and is filled before catch mode
 	ds $5
 
 wWildMonIsHittable:: ; 0xd5bb
@@ -728,16 +728,25 @@ wWildMonCollision:: ; 0xd5c7
 
 	ds $1
 
-wd5ca:: ; 0xd5ca
+wd5ca:: ; 0xd5ca set to 1 by a commonly called text function that is called at the start of catch and raises the score bar
 	ds $1
 
-wd5cb:: ; 0xd5cb
+wd5cb:: ; 0xd5cb set to 0 if the above is 0 during Func_33e3
 	ds $1
 
-wd5cc:: ; 0xd5cc
+wScrollingTextStruct1:: ; 0xd5cc Start of a scrolling message struct that contains 8 1-byte vars.
+; Byte 1: Toggles if enabled. 0 is off, non-0 is on
+; Byte 2: is how many frames until the next scroll
+; Byte 3: holds how long, in frames, it should take for the scroll to move 1 tile
+; Byte 4: is the current position to place the start of the text
+; Byte 5: is where in the scroll the message should stop for an extended period
+; Byte 6: is how many frames the extended stop from Byte 5 has left
+; Byte 7: is a pointer to the source text's position in the buffer
+; Byte 8: is decremented each scroll and scroll denied by the stop
+; Scrolling text relies on byte allignment for the text buffer and display area
 	ds $8
 
-wd5d4:: ; 0xd5d4
+wScrollingTextStruct2:: ; 0xd5d4 Start of a scrolling struct2
 	ds $4
 
 wd5d8:: ; 0xd5d8
@@ -746,7 +755,7 @@ wd5d8:: ; 0xd5d8
 wd5db:: ; 0xd5db
 	ds $1
 
-wd5dc:: ; 0xd5dc
+wScrollingTextStruct3:: ; 0xd5dc Start of a scrolling struct3
 	ds $8
 
 wd5e4:: ; 0xd5e4
@@ -1817,7 +1826,7 @@ wd803:: ; 0xd803
 wd804:: ; 0xd804
 	ds $1
 
-wd805:: ; 0xd805
+wd805:: ; 0xd805 enables unused and odd PlaceString
 	ds $1
 
 wd806:: ; 0xd806