Sideways stairs with diagonal movement - pret/pokecrystal GitHub Wiki

All the stairs in Gen 1 and 2 only go upwards. Gen 3 had a few that go downwards, like the ones descending towards Trainer Tower in FRLG, but it took until Gen 4 with its true 3D maps for sideways stairs to be introduced. ROM hacks have already implemented sideways stairs in Gen 3; this tutorial shows how to implement them in pokecrystal.

(The code for this feature was adapted from Pokémon Brass.)

Contents

  1. Define collision types for sideways stairs
  2. Add a step type for sideways stairs
  3. Add movement commands for diagonal steps
  4. Use the diagonal step movement for the sideways stair collision type
  5. Add sideways stairs to a map

1. Define collision types for sideways stairs

Edit constants/collision_constants.asm:

 ; collision data types (see data/tilesets/*_collision.asm)
 ; TileCollisionTable indexes (see data/collision_permissions.asm)
 DEF COLL_FLOOR             EQU $00
 ...
+DEF COLL_STAIRS_RIGHT_DOWN EQU $d0
+DEF COLL_STAIRS_LEFT_DOWN  EQU $d1
+DEF COLL_STAIRS_RIGHT_UP EQU $d2
+DEF COLL_STAIRS_LEFT_UP  EQU $d3
+DEF COLL_STAIRS_RIGHT_UP_FLAT EQU $d4
+DEF COLL_STAIRS_LEFT_UP_FLAT  EQU $d5
+DEF COLL_STAIRS_RIGHT_UP_MID EQU $d6
+DEF COLL_STAIRS_LEFT_UP_MID  EQU $d7
+DEF COLL_STAIRS_RIGHT_UP_BOTTOM EQU $d8
+DEF COLL_STAIRS_LEFT_UP_BOTTOM  EQU $d9
+DEF COLL_STAIRS_RIGHT_UP_TOP EQU $da
+DEF COLL_STAIRS_LEFT_UP_TOP  EQU $db
+DEF COLL_STAIRS_RIGHT_UP_HALF EQU $dc
+DEF COLL_STAIRS_LEFT_UP_HALF EQU $dd
 DEF COLL_FF                EQU $ff ; garbage

; collision data type nybbles
 LO_NYBBLE_GRASS      EQU $07
 ...
+HI_NYBBLE_DIAGONAL_STAIRS EQU $d0

Diagonal stairs need two collision constants, one for right and one for left, as there would be no sideways stairs that go up or down.

Notice the use of HI_NYBBLE_DIAGONAL_STAIRS. Sideways stairs are implemented much like jump ledges, and are triggered in a similar way; jump ledges all have a HI_NYBBLE_LEDGES grouping them together, so we're doing the same for sideways stairs.

Edit data/collision/collision_permissions.asm:

 TileCollisionTable::
 ; entries correspond to COLL_* constants
 	...
-	db LAND_TILE         ; d0
-	db LAND_TILE         ; d1
-	db LAND_TILE         ; d2
-	db LAND_TILE         ; d3
-	db LAND_TILE         ; d4
-	db LAND_TILE         ; d5
-	db LAND_TILE         ; d6
-	db LAND_TILE         ; d7
-	db LAND_TILE         ; d8
-	db LAND_TILE         ; d9
-	db LAND_TILE         ; da
-	db LAND_TILE         ; db
-	db LAND_TILE         ; dc
-	db LAND_TILE         ; dd

+	db LAND_TILE         ; COLL_STAIRS_RIGHT_DOWN
+	db LAND_TILE         ; COLL_STAIRS_LEFT_DOWN
+	db LAND_TILE         ; COLL_STAIRS_RIGHT_UP
+	db LAND_TILE         ; COLL_STAIRS_LEFT_UP
+	db LAND_TILE         ; COLL_STAIRS_RIGHT_UP_FLAT
+	db LAND_TILE         ; COLL_STAIRS_LEFT_UP_FLAT
+	db LAND_TILE         ; COLL_STAIRS_RIGHT_UP_MID
+	db LAND_TILE         ; COLL_STAIRS_LEFT_UP_MID
+	db WALL_TILE         ; COLL_STAIRS_RIGHT_UP_BOTTOM
+	db WALL_TILE         ; COLL_STAIRS_LEFT_UP_BOTTOM
+	db WALL_TILE         ; COLL_STAIRS_RIGHT_UP_TOP
+	db WALL_TILE         ; COLL_STAIRS_LEFT_UP_TOP
+	db WALL_TILE         ; COLL_STAIRS_RIGHT_UP_HALF
+	db WALL_TILE         ; COLL_STAIRS_LEFT_UP_HALF
 	...

2. Add a step type for sideways stairs

Edit constants/map_object_constants.asm:

 ; StepTypesJumptable indexes (see engine/overworld/map_objects.asm)
 	const_def
 	const STEP_TYPE_00              ; 00
 	...
 	const STEP_TYPE_SKYFALL_TOP     ; 19
+	const STEP_TYPE_NPC_DIAGONAL_STAIRS
+	const STEP_TYPE_PLAYER_DIAGONAL_STAIRS

The player is controlled by, well, the player, and has the camera follow them, so most types of steps have to account for it being an NPC or the player and act accordingly.

Edit engine/overworld/map_objects.asm:

 StepTypesJumptable:
 ; entries correspond to STEP_TYPE_* constants
 	dw ObjectMovementReset ; 00
 	...
 	dw SkyfallTop ; 19
+	dw NPCDiagonalStairs
+	dw PlayerDiagonalStairs

NPCDiagonalStairs:
	call Object28AnonymousJumptable
; anonymous dw
	dw .InitHorizontal
	dw .StepHorizontal
	dw .MaybeVertical
	dw .finish


.InitHorizontal:
	call IncrementObjectStructField28
.StepHorizontal:
	ld hl, OBJECT_STEP_DURATION
	add hl, bc
	ld a, [hl]
	cp 9
	ld a, [wFollowerStairsType]
	jr nc, .firsthalf
.secondhalf:
	and %10
	call nz, .FollowerUpdatePosition
	jr .donehalfcheck
.firsthalf:
	and %100
	call nz, .FollowerUpdatePosition
.donehalfcheck:

	call AddStepVector
	ld hl, OBJECT_STEP_DURATION
	add hl, bc
	dec [hl]
	ret nz
	call CopyNextCoordsTileToStandingCoordsTile
	ld hl, OBJECT_FLAGS2
	add hl, bc
	res 3, [hl]
	jp IncrementObjectStructField28

.FollowerUpdatePosition:
	ld a, [wFollowerGoingUpStairs]
	dec a
	jp UpdateDiagonalStairsPosition

.MaybeVertical:
	ld a, [wFollowerStairsType]
	and %1
	jr nz, .StepVertical
	call IncrementObjectStructField28
	jr .finish

.StepVertical:
	ld a, [wFollowerGoingUpStairs]
	dec a
	ld hl, OBJECT_WALKING
	add hl, bc
	ld [hl], a

	call GetNextTile
	call CopyNextCoordsTileToStandingCoordsTile
	call IncrementObjectStructField28
.finish:
	xor a
	ld [wFollowerGoingUpStairs], a
	ld hl, OBJECT_STEP_DURATION
	add hl, bc
	ld [hl], a

	ld hl, OBJECT_STANDING_TILE
	add hl, bc
	ld a, [hl]
	cp COLL_STAIRS_RIGHT_UP_MID
	jr nc, .no
	xor a
	ld [wFollowerStairsType], a
.no
	ld hl, OBJECT_STEP_TYPE
	add hl, bc
	ld [hl], STEP_TYPE_SLEEP
	ret

PlayerDiagonalStairs:
	call Object28AnonymousJumptable
; anonymous dw
	dw .PreLoadMapParts0
	dw .PreLoadMapParts1
	dw .PreLoadMapParts2
	dw .PreLoadMapParts3
	dw .PreLoadMapParts4
	dw .PreLoadMapParts5
	dw .InitHorizontal
	dw .StepHorizontal
	dw .MaybeVertical
	dw .finish

.PreLoadMapParts0:
	push bc
	ld a, [wPlayerGoingUpStairs]
	dec a
	farcall UpdateOverworldMap.SkipDirection
	pop bc
	jp IncrementObjectStructField28

.PreLoadMapParts1:
	push bc
	ld a, [wPlayerGoingUpStairs]
	dec a
	farcall UpdateOverworldMap.SkipDirection
	pop bc
	jp IncrementObjectStructField28

.PreLoadMapParts2:
	push bc
	ld a, [wPlayerGoingLeftRightStairs]
	cp FACE_RIGHT
	ld a, RIGHT
	jr z, .done2
	dec a ; LEFT
.done2
	farcall UpdateOverworldMap.SkipDirection
	pop bc
	jp IncrementObjectStructField28

.PreLoadMapParts3:
	push bc
	ld a, [wPlayerGoingUpStairs]
	and UP | DOWN
	farcall UpdateOverworldMap.SkipDirection
	pop bc
	jp IncrementObjectStructField28

.PreLoadMapParts4:
	push bc
	ld a, [wPlayerGoingUpStairs]
	and UP | DOWN
	farcall UpdateOverworldMap.SkipDirection
	pop bc
	jp IncrementObjectStructField28

.PreLoadMapParts5:
	push bc
	ld a, [wPlayerGoingLeftRightStairs]
	cp FACE_RIGHT
	ld a, LEFT
	jr z, .done5
	inc a ; RIGHT
.done5
	farcall UpdateOverworldMap.SkipDirection
	pop bc
	jp IncrementObjectStructField28

.InitHorizontal:
	ld hl, wPlayerStepFlags
	set 7, [hl]
	call IncrementObjectStructField28
.StepHorizontal:
	ld hl, OBJECT_STEP_DURATION
	add hl, bc
	ld a, [hl]
	cp 9
	ld a, [wPlayerStairsType]
	jr nc, .firsthalf
.secondhalf:
	and %10
	call nz, .PlayerUpdatePosition
	jr .donehalfcheck
.firsthalf:
	and %100
	call nz, .PlayerUpdatePosition
.donehalfcheck:
	call UpdatePlayerStep
	ld hl, OBJECT_STEP_DURATION
	add hl, bc
	dec [hl]
	ret nz
	call CopyNextCoordsTileToStandingCoordsTile
	ld hl, OBJECT_FLAGS2
	add hl, bc
	res 3, [hl]
	ld hl, wPlayerStepFlags
	set 6, [hl]
	set 4, [hl]
	jp IncrementObjectStructField28

.PlayerUpdatePosition:
	call UpdatePlayerStepVertical
	ld a, [wPlayerGoingUpStairs]
	dec a
	jp UpdateDiagonalStairsPosition

.MaybeVertical:
	ld a, -1
	ld [wPlayerStepDirection], a

	ld a, [wPlayerStairsType]
	and %1
	jr nz, .StepVertical
	call IncrementObjectStructField28
	jr .finish

.StepVertical:
	ld hl, wPlayerStepFlags
	set 7, [hl]
	set 5, [hl]
	set 4, [hl]
	ld a, [wPlayerGoingUpStairs]
	dec a
	ld hl, OBJECT_WALKING
	add hl, bc
	ld [hl], a
	ld [wPlayerStepDirection], a

	call GetNextTile
	call CopyNextCoordsTileToStandingCoordsTile
	call IncrementObjectStructField28
.finish:
	farcall UpdatePlayerCoords
	ld hl, wPlayerStepFlags
	set 6, [hl]
	xor a
	ld [wPlayerGoingUpStairs], a
	ld hl, OBJECT_STANDING_TILE
	add hl, bc
	ld a, [hl]
	cp COLL_STAIRS_RIGHT_UP_MID
	jr nc, .no
	xor a
	ld [wPlayerStairsType], a
.no
	ld hl, OBJECT_STEP_TYPE
	add hl, bc
	ld [hl], STEP_TYPE_SLEEP
	ret

UpdateDiagonalStairsPosition:
	and a
	ld e, 1
	jr z, .goingdown
	ld e, -1
.goingdown

	ld hl, OBJECT_SPRITE_Y
	add hl, bc
	ld a, [hl]
	add e
	ld [hl], a
	ret

UpdatePlayerStepVertical:
	ld a, [wPlayerGoingUpStairs]
	dec a
	ld e, 1
	jr z, .goingdown
	ld e, -1
.goingdown
	ld a, [hSCY]
	add e
	ld [hSCY], a
	ld a, [wPlayerBGMapOffsetY]
	sub e
	ld [wPlayerBGMapOffsetY], a
	ld hl, wPlayerStepFlags
	set 5, [hl]
	ret

This is where the step actually happens. First it makes the game load the tiles to the left and up, and then moves the player object and camera diagonal visually, whereas as far as the game is concerned they're still on the tile grid, even if visually they may appear to be between two tiles.

3. Add movement commands for diagonal steps

Edit macros/scripts/movement.asm:

 ; MovementPointers indexes (see engine/overworld/movement.asm)
 	enum_start 0, +4

 ; Directional movements

 	enum movement_turn_head ; $00
 turn_head: MACRO
 	db movement_turn_head | \1
 ENDM

 ...

 	enum movement_fast_jump_step ; $34
 fast_jump_step: MACRO
 	db movement_fast_jump_step | \1
 ENDM
+
+	enum movement_stairs_step
+stairs_step: MACRO
+	db movement_stairs_step | \1
+ENDM

 __enumdir__ = +1

Then edit engine/overworld/movement.asm:

 MovementPointers:
 ; entries correspond to macros/scripts/movement.asm enumeration
 	dw Movement_turn_head_down        ; 00
 	...
 	dw Movement_fast_jump_step_right  ; 37
+	dw Movement_stairs_step_down
+	dw Movement_stairs_step_up
+	dw Movement_stairs_step_left
+	dw Movement_stairs_step_right
 	dw Movement_remove_sliding        ; 38
 	...

+Movement_stairs_step_down:
+	ld a, STEP_WALK << 2 | DOWN
+	jp DiagonalStairsStep
+
+Movement_stairs_step_up:
+	ld a, STEP_WALK << 2 | UP
+	jp DiagonalStairsStep
+
+Movement_stairs_step_left:
+	ld a, STEP_WALK << 2 | LEFT
+	jp DiagonalStairsStep
+
+Movement_stairs_step_right:
+	ld a, STEP_WALK << 2 | RIGHT
+	jp DiagonalStairsStep
+
+DiagonalStairsStep:
+	call InitStep
+	ld hl, OBJECT_1F
+	add hl, bc
+	ld [hl], $0
+
+	ld hl, OBJECT_ACTION
+	add hl, bc
+	ld [hl], OBJECT_ACTION_STEP
+
+	ld hl, wCenteredObject
+	ldh a, [hMapObjectIndex]
+	cp [hl]
+	jr z, .player
+
+	ld hl, OBJECT_STEP_TYPE
+	add hl, bc
+	ld [hl], STEP_TYPE_NPC_DIAGONAL_STAIRS
+	ret
+
+.player
+	ld hl, OBJECT_STEP_TYPE
+	add hl, bc
+	ld [hl], STEP_TYPE_PLAYER_DIAGONAL_STAIRS
+	ret

Even though diagonal stairs only go in two directions, right and left, they need their macros and pointers placed with the other directional step types to be triggered correctly. It is here where the game determines if it should be making the player or an NPC take the step.

4. Use the diagonal step movement for the sideways stair collision type

Edit constants/map_object_constants.asm again:

 ; DoPlayerMovement.DoStep arguments (see engine/overworld/player_movement.asm)
 	const_def
 	const STEP_SLOW          ; 0
 	...
 	const STEP_WALK_IN_PLACE ; 7
+	const STEP_DIAGONAL_STAIRS

Then edit engine/overworld/player_movement.asm:

 DoPlayerMovement::

 	...

 .Normal:
 	call .CheckForced
 	call .GetAction
 	call .CheckTile
 	ret c
 	call .CheckTurning
 	ret c
 	call .TryStep
 	ret c
 	call .TryJump
 	ret c
+	call .TryDiagonalStairs
+	ret c
 	call .CheckWarp
 	ret c
 	jr .NotMoving

 	...

 .Ice:
 	call .CheckForced
 	call .GetAction
 	call .CheckTile
 	ret c
 	call .CheckTurning
 	ret c
 	call .TryStep
 	ret c
 	call .TryJump
 	ret c
+	call .TryDiagonalStairs
+	ret c
 	call .CheckWarp
 	ret c
 	ld a, [wWalkingDirection]
 	cp STANDING
 	jr z, .HitWall
 	call .BumpSound
 .HitWall:
 	call .StandInPlace
 	xor a
 	ret

 .TryJump:
 	ld a, [wPlayerStandingTile]
 	ld e, a
 	and $f0
 	cp HI_NYBBLE_LEDGES
 	jr nz, .DontJump

 	ld a, e
 	and 7
 	ld e, a
 	ld d, 0
 	ld hl, .data_8021e
 	add hl, de
 	ld a, [wFacingDirection]
 	and [hl]
 	jr z, .DontJump

 	ld de, SFX_JUMP_OVER_LEDGE
 	call PlaySFX
 	ld a, STEP_LEDGE
 	call .DoStep
 	ld a, 7
 	scf
 	ret

 .DontJump:
 	xor a
 	ret

 .data_8021e
 	db FACE_RIGHT             ; COLL_HOP_RIGHT
 	db FACE_LEFT              ; COLL_HOP_LEFT
 	db FACE_UP                ; COLL_HOP_UP
 	db FACE_DOWN              ; COLL_HOP_DOWN
 	db FACE_RIGHT | FACE_DOWN ; COLL_HOP_DOWN_RIGHT
 	db FACE_DOWN | FACE_LEFT  ; COLL_HOP_DOWN_LEFT
 	db FACE_UP | FACE_RIGHT   ; COLL_HOP_UP_RIGHT
 	db FACE_UP | FACE_LEFT    ; COLL_HOP_UP_LEFT
+
.TryDiagonalStairs:
	ld a, [wPlayerGoingUpStairs]
	and a
	jr nz, .DontJumpOrDiagonalStairs

	ld a, OBJECT_STANDING_TILE
	predef GetCenteredObjectStructParam
	ld e, a
	and $f0
	cp HI_NYBBLE_DIAGONAL_STAIRS
	jr nz, .DontJumpOrDiagonalStairs

	ld a, e
	and $0f
	ld e, a
	ld d, 0
	ld hl, .FacingStairsTable
	add hl, de
	add hl, de
	add hl, de
	ld a, [wFacingDirection]
	and [hl]
	jr z, .DontJumpOrDiagonalStairs
	inc hl
	cp FACE_LEFT
	ld a, [hli]
	ld b, [hl]
	jr z, .dont_swap
	swap a
	swap b
.dont_swap
	and $f
	ld [wPlayerGoingUpStairs], a
	ld a, b
	and $f
	ld [wPlayerStairsType], a

	ld a, [wFacingDirection]
	ld [wPlayerGoingLeftRightStairs], a

	ld a, STEP_DIAGONAL_STAIRS
	call .DoStep
	ld a, 7
	scf
	ret

stairtable: macro
	db \1
	dn \2, \3
	dn \4, \5
endm

.FacingStairsTable:
	stairtable FACE_RIGHT, 				DOWN+1, DOWN+1,  %11,  %11 ;COLL_STAIRS_RIGHT_DOWN
	stairtable FACE_LEFT, 				DOWN+1, DOWN+1,  %11,  %11 ;COLL_STAIRS_LEFT_DOWN
	stairtable FACE_RIGHT, 				UP+1, 	UP+1,  	 %10,  %10 ;COLL_STAIRS_RIGHT_UP
	stairtable FACE_LEFT, 				UP+1, 	UP+1, 	 %10,  %10 ;COLL_STAIRS_LEFT_UP
	stairtable FACE_RIGHT | FACE_LEFT,	UP+1, 	DOWN+1,	 %10,  %10 ;COLL_STAIRS_RIGHT_UP_FLAT
	stairtable FACE_RIGHT | FACE_LEFT,	DOWN+1, UP+1,  	 %10,  %10 ;COLL_STAIRS_LEFT_UP_FLAT
	stairtable FACE_RIGHT | FACE_LEFT,	UP+1, 	DOWN+1,	%111, %111 ;COLL_STAIRS_RIGHT_UP_MID
	stairtable FACE_RIGHT | FACE_LEFT,	DOWN+1, UP+1, 	%111, %111 ;COLL_STAIRS_LEFT_UP_MID
	stairtable FACE_RIGHT | FACE_LEFT,	UP+1, 	DOWN+1,	%111, %100 ;COLL_STAIRS_RIGHT_UP_BOTTOM
	stairtable FACE_RIGHT | FACE_LEFT,	DOWN+1, UP+1, 	%100, %111 ;COLL_STAIRS_LEFT_UP_BOTTOM
	stairtable FACE_RIGHT | FACE_LEFT,	UP+1, 	DOWN+1, %101, %111 ;COLL_STAIRS_RIGHT_UP_TOP
	stairtable FACE_RIGHT | FACE_LEFT,	DOWN+1, UP+1, 	%111, %101 ;COLL_STAIRS_LEFT_UP_TOP
	stairtable FACE_RIGHT | FACE_LEFT,	UP+1, 	DOWN+1, %101, %100 ;COLL_STAIRS_RIGHT_UP_HALF
	stairtable FACE_RIGHT | FACE_LEFT,	DOWN+1, UP+1, 	%100, %101 ;COLL_STAIRS_LEFT_UP_HALF

 .Steps:
 ; entries correspond to STEP_* constants
 	dw .SlowStep
 	dw .NormalStep
 	dw .FastStep
 	dw .JumpStep
 	dw .SlideStep
 	dw .TurningStep
 	dw .BackJumpStep
 	dw .FinishFacing
+	dw .DiagonalStairsStep

 .SlowStep:
 	slow_step DOWN
 	slow_step UP
 	slow_step LEFT
 	slow_step RIGHT
 	...
 .FinishFacing:
 	db $80 | DOWN
 	db $80 | UP
 	db $80 | LEFT
 	db $80 | RIGHT
+.DiagonalStairsStep:
+	stairs_step DOWN
+	stairs_step UP
+	stairs_step LEFT
+	stairs_step RIGHT

Now for actually triggering the step. Firstly is obviously just having the game try it among the other types of steps, and since it is extremely similar to the jump step in essence it is triggered in much the same way. It checks for the high nybble to see if it is the one the stair steps have, and if it does then it checks if the player is facing the direction matching the stairs to go up or down. If they do, it loads the step and then executes everything that was coded above.

5. Add sideways stairs to a map

Here are some sideways stair tiles:

Screenshot

Let's say you want to add some sideways stairs to the cliffs on Route 45. Since maps/Route45.blk uses the johto tileset, here's what that would involve:

  1. Add the stair tiles to gfx/tilesets/johto.png
  2. Assign the GRAY color to those tiles in gfx/tilesets/johto_palette_map.asm
  3. Design sideways stair blocks in data/tilesets/johto_metatiles.bin
  4. Assign the DIAGONAL_STAIRS_LEFT and DIAGONAL_STAIRS_RIGHT collision types to those blocks in data/tilesets/johto_collision.asm
  5. Redesign maps/Route45.blk to use the sideways stair blocks

You can use Polished Map to edit maps and tilesets; refer to the new map and new tileset tutorials for more information.

Now test it out!

Screenshot

Have you gone and looked at the tutorials on how to edit blocks and tilesets? Great! Now to explain how to use DIAGONAL_STAIRS_RIGHT and DIAGONAL_STAIRS_LEFT in a map properly. When these collision constants are placed on a tile with a WALL collision adjacent in the direction they indicate, they will trigger the diagonal stairs step coded and defined above. You will note that these do not have any definition for going up or down? Well that's because it is decided by which half of the mettatile/block you place the collision on.

If DIAGONAL_STAIRS_RIGHT is placed in the top half of a block and the step is triggered, then the player will move right two steps and then down one. If it's in the bottom half, it will move the player right two steps and then up one. The left direction works similarly.

To have a full set of stairs that you can walk up and down both ways, it requires four blocks with collision set accordingly: two blocks per direction of stairs, since the entire "structure" of sorts requires the space of three walkable tiles to function.

tilecoll FLOOR, FLOOR, FLOOR, DIAGONAL_STAIRS_RIGHT
tilecoll WALL, DIAGONAL_STAIRS_LEFT, WALL, FLOOR

This would be needed for a set of stairs going up to the right.

tilecoll DIAGONAL_STAIRS_RIGHT, WALL, FLOOR, WALL
tilecoll FLOOR, FLOOR, DIAGONAL_STAIRS_LEFT, FLOOR

This would be needed for a set of stairs going up to the left.