Identify various "????"s (#116)

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

data/player_names.asm

@@ -1,5 +1,5 @@
 NameMenuHeader:
-	db STATICMENU_NO_TOP_SPACING ; flags
+	db MENU_BACKUP_TILES ; flags
 	menu_coords 0, 0, 10, TEXTBOX_Y - 1
 	dw .Names
 	db 1 ; default option

engine/events/treemons.asm

@@ -51,7 +51,7 @@ RockMonEncounter:
 	xor a
 	ret
 
-	db $05 ; ????
+	db 5 ; unused
 
 GetTreeMonSet:
 ; Return carry and treemon set in a

engine/link/link.asm

@@ -588,7 +588,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

engine/overworld/events.asm

@@ -465,8 +465,8 @@ CheckTimeEvents:
 	scf
 	ret
 
-.unused ; unreferenced
-	ld a, $8 ; ???
+.hatch ; unreferenced
+	ld a, PLAYEREVENT_HATCH
 	scf
 	ret
 

engine/overworld/map_objects.asm

@@ -1925,7 +1925,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

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_step_stop             ; 4b
 	dw Movement_teleport_from         ; 4c
 	dw Movement_teleport_to           ; 4d
 	dw Movement_skyfall               ; 4e
@@ -206,7 +206,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
@@ -242,7 +242,7 @@ Movement_remove_object:
 	res SCRIPTED_MOVEMENT_STATE_F, [hl]
 	ret
 
-Movement_4b:
+Movement_step_stop:
 	ld hl, OBJECT_ACTION
 	add hl, bc
 	ld [hl], OBJECT_ACTION_STAND

engine/pokemon/breeding.asm

@@ -821,8 +821,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:

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