From 8819f7b117ffca65496077fa8f452792fb907258 Mon Sep 17 00:00:00 2001
From: Sylvie <35663410+Rangi42@users.noreply.github.com>
Date: Tue, 11 Jun 2024 20:54:45 -0400
Subject: [PATCH] Identify various "????"s (#1125)

---
 audio/engine.asm                 | 29 ++++++++++++++---------------
 data/player_names.asm            |  4 ++--
 engine/events/treemons.asm       |  2 +-
 engine/link/link.asm             |  2 +-
 engine/overworld/events.asm      |  4 ++--
 engine/overworld/map_objects.asm |  2 +-
 engine/overworld/movement.asm    |  8 ++++----
 engine/pokemon/breeding.asm      |  7 +++++--
 engine/pokemon/stats_screen.asm  |  6 ++++--
 macros/scripts/movement.asm      | 14 +++++++-------
 mobile/mobile_40.asm             |  5 ++---
 11 files changed, 43 insertions(+), 40 deletions(-)

diff --git a/audio/engine.asm b/audio/engine.asm
index 38e989440..9bea0b459 100644
--- a/audio/engine.asm
+++ b/audio/engine.asm
@@ -733,7 +733,7 @@ LoadNote:
 	ld e, [hl]
 	inc hl
 	ld d, [hl]
-	; get direction of pitch slide
+	; subtract pitch slide from frequency
 	ld hl, CHANNEL_PITCH_SLIDE_TARGET
 	add hl, bc
 	ld a, e
@@ -755,7 +755,7 @@ LoadNote:
 	ld e, [hl]
 	inc hl
 	ld d, [hl]
-	; ????
+	; subtract frequency from pitch slide
 	ld hl, CHANNEL_PITCH_SLIDE_TARGET
 	add hl, bc
 	ld a, [hl]
@@ -764,7 +764,6 @@ LoadNote:
 	ld a, d
 	sbc 0
 	ld d, a
-	; ????
 	ld hl, CHANNEL_PITCH_SLIDE_TARGET + 1
 	add hl, bc
 	ld a, [hl]
@@ -906,7 +905,7 @@ HandleTrackVibrato:
 	swap [hl]
 	or [hl]
 	ld [hl], a
-	; ????
+	; get the frequency
 	ld a, [wCurTrackFrequency]
 	ld e, a
 	; toggle vibrato up/down
@@ -1190,7 +1189,7 @@ ParseMusic:
 	ld [hl], e
 	inc hl
 	ld [hl], d
-	; ????
+	; set noise sampling
 	ld hl, CHANNEL_NOTE_FLAGS
 	add hl, bc
 	set NOTE_NOISE_SAMPLING, [hl]
@@ -1209,10 +1208,10 @@ ParseMusic:
 	add hl, bc
 	bit SOUND_SUBROUTINE, [hl] ; in a subroutine?
 	jr nz, .readcommand ; execute
+	; are we in a sfx channel right now?
 	ld a, [wCurChannel]
-	cp CHAN5
+	cp NUM_MUSIC_CHANS
 	jr nc, .chan_5to8
-	; ????
 	ld hl, CHANNEL_STRUCT_LENGTH * NUM_MUSIC_CHANS + CHANNEL_FLAGS1
 	add hl, bc
 	bit SOUND_CHANNEL_ON, [hl]
@@ -1226,9 +1225,9 @@ ParseMusic:
 	ld a, [wCurChannel]
 	cp CHAN5
 	jr nz, .ok
-	; ????
+	; sweep = 0
 	xor a
-	ldh [rNR10], a ; sweep = 0
+	ldh [rNR10], a
 .ok
 ; stop playing
 	; turn channel off
@@ -1348,7 +1347,7 @@ GetNoiseSample:
 	ld [wNoiseSampleAddress], a
 	ld a, [hl]
 	ld [wNoiseSampleAddress + 1], a
-	; clear ????
+	; clear noise sample delay
 	xor a
 	ld [wNoiseSampleDelay], a
 	ret
@@ -1629,7 +1628,7 @@ MusicEE:
 ; params: 2
 ;		ll hh ; pointer
 
-; if ????, jump
+; if condition is set, jump
 	; get channel
 	ld a, [wCurChannel]
 	maskbits NUM_MUSIC_CHANS
@@ -2206,7 +2205,7 @@ SetNoteDuration:
 	ld e, [hl]
 	inc hl
 	ld d, [hl]
-	; add ???? to the next result
+	; add ??? to the next result
 	ld hl, CHANNEL_FIELD16
 	add hl, bc
 	ld l, [hl]
@@ -2215,7 +2214,7 @@ SetNoteDuration:
 	; copy result to de
 	ld e, l
 	ld d, h
-	; store result in ????
+	; store result in ???
 	ld hl, CHANNEL_FIELD16
 	add hl, bc
 	ld [hl], e
@@ -2250,7 +2249,7 @@ SetGlobalTempo:
 	push bc ; save current channel
 	; are we dealing with music or sfx?
 	ld a, [wCurChannel]
-	cp CHAN5
+	cp NUM_MUSIC_CHANS
 	jr nc, .sfxchannels
 	ld bc, wChannel1
 	call Tempo
@@ -2284,7 +2283,7 @@ Tempo:
 	ld [hl], e
 	inc hl
 	ld [hl], d
-	; clear ????
+	; clear ???
 	xor a
 	ld hl, CHANNEL_FIELD16
 	add hl, bc
diff --git a/data/player_names.asm b/data/player_names.asm
index 0faadf1ab..650cbe9b5 100644
--- a/data/player_names.asm
+++ b/data/player_names.asm
@@ -3,7 +3,7 @@ ChrisNameMenuHeader:
 	menu_coords 0, 0, 10, TEXTBOX_Y - 1
 	dw .MaleNames
 	db 1 ; default option
-	db 0 ; ????
+	db 0 ; ???
 
 .MaleNames:
 	db STATICMENU_CURSOR | STATICMENU_PLACE_TITLE | STATICMENU_DISABLE_B ; flags
@@ -22,7 +22,7 @@ KrisNameMenuHeader:
 	menu_coords 0, 0, 10, TEXTBOX_Y - 1
 	dw .FemaleNames
 	db 1 ; default option
-	db 0 ; ????
+	db 0 ; ???
 
 .FemaleNames:
 	db STATICMENU_CURSOR | STATICMENU_PLACE_TITLE | STATICMENU_DISABLE_B ; flags
diff --git a/engine/events/treemons.asm b/engine/events/treemons.asm
index 231636ea0..804f7d666 100644
--- a/engine/events/treemons.asm
+++ b/engine/events/treemons.asm
@@ -53,7 +53,7 @@ RockMonEncounter:
 	xor a
 	ret
 
-	db $05 ; ????
+	db 5 ; unused
 
 GetTreeMonSet:
 ; Return carry and treemon set in a
diff --git a/engine/link/link.asm b/engine/link/link.asm
index 2b93fbb6c..693a6fb50 100644
--- a/engine/link/link.asm
+++ b/engine/link/link.asm
@@ -647,7 +647,7 @@ endr
 
 ; Loop through all the patchable link data
 	ld hl, wLinkData + SERIAL_PREAMBLE_LENGTH + NAME_LENGTH + (1 + PARTY_LENGTH + 1) - 1
-	ld de, wPlayerPatchLists + SERIAL_RNS_LENGTH ; ???
+	ld de, wPlayerPatchLists + SERIAL_RNS_LENGTH
 	lb bc, 0, 0
 .patch_loop
 ; Check if we've gone over the entire area
diff --git a/engine/overworld/events.asm b/engine/overworld/events.asm
index f593e8cc7..b069a7dd0 100644
--- a/engine/overworld/events.asm
+++ b/engine/overworld/events.asm
@@ -477,8 +477,8 @@ CheckTimeEvents:
 	scf
 	ret
 
-.unused ; unreferenced
-	ld a, $8 ; ???
+.hatch ; unreferenced
+	ld a, PLAYEREVENT_HATCH
 	scf
 	ret
 
diff --git a/engine/overworld/map_objects.asm b/engine/overworld/map_objects.asm
index f3c21aa7a..9d0cdbf52 100644
--- a/engine/overworld/map_objects.asm
+++ b/engine/overworld/map_objects.asm
@@ -1957,7 +1957,7 @@ ApplyMovementToFollower:
 	ret z
 	cp movement_step_end
 	ret z
-	cp movement_step_4b
+	cp movement_step_stop
 	ret z
 	cp movement_step_bump
 	ret z
diff --git a/engine/overworld/movement.asm b/engine/overworld/movement.asm
index 3be90a929..02ef02d46 100644
--- a/engine/overworld/movement.asm
+++ b/engine/overworld/movement.asm
@@ -73,10 +73,10 @@ MovementPointers:
 	dw Movement_step_sleep_8          ; 45
 	dw Movement_step_sleep            ; 46
 	dw Movement_step_end              ; 47
-	dw Movement_48                    ; 48
+	dw Movement_step_wait_end         ; 48
 	dw Movement_remove_object         ; 49
 	dw Movement_step_loop             ; 4a
-	dw Movement_4b                    ; 4b
+	dw Movement_stop                  ; 4b
 	dw Movement_teleport_from         ; 4c
 	dw Movement_teleport_to           ; 4d
 	dw Movement_skyfall               ; 4e
@@ -213,7 +213,7 @@ Movement_step_end:
 	ld [hl], STEP_TYPE_FROM_MOVEMENT
 	ret
 
-Movement_48:
+Movement_step_wait_end:
 	call RestoreDefaultMovement
 	ld hl, OBJECT_MOVEMENT_TYPE
 	add hl, bc
@@ -249,7 +249,7 @@ Movement_remove_object:
 	res SCRIPTED_MOVEMENT_STATE_F, [hl]
 	ret
 
-Movement_4b:
+Movement_stop:
 	ld hl, OBJECT_ACTION
 	add hl, bc
 	ld [hl], OBJECT_ACTION_STAND
diff --git a/engine/pokemon/breeding.asm b/engine/pokemon/breeding.asm
index 73b04570b..b4d44fa7c 100644
--- a/engine/pokemon/breeding.asm
+++ b/engine/pokemon/breeding.asm
@@ -837,8 +837,11 @@ Hatch_InitShellFragments:
 	ret
 
 MACRO shell_fragment
-; y tile, y pxl, x tile, x pxl, frameset offset, ???
-	db (\1 * TILE_WIDTH) % $100 + \2, (\3 * TILE_WIDTH) % $100 + \4, \5 - SPRITE_ANIM_FRAMESET_EGG_HATCH_1, \6
+; y tile, y pxl, x tile, x pxl, frameset, angle
+	db (\1) * TILE_WIDTH + (\2) ; y coord
+	db (\3) * TILE_WIDTH + (\4) ; x coord
+	db (\5) - SPRITE_ANIM_FRAMESET_EGG_HATCH_1 ; frameset offset
+	db \6 ; angle (6 bits)
 ENDM
 
 .SpriteData:
diff --git a/engine/pokemon/stats_screen.asm b/engine/pokemon/stats_screen.asm
index ef5a57b84..adfe6c63f 100644
--- a/engine/pokemon/stats_screen.asm
+++ b/engine/pokemon/stats_screen.asm
@@ -62,12 +62,13 @@ StatsScreenInit_gotaddress:
 StatsScreenMain:
 	xor a
 	ld [wJumptableIndex], a
-; ???
 	ld [wStatsScreenFlags], a
+
 	ld a, [wStatsScreenFlags]
 	and ~STAT_PAGE_MASK
 	or PINK_PAGE ; first_page
 	ld [wStatsScreenFlags], a
+
 .loop
 	ld a, [wJumptableIndex]
 	and ~(1 << 7)
@@ -82,12 +83,13 @@ StatsScreenMain:
 StatsScreenMobile:
 	xor a
 	ld [wJumptableIndex], a
-; ???
 	ld [wStatsScreenFlags], a
+
 	ld a, [wStatsScreenFlags]
 	and ~STAT_PAGE_MASK
 	or PINK_PAGE ; first_page
 	ld [wStatsScreenFlags], a
+
 .loop
 	farcall Mobile_SetOverworldDelay
 	ld a, [wJumptableIndex]
diff --git a/macros/scripts/movement.asm b/macros/scripts/movement.asm
index b5fc59bc4..0b75bf433 100644
--- a/macros/scripts/movement.asm
+++ b/macros/scripts/movement.asm
@@ -124,10 +124,10 @@ MACRO step_end
 	db movement_step_end
 ENDM
 
-	const movement_step_48 ; $48
-MACRO step_48
-	db movement_step_48
-	db \1 ; ???
+	const movement_step_wait_end ; $48
+MACRO step_wait_end
+	db movement_step_wait_end
+	db \1 ; length
 ENDM
 
 	const movement_remove_object ; $49
@@ -140,9 +140,9 @@ MACRO step_loop
 	db movement_step_loop
 ENDM
 
-	const movement_step_4b ; $4b
-MACRO step_4b
-	db movement_step_4b
+	const movement_step_stop ; $4b
+MACRO step_stop
+	db movement_step_stop
 ENDM
 
 	const movement_teleport_from ; $4c
diff --git a/mobile/mobile_40.asm b/mobile/mobile_40.asm
index f93e81492..2a5654836 100644
--- a/mobile/mobile_40.asm
+++ b/mobile/mobile_40.asm
@@ -239,7 +239,7 @@ Function10016f:
 	jr z, .asm_1001af
 	cp $f8
 	ret z
-	ret   ; ????????????????????????????
+	ret ; ???
 
 .asm_1001af
 	ld a, $d7
@@ -2445,9 +2445,8 @@ Unknown_10102c:
 Function101050:
 	call Function10107d
 	ld a, [wOTPartyCount]
-rept 2 ; ???
 	ld hl, wc608
-endr
+	ld hl, wc608 ; redundant
 	ld bc, wc7bb - wc608
 	call Function1010de
 	ld hl, wc7bb