Platformer

A short level with ground, blocks, pits, coins and patrolling enemies. Just enough to feel what defines the genre, which is jumping precisely.

Made with Kaplay, in about 149 lines of JavaScript.

How it's made

1. Setup and controls

   The game is created at a fixed size and virtual buttons are defined (left, right, jump). The rest of the code asks about those buttons, so the same game works with a keyboard or a touch screen. The gravity, speed and jump constants are the numbers that most change how the game feels.

   const k = kaplay({
     width: 640,
     height: 360,
     letterbox: true, pixelDensity,
     background: [30, 34, 72],
     // Virtual buttons: the game asks about "jump", not about a specific key.
     buttons: {
       left: { keyboard: ["left", "a"] },
       right: { keyboard: ["right", "d"] },
       jump: { keyboard: ["space", "up", "w"] },
     },
   });
   touchControls(k, [
     { button: "left", label: "◀" },
     { button: "right", label: "▶" },
     { button: "jump", label: "⤒", side: "right" },
   ]);
   
   const GRAVITY = 1600;
   const SPEED = 220;
   const JUMP_FORCE = 620;
   const COYOTE_TIME = 0.1; // seconds you can still jump after leaving a ledge
   const JUMP_BUFFER = 0.12; // seconds a jump pressed before landing is "remembered"
   const TILE = 32;
   setGravity(GRAVITY);

2. The level as text

   The level is a list of strings; each character becomes an object through addLevel. Designing levels this way is fast and lets anyone change them without tools.

   // The level is a text drawing: each character is a kind of tile.
   // = ground · # block · o coin · e enemy · F flag
   const MAP = [
     "                                                   ",
     "                                                   ",
     "                                          o o      ",
     "                      o o                ###       ",
     "                     #####       o             F   ",
     "           o o                  ###       e    #   ",
     "          #####        e                 ####  #   ",
     "    o           ######====    ====   e   ====  #   ",
     "=========   ======        ====    ======   ========",
     "=========   ======        ====    ======   ========",
   ];
   
   function solidTile(c) {
     return [rect(TILE, TILE), color(c), area(), body({ isStatic: true }), "solid"];
   }
   
   function buildLevel() {
     return addLevel(MAP, {
       tileWidth: TILE,
       tileHeight: TILE,
       tiles: {
         "=": () => solidTile(rgb(84, 160, 92)),
         "#": () => solidTile(rgb(176, 120, 72)),
         o: () => [circle(8), color(255, 205, 60), pos(16, 16), area(), anchor("center"), "coin"],
         e: () => [rect(28, 24), color(220, 70, 60), pos(2, 8), area(), body(), { dir: -1 }, "enemy"],
         F: () => [rect(8, 64), color(240, 240, 255), pos(12, -32), area(), "flag"],
       },
     });
   }

3. The player

   The player has area() to collide and body() so gravity affects it. Moving means applying a horizontal speed while a button is held.

   const player = add([rect(24, 32), color(120, 200, 255), pos(64, 160), area(), body(), anchor("bot"), "player"]);
   
   // Horizontal movement: constant speed while the button is held.
   onButtonDown("left", () => player.move(-SPEED, 0));
   onButtonDown("right", () => player.move(SPEED, 0));

4. The jump

   This is the genre's mechanic, and three tricks make it feel fair. «Coyote time» lets you jump a tenth of a second after leaving a ledge. The jump buffer does the opposite: if you press jump just before touching the ground, the game remembers the input and you jump the moment you land, instead of being ignored. And the variable jump cuts the rise short if you release the button. The first two forgive mistakes of a few hundredths of a second that players do not feel are their own.

   // Jumping is THE mechanic of the genre. Three details make it feel right:
   // 1) coyote time: you can still jump a moment after leaving a ledge;
   // 2) jump buffer: press just before landing and the jump happens on landing;
   // 3) variable height: release the button early for a shorter jump.
   let airTime = 0;
   let bufferedJump = 0; // time left on a jump that was pressed but not done yet
   function tryJump() {
     if (bufferedJump > 0 && airTime < COYOTE_TIME) {
       player.jump(JUMP_FORCE);
       airTime = 1;
       bufferedJump = 0;
       // If the button was already released (buffered jump), make it a short one.
       if (!isButtonDown("jump")) player.vel.y *= 0.45;
     }
   }
   player.onUpdate(() => {
     airTime = player.isGrounded() ? 0 : airTime + dt();
     bufferedJump = Math.max(0, bufferedJump - dt());
     tryJump();
   });
   onButtonPress("jump", () => {
     bufferedJump = JUMP_BUFFER;
     tryJump();
   });
   onButtonRelease("jump", () => {
     if (player.vel.y < 0) player.vel.y *= 0.45;
   });

5. Patrolling enemies

   Each enemy walks and turns around when it hits a block or when there is no ground ahead. The collision decides the outcome, because stomping from above destroys it and touching it from the side makes you lose.

   // They patrol back and forth, turning at a wall or at the edge of a platform.
   for (const e of level.get("enemy")) {
     e.onUpdate(() => {
       e.move(e.dir * 60, 0);
       const ahead = e.pos.add(level.pos).add(e.dir > 0 ? 30 : -2, 30);
       const groundAhead = level.get("solid").some((s) => s.hasPoint(ahead));
       if (!groundAhead) e.dir *= -1;
     });
     e.onCollide("solid", (_, col) => {
       if (col.isLeft() || col.isRight()) e.dir *= -1;
     });
   }
   // Stomping an enemy from above destroys it; touching it from the side loses.
   player.onCollide("enemy", (e, col) => {
     if (col.isBottom()) {
       destroy(e);
       player.jump(JUMP_FORCE * 0.6);
     } else {
       go("end", false, coins, totalCoins);
     }
   });

6. Coins and goal

   Coins are the collectible that invites riskier routes. The counter shows how many you have out of the level's total, so you know whether you missed any. The flag ends the level.

   player.onCollide("coin", (c) => {
     destroy(c);
     coins++;
     updateHud();
   });
   player.onCollide("flag", () => go("end", true, coins, totalCoins));

7. The camera

   The camera follows the player horizontally without leaving the level's edges. Falling below the screen counts as losing.

   // The camera follows the player horizontally; falling into a pit loses.
   const levelWidth = MAP[0].length * TILE;
   player.onUpdate(() => {
     const x = Math.min(Math.max(player.pos.x, width() / 2), levelWidth - width() / 2);
     camPos(x, height() / 2);
     if (player.pos.y > height() + 200) go("end", false, coins, totalCoins);
   });

8. Scenes

   The game has three scenes, title, game and end, and go() jumps between them. This restarts the level without cleaning anything up by hand.

   function screen(title, subtitle, next) {
     add([text(title, { size: 34, font: FONT, align: "center" }), pos(center().sub(0, 30)), anchor("center")]);
     add([
       text(subtitle, { size: 16, font: FONT, align: "center", width: 520 }),
       pos(center().add(0, 30)),
       anchor("center"),
       color(200, 210, 255),
     ]);
     onButtonPress("jump", next);
     onClick(next);
   }
   
   scene("title", () =>
     screen(
       t({ es: "Plataformas", en: "Platformer" }),
       t({
         es: "Flechas para moverte, espacio para saltar. Llega a la bandera.\nPulsa espacio o toca para empezar.",
         en: "Arrows to move, space to jump. Reach the flag.\nPress space or tap to start.",
       }),
       () => go("game"),
     ),
   );
   
   scene("end", (won, coins, total) =>
     screen(
       won ? t({ es: "¡Llegaste!", en: "You made it!" }) : t({ es: "Inténtalo otra vez", en: "Try again" }),
       t({
         es: `Monedas: ${coins}/${total}. Pulsa espacio para repetir.`,
         en: `Coins: ${coins}/${total}. Press space to play again.`,
       }),
       () => go("game"),
     ),
   );
   
   go("title");

What we simplified

• The character and blocks are rectangles; there are no animations or sound.
• A single level, with no lives or checkpoints.
• Horizontal movement is at a constant speed, with no momentum; accelerating and slowing down gradually is left as an exercise.

To modify it

• Add a second jump in mid-air (double jump) and think about how it changes the level design.
• Make the player accelerate and slow down gradually instead of moving at a constant speed.
• Add spikes (a new character in the map) that make you lose when touched.

// Platformer demo
// Engine: Kaplay 3001 (https://kaplayjs.com). MIT licence.
import kaplay from "../../vendor/kaplay.mjs";
import { t, FONT, touchControls, pixelDensity } from "../common.js";

// #region setup
const k = kaplay({
  width: 640,
  height: 360,
  letterbox: true, pixelDensity,
  background: [30, 34, 72],
  // Virtual buttons: the game asks about "jump", not about a specific key.
  buttons: {
    left: { keyboard: ["left", "a"] },
    right: { keyboard: ["right", "d"] },
    jump: { keyboard: ["space", "up", "w"] },
  },
});
touchControls(k, [
  { button: "left", label: "◀" },
  { button: "right", label: "▶" },
  { button: "jump", label: "⤒", side: "right" },
]);

const GRAVITY = 1600;
const SPEED = 220;
const JUMP_FORCE = 620;
const COYOTE_TIME = 0.1; // seconds you can still jump after leaving a ledge
const JUMP_BUFFER = 0.12; // seconds a jump pressed before landing is "remembered"
const TILE = 32;
setGravity(GRAVITY);
// #endregion

// #region level
// The level is a text drawing: each character is a kind of tile.
// = ground · # block · o coin · e enemy · F flag
const MAP = [
  "                                                   ",
  "                                                   ",
  "                                          o o      ",
  "                      o o                ###       ",
  "                     #####       o             F   ",
  "           o o                  ###       e    #   ",
  "          #####        e                 ####  #   ",
  "    o           ######====    ====   e   ====  #   ",
  "=========   ======        ====    ======   ========",
  "=========   ======        ====    ======   ========",
];

function solidTile(c) {
  return [rect(TILE, TILE), color(c), area(), body({ isStatic: true }), "solid"];
}

function buildLevel() {
  return addLevel(MAP, {
    tileWidth: TILE,
    tileHeight: TILE,
    tiles: {
      "=": () => solidTile(rgb(84, 160, 92)),
      "#": () => solidTile(rgb(176, 120, 72)),
      o: () => [circle(8), color(255, 205, 60), pos(16, 16), area(), anchor("center"), "coin"],
      e: () => [rect(28, 24), color(220, 70, 60), pos(2, 8), area(), body(), { dir: -1 }, "enemy"],
      F: () => [rect(8, 64), color(240, 240, 255), pos(12, -32), area(), "flag"],
    },
  });
}
// #endregion

scene("game", () => {
  const level = buildLevel();
  let coins = 0;
  const totalCoins = level.get("coin").length;
  const hud = add([text("", { size: 18, font: FONT }), pos(16, 12), fixed(), z(10)]);
  const updateHud = () => (hud.text = t({ es: "Monedas: ", en: "Coins: " }) + `${coins}/${totalCoins}`);
  updateHud();

  // #region player
  const player = add([rect(24, 32), color(120, 200, 255), pos(64, 160), area(), body(), anchor("bot"), "player"]);

  // Horizontal movement: constant speed while the button is held.
  onButtonDown("left", () => player.move(-SPEED, 0));
  onButtonDown("right", () => player.move(SPEED, 0));
  // #endregion

  // #region jump
  // Jumping is THE mechanic of the genre. Three details make it feel right:
  // 1) coyote time: you can still jump a moment after leaving a ledge;
  // 2) jump buffer: press just before landing and the jump happens on landing;
  // 3) variable height: release the button early for a shorter jump.
  let airTime = 0;
  let bufferedJump = 0; // time left on a jump that was pressed but not done yet
  function tryJump() {
    if (bufferedJump > 0 && airTime < COYOTE_TIME) {
      player.jump(JUMP_FORCE);
      airTime = 1;
      bufferedJump = 0;
      // If the button was already released (buffered jump), make it a short one.
      if (!isButtonDown("jump")) player.vel.y *= 0.45;
    }
  }
  player.onUpdate(() => {
    airTime = player.isGrounded() ? 0 : airTime + dt();
    bufferedJump = Math.max(0, bufferedJump - dt());
    tryJump();
  });
  onButtonPress("jump", () => {
    bufferedJump = JUMP_BUFFER;
    tryJump();
  });
  onButtonRelease("jump", () => {
    if (player.vel.y < 0) player.vel.y *= 0.45;
  });
  // #endregion

  // #region enemies
  // They patrol back and forth, turning at a wall or at the edge of a platform.
  for (const e of level.get("enemy")) {
    e.onUpdate(() => {
      e.move(e.dir * 60, 0);
      const ahead = e.pos.add(level.pos).add(e.dir > 0 ? 30 : -2, 30);
      const groundAhead = level.get("solid").some((s) => s.hasPoint(ahead));
      if (!groundAhead) e.dir *= -1;
    });
    e.onCollide("solid", (_, col) => {
      if (col.isLeft() || col.isRight()) e.dir *= -1;
    });
  }
  // Stomping an enemy from above destroys it; touching it from the side loses.
  player.onCollide("enemy", (e, col) => {
    if (col.isBottom()) {
      destroy(e);
      player.jump(JUMP_FORCE * 0.6);
    } else {
      go("end", false, coins, totalCoins);
    }
  });
  // #endregion

  // #region coins-goal
  player.onCollide("coin", (c) => {
    destroy(c);
    coins++;
    updateHud();
  });
  player.onCollide("flag", () => go("end", true, coins, totalCoins));
  // #endregion

  // #region camera
  // The camera follows the player horizontally; falling into a pit loses.
  const levelWidth = MAP[0].length * TILE;
  player.onUpdate(() => {
    const x = Math.min(Math.max(player.pos.x, width() / 2), levelWidth - width() / 2);
    camPos(x, height() / 2);
    if (player.pos.y > height() + 200) go("end", false, coins, totalCoins);
  });
  // #endregion
});

// #region scenes
function screen(title, subtitle, next) {
  add([text(title, { size: 34, font: FONT, align: "center" }), pos(center().sub(0, 30)), anchor("center")]);
  add([
    text(subtitle, { size: 16, font: FONT, align: "center", width: 520 }),
    pos(center().add(0, 30)),
    anchor("center"),
    color(200, 210, 255),
  ]);
  onButtonPress("jump", next);
  onClick(next);
}

scene("title", () =>
  screen(
    t({ es: "Plataformas", en: "Platformer" }),
    t({
      es: "Flechas para moverte, espacio para saltar. Llega a la bandera.\nPulsa espacio o toca para empezar.",
      en: "Arrows to move, space to jump. Reach the flag.\nPress space or tap to start.",
    }),
    () => go("game"),
  ),
);

scene("end", (won, coins, total) =>
  screen(
    won ? t({ es: "¡Llegaste!", en: "You made it!" }) : t({ es: "Inténtalo otra vez", en: "Try again" }),
    t({
      es: `Monedas: ${coins}/${total}. Pulsa espacio para repetir.`,
      en: `Coins: ${coins}/${total}. Press space to play again.`,
    }),
    () => go("game"),
  ),
);

go("title");
// #endregion