Platformers

Collisions reports which colliders overlap, and that is all it does for ordinary colliders: a hero that falls onto a roof sinks into it until a system pushes it back out. For characters that stand on floors, stop at walls and jump through ledges, klyph has two components on top of the same colliders. A Solid is a wall, floor or ledge, still or moving. A KinematicBody moves in every fixed step and stops at the solids in its way. There is no physics engine behind them: no mass, no bouncing and no slopes, only upright boxes that stop exactly where they touch.

What makes a platformer feel good stays in your code, because every game tunes it differently: gravity, acceleration, jump height, coyote time and the jump buffer. This page builds a hero with all of them in one FIXED_UPDATE system. The snippets are code for the setup block of runApp.

Solids

A Solid goes on an entity with a Transform and a Collider whose shape is a Shape.Box. The box is placed as for any collider: centered on the entity's position plus the collider's offset, scaled by the transform unless scalesWithTransform is false. A level built from data is easiest to write by edges, so this helper turns edges into a solid:

/** Spawns a roof, a wall or a ledge of the level from its edges. */
fun App.spawnSolid(left: Float, top: Float, right: Float, bottom: Float, passable: Passable = Passable.NEVER): Entity =
    commands.spawn {
        add(Transform, Transform(x = (left + right) / 2, y = (top + bottom) / 2))
        add(Sprite, Sprite(assets.whitePixel, width = right - left, height = bottom - top, color = Color(0.3f, 0.3f, 0.4f)))
        add(Collider, Collider(Shape.Box(width = right - left, height = bottom - top)))
        add(Solid, Solid(passable))
    }
// Two roofs with a gap between them, and a steel ledge over the gap.
spawnSolid(left = 0f, top = 400f, right = 900f, bottom = 1000f)
spawnSolid(left = 1100f, top = 360f, right = 1800f, bottom = 1000f)
spawnSolid(left = 860f, top = 300f, right = 1140f, bottom = 312f, passable = Passable.FROM_BELOW)

Solid(passable = Passable.FROM_BELOW) is a one-way ledge. A body that moves down onto it, with its feet at or above the ledge's top before the move, lands on it. A body that jumps up through it, or walks into it from the side, passes through. The default, Passable.NEVER, stops bodies from every side.

A solid on a circle collider, or without a collider, is a setup error: the next body move throws IllegalStateException naming the entity. Solids are also ordinary colliders, so they still take part in Overlap events and the overlap queries, and their layers and masks work as on the Collisions and particles page.

app.collisions keeps the solids in a grid of its own and checks them against the world once per fixed step and once per frame, which costs one pass over the solids, and rebuilds the grid only when a solid was added or removed or started or stopped moving. Moving solids live in a second hash grid, rebuilt over each moving solid's whole move, so a few moving platforms never rebuild the first. Moving platforms below shows how a solid moves.

The body

A KinematicBody goes on an entity with a Transform and a box Collider. Its dx and dy are its speed in world units per second, positive to the right and down. The body moves its Transform in world space, so it cannot have a parent.

val hero = commands.spawn {
    add(Transform, Transform(x = 100f, y = 380f - Collisions.CONTACT_GAP))
    add(Sprite, Sprite(assets.whitePixel, width = 24f, height = 40f, color = Color.YELLOW))
    add(Collider, Collider(Shape.Box(width = 24f, height = 40f)))
    add(KinematicBody, KinematicBody())
    // Drawn between its last two steps, so it moves smoothly at any frame rate.
    add(Interpolated, Interpolated)
}

In every fixed step, after the FIXED_UPDATE systems and after every Velocity, the engine moves each body across by dx times the step, stopping at the first solid it would enter, and then up or down by dy in the same way. A stop leaves a gap of Collisions.CONTACT_GAP, 0.01 units, between the body and the solid, so the body never overlaps it and walking along a floor does not count as running into it, and zeroes dx or dy. Moving across and then up or down is exact for upright boxes, and a fast body cannot pass through a thin floor, because each move is swept.

An entity with both a Velocity and a KinematicBody is an error: the body's speed is its own dx and dy.

Running and jumping

The engine adds no gravity, so the system that reads the input adds it to dy. It runs in FIXED_UPDATE, before the engine's move in the same step, and reads the jump there with isJustPressed, which inside FIXED_UPDATE counts steps, so each press reaches exactly one step. The contact flags it reads are the ones the previous step's move left, except that isOnFloor turns false as soon as dy is set upward: once the system has jumped, the body no longer stands, before it has moved.

var coyote = 0f
var jumpBuffer = 0f
addSystem(Phase.FIXED_UPDATE) { app ->
    val body = app.world.get(hero, KinematicBody)
    val keyboard = app.input.keyboard
    val dt = app.time.deltaSeconds
    body.dx = keyboard.axis(Scancode.A, Scancode.D) * 320f
    // Coyote time: a jump still works a tenth of a second after running off an edge.
    coyote = if (body.isOnFloor) 0.1f else coyote - dt
    // Jump buffer: a press a tenth of a second before landing still jumps when it lands.
    val pressed = keyboard.isJustPressed(Scancode.SPACE) || app.input.gamepads.isJustPressed(GamepadButton.SOUTH)
    jumpBuffer = if (pressed) 0.1f else jumpBuffer - dt
    if (jumpBuffer > 0f && coyote > 0f) {
        body.dy = -700f
        coyote = 0f
        jumpBuffer = 0f
    }
    // Letting go of the button early makes a short hop.
    val gravity = if (body.dy < 0f && !keyboard.isDown(Scancode.SPACE)) 5400f else 1800f
    body.dy = minOf(body.dy + gravity * dt, 900f)
}

Coyote time lets a jump start a few steps after the hero ran off an edge, and the jump buffer remembers a press made just before landing. Both are two timers in the system. The short hop is stronger gravity while the hero rises with the button up. Change the numbers until it feels right.

Contacts

After every move the body says what it touched:

PropertyMeaning
isOnFloorThe body stands: the move ended on a floor, landing on it or found by the floor check, and dy has not been set upward since.
isOnWallThe move ran into a wall moving across.
wallNormalX-1 for a wall on the right, 1 for one on the left, 0 with no wall: the way to push off for a wall jump.
isOnCeilingThe move ran into a ceiling moving up.
floorOrNullThe solid the body stands on, or null while isOnFloor is false.
hasLandedThe move came down onto a floor and the body did not stand before it: true for one step per landing.
landingSpeedThe downward speed that landing arrived with, kept because the landing zeroes dy; 0 without a landing.
wasPushedOutThe move began by pushing the body out of a solid it overlapped, the shortest way, such as after a respawn inside a floor or a solid moved onto the body.
isStuckFour pushes did not take the body out of the solids it overlapped, such as when it is squeezed between two, so it stayed where it was and the move went on from there.
wasCarriedThe move began by carrying the body along with the moving solid it stood on.
floorVelocityX, floorVelocityYHow fast the floor under the body moved in the last step, in units per second; 0 on a still floor or none.
isCrushedA moving solid pushed the body into another solid, so it stayed where the push stopped.

A body that stood on a floor and is not moving up looks Collisions.FLOOR_SNAP_DISTANCE, 2 units, further down after its move and lands on a floor it finds there. Walking down a small step then keeps isOnFloor true instead of falling for one step, which would let coyote time start.

To land with a sound or a puff of dust, act when hasLanded is true, and look at landingSpeed to do it only after a real fall:

addSystem(Phase.FIXED_UPDATE) { app ->
    val body = app.world.get(hero, KinematicBody)
    if (body.hasLanded && body.landingSpeed > 400f) app.audio.play(thud)
}

Walking down a small step is no landing, and neither is standing still. The first step of a body placed on a floor is one, at a low speed.

Dropping through a ledge

dropThrough() makes a body standing on one-way ledges fall through them: from the next move it ignores every one-way solid at the height of its feet, until it has fallen below them, landed on something else or moved up. Solids that are not one-way still stop it.

addSystem(Phase.FIXED_UPDATE) { app ->
    val body = app.world.get(hero, KinematicBody)
    // Down while standing on a ledge: fall through it.
    if (body.isOnFloor && app.input.keyboard.isJustPressed(Scancode.S)) body.dropThrough()
}

Moving platforms

A solid moves like any other entity. Give it a Velocity, or set its Transform from a system, and it is a moving platform, a lift or a closing wall:

// A steel ledge that shuttles across the gap: a Velocity on the solid is all it takes.
val shuttle = spawnSolid(left = 900f, top = 300f, right = 1000f, bottom = 312f, passable = Passable.FROM_BELOW)
commands.add(shuttle, Velocity, Velocity(dx = 80f))
// Drawn between its last two steps, like the hero who rides it.
commands.add(shuttle, Interpolated, Interpolated)
addSystem(Phase.FIXED_UPDATE) { app ->
    val x = app.world.get(shuttle, Transform).x
    val velocity = app.world.get(shuttle, Velocity)
    // Turn around at the ends of the track.
    if (x > 1100f) velocity.dx = -80f
    if (x < 900f) velocity.dx = 80f
}

In every fixed step, after the Velocity step and before the bodies' own moves, the engine compares each solid with where it was in the step before. A body standing on a solid that moved is carried by the same distance, across and up or down, and wasCarried says so. Riding down works at any speed, because the body moves with its floor before its own move. A solid that moves into a body it does not carry pushes the body along until it is clear. When another solid is in the way, such as a lift pressing the hero against a ceiling, the body stays where the push stopped and isCrushed is true; the engine destroys nothing, so your game decides what a crush does. A one-way ledge carries the bodies on it but pushes none, and one that carries a body up into a ceiling lets it drop through rather than crushing it. A solid that moves up or down beside a body, or across over its head, leaves it alone, and one that grows or shrinks, such as by its scale, has not moved: it carries nobody, and a body it grows into is pushed out.

The carry moves the body, not its speed: a hero who jumps off a moving platform leaves with his own dx and dy only, and in the step he jumps the platform neither carries nor pushes him. floorVelocityX and floorVelocityY hold the speed of the floor under him in units per second, so the jump can add it:

var platformSpeed = 0f
addSystem(Phase.FIXED_UPDATE) { app ->
    val body = app.world.get(hero, KinematicBody)
    val keyboard = app.input.keyboard
    if (body.isOnFloor) platformSpeed = 0f
    if (body.isOnFloor && keyboard.isJustPressed(Scancode.SPACE)) {
        // Leave with the platform's speed as well as your own.
        platformSpeed = body.floorVelocityX
        body.dy = -700f + body.floorVelocityY
    }
    body.dx = keyboard.axis(Scancode.A, Scancode.D) * 320f + platformSpeed
    body.dy = minOf(body.dy + 1800f * app.time.deltaSeconds, 900f)
}

Both keep their values after dy is set upward, unlike floorOrNull, so the jump can read them in either order. A solid moved by a system in UPDATE carries its riders in the next fixed step, and a solid of a frozen scene does not move.

Sweeps

app.collisions.sweepBox moves a box along a straight line against the solids, without moving anything, and returns where it first touches one as a SweepHit, or null if the way is clear. The hit holds the solid, the fraction of the move the box gets through, from 0 to 1, and the normal of the face it touched: normalY is -1 for a floor, because y points down. sweepBoxTo(destination, …) adds every solid along the move to a collection, in the order the box reaches them. A sweep with dx and dy both 0 returns the solid the box overlaps where it is. Sweeps follow the one-way rule and the mask parameter as bodies do. sweepCollider(entity, dx, dy) sweeps an entity's own box collider, placed, offset and scaled as for a body, against the solids in its mask, so a game need not repeat its hero's size to look ahead of him.

floorBelowOrNull(x, y, width, depth) answers the question every walker and autopilot asks: is there floor under this point? It moves a level line width wide at height y, such as the feet, depth units down and returns the first solid whose top it meets, landing on one-way ledges as a falling body does.

Unlike the overlap queries, which read the positions of the last detection, sweeps read the solids as they are now, so they work in FIXED_UPDATE. An enemy that turns at walls and at the edge of its roof needs one sweep a step:

/** An enemy that walks back and forth along a roof without falling off it. */
class Walker(var direction: Float = 1f) {
    override fun toString(): String = "Walker(direction=$direction)"

    companion object : ComponentType<Walker>("Walker")
}
commands.spawn {
    add(Transform, Transform(x = 1400f, y = 344f - Collisions.CONTACT_GAP))
    add(Sprite, Sprite(assets.whitePixel, width = 24f, height = 32f, color = Color.RED))
    add(Collider, Collider(Shape.Box(width = 24f, height = 32f)))
    add(KinematicBody, KinematicBody())
    add(Walker, Walker())
}
addSystem(Phase.FIXED_UPDATE) { app ->
    app.world.forEach(Walker, KinematicBody, Transform) { _, walker, body, transform ->
        // The floor just ahead of the feet, at the bottom of the 32 tall box, or a gap.
        val ahead = transform.x + walker.direction * 16f
        val floorAhead = app.collisions.floorBelowOrNull(x = ahead, y = transform.y + 16f, width = 4f, depth = 8f)
        if (body.isOnWall || (body.isOnFloor && floorAhead == null)) walker.direction = -walker.direction
        body.dx = walker.direction * 80f
        body.dy += 1800f * app.time.deltaSeconds
    }
}

Planning a jump

An autopilot or a smarter enemy plans by trying moves before making them. slideBox and slideCollider make the move a body makes in one step, across and then up or down with the same stops, contact gap and one-way rule, without a body and without moving anything. They write where the box ends and what it touched into a BoxSlide you pass in and reuse, so planning allocates nothing. The body's move and the slides are the same code, so a plan that feeds the slide the speeds your system would give ends where the body will:

/**
 * Returns where [hero] comes down if he jumps now and keeps rolling at [dx], following his body's
 * move one fixed step at a time, or `null` if he is still in the air after two seconds.
 */
fun App.jumpLandingOrNull(hero: Entity, dx: Float, slide: BoxSlide): BoxSlide? {
    val transform = world.get(hero, Transform)
    val dt = time.deltaSeconds
    var x = transform.x
    var y = transform.y
    var dy = -700f
    repeat(120) {
        // The same gravity and fall limit as the system that moves him.
        dy = minOf(dy + 1800f * dt, 900f)
        collisions.slideCollider(hero, x = x, y = y, dx = dx * dt, dy = dy * dt, result = slide)
        if (slide.isOnFloor) return slide
        if (slide.isOnCeiling) dy = 0f
        x = slide.x
        y = slide.y
    }
    return null
}

slideCollider starts from where the entity's Transform would be and returns that position, so each step's x and y feed the next; slideBox does the same for a box you describe. Neither looks for a floor below at the end unless you pass floorSnap, neither drops through ledges, and neither pushes the box out of a solid it starts inside, as a body is.

Limits

  • Bodies and solids are upright boxes: a rotation is ignored and a circle collider is an error.
  • A solid must be a root entity: one with a parent is an error. Put a moving solid's Sprite on the solid itself and mark it Interpolated, so it is drawn as smoothly as the hero riding it.
  • Bodies do not stop each other. Use Overlap events between them, as for any colliders.
  • A body that overlaps a solid when its move starts is pushed out of it first, the shortest way, in at most four pushes. A body squeezed between solids stays where it was and reports isStuck: the engine neither crushes nor moves it, so your game decides what happens to it.
  • A scene frozen under a pushed scene keeps its bodies still, and its solids stop nothing and do not move. A moving solid of the scene on top does not carry or push a frozen body.
  • A body moved by setting its Transform, such as a respawn, is drawn sliding from its old place to the new one during the next step when it is Interpolated, a dash across the screen. Call world.snapInterpolation(entity) right after the move to draw it at the new place at once. A camera that follows an interpolated body follows app.drawnPositionOf(body), the blended position the renderer uses this frame, not the Transform, or it jitters against the picture. Scrolling worlds shows both.

See also