Creating a retro-style game with Jetpack Compose: movement
Tags: kotlin, jetpackcompose, gamedev
Published: 2021-07-01 14:41:58

Welcome to the second part of *Creating a retro-style game with Jetpack Compose*. In this installment we will take a look at how to move players, enemies, and other objects.

### Moving around

To understand how this works, please recall that this series uses Jetpack Compose to emulate the text or pseudo graphics mode of home computers. The screen is divided in a grid, often 40 by 25 cells. Each cell displays one character (a byte). In text mode, the look of the character is defined by the character set in use. In pseudo graphics mode each character is represented by a small bitmap, usually 8 by 8 pixels. 

We focus on text mode. The game screen of Compose Dash consists of 40 columns and 14 rows. So we can address 560 cells. This can be done in two ways:

- **By index**: the cells are numbered from 0 to 559. The first row contains cells 0 to 39. The second 40 to 79. And so on.
- **By location**: Here we specify the row (or y) and column (x)

![The game screen is a grid with cells](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xolx7ct23crcfypvo2br.png)

To convert between these two representations is really simple. If we have a location consisting of `x` and `y` we get the index through `y * 40 + x`. The other way round is equally easy: `x = index % 40` and `y = index / 40`. 

Now, what does this mean regarding movement? Generally speaking, depending on the direction `x`, `y`, or both change. To move upward (north) `y` is decremented by 1. To go south, we increment `y` by 1. The same applies to `x` regarding west (-1) and east (+1). If we want to implement movement using the index we add or subtract 40 to go north or south. To go west or east we subtract or add 1. Let's see how I make use of this in Compose Dash. Please recall that currently each cell is represented through a `Text()`.

```kotlin
Text(
  modifier = Modifier
    .background(background)
    .clickable {
      movePlayerTo(levelData, index, gemsCollected)
    },
  text = symbol.unicodeToString()
)
```

When a cell is clicked `movePlayer()` is invoked. It receives the `index` of the location to move to. Please recall that I have defined the game screen like this:

```kotlin
private fun createLevelData(): SnapshotStateList<Char> {
  val data = mutableStateListOf<Char>()
  var rows = 0
  level.split("\n").forEach {
    if (it.length != COLUMNS)
      throw RuntimeException("length of row $rows is not $COLUMNS")
    data.addAll(it.toList())
    rows += 1
  }
  if (rows != ROWS)
    throw RuntimeException("number of rows is not $ROWS")
  return data
}
```

We parse a multiline string that contains the level data and convert it to a `SnapshotStateList<Char>`. This list is used inside `LazyVerticalGrid()` and passed to `itemsIndexed()`. Now let's take a look at `movePlayer()`. Please remember, it is passed an `index` which represents the new location.

```kotlin
private fun movePlayerTo(
  levelData: SnapshotStateList<Char>,
  desti: Int,
  gemsCollected: MutableState<Int>
) {
  val start = levelData.indexOf(CHAR_PLAYER)
  if (start == desti) return
  val startX = start % COLUMNS
  val startY = start / COLUMNS
  val destiX = desti % COLUMNS
  val destiY = desti / COLUMNS
  val dirX = if (destiX > startX) 1 else -1
  val dirY = if (destiY > startY) 1 else -1
  var current = start
  lifecycleScope.launch {
    var x = startX
    var y = startY
    while (current != -1 && y != destiY) {
      current = walk(levelData, current, x, y, gemsCollected)
      y += dirY
    }
    while (current != -1 && current != desti) {
      current = walk(levelData, current, x, y, gemsCollected)
      x += dirX
    }
  }
}
```

To calculate the direction it is not enough to know the new location. We also require the *current* one. I do it like this: `val start = levelData.indexOf(CHAR_PLAYER)` (a rather simplistic approach, by the way). As there is always exactly one player on the game screen I can search for it in the `levelData` list. Another (and possibly faster) way would be to just store it in some variable. Now, let's look at movement.

`if (start == desti) return` means: if there has been no movement we don't have anything to do.

```kotlin
val dirX = if (destiX > startX) 1 else -1
val dirY = if (destiY > startY) 1 else -1
```

By using `index` we move through simple arithmetics. The two lines above make this particularly convenient as we need not bother if we want to add or subtract. We can always add `dirX` or `dirY` because if we go upward or left, the value is -1. Adding -1 is the same as subtracting 1.

### Detecting (and reacting to) collisions

Compose Dash splits movement into two steps. First we walk along the y axis (vertically), then along the x axis (horizontally). Movement takes place until we reach the desired location on the corresponding axis or the index (stored in `current`) is -1. 

```kotlin
var x = startX
var y = startY
while (current != -1 && y != destiY) {
  current = walk(levelData, current, x, y, gemsCollected)
  y += dirY
}
while (current != -1 && current != desti) {
  current = walk(levelData, current, x, y, gemsCollected)
  x += dirX
}
```

So, `movePlayerTo()` orchestrates the movement of the player. Inside a `lifecycleScope.launch {` a function named `walk()` is invoked repeatedly.

But why do I need a coroutine here? Well, movement should take *some time*. As `movePlayerTo()` has been called from a composable it must return as soon as it can. That's why the actual movement must take place asynchronously. And, as you shall see shortly, moving around may well trigger other concurrent tasks. But before that, let's see what `walk()`does.

```kotlin
private suspend fun walk(
  levelData: SnapshotStateList<Char>,
  current: Int,
  x: Int,
  y: Int,
  gemsCollected: MutableState<Int>
): Int {
  val newPos = (y * COLUMNS) + x
  when (levelData[newPos]) {
    CHAR_GEM -> {
      gemsCollected.value += 1
    }
    CHAR_ROCK, CHAR_BRICK -> {
      return -1
    }
  }
  levelData[current] = ' '
  levelData[newPos] = CHAR_PLAYER
  delay(200)
  if (current != -1) {
    freeFall(levelData, current - COLUMNS, CHAR_ROCK)
    freeFall(levelData, current - COLUMNS, CHAR_GEM)
  }
  return newPos
}
```

The main idea of this function is to check the value in `levelData` at the `current` position and act accordingly. For example, detecting a collision with a rock or brick is as simple as

```kotlin
CHAR_ROCK, CHAR_BRICK -> {
 return -1
}
```

To control the duration of the movement, `delay(200)` makes sure that the function does not return too early.

### Objects and enemies

If the new location is not -1 (the player has moved in some direction) I invoke yet another function called `freeFall()`. It let's rocks or gems fall down. Have you noticed that I pass `current - COLUMNS`? This means *check what's above the player*. So we trigger the movement of objects that are directly above the current location.

```kotlin
private suspend fun freeFall(
  levelData: SnapshotStateList<Char>,
  current: Int,
  what: Char
) {
  if (levelData[current] == what) {
    lifecycleScope.launch {
      delay(200)
      freeFall(levelData, current - COLUMNS, what)
      val x = current % COLUMNS
      var y = current / COLUMNS + 1
      var pos = current
      while (y < ROWS) {
        val newPos = y * COLUMNS + x
        when (levelData[newPos]) {
          CHAR_BRICK, CHAR_ROCK, CHAR_GEM -> {
            break
          }
        }
        levelData[pos] = ' '
        levelData[newPos] = what
        y += 1
        pos = newPos
        delay(200)
      }
    }
  }
}
```

Movement happens inside `lifecycleScope.launch {`. After a short delay `freeFall()` is invoked with a location *above the current object*. This recursion is necessary to have **everything** above the player fall down eventually. Besides that, the movement of the current object takes place. Here, too, we have some collision checks to determine the fate of the player, rock, or gem.

### Conclusion

So far our player is not hurt by rocks (which should probably be the case ). We will turn our attention to this in the next episode. And we will introduce other enemies - seeing the rocks as enemies is probably far fetched given that they currently do not hurt the player. 🤣  Is there anything else you would like to see covered? Please do not hesitate to share your thoughts in the comments.

---

[Source](https://github.com/tkuenneth/compose_dash)