Cleanup and correct some collision handling logic

14 files changed, 195 insertions, 133 deletions

diff --git a/engine/pinball_game.asm b/engine/pinball_game.asm
index f094e82..86fd199 100644
--- a/engine/pinball_game.asm
+++ b/engine/pinball_game.asm
@@ -70,23 +70,23 @@ GameScreenFunction_HandleBallPhysics: ; 0xd909
 ; main loop for stage logic

 	xor a

 	ld [wFlipperCollision], a

-	ld [wd7eb], a

+	ld [wSpinForceAmplification], a

 	call ApplyGravityToBall

 	call LimitBallVelocity

 	xor a

-	ld [wd7e9], a

+	ld [wIsBallColliding], a

 	call HandleTilts

 	ld a, [wCurrentStage]

 	bit 0, a

-	callba nz, HandleFlippers  ; only perform flipper routines on the lower-half of stages

+	callba nz, HandleFlippers  ; only perform flipper logic on the lower half of stages

 	ld a, [wFlipperCollision]

 	and a

-	ld a, [wCollisionForceAngle]

+	ld a, [wCollisionNormalAngle]

 	push af

-	call CheckObjectCollision  ; collision stuff

+	call CheckStageCollision

 	pop af

 	jr z, .noFlipperCollision

-	ld [wCollisionForceAngle], a

+	ld [wCollisionNormalAngle], a

 .noFlipperCollision

 	call CheckGameObjectCollisions

 	call ResolveGameObjectCollisions

@@ -98,17 +98,20 @@ GameScreenFunction_HandleBallPhysics: ; 0xd909
 	callba HandleInGameMenu

 	jp z, SaveGame

 .didntPressMenuKey

-	ld a, [wd7e9]  ; check for collision flag

+	ld a, [wIsBallColliding]  ; check for collision flag

 	and a

-	jr z, .skip_collision

+	jr z, .moveBallPosition

 	call ApplyTiltForces

 	call LoadBallVelocity ; bc = x velocity, de = y velocity

-	ld a, [wCollisionForceAngle]

-	call ApplyCollisionForce

-	call ApplyTorque

+	; First, rotate the velocity vector into a standardized coordinate

+	; system where the normal angle points upwards.

+	ld a, [wCollisionNormalAngle]

+	call RotateVector

+	; Apply the collision forces to the ball in the rotated coordinate system.

+	call ApplyCollisionForces

 	ld a, [wFlipperCollision]

 	and a

-	jr z, .not_flippers_2

+	jr z, .noFlipperCollision2

 	; de -= *wFlipperYForce

 	ld hl, wFlipperYForce

 	ld a, [hli]

@@ -131,17 +134,19 @@ GameScreenFunction_HandleBallPhysics: ; 0xd909
 	ld a, b

 	adc h

 	ld b, a

-	jr .next

+	jr .updateBallVelocity

 

-.not_flippers_2

-	ld a, [wd7f8]

+.noFlipperCollision2

+	ld a, [wNoCollisionApplied]

 	and a

-	jr nz, .skip_collision

-.next

-	ld a, [wCollisionForceAngle]

-	call NegateAngleAndApplyCollisionForce

+	jr nz, .moveBallPosition

+.updateBallVelocity

+	; Rotate the velocity vector back to the regular coordinate system, and

+	; set the ball's velocity to the resulting vector.

+	ld a, [wCollisionNormalAngle]

+	call NegateAngleAndRotateVector

 	call SetBallVelocity

-.skip_collision

+.moveBallPosition

 	call MoveBallPosition

 	callba CheckStageTransition

 	callba DrawSpritesForStage

@@ -176,9 +181,9 @@ GameScreenFunction_HandleBallLoss: ; 0xda36
 	ld [hNewlyPressedButtons], a

 	ld [hPressedButtons], a

 	ld [wFlipperCollision], a

-	ld [wd7eb], a

+	ld [wSpinForceAmplification], a

 	xor a

-	ld [wd7e9], a

+	ld [wIsBallColliding], a

 	ld [wPinballIsVisible], a

 	ld [wEnableBallGravityAndTilt], a

 	call HandleTilts

diff --git a/engine/pinball_game/flippers.asm b/engine/pinball_game/flippers.asm
index d71419a..4ecc0b1 100644
--- a/engine/pinball_game/flippers.asm
+++ b/engine/pinball_game/flippers.asm
@@ -601,7 +601,7 @@ HandleFlipperCollision: ; 0xe442
 ; This is called when the ball is colliding with either the

 ; right or left flipper.

 	ld a, $1

-	ld [wd7e9], a

+	ld [wIsBallColliding], a

 	xor a

 	ld [wBallPositionPointerOffsetFromStageTopLeft], a

 	ld [wBallPositionPointerOffsetFromStageTopLeft + 1], a

@@ -638,9 +638,9 @@ HandleFlipperCollision: ; 0xe442
 	cpl  ; invert the x collision attribute

 	inc a

 .asm_e48b

-	ld [wCollisionForceAngle], a

-	ld a, $1

-	ld [wd7eb], a

+	ld [wCollisionNormalAngle], a

+	ld a, 1

+	ld [wSpinForceAmplification], a

 	ld a, [wFlipperYForce + 1]

 	bit 7, a

 	ret z

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 6b07d73..3bcc995 100644
--- a/engine/pinball_game/object_collision/blue_stage_resolve_collision.asm
+++ b/engine/pinball_game/object_collision/blue_stage_resolve_collision.asm
@@ -598,9 +598,9 @@ ApplyBumperCollision_BlueField: ; 0x1ce94
 	ld b, $0

 	ld hl, BumperCollisionAngleDeltas_BlueField

 	add hl, bc

-	ld a, [wCollisionForceAngle]

+	ld a, [wCollisionNormalAngle]

 	add [hl]

-	ld [wCollisionForceAngle], a

+	ld [wCollisionNormalAngle], a

 	lb de, $00, $0b

 	call PlaySoundEffect

 	ret

@@ -1808,10 +1808,10 @@ AddScorePsyduckOrPoliwag: ; 0x1de22
 	ret z

 	ld a, $55

 	ld [wRumblePattern], a

-	ld a, $4

+	ld a, 4

 	ld [wRumbleDuration], a

-	ld a, $2

-	ld [wd7eb], a

+	ld a, 2

+	ld [wSpinForceAmplification], a

 	ld bc, FiveHundredPoints

 	callba AddBigBCD6FromQueueWithBallMultiplier

 	lb de, $00, $0f

diff --git a/engine/pinball_game/object_collision/diglett_bonus_object_collision.asm b/engine/pinball_game/object_collision/diglett_bonus_object_collision.asm
index 91e0f82..e9ad851 100644
--- a/engine/pinball_game/object_collision/diglett_bonus_object_collision.asm
+++ b/engine/pinball_game/object_collision/diglett_bonus_object_collision.asm
@@ -10,7 +10,7 @@ CheckDiglettBonusStageDiglettHeadsCollision: ; 0x19aba
 	ld a, [wd73b]

 	bit 7, a

 	jr nz, .asm_19b16

-	ld a, [wd7e9]

+	ld a, [wIsBallColliding]

 	and a

 	ret z ; is a collision happening?

 	ld a, [wCurCollisionAttribute]

@@ -86,7 +86,7 @@ CheckDiglettBonusStageDugtrioCollision: ; 0x19b4b
 	ld a, [wd75f]

 	bit 7, a

 	jr nz, .asm_19b86

-	ld a, [wd7e9]

+	ld a, [wIsBallColliding]

 	and a

 	ret z

 	ld a, [wCurCollisionAttribute]

diff --git a/engine/pinball_game/object_collision/gengar_bonus_object_collision.asm b/engine/pinball_game/object_collision/gengar_bonus_object_collision.asm
index adf048b..f436b4d 100644
--- a/engine/pinball_game/object_collision/gengar_bonus_object_collision.asm
+++ b/engine/pinball_game/object_collision/gengar_bonus_object_collision.asm
@@ -79,9 +79,9 @@ CheckSingleGastlyCollision: ; 0x1820d
 	bit 7, a

 	jr nz, .noCollision

 	sla a

-	ld [wCollisionForceAngle], a

+	ld [wCollisionNormalAngle], a

 	ld a, $1

-	ld [wd7e9], a

+	ld [wIsBallColliding], a

 	scf

 	ret

 

@@ -156,9 +156,9 @@ CheckSingleHaunterCollision: ; 0x18298
 	bit 7, a

 	jr nz, .noCollision

 	sla a

-	ld [wCollisionForceAngle], a

+	ld [wCollisionNormalAngle], a

 	ld a, $1

-	ld [wd7e9], a

+	ld [wIsBallColliding], a

 	scf

 	ret

 

@@ -219,9 +219,9 @@ CheckGiantGengarCollision: ; 0x18308
 	bit 7, a

 	jr nz, .noCollision

 	sla a

-	ld [wCollisionForceAngle], a

+	ld [wCollisionNormalAngle], a

 	ld a, $1

-	ld [wd7e9], a

+	ld [wIsBallColliding], a

 	scf

 	ret

 

diff --git a/engine/pinball_game/object_collision/meowth_bonus_object_collision.asm b/engine/pinball_game/object_collision/meowth_bonus_object_collision.asm
index 4fc6179..71e326f 100644
--- a/engine/pinball_game/object_collision/meowth_bonus_object_collision.asm
+++ b/engine/pinball_game/object_collision/meowth_bonus_object_collision.asm
@@ -57,9 +57,9 @@ CheckMeowthCollision: ; 0x24170
 	bit 7, a

 	jr nz, .noCollision

 	sla a

-	ld [wCollisionForceAngle], a

+	ld [wCollisionNormalAngle], a

 	ld a, $1

-	ld [wd7e9], a

+	ld [wIsBallColliding], a

 	ld a, [wd6ec]

 	cp $2

 	ret z

@@ -205,9 +205,9 @@ CheckJewelCollision: ; 0x24272
 	bit 7, a

 	jr nz, .noCollision

 	sla a

-	ld [wCollisionForceAngle], a

+	ld [wCollisionNormalAngle], a

 	ld a, $1

-	ld [wd7e9], a

+	ld [wIsBallColliding], a

 	scf

 	ret

 

diff --git a/engine/pinball_game/object_collision/mewtwo_bonus_object_collision.asm b/engine/pinball_game/object_collision/mewtwo_bonus_object_collision.asm
index 7b15498..d1bdd07 100644
--- a/engine/pinball_game/object_collision/mewtwo_bonus_object_collision.asm
+++ b/engine/pinball_game/object_collision/mewtwo_bonus_object_collision.asm
@@ -159,7 +159,7 @@ Func_19414: ; 0x19414
 	ld a, [wd6aa]

 	bit 7, a

 	jr nz, .asm_1944f

-	ld a, [wd7e9]

+	ld a, [wIsBallColliding]

 	and a

 	ret z

 	ld a, [wCurCollisionAttribute]

diff --git a/engine/pinball_game/object_collision/object_collision.asm b/engine/pinball_game/object_collision/object_collision.asm
index 7e4c2ea..b80cddb 100644
--- a/engine/pinball_game/object_collision/object_collision.asm
+++ b/engine/pinball_game/object_collision/object_collision.asm
@@ -125,7 +125,7 @@ IsCollisionInList: ; 0x27da
 	ld c, [hl]

 	add hl, bc

 .checkList

-	ld a, [wd7e9]

+	ld a, [wIsBallColliding]

 	and a

 	ret z

 	ld a, [wCurCollisionAttribute]

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 84867d6..d79411c 100644
--- a/engine/pinball_game/object_collision/red_stage_resolve_collision.asm
+++ b/engine/pinball_game/object_collision/red_stage_resolve_collision.asm
@@ -460,10 +460,10 @@ HitLeftDiglett3Times: ; 0x14947
 AddScoreForHittingDiglett: ; 0x1496d

 	ld a, $55

 	ld [wRumblePattern], a

-	ld a, $4

+	ld a, 4

 	ld [wRumbleDuration], a

-	ld a, $2

-	ld [wd7eb], a

+	ld a, 2

+	ld [wSpinForceAmplification], a

 	ld bc, FiveHundredPoints

 	callba AddBigBCD6FromQueueWithBallMultiplier

 	lb de, $00, $0f

@@ -1699,9 +1699,9 @@ ApplyBumperCollision_RedField: ; 0x15fda
 	ld b, $0

 	ld hl, BumperCollisionAngleDeltas_RedField

 	add hl, bc

-	ld a, [wCollisionForceAngle]

+	ld a, [wCollisionNormalAngle]

 	add [hl]

-	ld [wCollisionForceAngle], a

+	ld [wCollisionNormalAngle], a

 	lb de, $00, $0b

 	call PlaySoundEffect

 	ret

diff --git a/engine/pinball_game/object_collision/seel_bonus_object_collision.asm b/engine/pinball_game/object_collision/seel_bonus_object_collision.asm
index e702dd2..1bf1791 100644
--- a/engine/pinball_game/object_collision/seel_bonus_object_collision.asm
+++ b/engine/pinball_game/object_collision/seel_bonus_object_collision.asm
@@ -80,9 +80,9 @@ CheckSeelHeadCollision: ; 0x25c12
 	bit 7, a

 	jr nz, .noCollision

 	sla a

-	ld [wCollisionForceAngle], a

+	ld [wCollisionNormalAngle], a

 	ld a, $1

-	ld [wd7e9], a

+	ld [wIsBallColliding], a

 	scf

 	ret

 

diff --git a/home.asm b/home.asm
index 898d713..9f88398 100644
--- a/home.asm
+++ b/home.asm
@@ -2269,48 +2269,55 @@ MultiplyBbyCSigned:
 	pop af
 	ret
 
-MultiplyBCByEAndRoundToMostSignificantShort: ; 0x210b
-; bc = round(bc * e / 256)
-; b^d = sign of output
+MultiplyVectorComponentByAngleFactor: ; 0x210b
+; Input: bc = velocity
+;         e = multiplier
+;         d = $0 if multiplier is treated as positive, $ff if multiplier is treated as negative
+; Output: bc = bc * e / 256
 	push af
 	push hl
 	ld a, b
 	xor d
 	ld [hSignedMathSignBuffer2], a
 	bit 7, b
-	jr z, .positive1
+	jr z, .positive
+	; negate bc
 	ld a, c
 	cpl
-	add $1
+	add 1
 	ld c, a
 	ld a, b
 	cpl
-	adc $0
+	adc 0
 	ld b, a
-.positive1
+.positive
 	push bc
+	; first, multiply the lo byte of the vector
 	ld b, e
 	call MultiplyBbyCUnsigned
 	ld l, c
 	ld h, b
+	; round to nearest hi byte
 	ld bc, $0080
 	add hl, bc
 	ld l, h
 	ld h, $0
 	pop bc
+	; then, multiply the hi byte of the vector
 	ld c, e
 	call MultiplyBbyCUnsigned
 	add hl, bc
 	ld a, [hSignedMathSignBuffer2]
 	rlca
 	jr nc, .positive2
+	; negate hl
 	ld a, l
 	cpl
-	add $1
+	add 1
 	ld l, a
 	ld a, h
 	cpl
-	adc $0
+	adc 0
 	ld h, a
 .positive2
 	ld c, l
@@ -2320,14 +2327,18 @@ MultiplyBCByEAndRoundToMostSignificantShort: ; 0x210b
 	ret
 
 Cosine: ; 0x2147
-	; cos(a)
+	; Input:  a = angle
+	; Output: e = cos(a)
+	;         d = 0 if cos(a) is positive, $ff if cos(a) is negative
 	add $40
 	; fall through
 Sine: ; 0x2149
-	; sin(a)
+	; Input:  a = angle
+	; Output: e = sin(a)
+	;         d = 0 if sin(a) is positive, $ff if sin(a) is negative
 	push hl
 	ld [hSignedMathSignBuffer], a
-	and $7f ; subtract 180 degrees
+	and $7f ; ensure angle is between 0 and 180 degrees
 	cp $40
 	jr c, .firstQuadrant
 	; convert angle so it's between 0 and 90 degrees
@@ -2366,7 +2377,7 @@ ApplyGravityToBall: ; 0x2168
 
 LimitBallVelocity: ; 0x2180
 ; Ensures that the ball's x and y velocity are kept under a threshold.
-; The ball can travel at a higher max speed when moving diagonally, since it
+; The ball can travel at a greater max speed when moving diagonally, since it
 ; limits the x and y components independently.
 	ld hl, wBallXVelocity + 1
 	call _LimitBallVelocity
@@ -2376,16 +2387,16 @@ _LimitBallVelocity: ; 0x2189
 	ld a, [hl]
 	bit 7, a  ; is it negative velocity?  (left or up)
 	jr nz, .negativeVelocity
-	cp $8
+	cp 8
 	ret c
-	ld a, $7  ; max positive velocity
+	ld a, 7  ; max positive velocity
 	ld [hl], a
 	ret
 
 .negativeVelocity
-	cp $f9
+	cp -7
 	ret nc
-	ld a, $f9  ; max negative velocity
+	ld a, -7  ; max negative velocity
 	ld [hl], a
 	ret
 
@@ -2409,24 +2420,24 @@ MoveBallPosition: ; 0x219c
 AddVelocityToPosition: ; 0x21c3
 	ld a, [de]
 	bit 7, a
-	jr nz, .asm_21d1
-	cp 1+4
-	jr c, .asm_21da
+	jr nz, .negativeVelocity
+	cp 5
+	jr c, .readLoByte
 	ld bc, $04ff
-	jr .asm_21de
+	jr .updateBallPos
 
-.asm_21d1
+.negativeVelocity
 	cp -4
-	jr nc, .asm_21da
+	jr nc, .readLoByte
 	ld bc, -$04ff
-	jr .asm_21de
+	jr .updateBallPos
 
-.asm_21da
+.readLoByte
 	ld b, a
 	dec de
 	ld a, [de]
 	ld c, a
-.asm_21de
+.updateBallPos
 	ld a, [hl]
 	add c
 	ld [hli], a
@@ -2435,35 +2446,42 @@ AddVelocityToPosition: ; 0x21c3
 	ld [hl], a
 	ret
 
-NegateAngleAndApplyCollisionForce: ; 0x21e5
+NegateAngleAndRotateVector: ; 0x21e5
 	cpl
 	inc a
 	; fall through
-ApplyCollisionForce: ; 0x21e7
+RotateVector: ; 0x21e7
+; Rotates a vector by an angle using the standard rotation matrix calculation. Note, that
+; the matrix is inverted vertically to account for negative y values mean "up" in this world.
+; Input:   bc = vector x component
+;          de = vector y component
+;           a = rotation angle
+; Returns: bc = resulting x component = xComponent * cos(angle) + yComponent * sin(angle)
+;          de = resulting y component = yComponent * cos(angle) - xComponent * sin(angle)
 	push hl
-	; bc_ret = bc * cos(a) + de * sin(x)
-	; de_ret = bc * cos(a) - de * sin(x)
 	push bc
 	push de
-	ld [hSineOrCosineArgumentBuffer], a
+	ld [hRotationAngleBuffer], a
 	call Cosine
 	ld a, e
 	ld [hCosineResultBuffer], a
 	ld a, d
 	ld [hCosineResultBuffer + 1], a
-	call MultiplyBCByEAndRoundToMostSignificantShort
+	; xComponent * cos(angle)
+	call MultiplyVectorComponentByAngleFactor
 	ld l, c
 	ld h, b
 	pop bc
 	push bc
-	ld a, [hSineOrCosineArgumentBuffer]
+	ld a, [hRotationAngleBuffer]
 	call Sine
 	ld a, e
 	ld [hSineResultBuffer], a
 	ld a, d
 	ld [hSineResultBuffer + 1], a
-	call MultiplyBCByEAndRoundToMostSignificantShort
-	add hl, bc
+	; yComponent * sin(angle)
+	call MultiplyVectorComponentByAngleFactor
+	add hl, bc  ; hl = xComponent * cos(angle) + yComponent * sin(angle)
 	pop de
 	pop bc
 	push hl
@@ -2473,7 +2491,8 @@ ApplyCollisionForce: ; 0x21e7
 	ld a, [hSineResultBuffer + 1]
 	cpl
 	ld d, a
-	call MultiplyBCByEAndRoundToMostSignificantShort
+	; xComponent * -sin(angle)
+	call MultiplyVectorComponentByAngleFactor
 	ld l, c
 	ld h, b
 	pop bc
@@ -2481,74 +2500,103 @@ ApplyCollisionForce: ; 0x21e7
 	ld e, a
 	ld a, [hCosineResultBuffer + 1]
 	ld d, a
-	call MultiplyBCByEAndRoundToMostSignificantShort
-	add hl, bc
+	; yComponent * cos(angle)
+	call MultiplyVectorComponentByAngleFactor
+	add hl, bc  ; hl = yComponent * cos(angle) - xComponent * sin(angle)
 	ld d, h
 	ld e, l
 	pop bc
 	pop hl
 	ret
 
-ApplyTorque: ; 0x222b
+ApplyCollisionForces: ; 0x222b
+; Applies the collision force to the ball's velocity and spin.
+; When this function is called, the ball's velocity has already been rotated
+; by the collision's normal angle, so that the velocity components are in a
+; standardized coordinate system, where the normal is pointing directly upward
+; at the colliding ball. If the ball is traveling away from the normal, then this
+; function is a no-op.
+; Input: bc = ball x velocity in rotated coordinate system
+;        de = ball y velocity in rotated coordinate system
+; Output: bc = updated ball x velocity in rotated coordinate system
+;         de = updated ball y velocity in rotated coordinate system
 	push hl
-	ld hl, wd7f8
+	ld hl, wNoCollisionApplied
 	ld [hl], $ff
+	; Early exit if the ball is traveling away from the collision normal.
 	bit 7, d
-	jr nz, .asm_2297
+	jr nz, .exit
 	ld [hl], $0
 	ld a, d
-	cp $3
-	jr c, .asm_2254
+	cp 3
+	jr c, .applyforces
+	; The ball collided hard because its y velocity is a
+	; large value. Shake the rumble pack, and play a little
+	; sound effect to enhance the collision.
 	ld a, $ff
 	ld [wRumblePattern], a
-	ld a, $1
+	ld a, 1
 	ld [wRumbleDuration], a
 	ld a, [wFlipperCollision]
 	and a
-	jr nz, .asm_2254
+	jr nz, .applyforces
 	push de
 	ld de, $0008
 	call PlaySFXIfNoneActive
 	pop de
-.asm_2254
+.applyforces
+	; First, apply some dampening of the vertical
+	; velocity component, so that walls absorb some
+	; of the ball's speed. Colliding with certain objects
+	; dampen the speed less that normal, like the flippers
+	; and Poliwag button.
+	; Divide y velocity by 4.
 	srl d
 	rr e
 	srl d
 	rr e
 	ld h, d
-	ld l, e
+	ld l, e  ; hl = yVelocity / 4
 	srl d
-	rr e
-	ld a, [wd7eb]
+	rr e  ; de = yVelocity / 8
+	ld a, [wSpinForceAmplification]
 	and a
-	jr z, .asm_226c
-.asm_2268
+	jr z, .updateYVelocity
+.amplify
 	add hl, de
 	dec a
-	jr nz, .asm_2268
-.asm_226c
+	jr nz, .amplify
+.updateYVelocity
+	; Negate the dampened dampened y velocity so that the ball
+	; bounces off.
 	ld d, h
 	ld e, l
 	ld a, e
 	cpl
-	add $1
+	add 1
 	ld e, a
 	ld a, d
 	cpl
-	adc $0
+	adc 0
 	ld d, a
 	ld a, [wBallSpin]
+	; Divide ball spin by 2, signed, and extend to 2 bytes (hl)
 	sra a
 	ld l, a
 	ld h, $0
 	bit 7, l
-	jr z, .asm_2286
+	jr z, .updateXVelocity
 	ld h, $ff
-.asm_2286
+.updateXVelocity
+	; hl = ballSpin / 2
+	; bc = x velocity component in rotated coordinate system
+	; Add the spin to the x velocity component.
 	add hl, bc
 	ld b, h
 	ld c, l
 	push bc
+	; Recalculate ball spin.
+	; new ball spin = (xVelocity * 4) >> 8
 	sla c
 	rl b
 	sla c
@@ -2556,7 +2604,7 @@ ApplyTorque: ; 0x222b
 	ld a, b
 	ld [wBallSpin], a
 	pop bc
-.asm_2297
+.exit
 	pop hl
 	ret
 
@@ -2594,7 +2642,7 @@ SetBallVelocity: ; 0x22a7
 	pop hl
 	ret
 
-CheckObjectCollision: ; 0x22b5
+CheckStageCollision: ; 0x22b5
 	ld a, [wBallXPos + 1]
 	sub $4
 	push af
@@ -2801,7 +2849,7 @@ CheckObjectCollision: ; 0x22b5
 	jr c, .asm_23c1
 .asm_23ee
 	ld a, e
-	ld [wd7e9], a
+	ld [wIsBallColliding], a
 	and a
 	ret z
 	ld a, [hLoadedROMBank]
@@ -2815,7 +2863,7 @@ CheckObjectCollision: ; 0x22b5
 	ld hl, CollisionForceAngles
 	add hl, de
 	ld a, [hl]
-	ld [wCollisionForceAngle], a
+	ld [wCollisionNormalAngle], a
 	sla e
 	rl d
 	ld hl, CollisionYDeltas
diff --git a/home/tilt.asm b/home/tilt.asm
index 058c554..4211498 100755
--- a/home/tilt.asm
+++ b/home/tilt.asm
@@ -12,11 +12,11 @@ HandleLeftTilt: ; 0x358c
 	call IsKeyPressed2

 	jr z, .tiltCoolDown

 	ld a, [wLeftTiltCounter]

-	cp $3

+	cp 3

 	jr z, .startCoolDown

 	inc a

 	ld [wLeftTiltCounter], a

-	cp $1

+	cp 1

 	jr nz, .skipSoundEffect

 	lb de, $00, $3f

 	call PlaySoundEffect

@@ -32,12 +32,12 @@ HandleLeftTilt: ; 0x358c
 	ld a, [wLeftAndRightTiltPixelsOffset]

 	inc a

 	ld [wLeftAndRightTiltPixelsOffset], a

-	ld a, $1

+	ld a, 1

 	ld [wLeftTiltPushing], a

 	ret

 

 .startCoolDown

-	ld a, $1

+	ld a, 1

 	ld [wLeftTiltReset], a

 .tiltCoolDown

 	xor a

@@ -68,11 +68,11 @@ HandleRightTilt: ; 0x35f3
 	call IsKeyPressed2

 	jr z, .tiltCoolDown

 	ld a, [wRightTiltCounter]

-	cp $3

+	cp 3

 	jr z, .startCoolDown

 	inc a

 	ld [wRightTiltCounter], a

-	cp $1

+	cp 1

 	jr nz, .skipSoundEffect

 	lb de, $00, $3f

 	call PlaySoundEffect

@@ -88,12 +88,12 @@ HandleRightTilt: ; 0x35f3
 	ld a, [wLeftAndRightTiltPixelsOffset]

 	dec a

 	ld [wLeftAndRightTiltPixelsOffset], a

-	ld a, $1

+	ld a, 1

 	ld [wRightTiltPushing], a

 	ret

 

 .startCoolDown

-	ld a, $1

+	ld a, 1

 	ld [wRightTiltReset], a

 .tiltCoolDown

 	xor a

@@ -124,11 +124,11 @@ HandleUpperTilt: ; 0x365a
 	call IsKeyPressed2

 	jr z, .tiltCoolDown

 	ld a, [wUpperTiltCounter]

-	cp $4

+	cp 4

 	jr z, .startCoolDown

 	inc a

 	ld [wUpperTiltCounter], a

-	cp $1

+	cp 1

 	jr nz, .skipSoundEffect

 	lb de, $00, $3f

 	call PlaySoundEffect

@@ -144,12 +144,12 @@ HandleUpperTilt: ; 0x365a
 	ld a, [wUpperTiltPixelsOffset]

 	dec a

 	ld [wUpperTiltPixelsOffset], a

-	ld a, $1

+	ld a, 1

 	ld [wUpperTiltPushing], a

 	ret

 

 .startCoolDown

-	ld a, $1

+	ld a, 1

 	ld [wUpperTiltReset], a

 .tiltCoolDown

 	xor a

@@ -196,7 +196,7 @@ ApplyTiltForces: ; 0x36c1
 	ld l, a

 	bit 7, h

 	ret nz

-	ld a, [wCollisionForceAngle]

+	ld a, [wCollisionNormalAngle]

 	ld c, a

 	ld b, $0

 	sla c

diff --git a/hram.asm b/hram.asm
index e8ea2fb..fa4defc 100644
--- a/hram.asm
+++ b/hram.asm
@@ -39,9 +39,9 @@ hStatIntrFired            EQU $FFB5
 hSignedMathSignBuffer     EQU $FFB6
 hSignedMathSignBuffer2    EQU $FFB7
 
-hSineOrCosineArgumentBuffer EQU $FF8C
-hCosineResultBuffer         EQU $FF8D
-hSineResultBuffer           EQU $FF8F
+hRotationAngleBuffer EQU $FF8C
+hCosineResultBuffer  EQU $FF8D
+hSineResultBuffer    EQU $FF8F
 
 hFlipperYCollisionAttribute  EQU $FFBF  ; Vertical collision attribute for when ball collides with a flipper.
 
diff --git a/wram.asm b/wram.asm
index ef720ea..7fc2c9b 100644
--- a/wram.asm
+++ b/wram.asm
@@ -1832,13 +1832,20 @@ wd7c9:: ; 0xd7c9
 wd7d9:: ; 0xd7d9
 	ds $10
 
-wd7e9:: ; 0xd7e9
+wIsBallColliding:: ; 0xd7e9
+; Set to non-zero when the pinball is colliding with something.
 	ds $1
 
-wCollisionForceAngle:: ; 0xd7ea
+wCollisionNormalAngle:: ; 0xd7ea
+; The normal angle of the ball's collision. The coordinate system
+; is rotate by 90 degrees compared to standard math.
+; $00 = directly up on the Game Boy screen
+; $40 = directly right on the Game Boy screen
+; $80 = directly down on the Game Boy screen
+; $C0 = directly left on the Game Boy screen
 	ds $1
 
-wd7eb:: ; 0xd7eb
+wSpinForceAmplification:: ; 0xd7eb
 	ds $1
 
 wStageCollisionMapPointer:: ; 0xd7ec
@@ -1868,7 +1875,9 @@ wd7f6:: ; 0xd7f6
 wd7f7:: ; 0xd7f7
 	ds $1
 
-wd7f8:: ; 0xd7f8
+wNoCollisionApplied:: ; 0xd7f8
+; Set to $FF when collision forces were NOT applied to the ball.
+; Set to $00 otherwise.
 	ds $1
 
 wInGameMenuIndex:: ; 0xd7f9