path: root/Sideways-stairs-with-diagonal-movement.md

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](https://www.pokecommunity.com/showthread.php?t=378934) in Gen 3; this tutorial shows how to implement them in pokecrystal.

(The code for this feature was adapted from [Pokémon Brass](https://github.com/WasabiRaptor/pokebrass).)


## Contents

1. [Define collision types for sideways stairs](#1-define-collision-types-for-sideways-stairs)
2. [Add a step type for sideways stairs](#2-add-a-step-type-for-sideways-stairs)
3. [Add movement commands for diagonal steps](#3-add-movement-commands-for-diagonal-steps)
4. [Use the diagonal step movement for the sideways stair collision type](#4-use-the-diagonal-step-movement-for-the-sideways-stair-collision-type)
5. [Add sideways stairs to a map](#5-add-sideways-stairs-to-a-map)


## 1. Define collision types for sideways stairs

Edit [constants/collision_constants.asm](../blob/master/constants/collision_constants.asm):

```diff
 ; collision data types (see data/tilesets/*_collision.asm)
 ; TileCollisionTable indexes (see data/collision_permissions.asm)
 COLL_FLOOR             EQU $00
 ...
+COLL_DIAGONAL_STAIRS_RIGHT EQU $d0
+COLL_DIAGONAL_STAIRS_LEFT  EQU $d1
 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_permissions.asm](../blob/master/data/collision_permissions.asm):

```diff
 TileCollisionTable::
 ; entries correspond to COLL_* constants
 	...
-	NONTALKABLE  LANDTILE ; d0
-	NONTALKABLE  LANDTILE ; d1
+	NONTALKABLE  LANDTILE ; COLL_DIAGONAL_STAIRS_RIGHT
+	NONTALKABLE  LANDTILE ; COLL_DIAGONAL_STAIRS_LEFT
 	...
```


## 2. Add a step type for sideways stairs

Edit [constants/map_object_constants.asm](../blob/master/constants/map_object_constants.asm):

```diff
 ; 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](../blob/master/engine/overworld/map_objects.asm):

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

```diff
+NPCDiagonalStairs:
+	; TODO
+	ret
+
+PlayerDiagonalStairs:
+	call Field1cAnonymousJumptable
+; anonymous dw
+	dw .InitHorizontal1
+	dw .StepHorizontal
+	dw .InitHorizontal2
+	dw .StepHorizontal
+	dw .InitVertical
+	dw .StepVertical
+
+.InitHorizontal2:
+	call GetNextTile
+.InitHorizontal1:
+	ld hl, wPlayerStepFlags
+	set 7, [hl]
+	call IncrementObjectStructField1c
+.StepHorizontal:
+	call UpdateDiagonalStairsPosition
+	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 IncrementObjectStructField1c
+
+.InitVertical:
+ 	ld hl, OBJECT_ACTION
+	add hl, bc
+	ld [hl], OBJECT_ACTION_STAND
+
+; If you start on the bottom half of a block, you go up;
+; if you start on the top half, you go down.
+	ld a, [wMetatileStandingY]
+	and a
+	ld a, DOWN
+	jr z, .got_dir
+	ld a, UP
+.got_dir
+	ld hl, OBJECT_DIRECTION_WALKING
+	add hl, bc
+	ld [hl], a
+
+	call GetNextTile
+	ld hl, wPlayerStepFlags
+	set 7, [hl]
+	call IncrementObjectStructField1c
+.StepVertical:
+	call UpdateDiagonalStairsPosition
+	call UpdatePlayerStep
+	ld hl, OBJECT_STEP_DURATION
+	add hl, bc
+	dec [hl]
+	ret nz
+	ld hl, wPlayerStepFlags
+	set 6, [hl]
+	call CopyNextCoordsTileToStandingCoordsTile
+	ld hl, OBJECT_STEP_TYPE
+	add hl, bc
+	ld [hl], STEP_TYPE_SLEEP
+	ret
+
+UpdateDiagonalStairsPosition:
+	ld a, [wMetatileStandingY]
+	and a
+	ld e, 1
+	jr z, .goingdown
+	ld e, -1
+.goingdown
+	ld hl, OBJECT_SPRITE_Y_OFFSET
+	add hl, bc
+	ld a, [hl]
+	add e
+	ld [hl], a
+	ret
```

This is where the step actually happens. The object never actually moves diagonally, but instead moves horizontally in the direction they entered from, and then vertically once.

While moving horizontally, the Y offset of the sprite is moved up or down depending on if the object is in the top half or bottom half of the mettatile/block where they triggered the step. This gives the illusion of moving diagonally.

While moving vertically, the object is then met back up with its sprite, removing the offset smoothly by doing the opposite to the offset as the object is now moving vertically towards it. During this time the object technically should not be moving while technically it is, so we set its action to standing so it does not play the step animation while waiting for itself to catch up, or in the player's case, for the camera to catch up.

The movement of going horizontal twice and vertical once might be noticeable by the player due to the camera movement not being "diagonal" like the sprite's. Theoretically the camera in pokecrystal can move diagonally, and I had worked to try and make it do so, but this causes de-sync with the screen and the player object so that it is no longer centered, and will load tiles and blocks incorrectly on the edge of the screen that would normally be outside the visible area.


## 3. Add movement commands for diagonal steps

Edit [macros/scripts/movement.asm](../blob/master/macros/scripts/movement.asm):

```diff
 ; 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](../blob/master/engine/overworld/movement.asm):

```diff
 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
 	...
```

```diff
+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, [hMapObjectIndexBuffer]
+	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](../blob/master/constants/map_object_constants.asm) again:

```diff
 ; 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](../blob/master/engine/overworld/player_movement.asm):

```diff
 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
```

```diff
 .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, [wPlayerStandingTile]
+	ld e, a
+	and $f0
+	cp HI_NYBBLE_DIAGONAL_STAIRS
+	jr nz, .DontDiagonalStairs
+
+	ld a, e
+	and 7
+	ld e, a
+	ld d, 0
+	ld hl, .FacingStairsTable
+	add hl, de
+	ld a, [wFacingDirection]
+	and [hl]
+	jr z, .DontDiagonalStairs
+
+	ld a, STEP_DIAGONAL_STAIRS
+	call .DoStep
+	ld a, 7
+	scf
+	ret
+
+.FacingStairsTable:
+	db FACE_RIGHT
+	db FACE_LEFT
+
+.DontDiagonalStairs:
+	xor a
+	ret
```

```diff
 .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](screenshots/sideways-stair-tiles.png)

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

1. Add the stair tiles to [gfx/tilesets/johto.png](../blob/master/gfx/tilesets/johto.png)
2. Assign the `GRAY` color to those tiles in [gfx/tilesets/johto_palette_map.asm](../blob/master/gfx/tilesets/johto_palette_map.asm)
3. Design sideways stair blocks in [data/tilesets/johto_metatiles.bin](../blob/master/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](../blob/master/data/tilesets/johto_collision.asm)
5. Redesign [maps/Route45.blk](../blob/master/maps/Route45.blk) to use the sideways stair blocks

You can use [Polished Map](https://github.com/Rangi42/polished-map) to edit maps and tilesets; refer to the [new map](Add-a-new-map-and-landmark) and [new tileset](Add-a-new-tileset) tutorials for more information.

Now test it out!

![Screenshot](screenshots/sideways-stairs.png)

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.