15_game.txt

:chap_num: 15
:prev_link: 14_event
:next_link: 16_canvas
:load_files: ["js/15_game.js", "js/code/game_levels.js"]

= Practical: A Platform Game =

My initial fascination with computers, like that of many kids,
originated with computer games. I was drawn in by the tiny
computer-simulated worlds which I could manipulate and impact (sort
of). More, I suppose, because of the way I could project my
imagination into them, than because of the possibilities they actually
offered.

I wouldn't wish a career in game programming on anyone—much like in
the music industry, the discrepancy between the many eager young
people wanting to work in it and the actual demand for such people
creates a rather exploitative atmosphere. But writing games for fun can
be very rewarding. A game world, even when simple, is still a world.
Who doesn't like creating worlds?

This chapter will walk through the implementation of a simple platform
game. Platform games (or “jump and run” games) are games that involve
moving a figure through an (often two-dimensional, side-view) world,
and jumping onto and over things.

== The game ==

Our game will be roughly based on “http://www.lessmilk.com/games/10[Dark
Blue]”!!tex (_www.lessmilk.com/games/10_)!! by Thomas Palef. I chose
this game because it is extremely minimal (and thus implementable
without _too_ much code), yet entertaining. It looks like this:

image::img/darkblue.png[alt="The game Dark Blue"]

// FIXME Make this explanation work for the grayscale paper book

The dark box represents the player, whose task it is to collect the
yellow boxes (coins) while avoiding the red stuff (lava?). A level is
completed when all coins have been collected.

The player can walk around with the left and right arrow keys, and
jump with the up arrow. Jumping is the main occupation of this game
character. It can reach many times their own height, and is able to
change direction in mid-air. Though this may not be entirely
realistic, it helps give the player a feeling of being in direct
control of the on-screen avator.

The game's consist of a fixed background, laid out like a grid, with
the moving elements overlaid on that. Each field on the background
grid is either empty, solid, or lava. The moving elements are the
player, coins, and pieces of lava that move. Unlike the artificial
life simulation from Chapter 7, the positions of these elements are
not constrained to the grid—their coordinates may be fractional,
allowing smooth motion.

== The technology ==

We will use the browser DOM to display the game, and read user input
by handling key events.

The screen- and keyboard-related code is only a tiny portion of the
work we need to do to implement this game. Since everything looks like
single-color boxes, drawing is uncomplicated: We create DOM elements,
and use styling to give them a background color, size, and position.

We can represent the background, which is a static grid, as a table of
colored cells. The free-moving elements can be overlaid on top of that
using absolutely positioned elements.

In games (and similar programs) that have to respond and animate
without noticeable delay, efficiency is an important concern. Though
the DOM was not originally designed for high-performance graphics, it
is surprisingly effective in that area. We saw some simple animations
in Chapter 13. On a modern machine, drawing a simple game like this
one will not require us to do anything special to get acceptable
performance.

In the next chapter, we will explore another browser technology, the
`<canvas>` tag, which provides a way to draw graphics that is more
similar to traditional graphics interfaces—working in terms of shapes
and pixels, rather than DOM elements.

== Levels ==

In Chapter 7 we used arrays of strings to describe a two-dimensional
grid. That approach is useful here as well. It will allow us to easily
design levels without first building a level editor.

This, for example, could specify a simple level:

// include_code

[source,javascript]
----
var simpleLevelPlan = [
  "                      ",
  "                      ",
  "  x              = x  ",
  "  x         o o    x  ",
  "  x @      xxxxx   x  ",
  "  xxxxx            x  ",
  "      x!!!!!!!!!!!!x  ",
  "      xxxxxxxxxxxxxx  ",
  "                      "
];
----

Both the fixed grid and the moving elements are included in the
strings. We use “x” characters for walls, spaces for empty space, and
exclamation marks for fixed, non-moving lava tiles.

The initial player position is indicated by an “@” character. Coins
will be put wherever there is an “o”, and the equals sign (“=”)
indicates a block of lava that moves back and forth horizontally. Note
that the grid for these positions will be set to contain empty space,
and an additional data structure will be used to track the position of
these non-fixed elements.

We will also support a pipe character (“|”) for vertically moving
lava, and “v” for _dripping_ lava—vertically moving blocks of lava
that don't bounce back and forth, but move down and jump back to their
start position when they hit the floor.

A whole game will be represented by an array of level arrays, though
which the player must progress one after the other, by collecting all
the coins in each. When the player touches lava, the current level is
simply restored to its starting position, and they can try again.

== Reading a level ==

The following constructor, given an array of strings as seen above,
constructs a level object.

// include_code

[source,javascript]
----
function Level(plan) {
  this.width = plan[0].length;
  this.height = plan.length;
  this.grid = [];
  this.actors = [];

  for (var y = 0; y < this.height; y++) {
    var line = plan[y], gridLine = [];
    for (var x = 0; x < this.width; x++) {
      var ch = line[x], fieldType = null;
      var Actor = actorChars[ch];
      if (Actor)
        this.actors.push(new Actor(new Vector(x, y), ch));
      else if (ch == "x")
        fieldType = "wall";
      else if (ch == "!")
        fieldType = "lava";
      gridLine.push(fieldType);
    }
    this.grid.push(gridLine);
  }

  this.player = this.actors.filter(function(actor) {
    return actor.type == "player";
  })[0];
  this.status = this.finishDelay = null;
}
----

A level stores its width and height, along with two arrays—one for the
grid, and one for the _actors_, the dynamic elements. The grid is
represented as an array of arrays, where each of the inner arrays
represents a horizontal line of the grid, and each square contains
either null, for empty squares, or a string indicating the type of the
square—`"wall"` or `"lava"`.

The actors array holds a number of objects that track the current
position and state of the dynamic elements in the level. Each of these
is expected to have a `pos` property giving its position (the
coordinates of its top left corner), a `size` property giving its
size, and a `type` property that holds a string that identifies the
element (`"lava"`, `"coin"`, or `"player"`).

After building up the grid, we use the `filter` method to find the
player actor object, and store it in a property of the level. The
`status` and `finishDelay` properties will be used when the player
dies or wins, to show a simple animation rather than immediately
resetting or advancing the level (which would look cheap). This method
can be used to determine whether a level is finished:

// include_code

[source,javascript]
----
Level.prototype.isFinished = function() {
  return this.status != null && this.finishDelay < 0;
};
----

For brevity, this code assumes that level plans are well-formed—that
each line has the same length and only contains allowed characters,
and that there is a single player start position in it.

== Actors ==

To represent the position and size of an actor, we will return to our
trusty `Point` type, which groups an x and y coordinate into an
object. Only, because sizes are not really points, and we will also
use this to represent speeds, we will call it `Vector` instead (in the
mathematical sense).

// include_code

[source,javascript]
----
function Vector(x, y) {
  this.x = x; this.y = y;
}
Vector.prototype.plus = function(other) {
  return new Vector(this.x + other.x, this.y + other.y);
};
Vector.prototype.times = function(factor) {
  return new Vector(this.x * factor, this.y * factor);
};
----

The `times` method scales a vector by a given factor, and will be
useful when we need to multiply a speed vector by a time interval.

The `actorChars` object was used by the `Level` constructor to
associate characters with constructor functions. It looks like this:

// include_code

[source,javascript]
----
var actorChars = {
  "@": Player,
  "o": Coin,
  "=": Lava, "|": Lava, "v": Lava
};
----

There are three characters mapping to `Lava`. The `Level` constructor
passes the actor the character it was based on as an argument, which
the `Lava` constructor uses to determine its behavior (bouncing
horizontally or vertically, or dripping).

The player type is built with this simple constructor. It has a
property `speed` containing its current speed, which we will
use to simulate momentum and gravity.

// include_code

[source,javascript]
----
function Player(pos) {
  this.pos = pos.plus(new Vector(0, -0.5));
  this.size = new Vector(0.8, 1.5);
  this.speed = new Vector(0, 0);
}
Player.prototype.type = "player";
----

When constructing a dynamic `Lava` object, we need to set up some
state based on the character it was based on. Moving lava will simply
move along at its given speed until it hits an obstacle. At that
point, if it has a `repeatPos` property, it will jump back to its
start position (dripping). If it does not, it will invert its speed
and continue in the other direction (bouncing). The constructor only
sets up the necessary properties—the method that does the actual
moving will be written later on.

// include_code

[source,javascript]
----
function Lava(pos, ch) {
  this.pos = pos;
  this.size = new Vector(1, 1);
  if (ch == "=") {
    this.speed = new Vector(2, 0);
  } else if (ch == "|") {
    this.speed = new Vector(0, 2);
  } else if (ch == "v") {
    this.speed = new Vector(0, 3);
    this.repeatPos = pos;
  }
}
Lava.prototype.type = "lava";
----

`Coin` actors are very simple, and mostly sit statically in their
place. But to liven up the game a little, they are given a “wobble”, a
slight vertical motion back and forth. To track this, a coin object
stores both a current position and a base position (around which the
wobble happens), as well as a `wobble` property that tracks the phase
of the bouncing motion.

// include_code

[source,javascript]
----
function Coin(pos) {
  this.basePos = this.pos = pos.plus(new Vector(0.2, 0.1));
  this.size = new Vector(0.6, 0.6);
  this.wobble = Math.random() * Math.PI * 2;
}
Coin.prototype.type = "coin";
----

To avoid a situation where all coins move up and down synchronously,
the starting phase of each coin is randomized. We will be using
`Math.sin` (a sine wave) to model the motion, so we multiply the value
returned by `Math.random` by 2π, which causes it to take a random
position on that wave. If none of this makes sense to you, don't
worry, it is not necessary to understand it to follow the chapter.

We now have all the parts needed to initialize a level.

// include_code strip_log

[source,javascript]
----
var simpleLevel = new Level(simpleLevelPlan);
console.log(simpleLevel.width, "by", simpleLevel.height);
// → 22 by 9
----

== Encapsulation as a burden ==

Most of the code in this chapter will worry very little about
encapsulation. This has two reasons. Firstly, encapsulation takes
extra effort. It will make programs bigger and require additional
concepts and interfaces to be introduced. Since there is only so much
code you can throw at a reader before their eyes glaze over, I've made
an effort to keep the program small.

Secondly, the various elements in this game are so closely tied
together that if the behavior of one of them changed, it is unlikely
that any of the others would be able to stay the same. Interfaces
between the elements would end up encoding a lot of assumptions about
the way the game works. This makes them a lot less effective—whenever
you make a change to one part of the system, you still have to worry
about the way it impacts the other parts, because their interfaces
wouldn't cover the new situation.

Some _cutting points_ in a system lend themselves very well to
separation through rigorous interfaces , others don't. Trying to
encapsulate something that isn't a suitable boundary is a sure way to
waste a lot of energy. When you are making this mistake, you'll
usually notice that your interfaces are getting awkwardly large and
detailed, and that they need to be modified often, as new requirements
come up.

There is one thing that we _will_ encapsulate in this chapter, and
that is the drawing subsystem. The reason for this is that we will
display the same game in a different way in the next chapter. By
putting the drawing behind an interface, we can simply load the same
game program there, but plug in a new display module.

== Drawing ==

The encapsulation of the drawing code is done by defining a _display_
object, which displays a given level. The display type we define in
this chapter is called `DOMDisplay`, because it uses simple DOM
elements to show the level.

We will be using a style sheet to set the actual colors and other
fixed properties of the elements that make up the game. It would also
be possible to directly assign to the elements' `style` property when
we create them, but that would produce rather verbose programs.

The following helper function provides a short way to create an
element and give it a class.

// include_code

[source,javascript]
----
function element(name, className) {
  var elt = document.createElement(name);
  if (className) elt.className = className;
  return elt;
}
----

A display is created by giving it a parent element to which it should
append itself, and a level object.

// include_code

[source,javascript]
----
function DOMDisplay(parent, level) {
  this.wrap = parent.appendChild(element("div", "game"));
  this.level = level;

  this.wrap.appendChild(this.drawBackground());
  this.actorLayer = null;
  this.drawFrame();
}
----

We used the fact that `appendChild` returns the appended element to
create the wrapper element and store it in the `wrap` property in a
single statement.

The level's background, which never changes, is drawn once. The actors
are redrawn every time the display is updated. The `actorLayer`
property will be used by `drawFrame` to track the element that holds
the actors, so that they can be easily removed and replaced.

Our coordinates and sizes are tracked in units relative to the grid
size, where a size or distance of one means one grid unit. When
setting pixel sizes, we will have to scale these coordinates up—things
would be ridiculously small at a single pixel per square. The `scale`
variable gives the amount of pixels a single unit takes up on the
screen.

// include_code

[source,javascript]
----
var scale = 20;

DOMDisplay.prototype.drawBackground = function() {
  var table = element("table", "background");
  table.style.width = this.level.width * scale + "px";
  this.level.grid.forEach(function(row) {
    var rowElt = table.appendChild(element("tr"));
    rowElt.style.height = scale + "px";
    row.forEach(function(type) {
      rowElt.appendChild(element("td", type));
    });
  });
  return table;
};
----

As mentioned earlier, the background is drawn as a `<table>` element.
This nicely corresponds to the structure of the `grid` property in the
level—each row of the grid is turned into a table row (`<tr>`
element). The strings in the grid are used as class names for the
table cell (`<td>`) elements. The following CSS helps the resulting
table look like the background we want:

[source,text/css]
----
.background    { background: #34a6fb;
                 table-layout: fixed;
                 border-spacing: 0;   }
.background td { padding: 0;          }
.lava          { background: #ff6363; }
.wall          { background: white;   }
----

Some of these (`table-layout`, `border-spacing`, and `padding`) are
simply used to suppress unwanted default behavior. We don't want space
between the table cells, or padding inside them, and we set the
table's algorithm for computing the width of its columns to a simple,
predictable variant (the way tables are laid out in HTML is a very
complicated thing).

The `background` rules set background colors. CSS allows colors to be
specified both as words (`white`) and with a rather cryptic `#RRGGBB`
format, where the hash sign is followed by pairs of hexadecimal
(base-16) digits giving first the red, then the green, and then the
blue components of the color, as numbers between zero and `ff` (255).
So in `#34a6fb` the the red component is hexadecimal `34` (3 × 16 + 4
equals decimal 52), green is `a6` (166), and blue `fb` (251). Since
the blue component is the largest, the resulting color will be
blueish. You can see that in the `.lava` rule, the first part of the
number (red) is the largest.

Drawing the actors is quite straightforward:

// include_code

[source,javascript]
----
DOMDisplay.prototype.drawActors = function() {
  var wrap = element("div");
  this.level.actors.forEach(function(actor) {
    var elt = wrap.appendChild(element("div", "actor " + actor.type));
    elt.style.width = actor.size.x * scale + "px";
    elt.style.height = actor.size.y * scale + "px";
    elt.style.left = actor.pos.x * scale + "px";
    elt.style.top = actor.pos.y * scale + "px";
  });
  return wrap;
};
----

Each actor gets an element, and we set the element's position and size
based on the actor's properties, multiplying each value by the display
`scale`.

Giving an element multiple classes is done by separating the class
names with spaces. Below the relevant CSS code is shown. The `actor`
class gives the actors their absolute position, and their type name is
used to give them a color (lava actors use the same class as lava grid
squares, which we defined earlier):

[source,text/css]
----
.actor  { position: absolute;  }
.coin   { background: #f1e559; }
.player { background: #404040; }
----

To update the display when the world changes, the `drawFrame` method
removes the old actor graphics, if any, and redraws them in their new
positions. It may be tempting to try and reuse the DOM elements for
actors, but that would seriously increase the way in which the display
code and the simulation code are tangled up. We'd need to have a way
to associate actors with elements, and the drawing code must know when
to remove elements when their actors vanish. For a simple game like
this, redrawing is fast enough.

// include_code

[source,javascript]
----
DOMDisplay.prototype.drawFrame = function() {
  if (this.actorLayer)
    this.wrap.removeChild(this.actorLayer);
  this.actorLayer = this.wrap.appendChild(this.drawActors());
  this.wrap.className = "game " + (this.level.status || "");
  this.scrollPlayerIntoView();
};
----

By adding the level's current status as a class name to the wrapper,
we can style the player actor slightly differently when the game is
won or lost. (We could also style other elements, like the background,
differently based on a class in one of their ancestor elements. CSS is
convenient like that.)

[source,text/css]
----
.lost .player {
  background: #a04040;
}
.won .player {
  box-shadow: -4px -7px 8px white, 4px -7px 8px white;
}
----

After touching lava, the player's color turns dark red, hopefully
suggesting scorching. When the last coin has been collected, we use a
two white box shadows, one to the top left and one to the top right,
to create a white halo effect.

We don't assume that levels fit into the viewport. That is why the
`scrollPlayerIntoView` call is needed—it ensures that, if the level is
sticking out outside of the viewport, we scroll that viewport to make
sure the player is near its center. The following CSS gives the game's
wrapping DOM element a maximum size, and ensures that anything that
sticks out is not displayed. We also give it a relative position, so
that the actors inside of it are positioned relative to its top left
corner.

[source,text/css]
----
.game {
  overflow: hidden;
  max-width: 600px;
  max-height: 450px;
  position: relative;
}
----

In the `scrollPlayerIntoView` method, we find the player's position,
and update the wrapping element's scroll position, by manipulating it's
`scrollLeft` and `scrollTop` properties, when the player is too close
to the edge.

// include_code

[source,javascript]
----
DOMDisplay.prototype.scrollPlayerIntoView = function() {
  var width = this.wrap.clientWidth;
  var height = this.wrap.clientHeight;
  var margin = width / 3;

  // The viewport
  var left = this.wrap.scrollLeft, right = left + width;
  var top = this.wrap.scrollTop, bottom = top + height;

  var player = this.level.player;
  var center = player.pos.plus(player.size.times(0.5))
                 .times(scale);

  if (center.x < left + margin)
    this.wrap.scrollLeft = center.x - margin;
  else if (center.x > right - margin)
    this.wrap.scrollLeft = center.x + margin - width;
  if (center.y < top + margin)
    this.wrap.scrollTop = center.y - margin;
  else if (center.y > bottom - margin)
    this.wrap.scrollTop = center.y + margin - height;
};
----

The way the player's center is found shows how the methods on our
`Vector` type allow rather natural-looking computations to be done
with objects. To find the actor's center, we add its position (its top
left corner) half its size. That is the center in level coordinates,
but we need it in pixel coordinates, so we then multiply the resulting
vector by our display scale.

Next, a series of checks verify that the player position isn't outside
of the allowed range. Note that sometimes this will set nonsense
scroll coordinates, below zero or beyond the element's scrollable
area. This is okay—the DOM will constrain them to sane values. Setting
`scrollLeft` to -10 will cause it to become zero.

It would have been slightly simpler to always try to scroll the player
to the center of the viewport. But this creates a rather jarring
effect. As you are jumping, the view will constantly shift up and
down. Having it move up as you jump close to the edge, and then stay
there, is more pleasant.

Finally, we'll need a way to clear a displayed level, to be used when
the game moves on to the next level or resets a level.

// include_code

[source,javascript]
----
DOMDisplay.prototype.clear = function() {
  this.wrap.parentNode.removeChild(this.wrap);
};
----

We should now be able to display our tiny level:

[source,text/html]
----
<link rel="stylesheet" href="css/game.css">

<script>
  var simpleLevel = new Level(simpleLevelPlan);
  var display = new DOMDisplay(document.body, simpleLevel);
</script>
----

ifdef::tex_target[]

image::img/game_simpleLevel.png[alt="Our level rendered"]

endif::tex_target[]

The `<link>` tag, when used with `rel="stylesheet"`, is a way to load
a CSS file into a page. The file `game.css` contains the styles
necessary for our game.

== Motion and collision ==

Now we get to the point where we can start adding motion—the most
interesting aspect of this game. The basic approach, which most games
like this take, is to split time into small steps, and for each step,
move the actors by a distance corresponding to their speed (distance
moved per second) multiplied by the size of the time step (in
seconds).

That is easy. The difficult part is to deal with the interactions
between the elements. When the player hits a wall or floor, they
should not simply move through it. The game must notice when a given
motion causes an object to hit another object, and respond
accordingly—for walls, the motion must be stopped, for coins, the coin
collected, and so on.

Solving this in the general case is quite a big undertaking. You can
find libraries, usually called _physics engines_, that simulate
interaction between physical objects in two or three dimensions. We'll
take a more modest approach in this chapter, handling only collisions
between boxes, and handling them in a rather simplistic way.

Before moving the player or a block of lava, we test whether the
motion would take it inside of a non-empty part of the background. If
it does, we simply cancel the motion altogether. The response to such
a collision depends on the type of actor—the player will stop, whereas
a lava block will bounce back.

This approach requires our time steps to be rather small, since it
will cause motion to stop before the objects actually touch. If the
time steps, and thus the motion steps, are too big, the player would
end up hovering a noticeable distance above the ground. Another
approach, arguably better but more complicated, would be to find the
exact collision spot, and move there. We will take the simple
approach, and hide its problems by ensuring the animation proceeds in
small steps.

This method tells us whether a rectangle (specified by a position and
a size) overlaps with any non-empty space on the background grid:

// include_code

[source,javascript]
----
Level.prototype.obstacleAt = function(pos, size) {
  var xStart = Math.floor(pos.x);
  var xEnd = Math.ceil(pos.x + size.x);
  var yStart = Math.floor(pos.y);
  var yEnd = Math.ceil(pos.y + size.y);

  if (xStart < 0 || xEnd > this.width || yStart < 0)
    return "wall";
  if (yEnd > this.height)
    return "lava";
  for (var y = yStart; y < yEnd; y++) {
    for (var x = xStart; x < xEnd; x++) {
      var fieldType = this.grid[y][x];
      if (fieldType) return fieldType;
    }
  }
};
----

It computes the set of grid squares that the body overlaps with by
using `Math.floor` and `Math.ceil` on its coordinates. Remember that
grid squares are one by one unit in size. By rounding the sides of a
box up and down, we get the range of background squares that the box
touches.

image::img/game-grid.svg[alt="Finding collisions on a grid"]

If the body sticks out of the level, we return a predetermined
obstacle type—`"wall"` for the sides and top, `"lava"` for the bottom.
When it is fully inside of the grid, we loop over the block of grid
squares found by rounding the coordinates, and return the content of
the first non-empty square we find.

Collisions between the player and other dynamic actors (coins, moving
lava) are handled _after_ the player moved. When the motion has taken
it into another other actor, the appropriate effect—collecting a
coin or dying—is activated.

This method scans through the array of actors, looking for an actor
that overlaps the one given as an argument, without actually being the
same actor.

// include_code

[source,javascript]
----
Level.prototype.actorAt = function(actor) {
  for (var i = 0; i < this.actors.length; i++) {
    var other = this.actors[i];
    if (other != actor &&
        actor.pos.x + actor.size.x > other.pos.x &&
        actor.pos.x < other.pos.x + other.size.x &&
        actor.pos.y + actor.size.y > other.pos.y &&
        actor.pos.y < other.pos.y + other.size.y)
      return other;
  }
};
----

== Actors and actions ==

The `animate` method, which we add to the `Level` type below, is
responsible for giving the actors in the level a chance to move.

// include_code

[source,javascript]
----
var maxStep = 0.05;

Level.prototype.animate = function(step, keys) {
  if (this.status != null)
    this.finishDelay -= step;

  while (step > 0) {
    var thisStep = Math.min(step, maxStep);
    for (var i = 0; i < this.actors.length; i++)
      this.actors[i].act(thisStep, this, keys);
    step -= thisStep;
  }
};
----

When the level's `status` property has a non-null value (which is the
case when the player has won or lost), we must count down the
`finishDelay` property, which tracks the time between the point where
winning or losing happens, and the point where we actually want to
stop showing the level.

The `while` loop is responsible for cutting the time step we are
animating into suitably small pieces. It ensures that no step larger
than `maxStep` is taken. For example, a `step` of 0.12 second would be
cut into two steps of 0.05 second, and one of 0.02.

Actor objects are supposed to implement an `act` method, which is
given as arguments the time step, the level object, and an object with
information about the keys the player is holding down. Here is a
simple one, for the `Lava` actor type:

// include_code

[source,javascript]
----
Lava.prototype.act = function(step, level) {
  var newPos = this.pos.plus(this.speed.times(step));
  if (!level.obstacleAt(newPos, this.size))
    this.pos = newPos;
  else if (this.repeatPos)
    this.pos = this.repeatPos;
  else
    this.speed = this.speed.times(-1);
};
----

It computes a new position by adding the product of the time step and
its current speed to its old position. If no obstacle blocks that new
position, it moves there. If there is an obstacle, the behavior
depends on the type of moving lava this is—dripping lava has a
`repeatPos` property, to which it jumps back when it hits something.
Bouncing lava simply inverts its speed (multiplies it by -1) in order
to start moving in the other direction.

Coins need to update their wobble phase in their `act` method:

// include_code

[source,javascript]
----
var wobbleSpeed = 8, wobbleDist = 0.07;

Coin.prototype.act = function(step) {
  this.wobble += step * wobbleSpeed;
  var wobblePos = Math.sin(this.wobble) * wobbleDist;
  this.pos = this.basePos.plus(new Vector(0, wobblePos));
};
----

The `wobble` property is updated to track time, and then used as
argument to `Math.sin` to create a wave, which is used to compute a
new position. Coins don't detect collisions. Their motion is defined
in such a way that it stays within their starting square, and
collision with the player is handled by the player's `act` method.

Which is the next things we get to. Player motion is separated per
axis, because hitting the floor should not prevent horizontal motion,
and hitting a wall should not stop falling or jumping motion. The
method below implements the horizontal part.

// include_code

[source,javascript]
----
var playerXSpeed = 7;

Player.prototype.moveX = function(step, level, keys) {
  this.speed.x = 0;
  if (keys.left) this.speed.x -= playerXSpeed;
  if (keys.right) this.speed.x += playerXSpeed;

  var motion = new Vector(this.speed.x * step, 0);
  var newPos = this.pos.plus(motion);
  var obstacle = level.obstacleAt(newPos, this.size);
  if (obstacle)
    level.playerTouched(obstacle);
  else
    this.pos = newPos;
};
----

The motion is computed based on the state of the left and right arrow
keys. When it would cause the player to hit something, the
`playerTouched` method for the level, which handles things like dying
in lava and collecting coins, is called. Otherwise, the object updates
its position.

The vertical motion works in a comparable way, but has to take jumping
and gravity into account.

// include_code

[source,javascript]
----
var gravity = 30;
var jumpSpeed = 17;

Player.prototype.moveY = function(step, level, keys) {
  this.speed.y += step * gravity;
  var motion = new Vector(0, this.speed.y * step);
  var newPos = this.pos.plus(motion);
  var obstacle = level.obstacleAt(newPos, this.size);
  if (obstacle) {
    level.playerTouched(obstacle);
    if (keys.up && this.speed.y > 0)
      this.speed.y = -jumpSpeed;
    else
      this.speed.y = 0;
  } else {
    this.pos = newPos;
  }
};
----

At the start of the method, the player's vertical speed is updated for
gravity. The gravity, jumping speed, and pretty much all other
constants in this game, have been set by trial-and-error. I tried out
various values to see how they felt.

We then check for obstacles again. If we are hitting an obstacle,
there are two possible outcomes. When the up arrow is pressed, _and_
we are moving down (meaning the thing we hit is below us), the speed
is set to a relatively large, negative value. This causes the player
to jump. If that is not the case, we simply bumped into something, and
the speed is reset to zero.

The actual `act` method looks like this:

// include_code

[source,javascript]
----
Player.prototype.act = function(step, level, keys) {
  this.moveX(step, level, keys);
  this.moveY(step, level, keys);

  var otherActor = level.actorAt(this);
  if (otherActor)
    level.playerTouched(otherActor.type, otherActor);

  // Losing animation
  if (level.status == "lost") {
    this.pos.y += step;
    this.size.y -= step;
  }
};
----

After moving, it checks for other actors that it is colliding with,
and again calls `playerTouched` when it finds one. This time, it
passes the actor object as second argument, because if the other actor
is a coin, `playerTouched` needs to know which one is being collected.

Finally, when the player died (touched lava) we set up a little
animation that causes them to “shrink” or “sink” down, by reducing the
height of the player object.

And here is the method that handles collisions between the player and
other objects:

// include_code

[source,javascript]
----
Level.prototype.playerTouched = function(type, actor) {
  if (type == "lava" && this.status == null) {
    this.status = "lost";
    this.finishDelay = 1;
  } else if (type == "coin") {
    this.actors.splice(this.actors.indexOf(actor), 1);
    if (!this.actors.some(function(actor) {
      return actor.type == "coin";
    })) {
      this.status = "won";
      this.finishDelay = 1;
    }
  }
};
----

When lava is touched, the game's status is set to `"lost"`. When a
coin is touched, that coin is removed from the array of actors, and if
it was the last one, the game's status is set to `"won"`.

The `splice` method is used to cut a piece out of an array. It is
given an index and a number of elements, and removes that many
elements starting at the given index. In this case, we remove a single
element, our coin actor, whose index we found by calling `indexOf`.
Additional arguments can be given to `splice`, and they will be
inserted into the array at the given position, replacing the removed
elements.

That gives us a level that can actually be animated. All that's
missing now is the code that _drives_ the animation.

== Tracking keys ==

For a game like this, we do not want keys to take effect once per
press. Rather, we want their effect (moving the player figure) to
continue happening as long as they are pressed.

We need to set up a key handler that stores the current state of the
left, right, and up keys. We will also want to call `preventDefault`
for those keys, so that they don't end up scrolling the page.

The function below, when given an object with key codes as property
names and key names as value, will return an object that tracks the
current position of those keys. It registers event handlers for
`"keydown"` and `"keyup"` events, and when the key code in the event
is present in the set of codes that it is tracking, update the object.

// include_code

[source,javascript]
----
var arrowCodes = {37: "left", 38: "up", 39: "right"};

function trackKeys(codes) {
  var pressed = Object.create(null);
  function handler(event) {
    if (codes.hasOwnProperty(event.keyCode)) {
      var state = event.type == "keydown";
      pressed[codes[event.keyCode]] = state;
      event.preventDefault();
    }
  }
  addEventListener("keydown", handler);
  addEventListener("keyup", handler);
  return pressed;
}
----

Note how the same handler function is used for both event types. It
looks at the event object's `type` property to determine whether the
key state should be updated to true (`"keydown"`) or false
(`"keyup"`).

== Running the game ==

The `requestAnimationFrame` function, which we saw in Chapter 13,
provides a good way to animate a game. But its interface is quite
primitive—using it requires us to track the last time value we saw,
and re-call the `requestAnimationFrame` function after every frame.

Here is a helper function that wraps those boring parts in a
convenient interface, and allows us to simply call `runAnimation`,
giving it a function that expects a time difference as argument and
draws a single frame. When the frame function returns the value
`false`, the animation stops.

// include_code

[source,javascript]
----
function runAnimation(frameFunc) {
  var lastTime = null;
  function frame(time) {
    var stop = false;
    if (lastTime != null) {
      var timeStep = Math.min(time - lastTime, 100) / 1000;
      stop = frameFunc(timeStep) === false;
    }
    lastTime = time;
    if (!stop)
      requestAnimationFrame(frame);
  }
  requestAnimationFrame(frame);
}
----

I have set a maximum frame step of 100 milliseconds (one tenth of a
second). When the browser tab or window with our page is hidden,
`requestAnimationFrame` calls will be suspended until it is shown
again. In this case, the difference between `lastTime` and `time` will
be the entire time in which the page was hidden. Advancing the game by
that much in a single step will look silly, and might be a lot of work
(remember the time-splitting in the `animate` method).

The function also converts the time steps to seconds, which are an
easier quantity to think about than milliseconds.

The `runLevel` function takes a `Level` object, a constructor for a
display, and optionally a function. It display the level (in
`document.body`), and lets the user play through it. When the level is
finished (lost or won) it clears the display, stops the animation, and
if an `andThen` function was given, calls it with the level's status.

// include_code

[source,javascript]
----
var arrows = trackKeys(arrowCodes);

function runLevel(level, Display, andThen) {
  var display = new Display(document.body, level);
  runAnimation(function(step) {
    level.animate(step, arrows);
    display.drawFrame(step);
    if (level.isFinished()) {
      display.clear();
      if (andThen)
        andThen(level.status);
      return false;
    }
  });
}
----

A game is a sequence of levels. Whenever the player dies, the current
level is restarted. When a level is completed, we move on to the next
level. This can be expressed by the following function, which takes an
array of level plans (arrays of strings) and a display constructor:

// include_code

[source,javascript]
----
function runGame(plans, Display) {
  function startLevel(n) {
    runLevel(new Level(plans[n]), Display, function(status) {
      if (status == "lost")
        startLevel(n);
      else if (n < plans.length - 1)
        startLevel(n + 1);
      else
        console.log("You win!");
    });
  }
  startLevel(0);
}
----

These functions show a peculiar style of programming. Both
`runAnimation` and `runLevel` are higher-order functions, but not in
the style we saw in Chapter 5. The function argument is used to
arrange things to happen at some time in the future, and neither of
the functions returns anything useful. Their task is, in a way, to
schedule actions. Wrapping these actions in functions gives us a way
to store them as a value, so that they can be called at the right
moment.

This programming style is usually called _asynchronous_ programming.
Event handling is also an instance of it, and we will see much more of
it when working with tasks that can take an arbitrary amount of time,
such as network requests in Chapter 17, and in- and output in general
in Chapter 21 (FIXME).

There is a set of level plans available in the `GAME_LEVELS` variable
!!tex (downloadable from `eloquentjavascript.net/code`)!!. This page
feeds them to `runGame`, starting an actual game:

[sandbox="null"]
[focus="yes"]
[source,text/html]
----
<link rel="stylesheet" href="css/game.css">

<script>
  runGame(GAME_LEVELS, DOMDisplay);
</script>
----

ifdef::html_target[]

See if you can beat those. I had quite a lot of fun building them.

endif::html_target[]

== Exercises ==

=== Game over ===

It is tradition for platform games to have the player start with a
limited number of _lives_, and subtract one life each time they die.
When out of lives, the game restarts from the beginning.

Adjust `runGame` to implement lives (have the player start with 3).

ifdef::html_target[]

// test: no

[focus="yes"]
[source,text/html]
----
<link rel="stylesheet" href="css/game.css">

<script>
  // The old runGame function. Modify it...
  function runGame(plans, Display) {
    function startLevel(n) {
      runLevel(new Level(plans[n]), Display, function(status) {
        if (status == "lost")
          startLevel(n);
        else if (n < plans.length - 1)
          startLevel(n + 1);
        else
          console.log("You win!");
      });
    }
    startLevel(0);
  }
  runGame(GAME_LEVELS, DOMDisplay);
</script>
----

endif::html_target[]

!!solution!!

The most obvious solution would be to make `lives` a variable that
lives in `runGame`, and is thus visible by the `startLevel` closure.

Another approach, which fits nicely with spirit of the rest of the
function, would be to add a second argument to `startLevel` that gives
the amount of lives. When the whole state of a system stored in the
arguments to a function, calling that function provides an elegant way
to transition to a new state.

In any case, when a level is lost, there should now be two possible
state transitions: If that was the last life, we go back to level zero
with the starting amount of lives. If not, we repeat the current level
with one less life remaining.

!!solution!!

=== Pausing the game ===

Make it possible to pause (suspend) and unpause the game by pressing
the Escape key.

This can be done by changing the `runLevel` function to use another
keyboard event handler, and interrupting or resuming the animation
whenever the Escape key is hit.

The `runAnimation` interface may not look like it is suitable for
this, at first glance, but it is, if you rearrange the way `runLevel`
calls it.

When you have that working, there is something else you could try. The
way we have been registering keyboard event handlers is somewhat
problematic. The `arrows` object is currently a global variable, and
its event handlers are kept around even when no game is running. They
_leak_ out of our system, you could say. Extend `trackKeys` to provide
a way to unregister its handlers, and then change `runLevel` to
register its handlers when it starts, and unregister them again when
it is finished.

ifdef::html_target[]

// test: no

[focus="yes"]
[source,text/html]
----
<link rel="stylesheet" href="css/game.css">

<script>
  // The old runLevel function. Modify this...
  function runLevel(level, Display, andThen) {
    var display = new Display(document.body, level);
    runAnimation(function(step) {
      level.animate(step, arrows);
      display.drawFrame(step);
      if (level.isFinished()) {
        display.clear();
        if (andThen)
          andThen(level.status);
        return false;
      }
    });
  }
  runGame(GAME_LEVELS, DOMDisplay);
</script>
----

endif::html_target[]

!!solution!!

An animation can be interrupted by returning `false` from the function
given to `runAnimation`. It can be continued by simply calling
`runAnimation` again.

To communicate the fact that the animation should be intterupted to
the animation function, you can use a variable that both the event
handler and that function have access to.

When finding a way to unregister the handlers registered by
`trackKeys`, remember that the _exact_ same function value that was
passed to `addEventListener` must be passed to `removeEventListener`
to successfully remove a handler. Thus, the `handler` function value
created in `trackKeys` must be available to the code that unregisters
the handlers.

You can add a property to the object returned by `trackKeys`,
containing either that function value, or a method that handles the
unregistering directly.

!!solution!!