8 files changed, 24 insertions, 16 deletions
diff --git a/engine/events/hidden_objects/indigo_plateau_statues.asm b/engine/events/hidden_objects/indigo_plateau_statues.asm
index 23e94fcf..f78a5a72 100644
--- a/engine/events/hidden_objects/indigo_plateau_statues.asm
+++ b/engine/events/hidden_objects/indigo_plateau_statues.asm
@@ -3,7 +3,7 @@ IndigoPlateauStatues::
 	ld hl, IndigoPlateauStatuesText1
 	call PrintText
 	ld a, [wXCoord]
-	bit 0, a
+	bit 0, a ; even or odd?
 	ld hl, IndigoPlateauStatuesText2
 	jr nz, .ok
 	ld hl, IndigoPlateauStatuesText3
diff --git a/engine/gfx/mon_icons.asm b/engine/gfx/mon_icons.asm
index e7016a1d..24e9446e 100644
--- a/engine/gfx/mon_icons.asm
+++ b/engine/gfx/mon_icons.asm
@@ -269,7 +269,7 @@ GetPartyMonSpriteID:
 	ld d, 0
 	add hl, de
 	ld a, [hl]
-	bit 0, c
+	bit 0, c ; even or odd?
 	jr nz, .skipSwap
 	swap a ; use lower nybble if pokedex num is even
 .skipSwap
diff --git a/engine/gfx/screen_effects.asm b/engine/gfx/screen_effects.asm
index c7a68734..7d0ccf7e 100644
--- a/engine/gfx/screen_effects.asm
+++ b/engine/gfx/screen_effects.asm
@@ -61,7 +61,7 @@ PredefShakeScreenHorizontally:
 	ldh a, [hMutateWX]
 	xor b
 	ldh [hMutateWX], a
-	bit 7, a
+	bit 7, a ; negative?
 	jr z, .skipZeroing
 	xor a ; zero a if it's negative
 .skipZeroing
diff --git a/engine/movie/oak_speech/oak_speech.asm b/engine/movie/oak_speech/oak_speech.asm
index 44b236c8..5c364435 100644
--- a/engine/movie/oak_speech/oak_speech.asm
+++ b/engine/movie/oak_speech/oak_speech.asm
@@ -4,9 +4,9 @@ PrepareOakSpeech:
 	ld a, [wOptions]
 	push af
 	; Retrieve BIT_DEBUG_MODE set in DebugMenu for StartNewGameDebug.
-	; BUG: StartNewGame carries over bit 5 from previous save files,
+	; BUG: StartNewGame carries over BIT_ALWAYS_ON_BIKE from previous save files,
 	; which causes CheckForceBikeOrSurf to not return.
-	; To fix this in debug builds, reset bit 5 here or in StartNewGame.
+	; To fix this in debug builds, reset BIT_ALWAYS_ON_BIKE here or in StartNewGame.
 	; In non-debug builds, the instructions can be removed.
 	ld a, [wStatusFlags6]
 	push af
diff --git a/engine/overworld/map_sprites.asm b/engine/overworld/map_sprites.asm
index 75c46474..57c2d4db 100644
--- a/engine/overworld/map_sprites.asm
+++ b/engine/overworld/map_sprites.asm
@@ -187,7 +187,7 @@ LoadMapSpriteTilePatterns:
 	jr nz, .loadWhileLCDOn
 	pop af
 	pop hl
-	set 3, h ; add $80 tiles to hl
+	set 3, h ; add $800 ($80 tiles) to hl (1 << 3 == $8)
 	push hl
 	ld h, d
 	ld l, e
@@ -200,7 +200,7 @@ LoadMapSpriteTilePatterns:
 .loadWhileLCDOn
 	pop af
 	pop hl
-	set 3, h ; add $80 tiles to hl
+	set 3, h ; add $800 ($80 tiles) to hl (1 << 3 == $8)
 	ld b, a
 	swap c
 	call CopyVideoData ; load tile pattern data for sprite when walking
diff --git a/engine/overworld/movement.asm b/engine/overworld/movement.asm
index 5f95cf6c..cb65c997 100644
--- a/engine/overworld/movement.asm
+++ b/engine/overworld/movement.asm
@@ -641,7 +641,7 @@ CanWalkOntoTile:
 	add SPRITESTATEDATA2_YDISPLACEMENT
 	ld l, a
 	ld a, [hli]        ; x#SPRITESTATEDATA2_YDISPLACEMENT (initialized at $8, keep track of where a sprite did go)
-	bit 7, d           ; check if going upwards (d=$ff)
+	bit 7, d           ; check if going upwards (d == -1)
 	jr nz, .upwards
 	add d
 	; bug: these tests against $5 probably were supposed to prevent
@@ -658,7 +658,7 @@ CanWalkOntoTile:
 .checkHorizontal
 	ld d, a
 	ld a, [hl]         ; x#SPRITESTATEDATA2_XDISPLACEMENT (initialized at $8, keep track of where a sprite did go)
-	bit 7, e           ; check if going left (e=$ff)
+	bit 7, e           ; check if going left (e == -1)
 	jr nz, .left
 	add e
 	cp $5              ; compare, but no conditional jump like in the vertical check above (bug?)
diff --git a/engine/overworld/player_state.asm b/engine/overworld/player_state.asm
index 4711bb5c..4da437da 100644
--- a/engine/overworld/player_state.asm
+++ b/engine/overworld/player_state.asm
@@ -294,6 +294,13 @@ _GetTileAndCoordsInFrontOfPlayer:
 	ld [wTileInFrontOfPlayer], a
 	ret
 
+; hPlayerFacing
+	const_def
+	const BIT_FACING_DOWN  ; 0
+	const BIT_FACING_UP    ; 1
+	const BIT_FACING_LEFT  ; 2
+	const BIT_FACING_RIGHT ; 3
+
 GetTileTwoStepsInFrontOfPlayer:
 	xor a
 	ldh [hPlayerFacing], a
@@ -306,7 +313,7 @@ GetTileTwoStepsInFrontOfPlayer:
 	jr nz, .notFacingDown
 ; facing down
 	ld hl, hPlayerFacing
-	set 0, [hl]
+	set BIT_FACING_DOWN, [hl]
 	lda_coord 8, 13
 	inc d
 	jr .storeTile
@@ -315,7 +322,7 @@ GetTileTwoStepsInFrontOfPlayer:
 	jr nz, .notFacingUp
 ; facing up
 	ld hl, hPlayerFacing
-	set 1, [hl]
+	set BIT_FACING_UP, [hl]
 	lda_coord 8, 5
 	dec d
 	jr .storeTile
@@ -324,7 +331,7 @@ GetTileTwoStepsInFrontOfPlayer:
 	jr nz, .notFacingLeft
 ; facing left
 	ld hl, hPlayerFacing
-	set 2, [hl]
+	set BIT_FACING_LEFT, [hl]
 	lda_coord 4, 9
 	dec e
 	jr .storeTile
@@ -333,7 +340,7 @@ GetTileTwoStepsInFrontOfPlayer:
 	jr nz, .storeTile
 ; facing right
 	ld hl, hPlayerFacing
-	set 3, [hl]
+	set BIT_FACING_RIGHT, [hl]
 	lda_coord 12, 9
 	inc e
 .storeTile
@@ -385,7 +392,7 @@ CheckForBoulderCollisionWithSprites:
 	ld de, $f
 	ld hl, wSprite01StateData2MapY
 	ldh a, [hPlayerFacing]
-	and $3 ; facing up or down?
+	and (1 << BIT_FACING_UP) | (1 << BIT_FACING_DOWN)
 	jr z, .pushingHorizontallyLoop
 .pushingVerticallyLoop
 	inc hl
@@ -396,6 +403,7 @@ CheckForBoulderCollisionWithSprites:
 	ld a, [hli]
 	ld b, a
 	ldh a, [hPlayerFacing]
+	assert BIT_FACING_DOWN == 0
 	rrca
 	jr c, .pushingDown
 ; pushing up
@@ -421,7 +429,7 @@ CheckForBoulderCollisionWithSprites:
 	jr nz, .nextSprite2
 	ld b, [hl]
 	ldh a, [hPlayerFacing]
-	bit 2, a
+	bit BIT_FACING_LEFT, a
 	jr nz, .pushingLeft
 ; pushing right
 	ldh a, [hPlayerXCoord]
diff --git a/engine/overworld/spinners.asm b/engine/overworld/spinners.asm
index 98b478c4..261a939e 100644
--- a/engine/overworld/spinners.asm
+++ b/engine/overworld/spinners.asm
@@ -15,7 +15,7 @@ LoadSpinnerArrowTiles::
 	ld hl, GymSpinnerArrows
 .gotSpinnerArrows
 	ld a, [wSimulatedJoypadStatesIndex]
-	bit 0, a
+	bit 0, a ; even or odd?
 	jr nz, .alternateGraphics
 	ld de, 6 * 4
 	add hl, de