Remove c1x*/c2x* comments, use struct offset constants

constants/map_object_constants.asm

@@ -1,3 +1,43 @@
+; spritestatedata1 struct members (see macros/wram.asm)
+	const_def
+	const SPRITESTATEDATA1_PICTUREID             ; 0
+	const SPRITESTATEDATA1_MOVEMENTSTATUS        ; 1
+	const SPRITESTATEDATA1_IMAGEINDEX            ; 2
+	const SPRITESTATEDATA1_YSTEPVECTOR           ; 3
+	const SPRITESTATEDATA1_YPIXELS               ; 4
+	const SPRITESTATEDATA1_XSTEPVECTOR           ; 5
+	const SPRITESTATEDATA1_XPIXELS               ; 6
+	const SPRITESTATEDATA1_INTRAANIMFRAMECOUNTER ; 7
+	const SPRITESTATEDATA1_ANIMFRAMECOUNTER      ; 8
+	const SPRITESTATEDATA1_FACINGDIRECTION       ; 9
+	const SPRITESTATEDATA1_YADJUSTED             ; a
+	const SPRITESTATEDATA1_XADJUSTED             ; b
+	const SPRITESTATEDATA1_COLLISIONDATA         ; c
+	const SPRITESTATEDATA1_0D                    ; d
+	const SPRITESTATEDATA1_0E                    ; e
+	const SPRITESTATEDATA1_0F                    ; f
+SPRITESTATEDATA1_LENGTH EQU const_value
+
+; spritestatedata2 struct members (see macros/wram.asm)
+	const_def
+	const SPRITESTATEDATA2_WALKANIMATIONCOUNTER ; 0
+	const SPRITESTATEDATA2_01                   ; 1
+	const SPRITESTATEDATA2_YDISPLACEMENT        ; 2
+	const SPRITESTATEDATA2_XDISPLACEMENT        ; 3
+	const SPRITESTATEDATA2_MAPY                 ; 4
+	const SPRITESTATEDATA2_MAPX                 ; 5
+	const SPRITESTATEDATA2_MOVEMENTBYTE1        ; 6
+	const SPRITESTATEDATA2_GRASSPRIORITY        ; 7
+	const SPRITESTATEDATA2_MOVEMENTDELAY        ; 8
+	const SPRITESTATEDATA2_09                   ; 9
+	const SPRITESTATEDATA2_0A                   ; a
+	const SPRITESTATEDATA2_0B                   ; b
+	const SPRITESTATEDATA2_0C                   ; c
+	const SPRITESTATEDATA2_PICTUREID            ; d
+	const SPRITESTATEDATA2_IMAGEBASEOFFSET      ; e
+	const SPRITESTATEDATA2_0F                   ; f
+SPRITESTATEDATA2_LENGTH EQU const_value
+
 ; different kinds of people events
 ITEM    EQU $80
 TRAINER EQU $40

engine/gfx/sprite_oam.asm

@@ -21,13 +21,13 @@ PrepareOAMData::
 	ld d, HIGH(wSpriteStateData1)
 	ldh a, [hSpriteOffset2]
 	ld e, a
-	ld a, [de] ; c1x0
+	ld a, [de] ; [x#SPRITESTATEDATA1_PICTUREID]
 	and a
 	jp z, .nextSprite
 
 	inc e
 	inc e
-	ld a, [de] ; c1x2 (facing/anim)
+	ld a, [de] ; [x#SPRITESTATEDATA1_IMAGEINDEX]
 	ld [wd5cd], a
 	cp $ff ; off-screen (don't draw)
 	jr nz, .visible
@@ -56,7 +56,7 @@ PrepareOAMData::
 	ld a, e
 	add $5
 	ld e, a
-	ld a, [de] ; c2x7
+	ld a, [de] ; [x#SPRITESTATEDATA2_GRASSPRIORITY]
 	and $80
 	ldh [hSpritePriority], a ; temp store sprite priority
 	pop de
@@ -98,7 +98,7 @@ PrepareOAMData::
 	push bc
 	ld b, a
 
-	ld a, [wd5cd]            ; temp copy of c1x2
+	ld a, [wd5cd]            ; temp copy of [x#SPRITESTATEDATA1_IMAGEINDEX]
 	swap a                   ; high nybble determines sprite used (0 is always player sprite, next are some npcs)
 	and $f
 
@@ -169,11 +169,11 @@ PrepareOAMData::
 GetSpriteScreenXY:
 	inc e
 	inc e
-	ld a, [de] ; c1x4
+	ld a, [de] ; [x#SPRITESTATEDATA1_YPIXELS]
 	ldh [hSpriteScreenY], a
 	inc e
 	inc e
-	ld a, [de] ; c1x6
+	ld a, [de] ; [x#SPRITESTATEDATA1_XPIXELS]
 	ldh [hSpriteScreenX], a
 	ld a, 4
 	add e
@@ -181,9 +181,9 @@ GetSpriteScreenXY:
 	ldh a, [hSpriteScreenY]
 	add 4
 	and $f0
-	ld [de], a ; c1xa (y)
+	ld [de], a ; [x#SPRITESTATEDATA1_YADJUSTED]
 	inc e
 	ldh a, [hSpriteScreenX]
 	and $f0
-	ld [de], a  ; c1xb (x)
+	ld [de], a  ; [x#SPRITESTATEDATA1_XADJUSTED]
 	ret

engine/menus/display_text_id_init.asm

@@ -38,7 +38,8 @@ DisplayTextIDInit::
 	jr nz, .skipMovingSprites
 	call UpdateSprites
 .skipMovingSprites
-; loop to copy C1X9 (direction the sprite is facing) to C2X9 for each sprite
+; loop to copy [x#SPRITESTATEDATA1_FACINGDIRECTION] to [x#SPRITESTATEDATA2_09]
+; for each sprite from x=01 to x=15
 ; this is done because when you talk to an NPC, they turn to look your way
 ; the original direction they were facing must be restored after the dialogue is over
 	ld hl, wSprite01StateData1FacingDirection

engine/overworld/map_sprites.asm

@@ -4,20 +4,21 @@
 ; This is also called after displaying text because loading
 ; text tile patterns overwrites half of the sprite tile pattern data.
 ; Note on notation:
-; $C1X* and $C2X* are used to denote wSpriteStateData1-wSpriteStateData1 + $ff and wSpriteStateData2 + $00-wSpriteStateData2 + $ff sprite slot
+; x#SPRITESTATEDATA1_* and x#SPRITESTATEDATA2_* are used to denote wSpriteStateData1 and
-; fields, respectively, within loops. The X is the loop index.
+; wSpriteStateData2 sprite slot, respectively, within loops. The X is the loop index.
-; If there is an inner loop, Y is the inner loop index, i.e. $C1Y* and $C2Y*
+; If there is an inner loop, Y is the inner loop index, i.e. y#SPRITESTATEDATA1_* and
-; denote fields of the sprite slots iterated over in the inner loop.
+; y#SPRITESTATEDATA2_* denote fields of the sprite slots iterated over in the inner loop.
 InitMapSprites::
 	call InitOutsideMapSprites
 	ret c ; return if the map is an outside map (already handled by above call)
 ; if the map is an inside map (i.e. mapID >= $25)
 	ld hl, wSpritePlayerStateData1PictureID
 	ld de, wSpritePlayerStateData2PictureID
-; Loop to copy picture ID's from $C1X0 to $C2XD for LoadMapSpriteTilePatterns.
+; Loop to copy picture IDs from [x#SPRITESTATEDATA1_PICTUREID]
+; to [x#SPRITESTATEDATA2_PICTUREID] for LoadMapSpriteTilePatterns.
 .copyPictureIDLoop
-	ld a, [hl] ; $C1X0 (picture ID)
+	ld a, [hl] ; a = [x#SPRITESTATEDATA1_PICTUREID]
-	ld [de], a ; $C2XD
+	ld [de], a ; [x#SPRITESTATEDATA2_PICTUREID] = a
 	ld a, $10
 	add e
 	ld e, a
@@ -40,9 +41,11 @@ LoadMapSpriteTilePatterns:
 	ld hl, wSpritePlayerStateData2PictureID
 	xor a
 	ldh [hFourTileSpriteCount], a
-.copyPictureIDLoop ; loop to copy picture ID from $C2XD to $C2XE
+; Loop to copy picture IDs from [x#SPRITESTATEDATA2_PICTUREID]
-	ld a, [hli] ; $C2XD (sprite picture ID)
+; to [x#SPRITESTATEDATA2_IMAGEBASEOFFSET].
-	ld [hld], a ; $C2XE
+.copyPictureIDLoop
+	ld a, [hli] ; a = [x#SPRITESTATEDATA2_PICTUREID]
+	ld [hld], a ; [x#SPRITESTATEDATA2_IMAGEBASEOFFSET] = a
 	ld a, l
 	add $10
 	ld l, a
@@ -81,7 +84,7 @@ LoadMapSpriteTilePatterns:
 	ld a, l
 	cp e ; reached current slot?
 	jr z, .foundNextVRAMSlot
-	ld a, [de] ; $C2YE (VRAM slot)
+	ld a, [de] ; y#SPRITESTATEDATA2_IMAGEBASEOFFSET
 	cp 11 ; is it one of the first 10 slots?
 	jr nc, .findNextVRAMSlotLoop
 	cp b ; compare the slot being checked to the current max
@@ -93,7 +96,7 @@ LoadMapSpriteTilePatterns:
 	inc b ; increment previous max value to get next VRAM tile pattern slot
 	ld a, b ; a = next VRAM tile pattern slot
 	push af
-	ld a, [hl] ; $C2XE (sprite picture ID)
+	ld a, [hl] ; [x#SPRITESTATEDATA2_IMAGEBASEOFFSET]
 	ld b, a ; b = current sprite picture ID
 	cp SPRITE_BALL ; is it a 4-tile sprite?
 	jr c, .notFourTileSprite
@@ -104,7 +107,7 @@ LoadMapSpriteTilePatterns:
 .notFourTileSprite
 	pop af
 .storeVRAMSlot
-	ld [hl], a ; store VRAM slot at $C2XE
+	ld [hl], a ; store VRAM slot at [x#SPRITESTATEDATA2_IMAGEBASEOFFSET]
 	ldh [hVRAMSlot], a ; used to determine if it's 4-tile sprite later
 	ld a, b ; a = current sprite picture ID
 	dec a
@@ -207,8 +210,8 @@ LoadMapSpriteTilePatterns:
 	jr .nextSpriteSlot
 .alreadyLoaded ; if the current picture ID has already had its tile patterns loaded
 	inc de
-	ld a, [de] ; a = VRAM slot for the current picture ID (from $C2YE)
+	ld a, [de] ; a = [y#SPRITESTATEDATA2_IMAGEBASEOFFSET]
-	ld [hl], a ; store VRAM slot in current wSpriteStateData2 sprite slot (at $C2XE)
+	ld [hl], a ; [x#SPRITESTATEDATA2_IMAGEBASEOFFSET] = a
 .nextSpriteSlot
 	ld a, l
 	add $10
@@ -217,10 +220,11 @@ LoadMapSpriteTilePatterns:
 	jp nz, .loadTilePatternLoop
 	ld hl, wSpritePlayerStateData2PictureID
 	ld b, $10
-; the pictures ID's stored at $C2XD are no longer needed, so zero them
+; the pictures IDs stored at [x#SPRITESTATEDATA2_PICTUREID] are no longer needed,
+; so zero them
 .zeroStoredPictureIDLoop
 	xor a
-	ld [hl], a ; $C2XD
+	ld [hl], a ; [x#SPRITESTATEDATA2_PICTUREID]
 	ld a, $10
 	add l
 	ld l, a
@@ -292,15 +296,15 @@ InitOutsideMapSprites:
 	ld [hl], a
 	ld bc, wSpriteSet
 ; Load the sprite set into RAM.
-; This loop also fills $C2XD (sprite picture ID) where X is from $0 to $A
+; This loop also fills [x#SPRITESTATEDATA2_PICTUREID] where X is from $0 to $A
-; with picture ID's. This is done so that LoadMapSpriteTilePatterns will
+; with picture IDs. This is done so that LoadMapSpriteTilePatterns will
 ; load tile patterns for all sprite pictures in the sprite set.
 .loadSpriteSetLoop
 	ld a, $10
 	add l
 	ld l, a
 	ld a, [de] ; sprite picture ID from sprite set
-	ld [hl], a ; $C2XD (sprite picture ID)
+	ld [hl], a ; [x#SPRITESTATEDATA2_PICTUREID]
 	ld [bc], a
 	inc de
 	inc bc
@@ -313,7 +317,7 @@ InitOutsideMapSprites:
 	add l
 	ld l, a
 	xor a
-	ld [hl], a ; $C2XD (sprite picture ID)
+	ld [hl], a ; [x#SPRITESTATEDATA2_PICTUREID]
 	dec b
 	jr nz, .zeroRemainingSlotsLoop
 	ld a, [wNumSprites]
@@ -330,7 +334,7 @@ InitOutsideMapSprites:
 ; for the current map. So, they are not needed and are zeroed by this loop.
 .zeroVRAMSlotsLoop
 	xor a
-	ld [hl], a ; $C2XE (VRAM slot)
+	ld [hl], a ; [x#SPRITESTATEDATA2_IMAGEBASEOFFSET]
 	ld a, $10
 	add l
 	ld l, a
@@ -347,7 +351,7 @@ InitOutsideMapSprites:
 ; VRAM tile pattern slot.
 .storeVRAMSlotsLoop
 	ld c, 0
-	ld a, [hl] ; $C1X0 (picture ID) (zero if sprite slot is not used)
+	ld a, [hl] ; [x#SPRITESTATEDATA1_PICTUREID] (zero if sprite slot is not used)
 	and a ; is the sprite slot used?
 	jr z, .skipGettingPictureIndex ; if the sprite slot is not used
 	ld b, a ; b = picture ID
@@ -367,7 +371,7 @@ InitOutsideMapSprites:
 	add l
 	ld l, a
 	ld a, c ; a = VRAM slot (zero if sprite slot is not used)
-	ld [hl], a ; $C2XE (VRAM slot)
+	ld [hl], a ; [x#SPRITESTATEDATA2_IMAGEBASEOFFSET]
 	pop hl
 	ld a, $10
 	add l

engine/overworld/movement.asm

@@ -121,20 +121,20 @@ UpdateNPCSprite:
 	ld l, a
 	ld a, [hl]        ; read movement byte 2
 	ld [wCurSpriteMovement2], a
-	ld h, $c1
+	ld h, HIGH(wSpriteStateData1)
 	ldh a, [hCurrentSpriteOffset]
 	ld l, a
 	inc l
-	ld a, [hl]        ; c1x1
+	ld a, [hl]        ; x#SPRITESTATEDATA1_MOVEMENTSTATUS
 	and a
 	jp z, InitializeSpriteStatus
 	call CheckSpriteAvailability
 	ret c             ; if sprite is invisible, on tile >=MAP_TILESET_SIZE, in grass or player is currently walking
-	ld h, $c1
+	ld h, HIGH(wSpriteStateData1)
 	ldh a, [hCurrentSpriteOffset]
 	ld l, a
 	inc l
-	ld a, [hl]        ; c1x1
+	ld a, [hl]        ; x#SPRITESTATEDATA1_MOVEMENTSTATUS
 	bit 7, a ; is the face player flag set?
 	jp nz, MakeNPCFacePlayer
 	ld b, a
@@ -143,9 +143,9 @@ UpdateNPCSprite:
 	jp nz, notYetMoving
 	ld a, b
 	cp $2
-	jp z, UpdateSpriteMovementDelay  ; c1x1 == 2
+	jp z, UpdateSpriteMovementDelay  ; [x#SPRITESTATEDATA1_MOVEMENTSTATUS] == 2
 	cp $3
-	jp z, UpdateSpriteInWalkingAnimation  ; c1x1 == 3
+	jp z, UpdateSpriteInWalkingAnimation  ; [x#SPRITESTATEDATA1_MOVEMENTSTATUS] == 3
 	ld a, [wWalkCounter]
 	and a
 	ret nz           ; don't do anything yet if player is currently moving (redundant, already tested in CheckSpriteAvailability)
@@ -154,7 +154,7 @@ UpdateNPCSprite:
 	ldh a, [hCurrentSpriteOffset]
 	add $6
 	ld l, a
-	ld a, [hl]       ; c2x6: movement byte 1
+	ld a, [hl]       ; x#SPRITESTATEDATA2_MOVEMENTBYTE1
 	inc a
 	jr z, .randomMovement  ; value $FF
 	inc a
@@ -263,18 +263,18 @@ ChangeFacingDirection:
 ; set carry on failure, clears carry on success
 TryWalking:
 	push hl
-	ld h, $c1
+	ld h, HIGH(wSpriteStateData1)
 	ldh a, [hCurrentSpriteOffset]
 	add $9
 	ld l, a
-	ld [hl], c          ; c1x9 (update facing direction)
+	ld [hl], c          ; x#SPRITESTATEDATA1_FACINGDIRECTION
 	ldh a, [hCurrentSpriteOffset]
 	add $3
 	ld l, a
-	ld [hl], d          ; c1x3 (update Y movement delta)
+	ld [hl], d          ; x#SPRITESTATEDATA1_YSTEPVECTOR
 	inc l
 	inc l
-	ld [hl], e          ; c1x5 (update X movement delta)
+	ld [hl], e          ; x#SPRITESTATEDATA1_XSTEPVECTOR
 	pop hl
 	push de
 	ld c, [hl]          ; read tile to walk onto
@@ -285,18 +285,18 @@ TryWalking:
 	ldh a, [hCurrentSpriteOffset]
 	add $4
 	ld l, a
-	ld a, [hl]          ; c2x4: Y position
+	ld a, [hl]          ; x#SPRITESTATEDATA2_MAPY
 	add d
 	ld [hli], a         ; update Y position
-	ld a, [hl]          ; c2x5: X position
+	ld a, [hl]          ; x#SPRITESTATEDATA2_MAPX
 	add e
 	ld [hl], a          ; update X position
 	ldh a, [hCurrentSpriteOffset]
 	ld l, a
-	ld [hl], $10        ; c2x0=16: walk animation counter
+	ld [hl], $10        ; [x#SPRITESTATEDATA2_WALKANIMATIONCOUNTER] = 16
 	dec h
 	inc l
-	ld [hl], $3         ; c1x1: set movement status to walking
+	ld [hl], $3         ; x#SPRITESTATEDATA1_MOVEMENTSTATUS
 	jp UpdateSpriteImage
 
 ; update the walking animation parameters for a sprite that is currently walking
@@ -304,15 +304,15 @@ UpdateSpriteInWalkingAnimation:
 	ldh a, [hCurrentSpriteOffset]
 	add $7
 	ld l, a
-	ld a, [hl]                       ; c1x7 (counter until next walk animation frame)
+	ld a, [hl]                       ; x#SPRITESTATEDATA1_INTRAANIMFRAMECOUNTER
 	inc a
-	ld [hl], a                       ; c1x7 += 1
+	ld [hl], a                       ; [x#SPRITESTATEDATA1_INTRAANIMFRAMECOUNTER]++
 	cp $4
 	jr nz, .noNextAnimationFrame
 	xor a
-	ld [hl], a                       ; c1x7 = 0
+	ld [hl], a                       ; [x#SPRITESTATEDATA1_INTRAANIMFRAMECOUNTER] = 0
 	inc l
-	ld a, [hl]                       ; c1x8 (walk animation frame)
+	ld a, [hl]                       ; x#SPRITESTATEDATA1_ANIMFRAMECOUNTER
 	inc a
 	and $3
 	ld [hl], a                       ; advance to next animation frame every 4 ticks (16 ticks total for one step)
@@ -320,34 +320,34 @@ UpdateSpriteInWalkingAnimation:
 	ldh a, [hCurrentSpriteOffset]
 	add $3
 	ld l, a
-	ld a, [hli]                      ; c1x3 (movement Y delta)
+	ld a, [hli]                      ; x#SPRITESTATEDATA1_YSTEPVECTOR
 	ld b, a
-	ld a, [hl]                       ; c1x4 (screen Y position)
+	ld a, [hl]                       ; x#SPRITESTATEDATA1_YPIXELS
 	add b
-	ld [hli], a                      ; update screen Y position
+	ld [hli], a                      ; update [x#SPRITESTATEDATA1_YPIXELS]
-	ld a, [hli]                      ; c1x5 (movement X delta)
+	ld a, [hli]                      ; x#SPRITESTATEDATA1_XSTEPVECTOR
 	ld b, a
-	ld a, [hl]                       ; c1x6 (screen X position)
+	ld a, [hl]                       ; x#SPRITESTATEDATA1_XPIXELS
 	add b
-	ld [hl], a                       ; update screen X position
+	ld [hl], a                       ; update [x#SPRITESTATEDATA1_XPIXELS]
 	ldh a, [hCurrentSpriteOffset]
 	ld l, a
 	inc h
-	ld a, [hl]                       ; c2x0 (walk animation counter)
+	ld a, [hl]                       ; x#SPRITESTATEDATA2_WALKANIMATIONCOUNTER
 	dec a
 	ld [hl], a                       ; update walk animation counter
 	ret nz
 	ld a, $6                         ; walking finished, update state
 	add l
 	ld l, a
-	ld a, [hl]                       ; c2x6 (movement byte 1)
+	ld a, [hl]                       ; x#SPRITESTATEDATA2_MOVEMENTBYTE1
 	cp $fe
 	jr nc, .initNextMovementCounter  ; values $fe and $ff
 	ldh a, [hCurrentSpriteOffset]
 	inc a
 	ld l, a
 	dec h
-	ld [hl], $1                      ; c1x1 = 1 (movement status ready)
+	ld [hl], $1                      ; [x#SPRITESTATEDATA1_MOVEMENTSTATUS] = 1 (movement status ready)
 	ret
 .initNextMovementCounter
 	call Random
@@ -356,29 +356,31 @@ UpdateSpriteInWalkingAnimation:
 	ld l, a
 	ldh a, [hRandomAdd]
 	and $7f
-	ld [hl], a                       ; c2x8: set next movement delay to a random value in [0,$7f]
+	ld [hl], a                       ; x#SPRITESTATEDATA2_MOVEMENTDELAY:
-	dec h                            ;       note that value 0 actually makes the delay $100 (bug?)
+	                                 ; set next movement delay to a random value in [0,$7f]
+	                                 ; note that value 0 actually makes the delay $100 (bug?)
+	dec h ; HIGH(wSpriteStateData1)
 	ldh a, [hCurrentSpriteOffset]
 	inc a
 	ld l, a
-	ld [hl], $2                      ; c1x1 = 2 (movement status)
+	ld [hl], $2                      ; [x#SPRITESTATEDATA1_MOVEMENTSTATUS] = 2 (movement status)
 	inc l
 	inc l
 	xor a
-	ld b, [hl]                       ; c1x3 (movement Y delta)
+	ld b, [hl]                       ; x#SPRITESTATEDATA1_YSTEPVECTOR
-	ld [hli], a                      ; reset movement Y delta
+	ld [hli], a                      ; [x#SPRITESTATEDATA1_YSTEPVECTOR] = 0
 	inc l
-	ld c, [hl]                       ; c1x5 (movement X delta)
+	ld c, [hl]                       ; x#SPRITESTATEDATA1_XSTEPVECTOR
-	ld [hl], a                       ; reset movement X delta
+	ld [hl], a                       ; [x#SPRITESTATEDATA1_XSTEPVECTOR] = 0
 	ret
 
-; update delay value (c2x8) for sprites in the delayed state (c1x1)
+; update [x#SPRITESTATEDATA2_MOVEMENTDELAY] for sprites in the delayed state (x#SPRITESTATEDATA1_MOVEMENTSTATUS)
 UpdateSpriteMovementDelay:
-	ld h, $c2
+	ld h, HIGH(wSpriteStateData2)
 	ldh a, [hCurrentSpriteOffset]
 	add $6
 	ld l, a
-	ld a, [hl]              ; c2x6: movement byte 1
+	ld a, [hl]              ; x#SPRITESTATEDATA2_MOVEMENTBYTE1
 	inc l
 	inc l
 	cp $fe
@@ -386,20 +388,20 @@ UpdateSpriteMovementDelay:
 	ld [hl], $0
 	jr .moving
 .tickMoveCounter
-	dec [hl]                ; c2x8: frame counter until next movement
+	dec [hl]                ; x#SPRITESTATEDATA2_MOVEMENTDELAY
 	jr nz, notYetMoving
 .moving
 	dec h
 	ldh a, [hCurrentSpriteOffset]
 	inc a
 	ld l, a
-	ld [hl], $1             ; c1x1 = 1 (mark as ready to move)
+	ld [hl], $1             ; [x#SPRITESTATEDATA1_MOVEMENTSTATUS] = 1 (mark as ready to move)
 notYetMoving:
 	ld h, HIGH(wSpriteStateData1)
 	ldh a, [hCurrentSpriteOffset]
-	add wSpritePlayerStateData1AnimFrameCounter - wSpritePlayerStateData1
+	add SPRITESTATEDATA1_ANIMFRAMECOUNTER
 	ld l, a
-	ld [hl], $0             ; c1x8 = 0 (walk animation frame)
+	ld [hl], $0             ; [x#SPRITESTATEDATA1_ANIMFRAMECOUNTER] = 0 (walk animation frame)
 	jp UpdateSpriteImage
 
 MakeNPCFacePlayer:
@@ -432,44 +434,44 @@ MakeNPCFacePlayer:
 	ldh a, [hCurrentSpriteOffset]
 	add $9
 	ld l, a
-	ld [hl], c              ; c1x9: set facing direction
+	ld [hl], c              ; [x#SPRITESTATEDATA1_FACINGDIRECTION]: set facing direction
 	jr notYetMoving
 
 InitializeSpriteStatus:
-	ld [hl], $1   ; $c1x1: set movement status to ready
+	ld [hl], $1   ; [x#SPRITESTATEDATA1_MOVEMENTSTATUS] = ready
 	inc l
-	ld [hl], $ff  ; $c1x2: set sprite image to $ff (invisible/off screen)
+	ld [hl], $ff  ; [x#SPRITESTATEDATA1_IMAGEINDEX] = invisible/off screen
-	inc h
+	inc h ; HIGH(wSpriteStateData2)
 	ldh a, [hCurrentSpriteOffset]
 	add $2
 	ld l, a
 	ld a, $8
-	ld [hli], a   ; $c2x2: set Y displacement to 8
+	ld [hli], a   ; [x#SPRITESTATEDATA2_YDISPLACEMENT] = 8
-	ld [hl], a    ; $c2x3: set X displacement to 8
+	ld [hl], a    ; [x#SPRITESTATEDATA2_XDISPLACEMENT] = 8
 	ret
 
-; calculates the sprite's screen position form its map position and the player position
+; calculates the sprite's screen position from its map position and the player position
 InitializeSpriteScreenPosition:
 	ld h, HIGH(wSpriteStateData2)
 	ldh a, [hCurrentSpriteOffset]
-	add wSpritePlayerStateData2MapY - wSpritePlayerStateData2
+	add SPRITESTATEDATA2_MAPY
 	ld l, a
 	ld a, [wYCoord]
 	ld b, a
-	ld a, [hl]      ; c2x4 (Y position + 4)
+	ld a, [hl]      ; x#SPRITESTATEDATA2_MAPY
 	sub b           ; relative to player position
 	swap a          ; * 16
 	sub $4          ; - 4
 	dec h
-	ld [hli], a     ; c1x4 (screen Y position)
+	ld [hli], a     ; [x#SPRITESTATEDATA1_YPIXELS]
 	inc h
 	ld a, [wXCoord]
 	ld b, a
-	ld a, [hli]     ; c2x6 (X position + 4)
+	ld a, [hli]     ; x#SPRITESTATEDATA2_MAPX
 	sub b           ; relative to player position
 	swap a          ; * 16
 	dec h
-	ld [hl], a      ; c1x6 (screen X position)
+	ld [hl], a      ; [x#SPRITESTATEDATA1_XPIXELS]
 	ret
 
 ; tests if sprite is off screen or otherwise unable to do anything
@@ -480,15 +482,15 @@ CheckSpriteAvailability:
 	jp nz, .spriteInvisible
 	ld h, HIGH(wSpriteStateData2)
 	ldh a, [hCurrentSpriteOffset]
-	add wSpritePlayerStateData2MovementByte1 - wSpritePlayerStateData2
+	add SPRITESTATEDATA2_MOVEMENTBYTE1
 	ld l, a
-	ld a, [hl]      ; c2x6: movement byte 1
+	ld a, [hl]      ; x#SPRITESTATEDATA2_MOVEMENTBYTE1
 	cp $fe
 	jr c, .skipXVisibilityTest ; movement byte 1 < $fe (i.e. the sprite's movement is scripted)
 	ldh a, [hCurrentSpriteOffset]
-	add wSpritePlayerStateData2MapY - wSpritePlayerStateData2
+	add SPRITESTATEDATA2_MAPY
 	ld l, a
-	ld b, [hl]      ; c2x4: Y pos (+4)
+	ld b, [hl]      ; x#SPRITESTATEDATA2_MAPY
 	ld a, [wYCoord]
 	cp b
 	jr z, .skipYVisibilityTest
@@ -498,7 +500,7 @@ CheckSpriteAvailability:
 	jr c, .spriteInvisible  ; below screen region
 .skipYVisibilityTest
 	inc l
-	ld b, [hl]      ; c2x5: X pos (+4)
+	ld b, [hl]      ; x#SPRITESTATEDATA2_MAPX
 	ld a, [wXCoord]
 	cp b
 	jr z, .skipXVisibilityTest
@@ -528,9 +530,9 @@ CheckSpriteAvailability:
 .spriteInvisible
 	ld h, HIGH(wSpriteStateData1)
 	ldh a, [hCurrentSpriteOffset]
-	add wSpritePlayerStateData1ImageIndex - wSpritePlayerStateData1
+	add SPRITESTATEDATA1_IMAGEINDEX
 	ld l, a
-	ld [hl], $ff       ; c1x2
+	ld [hl], $ff       ; x#SPRITESTATEDATA1_IMAGEINDEX
 	scf
 	jr .done
 .spriteVisible
@@ -549,19 +551,19 @@ CheckSpriteAvailability:
 	jr nz, .notInGrass
 	ld a, $80
 .notInGrass
-	ld [hl], a       ; c2x7
+	ld [hl], a       ; x#SPRITESTATEDATA2_GRASSPRIORITY
 	and a
 .done
 	ret
 
 UpdateSpriteImage:
-	ld h, $c1
+	ld h, HIGH(wSpriteStateData1)
 	ldh a, [hCurrentSpriteOffset]
 	add $8
 	ld l, a
-	ld a, [hli]        ; c1x8: walk animation frame
+	ld a, [hli]        ; x#SPRITESTATEDATA1_ANIMFRAMECOUNTER
 	ld b, a
-	ld a, [hl]         ; c1x9: facing direction
+	ld a, [hl]         ; x#SPRITESTATEDATA1_FACINGDIRECTION
 	add b
 	ld b, a
 	ldh a, [hTilePlayerStandingOn]
@@ -570,7 +572,7 @@ UpdateSpriteImage:
 	ldh a, [hCurrentSpriteOffset]
 	add $2
 	ld l, a
-	ld [hl], b         ; c1x2: sprite to display
+	ld [hl], b         ; x#SPRITESTATEDATA1_IMAGEINDEX
 	ret
 
 ; tests if sprite can walk the specified direction
@@ -582,9 +584,9 @@ UpdateSpriteImage:
 CanWalkOntoTile:
 	ld h, HIGH(wSpriteStateData2)
 	ldh a, [hCurrentSpriteOffset]
-	add wSpritePlayerStateData2MovementByte1 - wSpritePlayerStateData2
+	add SPRITESTATEDATA2_MOVEMENTBYTE1
 	ld l, a
-	ld a, [hl]         ; c2x6 (movement byte 1)
+	ld a, [hl]         ; x#SPRITESTATEDATA2_MOVEMENTBYTE1
 	cp $fe
 	jr nc, .notScripted    ; values $fe and $ff
 ; always allow walking if the movement is scripted
@@ -605,20 +607,20 @@ CanWalkOntoTile:
 	ldh a, [hCurrentSpriteOffset]
 	add $6
 	ld l, a
-	ld a, [hl]         ; $c2x6 (movement byte 1)
+	ld a, [hl]         ; x#SPRITESTATEDATA2_MOVEMENTBYTE1
 	inc a
 	jr z, .impassable  ; if $ff, no movement allowed (however, changing direction is)
 	ld h, HIGH(wSpriteStateData1)
 	ldh a, [hCurrentSpriteOffset]
-	add wSpritePlayerStateData1YPixels - wSpritePlayerStateData1
+	add SPRITESTATEDATA1_YPIXELS
 	ld l, a
-	ld a, [hli]        ; c1x4 (screen Y pos)
+	ld a, [hli]        ; x#SPRITESTATEDATA1_YPIXELS
 	add $4             ; align to blocks (Y pos is always 4 pixels off)
 	add d              ; add Y delta
 	cp $80             ; if value is >$80, the destination is off screen (either $81 or $FF underflow)
 	jr nc, .impassable ; don't walk off screen
 	inc l
-	ld a, [hl]         ; c1x6 (screen X pos)
+	ld a, [hl]         ; x#SPRITESTATEDATA1_XPIXELS
 	add e              ; add X delta
 	cp $90             ; if value is >$90, the destination is off screen (either $91 or $FF underflow)
 	jr nc, .impassable ; don't walk off screen
@@ -631,26 +633,31 @@ CanWalkOntoTile:
 	ldh a, [hCurrentSpriteOffset]
 	add $c
 	ld l, a
-	ld a, [hl]         ; c1xc (directions in which sprite collision would occur)
+	ld a, [hl]         ; x#SPRITESTATEDATA1_COLLISIONDATA (directions in which sprite collision would occur)
 	and b              ; check against chosen direction (1,2,4 or 8)
 	jr nz, .impassable ; collision between sprites, don't go there
 	ld h, HIGH(wSpriteStateData2)
 	ldh a, [hCurrentSpriteOffset]
-	add wSpritePlayerStateData2YDisplacement - wSpritePlayerStateData2
+	add SPRITESTATEDATA2_YDISPLACEMENT
 	ld l, a
-	ld a, [hli]        ; c2x2 (sprite Y displacement, initialized at $8, keep track of where a sprite did go)
+	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)
 	jr nz, .upwards
 	add d
+	; bug: these tests against $5 probably were supposed to prevent
+	; sprites from walking out too far, but this line makes sprites get
+	; stuck whenever they walked upwards 5 steps
+	; on the other hand, the amount a sprite can walk out to the
+	; right of bottom is not limited (until the counter overflows)
 	cp $5
-	jr c, .impassable  ; if c2x2+d < 5, don't go ;bug: this tests probably were supposed to prevent sprites
+	jr c, .impassable  ; if [x#SPRITESTATEDATA2_YDISPLACEMENT]+d < 5, don't go
-	jr .checkHorizontal                          ; from walking out too far, but this line makes sprites get stuck
+	jr .checkHorizontal
-.upwards                                         ; whenever they walked upwards 5 steps
+.upwards
-	sub $1                                       ; on the other hand, the amount a sprite can walk out to the
+	sub $1
-	jr c, .impassable  ; if d2x2 == 0, don't go  ; right of bottom is not limited (until the counter overflows)
+	jr c, .impassable  ; if [x#SPRITESTATEDATA2_YDISPLACEMENT] == 0, don't go
 .checkHorizontal
 	ld d, a
-	ld a, [hl]         ; c2x3 (sprite X displacement, initialized at $8, keep track of where a sprite did go)
+	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)
 	jr nz, .left
 	add e
@@ -658,10 +665,10 @@ CanWalkOntoTile:
 	jr .passable
 .left
 	sub $1
-	jr c, .impassable  ; if d2x3 == 0, don't go
+	jr c, .impassable  ; if [x#SPRITESTATEDATA2_XDISPLACEMENT] == 0, don't go
 .passable
-	ld [hld], a        ; update c2x3
+	ld [hld], a        ; update x#SPRITESTATEDATA2_XDISPLACEMENT
-	ld [hl], d         ; update c2x2
+	ld [hl], d         ; update x#SPRITESTATEDATA2_YDISPLACEMENT
 	and a              ; clear carry (marking success)
 	ret
 .impassable
@@ -669,13 +676,13 @@ CanWalkOntoTile:
 	ldh a, [hCurrentSpriteOffset]
 	inc a
 	ld l, a
-	ld [hl], $2        ; c1x1 = 2 (set movement status to delayed)
+	ld [hl], $2        ; [x#SPRITESTATEDATA1_MOVEMENTSTATUS] = 2 (delayed)
 	inc l
 	inc l
 	xor a
-	ld [hli], a        ; c1x3 = 0 (clear Y movement delta)
+	ld [hli], a        ; [x#SPRITESTATEDATA1_YSTEPVECTOR] = 0
 	inc l
-	ld [hl], a         ; c1x5 = 0 (clear X movement delta)
+	ld [hl], a         ; [x#SPRITESTATEDATA1_XSTEPVECTOR] = 0
 	inc h
 	ldh a, [hCurrentSpriteOffset]
 	add $8
@@ -683,7 +690,7 @@ CanWalkOntoTile:
 	call Random
 	ldh a, [hRandomAdd]
 	and $7f
-	ld [hl], a         ; c2x8: set next movement delay to a random value in [0,$7f] (again with delay $100 if value is 0)
+	ld [hl], a         ; x#SPRITESTATEDATA2_MOVEMENTDELAY: set to a random value in [0,$7f] (again with delay $100 if value is 0)
 	scf                ; set carry (marking failure to walk)
 	ret
 
@@ -693,16 +700,16 @@ CanWalkOntoTile:
 GetTileSpriteStandsOn:
 	ld h, HIGH(wSpriteStateData1)
 	ldh a, [hCurrentSpriteOffset]
-	add wSpritePlayerStateData1YPixels - wSpritePlayerStateData1
+	add SPRITESTATEDATA1_YPIXELS
 	ld l, a
-	ld a, [hli]     ; c1x4: screen Y position
+	ld a, [hli]     ; x#SPRITESTATEDATA1_YPIXELS
 	add $4          ; align to 2*2 tile blocks (Y position is always off 4 pixels to the top)
 	and $f0         ; in case object is currently moving
 	srl a           ; screen Y tile * 4
 	ld c, a
 	ld b, $0
 	inc l
-	ld a, [hl]      ; c1x6: screen X position
+	ld a, [hl]      ; x#SPRITESTATEDATA1_XPIXELS
 	srl a
 	srl a
 	srl a            ; screen X tile
@@ -807,12 +814,12 @@ InitScriptedNPCMovement:
 	jp AnimScriptedNPCMovement
 
 GetSpriteScreenYPointer:
-	ld a, wSpritePlayerStateData1YPixels - wSpritePlayerStateData1
+	ld a, SPRITESTATEDATA1_YPIXELS
 	ld b, a
 	jr GetSpriteScreenXYPointerCommon
 
 GetSpriteScreenXPointer:
-	ld a, wSpritePlayerStateData1XPixels - wSpritePlayerStateData1
+	ld a, SPRITESTATEDATA1_XPIXELS
 	ld b, a
 
 GetSpriteScreenXYPointerCommon:
@@ -826,7 +833,7 @@ GetSpriteScreenXYPointerCommon:
 AnimScriptedNPCMovement:
 	ld hl, wSpriteStateData2
 	ldh a, [hCurrentSpriteOffset]
-	add wSpritePlayerStateData2ImageBaseOffset - wSpritePlayerStateData2
+	add SPRITESTATEDATA2_IMAGEBASEOFFSET
 	ld l, a
 	ld a, [hl] ; VRAM slot
 	dec a
@@ -834,7 +841,7 @@ AnimScriptedNPCMovement:
 	ld b, a
 	ld hl, wSpriteStateData1
 	ldh a, [hCurrentSpriteOffset]
-	add wSpritePlayerStateData1FacingDirection - wSpritePlayerStateData1
+	add SPRITESTATEDATA1_FACINGDIRECTION
 	ld l, a
 	ld a, [hl] ; facing direction
 	cp SPRITE_FACING_DOWN
@@ -853,7 +860,7 @@ AnimScriptedNPCMovement:
 	call AdvanceScriptedNPCAnimFrameCounter
 	ld hl, wSpriteStateData1
 	ldh a, [hCurrentSpriteOffset]
-	add wSpritePlayerStateData1ImageIndex - wSpritePlayerStateData1
+	add SPRITESTATEDATA1_IMAGEINDEX
 	ld l, a
 	ldh a, [hSpriteVRAMSlotAndFacing]
 	ld b, a

engine/overworld/pathfinding.asm

@@ -84,7 +84,7 @@ CalcPositionOfPlayerRelativeToNPC:
 	ld hl, wSpriteStateData1
 	ldh a, [hNPCSpriteOffset]
 	add l
-	add wSpritePlayerStateData1YPixels - wSpritePlayerStateData1
+	add SPRITESTATEDATA1_YPIXELS
 	ld l, a
 	jr nc, .noCarry
 	inc h

engine/overworld/sprite_collisions.asm

@@ -1,15 +1,15 @@
 _UpdateSprites::
 	ld h, $c1
 	inc h
-	ld a, wSpritePlayerStateData2ImageBaseOffset - wSpritePlayerStateData2
+	ld a, SPRITESTATEDATA2_IMAGEBASEOFFSET
 .spriteLoop
 	ld l, a
-	sub wSpritePlayerStateData2ImageBaseOffset - wSpritePlayerStateData2
+	sub SPRITESTATEDATA2_IMAGEBASEOFFSET
 	ld c, a
 	ldh [hCurrentSpriteOffset], a
 	ld a, [hl]
 	and a
-	jr z, .skipSprite   ; tests $c2Xe
+	jr z, .skipSprite   ; tests SPRITESTATEDATA2_IMAGEBASEOFFSET
 	push hl
 	push de
 	push bc
@@ -20,7 +20,7 @@ _UpdateSprites::
 .skipSprite
 	ld a, l
 	add $10             ; move to next sprite
-	cp wSpritePlayerStateData2ImageBaseOffset - wSpritePlayerStateData2 ; test for overflow (back at beginning)
+	cp SPRITESTATEDATA2_IMAGEBASEOFFSET ; test for overflow (back at beginning)
 	jr nz, .spriteLoop
 	ret
 .updateCurrentSprite
@@ -43,11 +43,12 @@ UpdateNonPlayerSprite:
 
 ; This detects if the current sprite (whose offset is at hCurrentSpriteOffset)
 ; is going to collide with another sprite by looping over the other sprites.
-; The current sprite's offset will be labelled with i (e.g. $c1i0).
+; The current sprite's offset will be labelled with i (e.g. i#SPRITESTATEDATA1_PICTUREID).
-; The loop sprite's offset will labelled with j (e.g. $c1j0).
+; The loop sprite's offset will labelled with j (e.g. j#SPRITESTATEDATA1_PICTUREID).
 ;
-; Note that the Y coordinate of the sprite (in [$c1k4]) is one of the following
+; Note that the Y coordinate of the sprite (in [k#SPRITESTATEDATA1_YPIXELS])
-; 9 values when the sprite is aligned with the grid: $fc, $0c, $1c, $2c, ..., $7c.
+; is one of the following 9 values when the sprite is aligned with the grid:
+; $fc, $0c, $1c, $2c, ..., $7c.
 ; The reason that 4 is added below to the coordinate is to make it align with a
 ; multiple of $10 to make comparisons easier.
 DetectCollisionBetweenSprites:
@@ -58,7 +59,7 @@ DetectCollisionBetweenSprites:
 	add LOW(wSpriteStateData1)
 	ld l, a
 
-	ld a, [hl] ; a = [$c1i0] (picture) (0 if slot is unused)
+	ld a, [hl] ; a = [i#SPRITESTATEDATA1_PICTUREID] (0 if slot is unused)
 	and a ; is this sprite slot slot used?
 	ret z ; return if not used
 
@@ -66,10 +67,10 @@ DetectCollisionBetweenSprites:
 	add 3
 	ld l, a
 
-	ld a, [hli] ; a = [$c1i3] (delta Y) (-1, 0, or 1)
+	ld a, [hli] ; a = [i#SPRITESTATEDATA1_YSTEPVECTOR] (-1, 0, or 1)
 	call SetSpriteCollisionValues
 
-	ld a, [hli] ; a = [$C1i4] (Y screen coordinate)
+	ld a, [hli] ; a = [i#SPRITESTATEDATA1_YPIXELS]
 	add 4 ; align with multiple of $10
 
 ; The effect of the following 3 lines is to
@@ -81,9 +82,9 @@ DetectCollisionBetweenSprites:
 
 	ldh [hFF90], a ; store Y coordinate adjusted for direction of movement
 
-	ld a, [hli] ; a = [$c1i5] (delta X) (-1, 0, or 1)
+	ld a, [hli] ; a = [i#SPRITESTATEDATA1_XSTEPVECTOR] (-1, 0, or 1)
 	call SetSpriteCollisionValues
-	ld a, [hl] ; a = [$C1i6] (X screen coordinate)
+	ld a, [hl] ; a = [i#SPRITESTATEDATA1_XPIXELS]
 
 ; The effect of the following 3 lines is to
 ; add 7 to a if moving east or
@@ -99,13 +100,13 @@ DetectCollisionBetweenSprites:
 	ld l, a
 
 	xor a
-	ld [hld], a ; zero [$c1id] XXX what's [$c1id] for?
+	ld [hld], a ; zero [i#SPRITESTATEDATA1_0D] XXX what's this for?
-	ld [hld], a ; zero [$c1ic] (directions in which collisions occurred)
+	ld [hld], a ; zero [i#SPRITESTATEDATA1_COLLISIONDATA]
 
 	ldh a, [hFF91]
-	ld [hld], a ; [$c1ib] = adjusted X coordinate
+	ld [hld], a ; [i#SPRITESTATEDATA1_XADJUSTED]
 	ldh a, [hFF90]
-	ld [hl], a ; [$c1ia] = adjusted Y coordinate
+	ld [hl], a ; [i#SPRITESTATEDATA1_YADJUSTED]
 
 	xor a ; zero the loop counter
 
@@ -118,13 +119,13 @@ DetectCollisionBetweenSprites:
 	jp z, .next ; go to the next sprite if they match
 
 	ld d, h
-	ld a, [de] ; a = [$c1j0] (picture) (0 if slot is unused)
+	ld a, [de] ; a = [j#SPRITESTATEDATA1_PICTUREID] (0 if slot is unused)
 	and a ; is this sprite slot slot used?
 	jp z, .next ; go the next sprite if not used
 
 	inc e
 	inc e
-	ld a, [de] ; a = [$c1j2] ($ff means the sprite is offscreen)
+	ld a, [de] ; a = [j#SPRITESTATEDATA1_IMAGEINDEX] ($ff means the sprite is offscreen)
 	inc a
 	jp z, .next ; go the next sprite if offscreen
 
@@ -133,11 +134,11 @@ DetectCollisionBetweenSprites:
 	ld l, a
 
 	inc e
-	ld a, [de] ; a = [$c1j3] (delta Y)
+	ld a, [de] ; a = [j#SPRITESTATEDATA1_YSTEPVECTOR]
 	call SetSpriteCollisionValues
 
 	inc e
-	ld a, [de] ; a = [$C1j4] (Y screen coordinate)
+	ld a, [de] ; a = [j#SPRITESTATEDATA1_YPIXELS]
 	add 4 ; align with multiple of $10
 
 ; The effect of the following 3 lines is to
@@ -147,7 +148,7 @@ DetectCollisionBetweenSprites:
 	and $f0
 	or c
 
-	sub [hl] ; subtract the adjusted Y coordinate of sprite i ([$c1ia]) from that of sprite j
+	sub [hl] ; subtract [i#SPRITESTATEDATA1_YADJUSTED] from [j#SPRITESTATEDATA1_YADJUSTED]
 
 ; calculate the absolute value of the difference to get the distance
 	jr nc, .noCarry1
@@ -157,8 +158,8 @@ DetectCollisionBetweenSprites:
 	ldh [hFF90], a ; store the distance between the two sprites' adjusted Y values
 
 ; Use the carry flag set by the above subtraction to determine which sprite's
-; Y coordinate is larger. This information is used later to set [$c1ic],
+; Y coordinate is larger. This information is used later to set
-; which stores which direction the collision occurred in.
+; [i#SPRITESTATEDATA1_COLLISIONDATA].
 ; The following 5 lines set the lowest 2 bits of c, which are later shifted left by 2.
 ; If sprite i's Y is larger, set lowest 2 bits of c to 10.
 ; If sprite j's Y is larger or both are equal, set lowest 2 bits of c to 01.
@@ -170,7 +171,7 @@ DetectCollisionBetweenSprites:
 
 ; If sprite i's delta Y is 0, then b = 7, else b = 9.
 	ld b, 7
-	ld a, [hl] ; a = [$c1ia] (adjusted Y coordinate)
+	ld a, [hl] ; a = [i#SPRITESTATEDATA1_YADJUSTED]
 	and $f
 	jr z, .next1
 	ld b, 9
@@ -186,7 +187,7 @@ DetectCollisionBetweenSprites:
 ; If sprite j's delta Y is 0, then b = 7, else b = 9.
 	ld b, 7
 	dec e
-	ld a, [de] ; a = [$c1j3] (delta Y)
+	ld a, [de] ; a = [j#SPRITESTATEDATA1_YSTEPVECTOR]
 	inc e
 	and a
 	jr z, .next2
@@ -201,13 +202,13 @@ DetectCollisionBetweenSprites:
 .checkXDistance
 	inc e
 	inc l
-	ld a, [de] ; a = [$c1j5] (delta X)
+	ld a, [de] ; a = [j#SPRITESTATEDATA1_XSTEPVECTOR]
 
 	push bc
 
 	call SetSpriteCollisionValues
 	inc e
-	ld a, [de] ; a = [$c1j6] (X screen coordinate)
+	ld a, [de] ; a = [j#SPRITESTATEDATA1_XPIXELS]
 
 ; The effect of the following 3 lines is to
 ; add 7 to a if moving east or
@@ -218,7 +219,7 @@ DetectCollisionBetweenSprites:
 
 	pop bc
 
-	sub [hl] ; subtract the adjusted X coordinate of sprite i ([$c1ib]) from that of sprite j
+	sub [hl] ; subtract [i#SPRITESTATEDATA1_XADJUSTED] from [j#SPRITESTATEDATA1_XADJUSTED]
 
 ; calculate the absolute value of the difference to get the distance
 	jr nc, .noCarry2
@@ -228,8 +229,8 @@ DetectCollisionBetweenSprites:
 	ldh [hFF91], a ; store the distance between the two sprites' adjusted X values
 
 ; Use the carry flag set by the above subtraction to determine which sprite's
-; X coordinate is larger. This information is used later to set [$c1ic],
+; X coordinate is larger. This information is used later to set
-; which stores which direction the collision occurred in.
+; [i#SPRITESTATEDATA1_COLLISIONDATA].
 ; The following 5 lines set the lowest 2 bits of c.
 ; If sprite i's X is larger, set lowest 2 bits of c to 10.
 ; If sprite j's X is larger or both are equal, set lowest 2 bits of c to 01.
@@ -241,7 +242,7 @@ DetectCollisionBetweenSprites:
 
 ; If sprite i's delta X is 0, then b = 7, else b = 9.
 	ld b, 7
-	ld a, [hl] ; a = [$c1ib] (adjusted X coordinate)
+	ld a, [hl] ; a = [i#SPRITESTATEDATA1_XADJUSTED]
 	and $f
 	jr z, .next3
 	ld b, 9
@@ -257,7 +258,7 @@ DetectCollisionBetweenSprites:
 ; If sprite j's delta X is 0, then b = 7, else b = 9.
 	ld b, 7
 	dec e
-	ld a, [de] ; a = [$c1j5] (delta X)
+	ld a, [de] ; a = [j#SPRITESTATEDATA1_XSTEPVECTOR]
 	inc e
 	and a
 	jr z, .next4
@@ -287,11 +288,12 @@ DetectCollisionBetweenSprites:
 .next6
 	ld a, c ; c has 2 bits set (one of bits 0-1 is set for the X axis and one of bits 2-3 for the Y axis)
 	and b ; we select either the bit in bits 0-1 or bits 2-3 based on the calculation immediately above
-	or [hl] ; or with existing collision direction bits in [$c1ic]
+	or [hl] ; or with existing collision direction bits in [i#SPRITESTATEDATA1_COLLISIONDATA]
 	ld [hl], a ; store new value
 	ld a, c ; useless code because a is overwritten before being used again
 
-; set bit in [$c1ie] or [$c1if] to indicate which sprite the collision occurred with
+; set bit in [i#SPRITESTATEDATA1_0E] or [i#SPRITESTATEDATA1_0F]
+; to indicate which sprite the collision occurred with
 	inc l
 	inc l
 	ldh a, [hFF8F] ; a = loop counter

engine/overworld/trainer_sight.asm

@@ -1,77 +1,77 @@
 _GetSpritePosition1::
 	ld hl, wSpriteStateData1
-	ld de, wSpritePlayerStateData1YPixels - wSpritePlayerStateData1
+	ld de, SPRITESTATEDATA1_YPIXELS
 	ld a, [wSpriteIndex]
 	ldh [hSpriteIndex], a
 	call GetSpriteDataPointer
-	ld a, [hli] ; c1x4 (screen Y pos)
+	ld a, [hli] ; x#SPRITESTATEDATA1_YPIXELS
 	ldh [hSpriteScreenYCoord], a
 	inc hl
-	ld a, [hl] ; c1x6 (screen X pos)
+	ld a, [hl] ; x#SPRITESTATEDATA1_XPIXELS
 	ldh [hSpriteScreenXCoord], a
 	ld de, wSpritePlayerStateData2MapY - wSpritePlayerStateData1XPixels
 	add hl, de
-	ld a, [hli] ; c2x4 (map Y pos)
+	ld a, [hli] ; x#SPRITESTATEDATA2_MAPY
 	ldh [hSpriteMapYCoord], a
-	ld a, [hl] ; c2x5 (map X pos)
+	ld a, [hl] ; x#SPRITESTATEDATA2_MAPX
 	ldh [hSpriteMapXCoord], a
 	ret
 
 _GetSpritePosition2::
 	ld hl, wSpriteStateData1
-	ld de, wSpritePlayerStateData1YPixels - wSpritePlayerStateData1
+	ld de, SPRITESTATEDATA1_YPIXELS
 	ld a, [wSpriteIndex]
 	ldh [hSpriteIndex], a
 	call GetSpriteDataPointer
-	ld a, [hli] ; c1x4 (screen Y pos)
+	ld a, [hli] ; x#SPRITESTATEDATA1_YPIXELS
 	ld [wSavedSpriteScreenY], a
 	inc hl
-	ld a, [hl] ; c1x6 (screen X pos)
+	ld a, [hl] ; x#SPRITESTATEDATA1_XPIXELS
 	ld [wSavedSpriteScreenX], a
 	ld de, wSpritePlayerStateData2MapY - wSpritePlayerStateData1XPixels
 	add hl, de
-	ld a, [hli] ; c2x4 (map Y pos)
+	ld a, [hli] ; x#SPRITESTATEDATA2_MAPY
 	ld [wSavedSpriteMapY], a
-	ld a, [hl] ; c2x5 (map X pos)
+	ld a, [hl] ; x#SPRITESTATEDATA2_MAPX
 	ld [wSavedSpriteMapX], a
 	ret
 
 _SetSpritePosition1::
 	ld hl, wSpriteStateData1
-	ld de, wSpritePlayerStateData1YPixels - wSpritePlayerStateData1
+	ld de, SPRITESTATEDATA1_YPIXELS
 	ld a, [wSpriteIndex]
 	ldh [hSpriteIndex], a
 	call GetSpriteDataPointer
-	ldh a, [hSpriteScreenYCoord] ; c1x4 (screen Y pos)
+	ldh a, [hSpriteScreenYCoord] ; x#SPRITESTATEDATA1_YPIXELS
 	ld [hli], a
 	inc hl
-	ldh a, [hSpriteScreenXCoord] ; c1x6 (screen X pos)
+	ldh a, [hSpriteScreenXCoord] ; x#SPRITESTATEDATA1_XPIXELS
 	ld [hl], a
 	ld de, wSpritePlayerStateData2MapY - wSpritePlayerStateData1XPixels
 	add hl, de
-	ldh a, [hSpriteMapYCoord] ; c2x4 (map Y pos)
+	ldh a, [hSpriteMapYCoord] ; x#SPRITESTATEDATA2_MAPY
 	ld [hli], a
-	ldh a, [hSpriteMapXCoord] ; c2x5 (map X pos)
+	ldh a, [hSpriteMapXCoord] ; x#SPRITESTATEDATA2_MAPX
 	ld [hl], a
 	ret
 
 _SetSpritePosition2::
 	ld hl, wSpriteStateData1
-	ld de, wSpritePlayerStateData1YPixels - wSpritePlayerStateData1
+	ld de, SPRITESTATEDATA1_YPIXELS
 	ld a, [wSpriteIndex]
 	ldh [hSpriteIndex], a
 	call GetSpriteDataPointer
 	ld a, [wSavedSpriteScreenY]
-	ld [hli], a ; c1x4 (screen Y pos)
+	ld [hli], a ; x#SPRITESTATEDATA1_YPIXELS
 	inc hl
 	ld a, [wSavedSpriteScreenX]
-	ld [hl], a ; c1x6 (screen X pos)
+	ld [hl], a ; x#SPRITESTATEDATA1_XPIXELS
 	ld de, wSpritePlayerStateData2MapY - wSpritePlayerStateData1XPixels
 	add hl, de
 	ld a, [wSavedSpriteMapY]
-	ld [hli], a ; c2x4 (map Y pos)
+	ld [hli], a ; x#SPRITESTATEDATA2_MAPY
 	ld a, [wSavedSpriteMapX]
-	ld [hl], a ; c2x5 (map X pos)
+	ld [hl], a ; x#SPRITESTATEDATA2_MAPX
 	ret
 
 TrainerWalkUpToPlayer::
@@ -165,23 +165,23 @@ TrainerEngage:
 	push hl
 	push de
 	ld a, [wTrainerSpriteOffset]
-	add wSpritePlayerStateData1ImageIndex - wSpritePlayerStateData1
+	add SPRITESTATEDATA1_IMAGEINDEX
 	ld d, $0
 	ld e, a
 	ld hl, wSpriteStateData1
 	add hl, de
-	ld a, [hl]             ; c1x2: sprite image index
+	ld a, [hl]             ; x#SPRITESTATEDATA1_IMAGEINDEX
 	sub $ff
 	jr nz, .spriteOnScreen ; test if sprite is on screen
 	jp .noEngage
 .spriteOnScreen
 	ld a, [wTrainerSpriteOffset]
-	add wSpritePlayerStateData1FacingDirection - wSpritePlayerStateData1
+	add SPRITESTATEDATA1_FACINGDIRECTION
 	ld d, $0
 	ld e, a
 	ld hl, wSpriteStateData1
 	add hl, de
-	ld a, [hl]             ; c1x9: facing direction
+	ld a, [hl]             ; x#SPRITESTATEDATA1_FACINGDIRECTION
 	ld [wTrainerFacingDirection], a
 	call ReadTrainerScreenPosition
 	ld a, [wTrainerScreenY]          ; sprite screen Y pos
@@ -234,20 +234,20 @@ TrainerEngage:
 ; reads trainer's Y position to wTrainerScreenY and X position to wTrainerScreenX
 ReadTrainerScreenPosition:
 	ld a, [wTrainerSpriteOffset]
-	add wSpritePlayerStateData1YPixels - wSpritePlayerStateData1
+	add SPRITESTATEDATA1_YPIXELS
 	ld d, $0
 	ld e, a
 	ld hl, wSpriteStateData1
 	add hl, de
-	ld a, [hl] ; c1x4 (sprite Y pos)
+	ld a, [hl] ; x#SPRITESTATEDATA1_YPIXELS
 	ld [wTrainerScreenY], a
 	ld a, [wTrainerSpriteOffset]
-	add wSpritePlayerStateData1XPixels - wSpritePlayerStateData1
+	add SPRITESTATEDATA1_XPIXELS
 	ld d, $0
 	ld e, a
 	ld hl, wSpriteStateData1
 	add hl, de
-	ld a, [hl] ; c1x6 (sprite X pos)
+	ld a, [hl] ; x#SPRITESTATEDATA1_XPIXELS
 	ld [wTrainerScreenX], a
 	ret
 
@@ -295,24 +295,24 @@ CheckPlayerIsInFrontOfSprite:
 	cp POWER_PLANT
 	jp z, .engage       ; bypass this for power plant to get voltorb fake items to work
 	ld a, [wTrainerSpriteOffset]
-	add wSpritePlayerStateData1YPixels - wSpritePlayerStateData1
+	add SPRITESTATEDATA1_YPIXELS
 	ld d, $0
 	ld e, a
 	ld hl, wSpriteStateData1
 	add hl, de
-	ld a, [hl]          ; c1x4 (sprite screen Y pos)
+	ld a, [hl]          ; x#SPRITESTATEDATA1_YPIXELS
 	cp $fc
 	jr nz, .notOnTopmostTile ; special case if sprite is on topmost tile (Y = $fc (-4)), make it come down a block
 	ld a, $c
 .notOnTopmostTile
 	ld [wTrainerScreenY], a
 	ld a, [wTrainerSpriteOffset]
-	add wSpritePlayerStateData1XPixels - wSpritePlayerStateData1
+	add SPRITESTATEDATA1_XPIXELS
 	ld d, $0
 	ld e, a
 	ld hl, wSpriteStateData1
 	add hl, de
-	ld a, [hl]          ; c1x6 (sprite screen X pos)
+	ld a, [hl]          ; x#SPRITESTATEDATA1_XPIXELS
 	ld [wTrainerScreenX], a
 	ld a, [wTrainerFacingDirection]       ; facing direction
 	cp SPRITE_FACING_DOWN

engine/overworld/turn_sprite.asm

@@ -1,25 +1,25 @@
 UpdateSpriteFacingOffsetAndDelayMovement::
-	ld h, $c2
+	ld h, HIGH(wSpriteStateData2)
 	ldh a, [hCurrentSpriteOffset]
 	add $8
 	ld l, a
 	ld a, $7f ; maximum movement delay
-	ld [hl], a ; c2x8 (movement delay)
+	ld [hl], a ; x#SPRITESTATEDATA2_MOVEMENTDELAY
-	dec h
+	dec h ; HIGH(wSpriteStateData1)
 	ldh a, [hCurrentSpriteOffset]
 	add $9
 	ld l, a
-	ld a, [hld] ; c1x9 (facing direction)
+	ld a, [hld] ; x#SPRITESTATEDATA1_FACINGDIRECTION
 	ld b, a
 	xor a
 	ld [hld], a
-	ld [hl], a ; c1x8 (walk animation frame)
+	ld [hl], a ; x#SPRITESTATEDATA1_ANIMFRAMECOUNTER
 	ldh a, [hCurrentSpriteOffset]
-	add $2
+	add SPRITESTATEDATA1_IMAGEINDEX
 	ld l, a
-	ld a, [hl] ; c1x2 (facing and animation table offset)
+	ld a, [hl] ; x#SPRITESTATEDATA1_IMAGEINDEX
 	or b ; or in the facing direction
 	ld [hld], a
 	ld a, $2 ; delayed movement status
-	ld [hl], a ; c1x1 (movement status)
+	ld [hl], a ; x#SPRITESTATEDATA1_MOVEMENTSTATUS
 	ret

home/overworld.asm

@@ -678,7 +678,7 @@ CheckMapConnections::
 	ld b, SET_PAL_OVERWORLD
 	call RunPaletteCommand
 ; Since the sprite set shouldn't change, this will just update VRAM slots at
-; $C2XE without loading any tile patterns.
+; x#SPRITESTATEDATA2_IMAGEBASEOFFSET without loading any tile patterns.
 	farcall InitMapSprites
 	call LoadTileBlockMap
 	jp OverworldLoopLessDelay
@@ -1210,7 +1210,7 @@ IsSpriteInFrontOfPlayer2::
 	ld a, l
 	and $f0
 	inc a
-	ld l, a ; hl = $c1x1
+	ld l, a ; hl = x#SPRITESTATEDATA1_MOVEMENTSTATUS
 	set 7, [hl] ; set flag to make the sprite face the player
 	ld a, e
 	ldh [hSpriteIndexOrTextID], a
@@ -2167,7 +2167,7 @@ LoadMapHeader::
 	ld a, [hli]
 	ld [wNumSprites], a ; save the number of sprites
 	push hl
-; zero C110-C1FF and C210-C2FF
+; zero out sprite state data for sprites 01-15
 	ld hl, wSprite01StateData1
 	ld de, wSprite01StateData2
 	xor a
@@ -2178,7 +2178,7 @@ LoadMapHeader::
 	inc e
 	dec b
 	jr nz, .zeroSpriteDataLoop
-; initialize all C100-C1FF sprite entries to disabled (other than player's)
+; disable SPRITESTATEDATA1_IMAGEINDEX (set to $ff) for sprites 01-15
 	ld hl, wSprite01StateData1ImageIndex
 	ld de, $10
 	ld c, $0f
@@ -2196,19 +2196,19 @@ LoadMapHeader::
 	ld c, $00
 .loadSpriteLoop
 	ld a, [hli]
-	ld [de], a ; store picture ID at C1X0
+	ld [de], a ; x#SPRITESTATEDATA1_PICTUREID
 	inc d
 	ld a, $04
 	add e
 	ld e, a
 	ld a, [hli]
-	ld [de], a ; store Y position at C2X4
+	ld [de], a ; x#SPRITESTATEDATA2_MAPY
 	inc e
 	ld a, [hli]
-	ld [de], a ; store X position at C2X5
+	ld [de], a ; x#SPRITESTATEDATA2_MAPX
 	inc e
 	ld a, [hli]
-	ld [de], a ; store movement byte 1 at C2X6
+	ld [de], a ; x#SPRITESTATEDATA2_MOVEMENTBYTE1
 	ld a, [hli]
 	ldh [hLoadSpriteTemp1], a ; save movement byte 2
 	ld a, [hli]

macros/wram.asm

@@ -71,7 +71,8 @@ spritestatedata1: MACRO
 \1IntraAnimFrameCounter:: db
 \1AnimFrameCounter:: db
 \1FacingDirection:: db
-	ds 2
+\1YAdjusted:: db
+\1XAdjusted:: db
 \1CollisionData:: db
 	ds 3
 \1End::

wram.asm

@@ -158,22 +158,23 @@ wSpriteStateData1::
 ; data for all sprites on the current map
 ; holds info for 16 sprites with $10 bytes each
 ; player sprite is always sprite 0
-; C1x0: picture ID (fixed, loaded at map init)
+; struct fields:
-; C1x1: movement status (0: uninitialized, 1: ready, 2: delayed, 3: moving)
+; - 0: picture ID (fixed, loaded at map init)
-; C1x2: sprite image index (changed on update, $ff if off screen, includes facing direction, progress in walking animation and a sprite-specific offset)
+; - 1: movement status (0: uninitialized, 1: ready, 2: delayed, 3: moving)
-; C1x3: Y screen position delta (-1,0 or 1; added to c1x4 on each walking animation update)
+; - 2: sprite image index (changed on update, $ff if off screen, includes facing direction, progress in walking animation and a sprite-specific offset)
-; C1x4: Y screen position (in pixels, always 4 pixels above grid which makes sprites appear to be in the center of a tile)
+; - 3: Y screen position delta (-1,0 or 1; added to Y pixels on each walking animation update)
-; C1x5: X screen position delta (-1,0 or 1; added to c1x6 on each walking animation update)
+; - 4: Y screen position (in pixels, always 4 pixels above grid which makes sprites appear to be in the center of a tile)
-; C1x6: X screen position (in pixels, snaps to grid if not currently walking)
+; - 5: X screen position delta (-1,0 or 1; added to field X pixels on each walking animation update)
-; C1x7: intra-animation-frame counter (counting upwards to 4 until c1x8 is incremented)
+; - 6: X screen position (in pixels, snaps to grid if not currently walking)
-; C1x8: animation frame counter (increased every 4 updates, hold four states (totalling to 16 walking frames)
+; - 7: intra-animation-frame counter (counting upwards to 4 until animation frame counter is incremented)
-; C1x9: facing direction (0: down, 4: up, 8: left, $c: right)
+; - 8: animation frame counter (increased every 4 updates, hold four states (totalling to 16 walking frames)
-; C1xA
+; - 9: facing direction ($0: down, $4: up, $8: left, $c: right)
-; C1xB
+; - A: adjusted Y coordinate
-; C1xC
+; - B: adjusted X coordinate
-; C1xD
+; - C: direction of collision
-; C1xE
+; - D
-; C1xF
+; - E
+; - F
 wSpritePlayerStateData1::  spritestatedata1 wSpritePlayerStateData1
 wSprite01StateData1::      spritestatedata1 wSprite01StateData1
 wSprite02StateData1::      spritestatedata1 wSprite02StateData1
@@ -195,22 +196,23 @@ wSpriteStateData2::
 ; more data for all sprites on the current map
 ; holds info for 16 sprites with $10 bytes each
 ; player sprite is always sprite 0
-; C2x0: walk animation counter (counting from $10 backwards when moving)
+; struct fields:
-; C2x1:
+; - 0: walk animation counter (counting from $10 backwards when moving)
-; C2x2: Y displacement (initialized at 8, supposed to keep moving sprites from moving too far, but bugged)
+; - 1:
-; C2x3: X displacement (initialized at 8, supposed to keep moving sprites from moving too far, but bugged)
+; - 2: Y displacement (initialized at 8, supposed to keep moving sprites from moving too far, but bugged)
-; C2x4: Y position (in 2x2 tile grid steps, topmost 2x2 tile has value 4)
+; - 3: X displacement (initialized at 8, supposed to keep moving sprites from moving too far, but bugged)
-; C2x5: X position (in 2x2 tile grid steps, leftmost 2x2 tile has value 4)
+; - 4: Y position (in 2x2 tile grid steps, topmost 2x2 tile has value 4)
-; C2x6: movement byte 1 (determines whether a sprite can move, $ff:not moving, $fe:random movements, others unknown)
+; - 5: X position (in 2x2 tile grid steps, leftmost 2x2 tile has value 4)
-; C2x7: (?) (set to $80 when in grass, else $0; may be used to draw grass above the sprite)
+; - 6: movement byte 1 (determines whether a sprite can move, $ff:not moving, $fe:random movements, others unknown)
-; C2x8: delay until next movement (counted downwards, status (c1x1) is set to ready if reached 0)
+; - 7: (?) (set to $80 when in grass, else $0; may be used to draw grass above the sprite)
-; C2x9
+; - 8: delay until next movement (counted downwards, movement status is set to ready if reached 0)
-; C2xA
+; - 9
-; C2xB
+; - A
-; C2xC
+; - B
-; C2xD
+; - C
-; C2xE: sprite image base offset (in video ram, player always has value 1, used to compute c1x2)
+; - D: picture ID
-; C2xF
+; - E: sprite image base offset (in video ram, player always has value 1, used to compute sprite image index)
+; - F
 wSpritePlayerStateData2::  spritestatedata2 wSpritePlayerStateData2
 wSprite01StateData2::      spritestatedata2 wSprite01StateData2
 wSprite02StateData2::      spritestatedata2 wSprite02StateData2
@@ -2577,7 +2579,7 @@ wMissableObjectFlagsEnd::
 
 	ds 7
 
-wd5cd:: ds 1 ; temp copy of c1x2 (sprite facing/anim)
+wd5cd:: ds 1 ; temp copy of SPRITESTATEDATA1_IMAGEINDEX (used for sprite facing/anim)
 
 wMissableObjectList::
 ; each entry consists of 2 bytes