commented movement stuff

7 files changed, 206 insertions, 163 deletions

diff --git a/engine/overworld/movement.asm b/engine/overworld/movement.asm
index 0cbb7f1c..5b9f878d 100644
--- a/engine/overworld/movement.asm
+++ b/engine/overworld/movement.asm
@@ -12,7 +12,7 @@ UpdatePlayerSprite: ; 4e31 (1:4e31)
 ; the maximum number for map tiles
 .checkIfTextBoxInFrontOfSprite
 	aCoord 8, 9
-	ld [$ff93], a
+	ld [hTilePlayerStandingOn], a
 	cp $60
 	jr c, .lowerLeftTileIsMapTile
 .disableSprite
@@ -21,52 +21,54 @@ UpdatePlayerSprite: ; 4e31 (1:4e31)
 	ret
 .lowerLeftTileIsMapTile
 	call DetectCollisionBetweenSprites
-	ld h, $c1
+	ld h, wSpriteStateData1 / $100
 	ld a, [wWalkCounter]
 	and a
-	jr nz, .asm_4e90
+	jr nz, .moving
 	ld a, [wd528]
+; check if down
 	bit 2, a
-	jr z, .notDown
+	jr z, .checkIfUp
 	xor a ; ld a, SPRITE_FACING_DOWN
-	jr .done
-.notDown
+	jr .next
+.checkIfUp
 	bit 3, a
-	jr z, .notUp
+	jr z, .checkIfLeft
 	ld a, SPRITE_FACING_UP
-	jr .done
-.notUp
+	jr .next
+.checkIfLeft
 	bit 1, a
-	jr z, .notLeft
+	jr z, .checkIfRight
 	ld a, SPRITE_FACING_LEFT
-	jr .done
-.notLeft
+	jr .next
+.checkIfRight
 	bit 0, a
-	jr z, .notRight
+	jr z, .notMoving
 	ld a, SPRITE_FACING_RIGHT
-	jr .done
-.notRight
+	jr .next
+.notMoving
+; zero the animation counters
 	xor a
 	ld [wSpriteStateData1 + 7], a
 	ld [wSpriteStateData1 + 8], a
-	jr .asm_4eab
-.done
-	ld [wSpriteStateData1 + 9], a
+	jr .calcImageIndex
+.next
+	ld [wSpriteStateData1 + 9], a ; facing direction
 	ld a, [wFontLoaded]
 	bit 0, a
-	jr nz, .notRight
-.asm_4e90
+	jr nz, .notMoving
+.moving
 	ld a, [wd736]
-	bit 7, a
-	jr nz, .asm_4eb6
+	bit 7, a ; is the player sprite spinning due to a spin tile?
+	jr nz, .skipSpriteAnim
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $7
 	ld l, a
 	ld a, [hl]
 	inc a
 	ld [hl], a
-	cp $4
-	jr nz, .asm_4eab
+	cp 4
+	jr nz, .calcImageIndex
 	xor a
 	ld [hl], a
 	inc hl
@@ -74,28 +76,32 @@ UpdatePlayerSprite: ; 4e31 (1:4e31)
 	inc a
 	and $3
 	ld [hl], a
-.asm_4eab
+.calcImageIndex
 	ld a, [wSpriteStateData1 + 8]
 	ld b, a
 	ld a, [wSpriteStateData1 + 9]
 	add b
 	ld [wSpriteStateData1 + 2], a
-.asm_4eb6
-	ld a, [$ff93]
+.skipSpriteAnim
+; If the player is standing on a grass tile, make the player's sprite have
+; lower priority than the background so that it's partially obscured by the
+; grass. Only the lower half of the sprite is permitted to have the priority
+; bit set by later logic.
+	ld a, [hTilePlayerStandingOn]
 	ld c, a
 	ld a, [W_GRASSTILE]
 	cp c
 	ld a, $0
-	jr nz, .asm_4ec3
+	jr nz, .next2
 	ld a, $80
-.asm_4ec3
+.next2
 	ld [wSpriteStateData2 + $07], a
 	ret
 
-Func_4ec7: ; 4ec7 (1:4ec7)
+UnusedReadSpriteDataFunction: ; 4ec7 (1:4ec7)
 	push bc
 	push af
-	ld a, [$ffda]
+	ld a, [H_CURRENTSPRITEOFFSET]
 	ld c, a
 	pop af
 	add c
@@ -103,7 +109,7 @@ Func_4ec7: ; 4ec7 (1:4ec7)
 	pop bc
 	ret
 
-Func_4ed1: ; 4ed1 (1:4ed1)
+UpdateNPCSprite: ; 4ed1 (1:4ed1)
 	ld a, [H_CURRENTSPRITEOFFSET]
 	swap a
 	dec a
@@ -148,40 +154,43 @@ Func_4ed1: ; 4ed1 (1:4ed1)
 	ld l, a
 	ld a, [hl]       ; c2x6: movement byte 1
 	inc a
-	jr z, .asm_4f59  ; value $FF
+	jr z, .randomMovement  ; value $FF
 	inc a
-	jr z, .asm_4f59  ; value $FE
+	jr z, .randomMovement  ; value $FE
+; scripted movement
 	dec a
-	ld [hl], a       ; (temporarily) increment movement byte 1
+	ld [hl], a       ; increment movement byte 1 (movement data index)
 	dec a
 	push hl
 	ld hl, wcf0f
 	dec [hl]         ; decrement wcf0f
 	pop hl
-	ld de, wcc5b
-	call LoadDEPlusA ; a = [wcc5b + movement byte 1]
+	ld de, wNPCMovementDirections
+	call LoadDEPlusA ; a = [wNPCMovementDirections + movement byte 1]
 	cp $e0
 	jp z, ChangeFacingDirection
 	cp $ff
-	jr nz, .asm_4f4b
-	ld [hl], a       ; reset movement byte 1 to initial value
+	jr nz, .next
+; reached end of wNPCMovementDirections list
+	ld [hl], a ; store $ff in movement byte 1, disabling scripted movement
 	ld hl, wd730
 	res 0, [hl]
 	xor a
 	ld [wSimulatedJoypadStatesIndex], a
 	ld [wWastedByteCD3A], a
 	ret
-.asm_4f4b
+.next
 	cp $fe
-	jr nz, .asm_4f5f
+	jr nz, .determineDirection
+; current NPC movement data is $fe. this seems buggy
 	ld [hl], $1     ; set movement byte 1 to $1
-	ld de, wcc5b
-	call LoadDEPlusA ; a = [wcc5b + $fe] (?)
-	jr .asm_4f5f
-.asm_4f59
+	ld de, wNPCMovementDirections
+	call LoadDEPlusA ; a = [wNPCMovementDirections + $fe] (?)
+	jr .determineDirection
+.randomMovement
 	call getTileSpriteStandsOn
 	call Random
-.asm_4f5f
+.determineDirection
 	ld b, a
 	ld a, [wCurSpriteMovement2]
 	cp $d0
@@ -199,7 +208,7 @@ Func_4ed1: ; 4ed1 (1:4ed1)
 	cp $2
 	jr z, .moveLeft    ; movement byte 2 = $2 only allows left or right
 .moveDown
-	ld de, 2*20
+	ld de, 2*SCREEN_WIDTH
 	add hl, de         ; move tile pointer two rows down
 	ld de, $100
 
@@ -212,7 +221,7 @@ Func_4ed1: ; 4ed1 (1:4ed1)
 	cp $2
 	jr z, .moveRight   ; movement byte 2 = $2 only allows left or right
 .moveUp
-	ld de, -2*20
+	ld de, -2*SCREEN_WIDTH
 	add hl, de         ; move tile pointer two rows up
 	ld de, $ff00
 	ld bc, $804
@@ -249,7 +258,7 @@ ChangeFacingDirection: ; 4fc8 (1:4fc8)
 ; c: new facing direction (0,4,8 or $c)
 ; d: Y movement delta (-1, 0 or 1)
 ; e: X movement delta (-1, 0 or 1)
-; hl: pointer to tile the sprite would wlak onto
+; hl: pointer to tile the sprite would walk onto
 ; set carry on failure, clears carry on success
 TryWalking: ; 4fcb (1:4fcb)
 	push hl
@@ -470,7 +479,7 @@ CheckSpriteAvailability: ; 50dc (1:50dc)
 	ld l, a
 	ld a, [hl]      ; c2x6: movement byte 1
 	cp $fe
-	jr c, .skipXVisibilityTest ; movement byte 1 < $fe
+	jr c, .skipXVisibilityTest ; movement byte 1 < $fe (i.e. the sprite's movement is scripted)
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $4
 	ld l, a
@@ -572,10 +581,11 @@ CanWalkOntoTile: ; 516e (1:516e)
 	ld l, a
 	ld a, [hl]         ; c2x6 (movement byte 1)
 	cp $fe
-	jr nc, .canMove    ; values $fe and $ff
+	jr nc, .notScripted    ; values $fe and $ff
+; always allow walking if the movement is scripted
 	and a
 	ret
-.canMove
+.notScripted
 	ld a, [W_TILESETCOLLISIONPTR]
 	ld l, a
 	ld a, [W_TILESETCOLLISIONPTR+1]
@@ -713,53 +723,54 @@ LoadDEPlusA: ; 522f (1:522f)
 	ld a, [de]
 	ret
 
-Func_5236: ; 5236 (1:5236)
+DoScriptedNPCMovement: ; 5236 (1:5236)
 	ld a, [wd730]
 	bit 7, a
 	ret z
 	ld hl, wd72e
 	bit 7, [hl]
 	set 7, [hl]
-	jp z, Func_52a6
+	jp z, InitScriptedNPCMovement
 	ld hl, wNPCMovementDirections2
 	ld a, [wNPCMovementDirections2Index]
 	add l
 	ld l, a
-	jr nc, .asm_5251
+	jr nc, .noCarry
 	inc h
-.asm_5251
+.noCarry
 	ld a, [hl]
+; check if moving up
 	cp $40
-	jr nz, .asm_525f
-	call Func_52b2
-	ld c, $4
-	ld a, $fe
-	jr .asm_5289
-.asm_525f
+	jr nz, .checkIfMovingDown
+	call GetSpriteScreenYPointer
+	ld c, SPRITE_FACING_UP
+	ld a, -2
+	jr .move
+.checkIfMovingDown
 	cp $0
-	jr nz, .asm_526c
-	call Func_52b2
-	ld c, $0
-	ld a, $2
-	jr .asm_5289
-.asm_526c
+	jr nz, .checkIfMovingLeft
+	call GetSpriteScreenYPointer
+	ld c, SPRITE_FACING_DOWN
+	ld a, 2
+	jr .move
+.checkIfMovingLeft
 	cp $80
-	jr nz, .asm_5279
-	call Func_52b7
-	ld c, $8
-	ld a, $fe
-	jr .asm_5289
-.asm_5279
+	jr nz, .checkIfMovingRight
+	call GetSpriteScreenXPointer
+	ld c, SPRITE_FACING_LEFT
+	ld a, -2
+	jr .move
+.checkIfMovingRight
 	cp $c0
-	jr nz, .asm_5286
-	call Func_52b7
-	ld c, $c
-	ld a, $2
-	jr .asm_5289
-.asm_5286
+	jr nz, .noMatch
+	call GetSpriteScreenXPointer
+	ld c, SPRITE_FACING_RIGHT
+	ld a, 2
+	jr .move
+.noMatch
 	cp $ff
 	ret
-.asm_5289
+.move
 	ld b, a
 	ld a, [hl]
 	add b
@@ -768,8 +779,8 @@ Func_5236: ; 5236 (1:5236)
 	add $9
 	ld l, a
 	ld a, c
-	ld [hl], a
-	call Func_52c3
+	ld [hl], a ; facing direction
+	call AnimScriptedNPCMovement
 	ld hl, wcf18
 	dec [hl]
 	ret nz
@@ -779,22 +790,23 @@ Func_5236: ; 5236 (1:5236)
 	inc [hl]
 	ret
 
-Func_52a6: ; 52a6 (1:52a6)
+InitScriptedNPCMovement: ; 52a6 (1:52a6)
 	xor a
 	ld [wNPCMovementDirections2Index], a
 	ld a, $8
 	ld [wcf18], a
-	jp Func_52c3
+	jp AnimScriptedNPCMovement
 
-Func_52b2: ; 52b2 (1:52b2)
+GetSpriteScreenYPointer: ; 52b2 (1:52b2)
 	ld a, $4
 	ld b, a
-	jr asm_52ba
+	jr GetSpriteScreenXYPointerCommon
 
-Func_52b7: ; 52b7 (1:52b7)
+GetSpriteScreenXPointer: ; 52b7 (1:52b7)
 	ld a, $6
 	ld b, a
-asm_52ba: ; 52ba (1:52ba)
+
+GetSpriteScreenXYPointerCommon: ; 52ba (1:52ba)
 	ld hl, wSpriteStateData1
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add l
@@ -802,12 +814,12 @@ asm_52ba: ; 52ba (1:52ba)
 	ld l, a
 	ret
 
-Func_52c3: ; 52c3 (1:52c3)
+AnimScriptedNPCMovement: ; 52c3 (1:52c3)
 	ld hl, wSpriteStateData2
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $e
 	ld l, a
-	ld a, [hl]
+	ld a, [hl] ; VRAM slot
 	dec a
 	swap a
 	ld b, a
@@ -815,47 +827,47 @@ Func_52c3: ; 52c3 (1:52c3)
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $9
 	ld l, a
-	ld a, [hl]
-	cp $0
-	jr z, .asm_52ea
-	cp $4
-	jr z, .asm_52ea
-	cp $8
-	jr z, .asm_52ea
-	cp $c
-	jr z, .asm_52ea
+	ld a, [hl] ; facing direction
+	cp SPRITE_FACING_DOWN
+	jr z, .anim
+	cp SPRITE_FACING_UP
+	jr z, .anim
+	cp SPRITE_FACING_LEFT
+	jr z, .anim
+	cp SPRITE_FACING_RIGHT
+	jr z, .anim
 	ret
-.asm_52ea
+.anim
 	add b
 	ld b, a
-	ld [$ffe9], a
-	call Func_5301
+	ld [hSpriteVRAMSlotAndFacing], a
+	call AdvanceScriptedNPCAnimFrameCounter
 	ld hl, wSpriteStateData1
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $2
 	ld l, a
-	ld a, [$ffe9]
+	ld a, [hSpriteVRAMSlotAndFacing]
 	ld b, a
-	ld a, [$ffea]
+	ld a, [hSpriteAnimFrameCounter]
 	add b
 	ld [hl], a
 	ret
 
-Func_5301: ; 5301 (1:5301)
+AdvanceScriptedNPCAnimFrameCounter: ; 5301 (1:5301)
 	ld a, [H_CURRENTSPRITEOFFSET]
 	add $7
 	ld l, a
-	ld a, [hl]
+	ld a, [hl] ; intra-animation frame counter
 	inc a
 	ld [hl], a
-	cp $4
+	cp 4
 	ret nz
 	xor a
-	ld [hl], a
+	ld [hl], a ; reset intra-animation frame counter
 	inc l
-	ld a, [hl]
+	ld a, [hl] ; animation frame counter
 	inc a
 	and $3
 	ld [hl], a
-	ld [$ffea], a
+	ld [hSpriteAnimFrameCounter], a
 	ret
diff --git a/engine/overworld/npc_movement.asm b/engine/overworld/npc_movement.asm
index 73a3fdfb..f27df648 100755
--- a/engine/overworld/npc_movement.asm
+++ b/engine/overworld/npc_movement.asm
@@ -63,7 +63,7 @@ Func_1a44c: ; 1a44c (6:644c)
 	call FillMemory
 	ld [hl], $ff
 	ld a, [wSpriteIndex]
-	ld [H_DOWNARROWBLINKCNT2], a
+	ld [H_SPRITEINDEX], a
 	ld de, wNPCMovementDirections2
 	call MoveSprite
 	ld a, $1
diff --git a/engine/overworld/oam.asm b/engine/overworld/oam.asm
index c972ea43..0bd16e1a 100644
--- a/engine/overworld/oam.asm
+++ b/engine/overworld/oam.asm
@@ -4,25 +4,26 @@ PrepareOAMData:
 
 	ld a, [wUpdateSpritesEnabled]
 	dec a
-	jr z, .asm_4b1e
+	jr z, .updateEnabled
 
 	cp 0 - 1
 	ret nz
 	ld [wUpdateSpritesEnabled], a
 	jp HideSprites
 
-.asm_4b1e
+.updateEnabled
 	xor a
-	ld [$ff90], a
-.asm_4b21
-	ld [$ff8f], a
+	ld [hOAMBufferOffset], a
+
+.spriteLoop
+	ld [hSpriteDataOffset2], a
 
 	ld d, wSpriteStateData1 / $100
-	ld a, [$ff8f]
+	ld a, [hSpriteDataOffset2]
 	ld e, a
 	ld a, [de] ; c1x0
 	and a
-	jp z, .asm_4bad
+	jp z, .nextSprite
 
 	inc e
 	inc e
@@ -31,21 +32,25 @@ PrepareOAMData:
 	cp $ff ; off-screen (don't draw)
 	jr nz, .visible
 
-	call Func_4bd1
-	jr .asm_4bad
+	call GetSpriteScreenXY
+	jr .nextSprite
 
 .visible
-	cp $a0
+	cp $a0 ; is the sprite unchanging like an item ball or boulder?
 	jr c, .usefacing
+
+; unchanging
 	and $f
-	add $10
-	jr .asm_4b48
+	add $10 ; skip to the second half of the table which doesn't account for facing direction
+	jr .next
 
 .usefacing
 	and $f
-.asm_4b48
+
+.next
 	ld l, a
 
+; get sprite priority
 	push de
 	inc d
 	ld a, e
@@ -53,15 +58,15 @@ PrepareOAMData:
 	ld e, a
 	ld a, [de] ; c2x7
 	and $80
-	ld [$ff94], a ; temp store sprite priority
+	ld [hSpritePriority], a ; temp store sprite priority
 	pop de
 
+; read the entry from the table
 	ld h, 0
 	ld bc, SpriteFacingAndAnimationTable
 	add hl, hl
 	add hl, hl
 	add hl, bc
-
 	ld a, [hli]
 	ld c, a
 	ld a, [hli]
@@ -70,24 +75,25 @@ PrepareOAMData:
 	ld h, [hl]
 	ld l, a
 
-	call Func_4bd1
+	call GetSpriteScreenXY
 
-	ld a, [$ff90]
+	ld a, [hOAMBufferOffset]
 	ld e, a
 	ld d, wOAMBuffer / $100
-.tile
-	ld a, [$ff92]            ; temp for sprite Y position
+
+.tileLoop
+	ld a, [hSpriteScreenY]   ; temp for sprite Y position
 	add $10                  ; Y=16 is top of screen (Y=0 is invisible)
 	add [hl]                 ; add Y offset from table
 	ld [de], a               ; write new sprite OAM Y position
 	inc hl
-	ld a, [$ff91]            ; temp for sprite X position
+	ld a, [hSpriteScreenX]   ; temp for sprite X position
 	add $8                   ; X=8 is left of screen (X=0 is invisible)
 	add [hl]                 ; add X offset from table
 	inc e
 	ld [de], a               ; write new sprite OAM X position
 	inc e
-	ld a, [bc]               ; read pattern number offset (accomodates orientation (offset 0,4 or 8) and animation (offset 0 or $80))
+	ld a, [bc]               ; read pattern number offset (accommodates orientation (offset 0,4 or 8) and animation (offset 0 or $80))
 	inc bc
 	push bc
 	ld b, a
@@ -99,46 +105,47 @@ PrepareOAMData:
 	; Sprites $a and $b have one face (and therefore 4 tiles instead of 12).
 	; As a result, sprite $b's tile offset is less than normal.
 	cp $b
-	jr nz, .offset
+	jr nz, .notFourTileSprite
 	ld a, $a * 12 + 4
-	jr .gotoffset
+	jr .next2
 
-.offset
+.notFourTileSprite
 	; a *= 12
 	sla a
 	sla a
 	ld c, a
 	sla a
 	add c
-.gotoffset
-	add b ; which frame
+
+.next2
+	add b ; add the tile offset from the table (based on frame and facing direction)
 	pop bc
 	ld [de], a ; tile id
 	inc hl
 	inc e
 	ld a, [hl]
-	bit 1, a ; sprite priority
-	jr z, .fg
-	ld a, [$ff94] ; facing priority
+	bit 1, a ; is the tile allowed to set the sprite priority bit?
+	jr z, .skipPriority
+	ld a, [hSpritePriority]
 	or [hl]
-.fg
+.skipPriority
 	inc hl
 	ld [de], a
 	inc e
 	bit 0, a ; OAMFLAG_ENDOFDATA
-	jr z, .tile
+	jr z, .tileLoop
 
 	ld a, e
-	ld [$ff90], a
+	ld [hOAMBufferOffset], a
 
-.asm_4bad
-	ld a, [$ff8f]
+.nextSprite
+	ld a, [hSpriteDataOffset2]
 	add $10
 	cp $100 % $100
-	jp nz, .asm_4b21
+	jp nz, .spriteLoop
 
 	; Clear unused OAM.
-	ld a, [$ff90]
+	ld a, [hOAMBufferOffset]
 	ld l, a
 	ld h, wOAMBuffer / $100
 	ld de, $4
@@ -159,24 +166,24 @@ PrepareOAMData:
 	add hl, de
 	jr .clear
 
-Func_4bd1: ; 4bd1 (1:4bd1)
+GetSpriteScreenXY: ; 4bd1 (1:4bd1)
 	inc e
 	inc e
 	ld a, [de] ; c1x4
-	ld [$ff92], a
+	ld [hSpriteScreenY], a
 	inc e
 	inc e
 	ld a, [de] ; c1x6
-	ld [$ff91], a
-	ld a, $4
+	ld [hSpriteScreenX], a
+	ld a, 4
 	add e
 	ld e, a
-	ld a, [$ff92]
-	add $4
+	ld a, [hSpriteScreenY]
+	add 4
 	and $f0
 	ld [de], a ; c1xa (y)
 	inc e
-	ld a, [$ff91]
+	ld a, [hSpriteScreenX]
 	and $f0
 	ld [de], a  ; c1xb (x)
 	ret
diff --git a/home.asm b/home.asm
index 608fb8a6..8109c9c4 100644
--- a/home.asm
+++ b/home.asm
@@ -3043,8 +3043,8 @@ CalcDifference:: ; 3633 (0:3633)
 	ret
 
 MoveSprite:: ; 363a (0:363a)
-; move the sprite [$FF8C] with the movement pointed to by de
-; actually only copies the movement data to wcc5b for later
+; move the sprite [H_SPRITEINDEX] with the movement pointed to by de
+; actually only copies the movement data to wNPCMovementDirections for later
 	call SetSpriteMovementBytesToFF
 MoveSprite_:: ; 363d (0:363d)
 	push hl
@@ -3052,7 +3052,7 @@ MoveSprite_:: ; 363d (0:363d)
 	call GetSpriteMovementByte1Pointer
 	xor a
 	ld [hl],a
-	ld hl,wcc5b
+	ld hl,wNPCMovementDirections
 	ld c,0
 
 .loop
diff --git a/hram.asm b/hram.asm
index 401c4b80..55f757ff 100644
--- a/hram.asm
+++ b/hram.asm
@@ -28,6 +28,17 @@ hPartyMonIndex EQU $FF8C
 
 hHalveItemPrices EQU $FF8E
 
+hSpriteDataOffset2 EQU $FF8F
+
+hOAMBufferOffset EQU $FF90
+
+hSpriteScreenX EQU $FF91
+hSpriteScreenY EQU $FF92
+
+hTilePlayerStandingOn EQU $FF93
+
+hSpritePriority EQU $FF94
+
 ; Multiplcation and division variables are meant
 ; to overlap for back-to-back usage. Big endian.
 
@@ -155,6 +166,10 @@ hTilesetType EQU $FFD7
 
 H_CURRENTSPRITEOFFSET EQU $FFDA ; multiple of $10
 
+hSpriteVRAMSlotAndFacing EQU $FFE9
+
+hSpriteAnimFrameCounter EQU $FFEA
+
 H_WHOSETURN EQU $FFF3 ; 0 on player’s turn, 1 on enemy’s turn
 
 ; bit 0: draw HP fraction to the right of bar instead of below (for party menu)
diff --git a/main.asm b/main.asm
index c8907c72..1d288543 100755
--- a/main.asm
+++ b/main.asm
@@ -218,9 +218,9 @@ UpdateNonPlayerSprite:
 	ld a, [H_CURRENTSPRITEOFFSET]
 	cp b
 	jr nz, .unequal
-	jp Func_5236
+	jp DoScriptedNPCMovement
 .unequal
-	jp Func_4ed1
+	jp UpdateNPCSprite
 
 ; This detects if the current sprite (whose offset is at H_CURRENTSPRITEOFFSET)
 ; is going to collide with another sprite by looping over the other sprites.
diff --git a/wram.asm b/wram.asm
index 2cc8d676..4658b84d 100755
--- a/wram.asm
+++ b/wram.asm
@@ -369,6 +369,8 @@ wBoostExpByExpAll:: ; cc5b
 wAnimationType:: ; cc5b
 ; values between 0-6. Shake screen horizontally, shake screen vertically, blink Pokemon...
 
+wNPCMovementDirections:: ; cc5b
+
 wcc5b:: ds 1 ; these upcoming values below are miscellaneous storage values
 wcc5c:: ds 1 ; used in pokedex evaluation as well
 wcc5d:: ds 1 ; used in pokedex evaluation
@@ -1092,7 +1094,10 @@ wcfc9:: ds 1 ; also used with audio
 wcfca:: ds 1 ; also used with audio too
 
 wUpdateSpritesEnabled:: ; cfcb
-; $01 enables UpdateSprites; anything else disables it
+; $00 = causes sprites to be hidden and the value to change to $ff
+; $01 = enabled
+; $ff = disabled
+; other values aren't used
 	ds 1
 
 W_ENEMYMOVENUM:: ; cfcc
@@ -2291,13 +2296,16 @@ wd72c:: ; d72c
 
 wd72d:: ds 1 ; misc temp flags? (in some scripts, bit 6 and 7 set after a special battle (e.g. gym leaders) has been won)
              ; also used as a start menu flag
-wd72e:: ds 2 ; more temp misc flags, used with npc movement, main menu and other stuff
+
+wd72e::
+; bit 7: set if scripted NPC movement has been initialised
+	ds 2 ; more temp misc flags, used with npc movement, main menu and other stuff
 
 wd730::
 ; bit 0: NPC sprite being moved by script
 ; bit 5: ignore joypad input
 ; bit 6: print text with no delay between each letter
-; bit 7: set if joypad states are being simulated in the overworld
+; bit 7: set if joypad states are being simulated in the overworld or an NPC's movement is being scripted
 	ds 1
 
 	ds 1
@@ -2328,6 +2336,7 @@ wd736:: ; d736
 ; bit 1: the player is currently stepping down from a door
 ; bit 2: standing on a warp
 ; bit 6: jumping down a ledge / fishing animation
+; bit 7: player sprite spinning due to spin tiles (Rocket hidehout / Viridian Gym)
 	ds 1
 
 wCompletedInGameTradeFlags:: ; d737