NPC functions disasm and documenting

4 files changed, 715 insertions, 178 deletions

diff --git a/src/engine/bank03.asm b/src/engine/bank03.asm
index 75e3081..f9958b5 100644
--- a/src/engine/bank03.asm
+++ b/src/engine/bank03.asm
@@ -28,7 +28,7 @@ LoadMap: ; c000 (3:4000)
 	call Func_3ca0
 	ld a, PLAYER_TURN
 	ldh [hWhoseTurn], a
-	farcall Func_1c440
+	farcall ClearNPCs
 	ld a, [wTempMap]
 	ld [wCurMap], a
 	ld a, [wTempPlayerXCoord]
@@ -184,7 +184,7 @@ Func_c158: ; c158 (3:4158)
 	call GetItemInLoadedNPCIndex
 	ld a, [wd0c5]
 	ld [hl], a
-	farcall Func_1c58e
+	farcall UpdateNPCAnimation
 .asm_c179
 	ret
 
@@ -241,7 +241,7 @@ Func_c1b1: ; c1b1 (3:41b1)
 	call Func_c9cb
 	call Func_c9dd
 	farcall Func_80b7a
-	farcall Func_1c82e
+	farcall ClearMasterBeatenList
 	farcall Func_131b3
 	xor a
 	ld [wPlayTimeCounter + 0], a
@@ -266,7 +266,7 @@ Func_c1f8: ; c1f8 (3:41f8)
 	ld [wd0c2], a
 	ld [wDefaultSong], a
 	ld [wd112], a
-	ld [wd3b8], a
+	ld [wRonaldIsInMap], a
 	call EnableSRAM
 	ld a, [sAnimationsDisabled]
 	ld [wAnimationsDisabled], a
@@ -409,7 +409,7 @@ Func_c2db: ; c2db (3:42db)
 	res 0, [hl]
 	call Func_c34e
 	farcall Func_12c5e
-	farcall Func_1c6f8
+	farcall SetAllNPCTilePermissions
 	ld hl, wd0c1
 	res 7, [hl]
 	ld hl, wd10f
@@ -1430,7 +1430,7 @@ Func_c943: ; c943 (3:4943)
 	ld a, [wTempNPC]
 	farcall LoadNPCSpriteData
 	call Func_c998
-	farcall Func_1c485
+	farcall LoadNPC
 .next_npc
 	pop hl
 	ld bc, NPC_MAP_SIZE
@@ -1458,9 +1458,9 @@ Func_c998: ; c998 (3:4998)
 	ld b, $e
 .not_cgb
 	ld a, b
-	ld [wd3b1], a
+	ld [wNPCAnim], a
 	ld a, $0
-	ld [wd3b2], a
+	ld [wNPCAnimFlags], a
 	ret
 
 Func_c9b8: ; c9b8 (3:49b8)
@@ -2195,7 +2195,7 @@ ScriptCommand_UnloadActiveNPC: ; cdcb (3:4dcb)
 	ld a, [wScriptNPC]
 	ld [wLoadedNPCTempIndex], a
 Func_cdd1: ; cdd1 (3:4dd1)
-	farcall Func_1c50a
+	farcall UnloadNPC
 	jp IncreaseScriptPointerBy1
 
 ScriptCommand_UnloadChallengeHallNPC: ; cdd8 (3:4dd8)
@@ -2228,7 +2228,7 @@ ScriptCommand_SetChallengeHallNPCCoords: ; cdf5 (3:4df5)
 	ld [wLoadNPCDirection], a
 	ld a, [wTempNPC]
 	farcall LoadNPCSpriteData
-	farcall Func_1c485
+	farcall LoadNPC
 	pop af
 	ld [wTempNPC], a
 	pop af
@@ -2255,10 +2255,10 @@ ScriptCommand_MoveActiveNPCByDirection: ; ce26 (3:4e26)
 ; Moves an NPC given the list of directions pointed to by bc
 ; set bit 7 to only rotate the NPC
 ExecuteNPCMovement: ; ce3a (3:4e3a)
-	farcall Func_1c78d
+	farcall StartNPCMovement
 .loop
 	call DoFrameIfLCDEnabled
-	farcall Func_1c7de
+	farcall CheckIsAnNPCMoving
 	jr nz, .loop
 	jp IncreaseScriptPointerBy3
 
@@ -2656,9 +2656,9 @@ ScriptCommand_SetSpriteAttributes: ; d095 (3:5095)
 	push bc
 	call GetScriptArgs3AfterPointer
 	ld a, [wScriptNPC]
-	ld l, LOADED_NPC_FIELD_05
+	ld l, LOADED_NPC_FLAGS
 	call GetItemInLoadedNPCIndex
-	res 4, [hl]
+	res NPC_FLAG_DIRECTIONLESS_F, [hl]
 	ld a, [hl]
 	or c
 	ld [hl], a
@@ -2670,7 +2670,7 @@ ScriptCommand_SetSpriteAttributes: ; d095 (3:5095)
 	ld e, b
 .not_cgb
 	ld a, e
-	farcall Func_1c57b
+	farcall SetNPCAnimation
 	jp IncreaseScriptPointerBy4
 
 ScriptCommand_SetActiveNPCCoords: ; d0be (3:50be)
@@ -2679,7 +2679,7 @@ ScriptCommand_SetActiveNPCCoords: ; d0be (3:50be)
 	ld a, c
 	ld c, b
 	ld b, a
-	farcall Func_1c461
+	farcall SetNPCPosition
 	jp IncreaseScriptPointerBy3
 
 ScriptCommand_DoFrames: ; d0ce (3:50ce)
@@ -2695,7 +2695,7 @@ ScriptCommand_JumpIfActiveNPCCoordsMatch: ; d0d9 (3:50d9)
 	ld [wLoadedNPCTempIndex], a
 	ld d, c
 	ld e, b
-	farcall Func_1c477
+	farcall GetNPCPosition
 	ld a, e
 	cp c
 	jp nz, ScriptCommand_JumpIfEventEqual.fail
@@ -3256,7 +3256,7 @@ ScriptCommand_WaitForSongToFinish: ; d42f (3:542f)
 
 ScriptCommand_RecordMasterWin: ; d435 (3:5435)
 	ld a, c
-	farcall Func_1c83d
+	farcall AddMasterBeatenToList
 	jp IncreaseScriptPointerBy2
 
 ScriptCommand_ChallengeMachine: ; d43d (3:543d)
diff --git a/src/engine/bank04.asm b/src/engine/bank04.asm
index 38b1271..9140e09 100644
--- a/src/engine/bank04.asm
+++ b/src/engine/bank04.asm
@@ -311,7 +311,7 @@ TryGivePCPack: ; 10a70 (4:4a70)
 	push bc
 	push de
 	ld b, a
-	ld c, $f ; number of packs possible
+	ld c, NUM_PC_PACKS
 	ld hl, wPCPacks
 .searchLoop1
 	ld a, [hli]
@@ -320,7 +320,7 @@ TryGivePCPack: ; 10a70 (4:4a70)
 	jr z, .quit
 	dec c
 	jr nz, .searchLoop1
-	ld c, $f
+	ld c, NUM_PC_PACKS
 	ld hl, wPCPacks
 .findFreeSlotLoop
 	ld a, [hl]
@@ -334,7 +334,7 @@ TryGivePCPack: ; 10a70 (4:4a70)
 
 .foundFreeSlot
 	ld a, b
-	or $80 ; mark pack as unopened
+	or PACK_OPENED ; mark pack as unopened
 	ld [hl], a
 
 .quit
@@ -1116,10 +1116,163 @@ UpdateAlbumProgress: ; 1127f (4:527f)
 	INCROM $11299, $11320
 
 Func_11320: ; 11320 (4:5320)
-	INCROM $11320, $11343
+	push de
+	ldh a, [hBankSRAM]
+	push af
+	ld a, $02
+	call BankswitchSRAM
+	ld de, sb800
+	call Func_1135d
+	ld de, sAlbumProgress
+	call LoadAlbumProgressFromSRAM
+	pop af
+	call BankswitchSRAM
+	call DisableSRAM
+	pop de
+	ld a, [wNumSRAMValidationErrors]
+	cp 1
+	ret
+; 0x11343
 
 Func_11343: ; 11343 (4:5343)
-	INCROM $11343, $11416
+	INCROM $11343, $1135d
+
+Func_1135d: ; 1135d (4:535d)
+	push hl
+	push bc
+	push de
+	xor a
+	ld [wNumSRAMValidationErrors], a
+	push de
+
+	push de
+	inc de
+	inc de
+	ld a, [de]
+	inc de
+	ld [wNumGeneralSaveDataBytes + 0], a
+	ld a, [de]
+	inc de
+	ld [wNumGeneralSaveDataBytes + 1], a
+	ld a, [de]
+	inc de
+	ld [wGeneralSaveDataCheckSum + 0], a
+	ld a, [de]
+	inc de
+	ld [wGeneralSaveDataCheckSum + 1], a
+	pop de
+
+	ld hl, $8
+	add hl, de
+	ld e, l
+	ld d, h
+	ld hl, WRAMToSRAMMapper
+.loop
+	ld a, [hli]
+	ld c, a
+	ld a, [hli]
+	or c
+	jr z, .exit_loop
+	ld a, [hli]
+	ld c, a ; number of bytes LO
+	ld a, [hli]
+	ld b, a ; number of bytes HI
+	ld a, [wNumGeneralSaveDataBytes + 0]
+	sub c
+	ld [wNumGeneralSaveDataBytes + 0], a
+	ld a, [wNumGeneralSaveDataBytes + 1]
+	sbc b
+	ld [wNumGeneralSaveDataBytes + 1], a
+
+; loop all the bytes of this struct
+.loop_bytes
+	push hl
+	push bc
+	ld a, [de]
+	push af
+	ld c, a
+	ld a, [wGeneralSaveDataCheckSum + 0]
+	sub c
+	ld [wGeneralSaveDataCheckSum + 0], a
+	ld a, [wGeneralSaveDataCheckSum + 1]
+	sbc 0
+	ld [wGeneralSaveDataCheckSum + 1], a
+	pop af
+
+	; check if it's within the specified values
+	cp [hl] ; min value
+	jr c, .error
+	inc hl
+	cp [hl] ; max value
+	jr z, .next_byte
+	jr c, .next_byte
+.error
+	ld a, [wNumSRAMValidationErrors]
+	inc a
+	ld [wNumSRAMValidationErrors], a
+.next_byte
+	inc de
+	pop bc
+	pop hl
+	dec bc
+	ld a, c
+	or b
+	jr nz, .loop_bytes
+	; next mapped struct
+	inc hl
+	inc hl
+	jr .loop
+
+.exit_loop
+	pop hl
+	ld a, [hli]
+	sub $08
+	ld c, a
+	ld a, [hl]
+	sub 0
+	or c
+	ld hl, wNumGeneralSaveDataBytes
+	or [hl]
+	inc hl
+	or [hl]
+	ld hl, wGeneralSaveDataCheckSum
+	or [hl]
+	inc hl
+	or [hl]
+	jr z, .asm_113ea
+	ld hl, wNumSRAMValidationErrors
+	inc [hl]
+.asm_113ea
+	pop de
+	ld hl, $c
+	add hl, de
+	ld a, [hli]
+	ld [wd3c8 + 0], a
+	ld a, [hli]
+	ld [wd3c8 + 1], a
+	ld a, [hli]
+	ld [wd3c8 + 2], a
+	ld hl, $8
+	add hl, de
+	ld a, [hli]
+	ld [wd3cc], a
+	ld a, [hl]
+	ld [wd3cb], a
+	pop bc
+	pop hl
+	ret
+; 0x1140a
+
+LoadAlbumProgressFromSRAM: ; 1140a (4:540a)
+	push de
+	ld a, [de]
+	ld [wTotalNumCardsCollected], a
+	inc de
+	ld a, [de]
+	ld [wTotalNumCardsToCollect], a
+	pop de
+	ret
+; 0x11416
 
 Func_11416: ; 11416 (4:5416)
 	INCROM $11416, $11430
@@ -1147,11 +1300,11 @@ Func_11430: ; 11430 (4:5430)
 	push de
 	ld a, e
 	add $08
-	ld [wTempPointer], a
+	ld [wTempPointer + 0], a
 	ld a, d
 	adc 0
 	ld [wTempPointer + 1], a
-	ld hl, .wram_map
+	ld hl, WRAMToSRAMMapper
 .asm_11459
 	ld a, [hli]
 	ld e, a
@@ -1166,7 +1319,7 @@ Func_11430: ; 11430 (4:5430)
 
 ; copy bc bytes from wTempPointer to de
 	push hl
-	ld a, [wTempPointer]
+	ld a, [wTempPointer + 0]
 	ld l, a
 	ld a, [wTempPointer + 1]
 	ld h, a
@@ -1180,7 +1333,7 @@ Func_11430: ; 11430 (4:5430)
 	jr nz, .loop_copy
 
 	ld a, l
-	ld [wTempPointer], a
+	ld [wTempPointer + 0], a
 	ld a, h
 	ld [wTempPointer + 1], a
 	pop hl
@@ -1199,48 +1352,61 @@ Func_11430: ; 11430 (4:5430)
 	pop bc
 	pop hl
 	ret
-
-.wram_map
+; 0x11498
+
+wram_sram_map: MACRO
+	dw \1 ; WRAM address
+	dw \2 ; number of bytes
+	db \3 ; min allowed value
+	db \4 ; max allowed value
+ENDM
+
+; maps WRAM addresses to SRAM addresses in order
+; to save and subsequently retreive them on game load
+; also works as a test in order check whether
+; the saved values is SRAM are legal, within the given value range
+WRAMToSRAMMapper: ; 11498 (4:5498)
 ; pointer, number of bytes, unknown
-	dw wd3cc,                  1, $ff00 ; sb808
-	dw wd3cb,                  1, $ff00 ; sb809
-	dw wPlayTimeCounter + 0,   1, $ff00 ; sPlayTimeCounter
-	dw wPlayTimeCounter + 1,   1, $ff00
-	dw wPlayTimeCounter + 2,   1, $ff00
-	dw wPlayTimeCounter + 3,   2, $ff00
-	dw wOverworldMapSelection, 1, $ff00 ; sOverworldMapSelection
-	dw wTempMap,               1, $ff00 ; sTempMap
-	dw wTempPlayerXCoord,      1, $ff00 ; sTempPlayerXCoord
-	dw wTempPlayerYCoord,      1, $ff00 ; sTempPlayerYCoord
-	dw wTempPlayerDirection,   1, $ff00 ; sTempPlayerDirection
-	dw wd0c2,                  1, $ff00 ; sb814
-	dw wDuelResult,            1, $ff00 ; sDuelResult
-	dw wNPCDuelist,            1, $ff00 ; sNPCDuelist
-	dw wChallengeHallNPC,      1, $ff00 ; sChallengeHallNPC
-	dw wd698,                  4, $ff00 ; sb818
-	dw wOWMapEvents,          11, $ff00 ; sOWMapEvents
-	dw Data_1156c,             1, $ff00 ; sb827
-	dw wd0b8,                  1, $ff00 ; sb828
-	dw wd0b9,                  1, $ff00 ; sb829
-	dw wd11b,                  1, $ff00 ; sb82a
-	dw wd0ba,                  1, $ff00 ; sb82b
-	dw wPCPackSelection,       1, $0e00 ; sPCPackSelection
-	dw wPCPacks,              15, $ff00 ; sPCPacks
-	dw wDefaultSong,           1, $ff00 ; sDefaultSong
-	dw wcad5,                  1, $ff00 ; sb83d
-	dw wd3b8,                  1, $ff00 ; sb83e
-	dw wd3bb,                 10, $ff00 ; sb83f
-	dw wd0c5,                  1, $ff00 ; sb849
-	dw wMultichoiceTextboxResult_ChooseDeckToDuelAgainst, 1, $ff00 ; sMultichoiceTextboxResult_ChooseDeckToDuelAgainst
-	dw wd10e,                  1, $ff00 ; sb84b
-	dw Data_1156c,            15, $ff00 ; sb84c
-	dw Data_1156c,            16, $ff00 ; sb85b
-	dw Data_1156c,            16, $ff00 ; sb86b
-	dw wEventVars,            64, $ff00 ; sEventVars
+	wram_sram_map wd3cc,                              1, $00, $ff ; sb808
+	wram_sram_map wd3cb,                              1, $00, $ff ; sb809
+	wram_sram_map wPlayTimeCounter + 0,               1, $00, $ff ; sPlayTimeCounter
+	wram_sram_map wPlayTimeCounter + 1,               1, $00, $ff
+	wram_sram_map wPlayTimeCounter + 2,               1, $00, $ff
+	wram_sram_map wPlayTimeCounter + 3,               2, $00, $ff
+	wram_sram_map wOverworldMapSelection,             1, $00, $ff ; sOverworldMapSelection
+	wram_sram_map wTempMap,                           1, $00, $ff ; sTempMap
+	wram_sram_map wTempPlayerXCoord,                  1, $00, $ff ; sTempPlayerXCoord
+	wram_sram_map wTempPlayerYCoord,                  1, $00, $ff ; sTempPlayerYCoord
+	wram_sram_map wTempPlayerDirection,               1, $00, $ff ; sTempPlayerDirection
+	wram_sram_map wd0c2,                              1, $00, $ff ; sb814
+	wram_sram_map wDuelResult,                        1, $00, $ff ; sDuelResult
+	wram_sram_map wNPCDuelist,                        1, $00, $ff ; sNPCDuelist
+	wram_sram_map wChallengeHallNPC,                  1, $00, $ff ; sChallengeHallNPC
+	wram_sram_map wd698,                              4, $00, $ff ; sb818
+	wram_sram_map wOWMapEvents,          NUM_MAP_EVENTS, $00, $ff ; sOWMapEvents
+	wram_sram_map .EmptySRAMSlot,                     1, $00, $ff ; sb827
+	wram_sram_map wd0b8,                              1, $00, $ff ; sb828
+	wram_sram_map wd0b9,                              1, $00, $ff ; sb829
+	wram_sram_map wd11b,                              1, $00, $ff ; sb82a
+	wram_sram_map wd0ba,                              1, $00, $ff ; sb82b
+	wram_sram_map wPCPackSelection,                   1,   0,  14 ; sPCPackSelection
+	wram_sram_map wPCPacks,                NUM_PC_PACKS, $00, $ff ; sPCPacks
+	wram_sram_map wDefaultSong,                       1, $00, $ff ; sDefaultSong
+	wram_sram_map wcad5,                              1, $00, $ff ; sb83d
+	wram_sram_map wRonaldIsInMap,                     1, $00, $ff ; sRonaldIsInMap
+	wram_sram_map wMastersBeatenList,                10, $00, $ff ; sMastersBeatenList
+	wram_sram_map wd0c5,                              1, $00, $ff ; sb849
+	wram_sram_map wMultichoiceTextboxResult_ChooseDeckToDuelAgainst, 1, $00, $ff ; sMultichoiceTextboxResult_ChooseDeckToDuelAgainst
+	wram_sram_map wd10e,                              1, $00, $ff ; sb84b
+	wram_sram_map .EmptySRAMSlot,                    15, $00, $ff ; sb84c
+	wram_sram_map .EmptySRAMSlot,                    16, $00, $ff ; sb85b
+	wram_sram_map .EmptySRAMSlot,                    16, $00, $ff ; sb86b
+	wram_sram_map wEventVars,                        64, $00, $ff ; sEventVars
 	dw NULL
 ; 0x1156c
 
-Data_1156c: ; 1156c (4:556c)
+; fills an empty SRAM slot with zero
+.EmptySRAMSlot: ; 1156c (4:556c)
 	db $00, $00, $00, $00, $00, $00, $00, $00, $00, $00, $00, $00, $00, $00, $00, $00
 ; 0x1157c
 
@@ -1325,17 +1491,17 @@ LoadNPCSpriteData: ; 11857 (4:5857)
 	ld a, [hli]
 	ld [wNPCSpriteID], a
 	ld a, [hli]
-	ld [wd3b1], a
+	ld [wNPCAnim], a
 	ld a, [hli]
 	push af
 	ld a, [hli]
-	ld [wd3b2], a
+	ld [wNPCAnimFlags], a
 	pop bc
 	ld a, [wConsole]
 	cp CONSOLE_CGB
 	jr nz, .not_cgb
 	ld a, b
-	ld [wd3b1], a
+	ld [wNPCAnim], a
 .not_cgb
 	pop bc
 	pop hl
@@ -3061,24 +3227,26 @@ FillNewSpriteAnimBufferEntry: ; 129d9 (4:69d9)
 	pop hl
 	ret
 
-Func_129fa: ; 129fa (4:69fa)
+DisableCurSpriteAnim: ; 129fa (4:69fa)
 	ld a, [wWhichSprite]
 	; fallthrough
 
-Func_129fd: ; 129fd (4:69fd)
+; sets SPRITE_ANIM_ENABLED to false
+; of sprite in register a
+DisableSpriteAnim: ; 129fd (4:69fd)
 	push af
 	ld a, [wd5d7]
 	or a
-	jr z, .asm_12a06
+	jr z, .disable
 	pop af
 	ret
-.asm_12a06
+.disable
 	pop af
 	push hl
 	push bc
 	ld c, SPRITE_ANIM_ENABLED
 	call GetSpriteAnimBufferProperty_SpriteInA
-	ld [hl], $00
+	ld [hl], FALSE
 	pop bc
 	pop hl
 	ret
diff --git a/src/engine/bank07.asm b/src/engine/bank07.asm
index 85de56b..206c014 100644
--- a/src/engine/bank07.asm
+++ b/src/engine/bank07.asm
@@ -94,8 +94,22 @@ LoadMapHeader: ; 1c33b (7:433b)
 
 INCLUDE "data/map_headers.asm"
 
-Func_1c440: ; 1c440 (7:4440)
-	INCROM $1c440, $1c455
+ClearNPCs: ; 1c440 (7:4440)
+	push hl
+	push bc
+	ld hl, wLoadedNPCs
+	ld c, LOADED_NPC_MAX * LOADED_NPC_LENGTH
+	xor a
+.loop
+	ld [hli], a
+	dec c
+	jr nz, .loop
+	ld [wNumLoadedNPCs], a
+	ld [wRonaldIsInMap], a
+	pop bc
+	pop hl
+	ret
+; 0x1c455
 
 GetNPCDirection: ; 1c455 (7:4455)
 	push hl
@@ -106,22 +120,25 @@ GetNPCDirection: ; 1c455 (7:4455)
 	pop hl
 	ret
 
-Func_1c461: ; 1c461 (7:4461)
+; sets new position to active NPC
+; and updates its tile permissions
+; bc = new coords
+SetNPCPosition: ; 1c461 (7:4461)
 	push hl
 	push bc
-	call Func_1c719
+	call UpdateNPCsTilePermission
 	ld a, [wLoadedNPCTempIndex]
 	ld l, LOADED_NPC_COORD_X
 	call GetItemInLoadedNPCIndex
 	ld a, b
 	ld [hli], a
 	ld [hl], c
-	call Func_1c6e3
+	call SetNPCsTilePermission
 	pop bc
 	pop hl
 	ret
 
-Func_1c477: ; 1c477 (7:4477)
+GetNPCPosition: ; 1c477 (7:4477)
 	push hl
 	ld a, [wLoadedNPCTempIndex]
 	ld l, LOADED_NPC_COORD_X
@@ -133,7 +150,7 @@ Func_1c477: ; 1c477 (7:4477)
 	ret
 
 ; Loads NPC Sprite Data
-Func_1c485: ; 1c485 (7:4485)
+LoadNPC: ; 1c485 (7:4485)
 	push hl
 	push bc
 	push de
@@ -173,65 +190,68 @@ Func_1c485: ; 1c485 (7:4485)
 	ld [hli], a
 	ld a, [wLoadNPCDirection]
 	ld [hli], a
-	ld a, [wd3b2]
+	ld a, [wNPCAnimFlags]
 	ld [hli], a
-	ld a, [wd3b1]
+	ld a, [wNPCAnim]
 	ld [hli], a
 	ld a, [wLoadNPCDirection]
 	ld [hli], a
-	call Func_1c58e
-	call Func_1c5b9
-	ld hl, wd349
+	call UpdateNPCAnimation
+	call ApplyRandomCountToNPCAnim
+	ld hl, wNumLoadedNPCs
 	inc [hl]
 	pop hl
-	call Func_1c665
-	call Func_1c6e3
+
+	call UpdateNPCSpritePosition
+	call SetNPCsTilePermission
+
 	ld a, [wTempNPC]
-	call Func_1c4fa
+	call CheckIfNPCIsRonald
 	jr nc, .exit
-	ld a, $01
-	ld [wd3b8], a
+	ld a, TRUE
+	ld [wRonaldIsInMap], a
 .exit
 	pop de
 	pop bc
 	pop hl
 	ret
 
-Func_1c4fa: ; 1c4fa (7:44fa)
+; returns carry if input NPC ID in register a is Ronald
+CheckIfNPCIsRonald: ; 1c4fa (7:44fa)
 	cp NPC_RONALD1
-	jr z, .asm_1c508
+	jr z, .set_carry
 	cp NPC_RONALD2
-	jr z, .asm_1c508
+	jr z, .set_carry
 	cp NPC_RONALD3
-	jr z, .asm_1c508
+	jr z, .set_carry
 	or a
 	ret
-.asm_1c508
+.set_carry
 	scf
 	ret
 
-Func_1c50a: ; 1c50a (7:450a)
+UnloadNPC: ; 1c50a (7:450a)
 	push hl
-	call Func_1c719
+	call UpdateNPCsTilePermission
 	ld a, [wLoadedNPCTempIndex]
 	call GetLoadedNPCID
 	ld a, [hl]
 	or a
-	jr z, .asm_1c52c
-	call Func_1c4fa
-	jr nc, .asm_1c521
-	xor a
-	ld [wd3b8], a
+	jr z, .exit
+	call CheckIfNPCIsRonald
+	jr nc, .not_ronald
+	xor a ; FALSE
+	ld [wRonaldIsInMap], a
+.not_ronald
 
-.asm_1c521
 	xor a
 	ld [hli], a
 	ld a, [hl]
-	farcall Func_129fd
-	ld hl, wd349
+	farcall DisableSpriteAnim
+	ld hl, wNumLoadedNPCs
 	dec [hl]
 
-.asm_1c52c
+.exit
 	pop hl
 	ret
 
@@ -239,7 +259,7 @@ Func_1c52e: ; 1c52e (7:452e)
 	push hl
 	push af
 	ld a, [wLoadedNPCTempIndex]
-	ld l, LOADED_NPC_FIELD_07
+	ld l, LOADED_NPC_UNKNOWN
 	call GetItemInLoadedNPCIndex
 	pop af
 	ld [hl], a
@@ -254,7 +274,7 @@ Func_1c53f: ; 1c53f (7:453f)
 	ld l, LOADED_NPC_DIRECTION
 	call GetItemInLoadedNPCIndex
 	ld a, [hl]
-	ld bc, $0003
+	ld bc, LOADED_NPC_UNKNOWN - LOADED_NPC_DIRECTION
 	add hl, bc
 	ld [hl], a
 	push af
@@ -288,21 +308,22 @@ Func_1c557: ; 1c557 (7:4557)
 	pop bc
 	ret
 
-Func_1c57b: ; 1c57b (7:457b)
+; a = NPC animation
+SetNPCAnimation: ; 1c57b (7:457b)
 	push hl
 	push bc
 	push af
 	ld a, [wLoadedNPCTempIndex]
-	ld l, LOADED_NPC_FIELD_06
+	ld l, LOADED_NPC_ANIM
 	call GetItemInLoadedNPCIndex
 	pop af
 	ld [hl], a
-	call Func_1c58e
+	call UpdateNPCAnimation
 	pop bc
 	pop hl
 	ret
 
-Func_1c58e: ; 1c58e (7:458e)
+UpdateNPCAnimation: ; 1c58e (7:458e)
 	push hl
 	push bc
 	ld a, [wWhichSprite]
@@ -314,13 +335,13 @@ Func_1c58e: ; 1c58e (7:458e)
 	jr z, .quit
 	ld a, [hl]
 	ld [wWhichSprite], a
-	ld bc, LOADED_NPC_FIELD_06 - LOADED_NPC_SPRITE
+	ld bc, LOADED_NPC_ANIM - LOADED_NPC_SPRITE
 	add hl, bc
-	ld a, [hld]
-	bit 4, [hl]
+	ld a, [hld] ; LOADED_NPC_ANIM
+	bit NPC_FLAG_DIRECTIONLESS_F, [hl] ; LOADED_NPC_FLAGS
 	jr nz, .asm_1c5ae
 	dec hl
-	add [hl]
+	add [hl] ; LOADED_NPC_ANIM + LOADED_NPC_DIRECTION
 	inc hl
 .asm_1c5ae
 	farcall StartNewSpriteAnimation
@@ -330,36 +351,250 @@ Func_1c58e: ; 1c58e (7:458e)
 	pop bc
 	pop hl
 	ret
+; 0x1c5b9
 
-Func_1c5b9: ; 1c5b9 (7:45b9)
-	INCROM $1c5b9, $1c5e9
+; if NPC's sprite has an animation,
+; give it a random initial value
+; this makes it so that all NPCs are out of phase
+; when they are loaded into a map
+ApplyRandomCountToNPCAnim: ; 1c5b9 (7:45b9)
+	push hl
+	push bc
+	ld a, [wWhichSprite]
+	push af
+	ld a, [wLoadedNPCTempIndex]
+	call GetLoadedNPCID
+	ld a, [hli]
+	or a
+	jr z, .done
+	ld a, [hl]
+	ld [wWhichSprite], a
+	ld c, SPRITE_ANIM_COUNTER
+	call GetSpriteAnimBufferProperty
+	ld a, [hl]
+	or a
+	jr z, .done
+	cp $ff
+	jr z, .done
+	dec a
+	call Random
+	ld c, a
+	ld a, [hl]
+	sub c
+	ld [hl], a
+.done
+	pop af
+	ld [wWhichSprite], a
+	pop bc
+	pop hl
+	ret
+; 0x1c5e9
 
+; sets the loaded NPC's direction
+; to the direction that is in LOADED_NPC_UNKNOWN
 Func_1c5e9: ; 1c5e9 (7:45e9)
 	push hl
 	push bc
 	ld a, [wLoadedNPCTempIndex]
-	ld l, LOADED_NPC_FIELD_07
+	ld l, LOADED_NPC_UNKNOWN
 	call GetItemInLoadedNPCIndex
 	ld a, [hl]
-	ld bc, -3
+	ld bc, LOADED_NPC_DIRECTION - LOADED_NPC_UNKNOWN
 	add hl, bc
 	ld [hl], a
-	call Func_1c58e
+	call UpdateNPCAnimation
 	pop bc
 	pop hl
 	ret
 ; 0x1c5ff
 
-Func_1c5ff: ; 1c5ff (7:45ff)
-	INCROM $1c5ff, $1c610
+; a = new direction
+SetNPCDirection: ; 1c5ff (7:45ff)
+	push hl
+	push af
+	ld a, [wLoadedNPCTempIndex]
+	ld l, LOADED_NPC_DIRECTION
+	call GetItemInLoadedNPCIndex
+	pop af
+	ld [hl], a
+	call UpdateNPCAnimation
+	pop hl
+	ret
+; 0x1c610
 
-Func_1c610: ; 1c610 (7:4610)
-	INCROM $1c610, $1c665
+HandleAllNPCMovement: ; 1c610 (7:4610)
+	push hl
+	push bc
+	push de
+	xor a
+	ld [wIsAnNPCMoving], a
+	ld a, [wNumLoadedNPCs]
+	or a
+	jr z, .exit
 
-Func_1c665: ; 1c665 (7:4665)
-	INCROM $1c665, $1c6e3
+	ld c, LOADED_NPC_MAX
+	ld hl, wLoadedNPCs
+	ld de, LOADED_NPC_LENGTH
+.loop_npcs
+	ld a, [hl]
+	or a
+	jr z, .next_npc
+	push bc
+	inc hl
+	ld a, [hld]
+	ld [wWhichSprite], a
+	call UpdateNPCMovementStep
+	call .UpdateSpriteAnimFlag
+	call UpdateNPCSpritePosition
+	call UpdateIsAnNPCMovingFlag
+	pop bc
+.next_npc
+	add hl, de
+	dec c
+	jr nz, .loop_npcs
+.exit
+	pop de
+	pop bc
+	pop hl
+	ret
 
-Func_1c6e3: ; 1c6e3 (7:46e3)
+.UpdateSpriteAnimFlag
+	push hl
+	push bc
+	ld bc, LOADED_NPC_COORD_X
+	add hl, bc
+	ld b, [hl]
+	inc hl
+	ld c, [hl]
+	call GetPermissionOfMapPosition
+	and $10
+	push af
+	ld c, SPRITE_ANIM_FLAGS
+	call GetSpriteAnimBufferProperty
+	pop af
+	ld a, [hl]
+	jr z, .reset_flag
+	set SPRITE_ANIM_FLAG_UNSKIPPABLE, [hl]
+	jr .done
+.reset_flag
+	res SPRITE_ANIM_FLAG_UNSKIPPABLE, [hl]
+.done
+	pop bc
+	pop hl
+	ret
+; 0x1c665
+
+UpdateNPCSpritePosition: ; 1c665 (7:4665)
+	push hl
+	push bc
+	push de
+	call .GetOffset
+
+	; get NPC and sprite coords
+	push bc
+	ld de, LOADED_NPC_COORD_X
+	add hl, de
+	ld e, l
+	ld d, h
+	ld c, SPRITE_ANIM_COORD_X
+	call GetSpriteAnimBufferProperty
+	pop bc
+
+	; hl = sprite coords
+	; de = NPC coords
+	ld a, [de] ; x
+	sla a
+	sla a
+	sla a
+	add $8
+	sub b
+	ld [hli], a
+	inc de
+	ld a, [de] ; y
+	sla a
+	sla a
+	sla a
+	add $10
+	sub c
+	ld [hli], a
+	pop de
+	pop bc
+	pop hl
+	ret
+
+; outputs in bc the coordinate offsets
+; given NPCs direction and its movement step
+.GetOffset
+	push hl
+	ld bc, $0
+	ld de, LOADED_NPC_FLAGS
+	add hl, de
+	ld e, 0
+	ld a, [hl]
+	and NPC_FLAG_MOVING
+	jr z, .got_direction
+	dec hl
+	ld a, [hl] ; LOADED_NPC_DIRECTION
+	ld de, LOADED_NPC_MOVEMENT_STEP - LOADED_NPC_DIRECTION
+	add hl, de
+	ld e, [hl] ; LOADED_NPC_MOVEMENT_STEP
+.got_direction
+	ld hl, .function_table
+	call JumpToFunctionInTable
+	pop hl
+	ret
+
+.function_table
+	dw .north
+	dw .east
+	dw .south
+	dw .west
+
+.west
+	ld a, e
+	cpl
+	inc a
+	ld e, a
+.east
+	ld b, e
+	ldh a, [hSCX]
+	sub b
+	ld b, a
+	ldh a, [hSCY]
+	ld c, a
+	ret
+
+.north
+	ld a, e
+	cpl
+	inc a
+	ld e, a
+.south
+	ld c, e
+	ldh a, [hSCY]
+	sub c
+	ld c, a
+	ldh a, [hSCX]
+	ld b, a
+	ret
+; 0x1c6d3
+
+; ands wIsAnNPCMoving with the current
+; NPC's NPC_FLAG_MOVING_F
+UpdateIsAnNPCMovingFlag: ; 1c6d3 (7:46d3)
+	push hl
+	push bc
+	ld bc, LOADED_NPC_FLAGS
+	add hl, bc
+	ld a, [wIsAnNPCMoving]
+	or [hl]
+	ld [wIsAnNPCMoving], a
+	pop bc
+	pop hl
+	ret
+; 0x1c6e3
+
+SetNPCsTilePermission: ; 1c6e3 (7:46e3)
 	push hl
 	push bc
 	ld a, [wLoadedNPCTempIndex]
@@ -374,10 +609,33 @@ Func_1c6e3: ; 1c6e3 (7:46e3)
 	pop hl
 	ret
 
-Func_1c6f8: ; 1c6f8 (7:46f8)
-	INCROM $1c6f8, $1c719
+SetAllNPCTilePermissions: ; 1c6f8 (7:46f8)
+	push hl
+	push bc
+	push de
+	ld b, $00
+	ld c, LOADED_NPC_MAX
+	ld hl, wLoadedNPCs
+	ld de, LOADED_NPC_LENGTH
+.loop_npcs
+	ld a, [hl]
+	or a
+	jr z, .next_npc
+	ld a, b
+	ld [wLoadedNPCTempIndex], a
+	call SetNPCsTilePermission
+.next_npc
+	add hl, de
+	inc b
+	dec c
+	jr nz, .loop_npcs
+	pop de
+	pop bc
+	pop hl
+	ret
+; 0x1c719
 
-Func_1c719: ; 1c719 (7:4719)
+UpdateNPCsTilePermission: ; 1c719 (7:4719)
 	push hl
 	push bc
 	ld a, [wLoadedNPCTempIndex]
@@ -452,7 +710,7 @@ SetNewScriptNPC: ; 1c768 (7:4768)
 	ld a, [wPlayerDirection]
 	xor $02
 	ld [hl], a
-	call Func_1c58e
+	call UpdateNPCAnimation
 	ld a, $02
 	farcall Func_c29b
 	ld a, [wLoadedNPCTempIndex]
@@ -462,103 +720,196 @@ SetNewScriptNPC: ; 1c768 (7:4768)
 	pop hl
 	ret
 
-Func_1c78d: ; 1c78d (7:478d)
+StartNPCMovement: ; 1c78d (7:478d)
 	push hl
+; set NPC as moving
 	ld a, [wLoadedNPCTempIndex]
-	ld l, LOADED_NPC_FIELD_05
+	ld l, LOADED_NPC_FLAGS
 	call GetItemInLoadedNPCIndex
-	set 5, [hl]
+	set NPC_FLAG_MOVING_F, [hl]
+
+; reset its movement step
 	ld a, [wLoadedNPCTempIndex]
-	ld l, LOADED_NPC_FIELD_08
+	ld l, LOADED_NPC_MOVEMENT_STEP
 	call GetItemInLoadedNPCIndex
 	xor a
 	ld [hli], a
-.asm_1c7a2
-	ld [hl], c
+.loop_movement
+	ld [hl], c ; LOADED_NPC_MOVEMENT_PTR
 	inc hl
 	ld [hl], b
 	dec hl
 	call GetNextNPCMovementByte
 	cp $f0
-	jr nc, .asm_1c7bb
+	jr nc, .special_command
 	push af
-	and $7f
-	call Func_1c5ff
+	and DIRECTION_MASK
+	call SetNPCDirection
 	pop af
+	; if it was not a rotation, exit...
 	bit 7, a
-	jr z, .asm_1c7dc
+	jr z, .exit
+	; ...otherwise jump to next movement instruction
 	inc bc
-	jr .asm_1c7a2
+	jr .loop_movement
 
-.asm_1c7bb
+.special_command
 	cp $ff
-	jr z, .asm_1c7d2
+	jr z, .stop_movement
+; jump to a movement command
+	; read its argument
 	inc bc
 	call GetNextNPCMovementByte
 	push hl
 	ld l, a
 	ld h, $0
 	bit 7, l
-	jr z, .asm_1c7cc
-	dec h
-
-.asm_1c7cc
+	jr z, .got_offset
+	dec h ; $ff
+.got_offset
+	; add the offset to bc
 	add hl, bc
 	ld c, l
 	ld b, h
 	pop hl
-	jr .asm_1c7a2
+	jr .loop_movement
 
-.asm_1c7d2
+.stop_movement
 	ld a, [wLoadedNPCTempIndex]
-	ld l, LOADED_NPC_FIELD_05
+	ld l, LOADED_NPC_FLAGS
 	call GetItemInLoadedNPCIndex
-	res 5, [hl]
+	res NPC_FLAG_MOVING_F, [hl]
 
-.asm_1c7dc
+.exit
 	pop hl
 	ret
 
-Func_1c7de: ; 1c7de (7:47de)
-	ld a, [wc3b7]
-	and $20
+; returns nz if there is an NPC currently moving
+CheckIsAnNPCMoving: ; 1c7de (7:47de)
+	ld a, [wIsAnNPCMoving]
+	and NPC_FLAG_MOVING
 	ret
 ; 0x1c7e4
 
-	INCROM $1c7e4, $1c82e
+; while the NPC is moving, increment its movement step by 1
+; once it reaches a value greater than 16, update
+; its tile permission and its position and start next movement
+UpdateNPCMovementStep: ; 1c7e4 (7:47e4)
+	push hl
+	push bc
+	push de
+	ld bc, LOADED_NPC_FLAGS
+	add hl, bc
+	bit NPC_FLAG_MOVING_F, [hl]
+	jr z, .exit
+	ld bc, LOADED_NPC_MOVEMENT_STEP - LOADED_NPC_FLAGS
+	add hl, bc
+	inc [hl] ; increment movement step
+	bit 4, [hl]
+	jr z, .exit ; still hasn't reached the next tile
+	call UpdateNPCsTilePermission
+	call UpdateNPCPosition
+	inc hl
+	ld c, [hl] ; LOADED_NPC_MOVEMENT_PTR
+	inc hl
+	ld b, [hl]
+	inc bc
+	call StartNPCMovement
+	call SetNPCsTilePermission
+.exit
+	pop de
+	pop bc
+	pop hl
+	ret
+; 0x1c80d
+
+UpdateNPCPosition: ; 1c80d (7:480d)
+	push hl
+	push bc
+	ld a, [wLoadedNPCTempIndex]
+	ld l, LOADED_NPC_DIRECTION
+	call GetItemInLoadedNPCIndex
+	ld a, [hld]
+	push hl
+	rlca ; *2
+	ld c, a
+	ld b, $00
+	ld hl, PlayerMovementOffsetTable_Tiles
+	add hl, bc
+	ld b, [hl] ; x offset
+	inc hl
+	ld c, [hl] ; y offset
+	pop hl
+	ld a, [hl] ; LOADED_NPC_COORD_Y
+	add c
+	ld [hld], a
+	ld a, [hl] ; LOADED_NPC_COORD_X
+	add b
+	ld [hl], a
+	pop bc
+	pop hl
+	ret
+; 0x1c82e
 
-Func_1c82e: ; 1c82e (7:482e)
-	INCROM $1c82e, $1c83d
+ClearMasterBeatenList: ; 1c82e (7:482e)
+	push hl
+	push bc
+	ld c, $a
+	ld hl, wMastersBeatenList
+	xor a
+.loop
+	ld [hli], a
+	dec c
+	jr nz, .loop
+	pop bc
+	pop hl
+	ret
+; 0x1c83d
 
-Func_1c83d: ; 1c83d (7:483d)
+; writes Master in register a to
+; first empty slot in wMastersBeatenList
+AddMasterBeatenToList: ; 1c83d (7:483d)
 	push hl
 	push bc
 	ld b, a
 	ld c, $a
-	ld hl, wd3bb
-.asm_1c845
+	ld hl, wMastersBeatenList
+.loop
 	ld a, [hl]
 	or a
-	jr z, .asm_1c853
+	jr z, .found_empty_slot
 	cp b
-	jr z, .asm_1c855
+	jr z, .exit
 	inc hl
 	dec c
-	jr nz, .asm_1c845
+	jr nz, .loop
 	debug_nop
-	jr .asm_1c855
+	jr .exit
 
-.asm_1c853
+.found_empty_slot
 	ld a, b
 	ld [hl], a
 
-.asm_1c855
+.exit
 	pop bc
 	pop hl
 	ret
 
-Func_1c858: ; 1c858 (7:4858)
-	INCROM $1c858, $1c8bc
+; iterates all masters and attempts to
+; add each of them to wMastersBeatenList
+AddAllMastersToMastersBeatenList: ; 1c858 (7:4858)
+	ld a, $01
+.loop
+	push af
+	call AddMasterBeatenToList
+	pop af
+	inc a
+	cp $0b
+	jr c, .loop
+	ret
+; 0x1c865
+
+	INCROM $1c865, $1c8bc
 
 Func_1c8bc: ; 1c8bc (7:48bc)
 	push hl
@@ -962,7 +1313,7 @@ Func_1cac5: ; 1cac5 (7:4ac5)
 	farcall GetSpriteAnimCounter
 	cp $ff
 	jr nz, .next
-	farcall Func_129fa
+	farcall DisableCurSpriteAnim
 	ld a, $ff
 	ld [hl], a
 
@@ -1019,7 +1370,7 @@ Func_1cb18: ; 1cb18 (7:4b18)
 	cp $ff
 	jr z, .asm_1cb4b
 	ld [wWhichSprite], a
-	farcall Func_129fa
+	farcall DisableCurSpriteAnim
 	ld a, $ff
 	ld [hl], a
 .asm_1cb4b
@@ -1589,7 +1940,23 @@ Func_1d078: ; 1d078 (7:5078)
 	ret
 
 Func_1d0fa: ; 1d0fa (7:50fa)
-	INCROM $1d0fa, $1d11c
+	farcall Func_11320
+	ld a, $01
+	jr c, .asm_1d104
+	ld a, $00
+.asm_1d104
+	ld [wd624], a
+	cp $00
+	jr z, .asm_1d114
+	bank1call ValidateSavedNonLinkDuelData
+	ld a, $01
+	jr nc, .asm_1d114
+	ld a, $00
+.asm_1d114
+	ld [wd625], a
+	farcall Func_11320
+	ret
+; 0x1d11c
 
 Func_1d11c: ; 1d11c (7:511c)
 	ld a, MUSIC_PC_MAIN_MENU
@@ -1708,7 +2075,7 @@ Credits_1d6ad: ; 1d6ad (7:56ad)
 	ld a, MUSIC_STOP
 	call PlaySong
 	call Func_1d705
-	call Func_1c858
+	call AddAllMastersToMastersBeatenList
 	xor a
 	ld [wOWMapEvents + 1], a
 	ld a, MUSIC_CREDITS
diff --git a/src/engine/home.asm b/src/engine/home.asm
index 0b60609..dc95294 100644
--- a/src/engine/home.asm
+++ b/src/engine/home.asm
@@ -10600,9 +10600,9 @@ OverworldDoFrameFunction: ; 380e (0:380e)
 	call BankswitchROM
 	call SetScreenScrollWram
 	call Func_c554
-	ld a, BANK(Func_1c610)
+	ld a, BANK(HandleAllNPCMovement)
 	call BankswitchROM
-	call Func_1c610
+	call HandleAllNPCMovement
 	call Func_3cb4
 	ld a, BANK(DoLoadedFramesetSubgroupsFrame)
 	call BankswitchROM
@@ -10948,9 +10948,11 @@ PlayDefaultSong: ; 39fc (0:39fc)
 
 ; returns [wDefaultSong] or MUSIC_RONALD in a
 GetDefaultSong: ; 3a1f (0:3a1f)
-	ld a, [wd3b8]
+	ld a, [wRonaldIsInMap]
 	or a
 	jr z, .default_song
+	; only return Ronald's theme if it's
+	; not in one of the following maps
 	ld a, [wOverworldMapSelection]
 	cp OWMAP_ISHIHARAS_HOUSE
 	jr z, .default_song