<h1>Freddy vs JSON: how to make a top-down shooter</h1>
<p><em>Written 2019-05-03</em></p>
<p>I will tell you how I created a simple top-down shooter in JavaScript without using any additional libraries. But this article is not replicating the full game but instead tries to show which steps to take to start writing a game from scratch.</p>
<!--more-->
<p>A couple of years ago (Oh it's almost a decade! Am I that old already?), when the Canvas API got widely adopted by most browsers, I started experimenting with it. The fascination was high and I immediately tried to use it for interactive toys and games.</p>
<p>Of course, the games I made (and make) are usually not very sophisticated. That is mainly because I create them only for fun and without much eye-candy or even sound. What really fascinates me is the underlying mechanics. Otherwise, I could just use one of those <ahref="https://github.com/collections/javascript-game-engines">awesome game engines</a>, that exist already.</p>
<p>To share some of the fun, I created a tiny top down shooter for a tech session in my company (<ahref="https://wunder.dog">we're hiring, btw</a>). The <ahref="https://github.com/nkoehring/FreddyvsJSON">result can be found on Github</a>. I commented the code well so it should be quite helpful to just read it. But if you want to know how I created the game step-by-step, this article is for you.</p>
<h2>The Game</h2>
<p>To give you an impression of what I created:</p>
<p>The little gray box is your ship. You are controlling the little gray box with either WASD or Arrow keys and you can shoot tiny yellow boxes at your enemies — the red boxes — by pressing Space or Enter. The enemies shoot back though. They don't really aim well, but at some point they'll flood the screen with tiny red boxes. If they hit you, they hurt. Every time you get hurt you shrink, until you completely disappear. The same happens with your opponents.</p>
<h2>Preconditions</h2>
<p>This post is not about the game itself but about the underlying mechanics and some of the tricks used to make it work. My intention is to provide an entry for understanding more complex game development for people with some existing programming experience. The following things are helpful to fully understand everything:</p>
<h3>Fundamental Game Engine Mechanics</h3>
<p>Most — if not all — game engines have the same fundamental building blocks:</p>
<ul>
<li>The <code>state</code>, that defines the current situation (like main menu, game running, game lost, game won, etc).</li>
<li>A place to store all the objects and related data.</li>
<li>The <code>main loop</code>, usually running sixty times per second, that reads the object information, draws the screen and applies updates to object data</li>
<li>An <code>event handler</code> that maps key presses, mouse movements and clicks to data changes.</li>
</ul>
<h3>The Canvas Element</h3>
<p>The Canvas element allows you to handle pixel based data directly inside the browser. It gives you a few functions to draw primitives. It is easy to draw, for example, a blue rectangle but you need more than one action to draw a triangle; to draw a circle you need to know how to use arcs.</p>
<p>Exactly because drawing rectangles is the easiest and fastest thing to do with the Canvas API, I used them for everything in Freddy vs JSON. That keeps the complexities of drawing more exciting patterns or graphics away and helps focus on the actual game mechanics. This means, after initializing the canvas besides setting colors we only use two functions:</p>
<pre><codeclass="language-js">const ctx = canvas.getContext('2d') // this is the graphics context
ctx.fillStyle = '#123456' // use color #123456
ctx.fillText(text, x, y) // write 'text' at coords x, y
ctx.fillRect(x, y, width, height) // draw filled rectangle
</code></pre>
<h2>Step One: Some HTML and an initialized Canvas</h2>
<p>Because the code is going to run in the browser, some HTML is necessary. A minimal set would be just the following two lines:</p>
<p>This works but of course some styling would be great. And maybe having a title? Check out a <ahref="https://github.com/nkoehring/FreddyvsJSON/blob/master/index.html">complete version on Github</a>.</p>
<p>Initializing a Canvas is also pretty simple. Inside <code>app.js</code> following lines are necessary:</p>
<p>I chose rather arbitrary values for width and height. Feel free to change them to your liking. Just know that higher values obviously will result in more work for your computer.</p>
<h2>Step Two: Game Mode / States</h2>
<p>To avoid creating a <ahref="http://en.wikipedia.org/wiki/Big_ball_of_mud">big ball of mud</a> it is common to use a <ahref="https://en.wikipedia.org/wiki/Finite-state_machine">state machine</a>. The idea is to describe the high level states and their valid transitions and using a central state handler to control them.</p>
<p>There libraries that help with state machines, but it is also not too hard to create this yourself. In the game I created I used a very simple state machine implementation: The possible states and their transitions are described in <ahref="https://en.wikipedia.org/wiki/Enumerated_type">Enum-like objects</a>. Here some code to illustrate the idea. The code uses some rather new language features: <ahref="https://developer.mozilla.org/en-US/docs/Glossary/Symbol">Symbols</a> and <ahref="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer#Computed_property_names">Computed Property Names</a>.</p>
<pre><codeclass="language-js">const STATE = {
start: Symbol('start'), // the welcome screen
game: Symbol('game'), // the actual game
pause: Symbol('pause'), // paused game
end: Symbol('end') // after losing the game
}
const STATE_TRANSITION = {
[STATE.start]: STATE.game, // Welcome screen => Game
[STATE.game]: STATE.pause, // Game => Pause
[STATE.pause]: STATE.game, // Pause => Game
[STATE.end]: STATE.start // End screen => Welcome screen
}
</code></pre>
<p>This is not a full state machine but does the job. For the sake of simplicity I violate the state machine in one occasion though: There is no transition from the running game to the end of the game. This means I have to jump directly, without using the state handler, to the end screen after the player dies. But this saved me from a lot of complexity. Now the state control logic is effectively only one line:</p>
<p>Freddy vs JSON uses this in the click handler. A click into the canvas changes the state from welcome screen to the actual game, pauses and un-pauses the game and brings you back to the welcome screen after losing. All that in only one line. The new state is set to a variable that is respected by the central update loop. More on that later.</p>
<p>Of course much more could be done with a state. For example weapon or ship upgrades could be realised. The game could transition towards higher difficulty levels and get special game states like an upgrade shop or transfer animations between stages. Your imagination is the limit. And the amount of lines in your state handler, I guess.</p>
<h2>Step Three: Data Handling</h2>
<p>Games usually have to handle a lot of information. Some examples are the position and health of the player, the position and health of each enemy, the position of each single bullet that is currently flying around and the amount of hits the player landed so far.</p>
<p>JavaScript allows different ways to handle this. Of course, the state could just be global. But we all (should) know that global variables are the root of all evil. Global constants are okay because they stay predictable. Just don't use global variables. If you're still not convinced, please read this <ahref="https://softwareengineering.stackexchange.com/questions/148108/why-is-global-state-so-evil">entry on stackexchange</a>.</p>
<p>Instead of global variables, you can put everything into the same scope. A simple example is shown next. The following code examples use template literals, a new language feature. <ahref="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals">Learn more about template literals here</a>.</p>
<pre><codeclass="language-js">function Game (canvas) { // the scope
<p>This is nice because you have easy access just like with global variables without actually using global variables. It still opens the door to potential problems if you only have one big scope for everything, but the first game is probably small enough to get away with not thinking about this too much.</p>
<p>Another way is to use classes:</p>
<pre><codeclass="language-js">class Game {
constructor (canvas) {
this.ctx = canvas.getContext('2d')
this.playerMaxHealth = 10
this.playerHealth = 10
}
handleThings () {
const max = this.playerMaxHealth
const hp = this.playerHealth
ctx.fillText(`HP: ${hp} / ${max}`, 10, 10)
}
}
</code></pre>
<p>That looks like a bit more boilerplate but classes are good to encapsulate common functionality. They get even better if your game grows and you want to stay sane. But in JavaScript they are just syntactical sugar. Everything can be achieved with functions and function scopes. So it is up to you, what you use. The two last code examples are essentially the same thing.</p>
<p>Now that we decided on how to save all the data (Freddy vs JSON uses a class so I'll use classes here too) we can further structure it... or not. Freddy vs JSON saves everything flat. That means for example that each player attribute gets its own variable instead of using a player object that contains a lot of properties. The latter is probably more readable so you might want to go this path. Object access is also pretty fast nowadays so there is probably not a noticeable difference if you write <code>this.player.health</code> instead of <code>this.playerHealth</code>. If you are really serious about performance though, you might want to investigate this topic further. You can check out my <ahref="https://jsperf.com/nested-and-flat-property-access/1">jsperf experiment</a> for a start.</p>
<p>Data manipulation happens in the update loop or when handling events. The next steps explain these topics further.</p>
<h2>Step Four: The Main Loop</h2>
<p>If event based changes are enough, like on a website, a separate loop wouldn't be necessary. The user clicks somewhere, which triggers an event that updates something and eventually re-renders a part of the page. But in a game some things happen without direct user interaction. Enemies come into the scene and shoot at you, there might be some background animation, music plays, and so on. To make all this possible a game needs an endlessly running loop which repeatedly calls a function that checks and updates the status of everything. And to make things awesomely smooth it should call this function in a consistent interval — at least thirty, better sixty times per second.</p>
<p>The following code examples use another rather new language feature called <ahref="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions">Arrow Functions</a>.</p>
<p>Typical approaches to run a function in an regular interval would include the usage of <code>setInterval</code>:</p>
<pre><codeclass="language-js">let someValue = 23
setInterval(() => {
someValue++
}, 16)
</code></pre>
<p>Or <code>setTimeout</code></p>
<pre><codeclass="language-js">let someValue = 42
function update () {
someValue++
setTimeout(update, 16)
}
update()
</code></pre>
<p>The first version just runs the function endlessly every sixteen milliseconds (which makes sixty-two and a half times per second), regardless of the time the function itself needs or if is done already. The second version does its potentially long running job before it sets a timer to start itself again after sixteen milliseconds.</p>
<p>The first version is especially problematic. If a single run needs more than sixteen milliseconds, it runs another time before the first run finished, which might lead to a lot of fun, but not necessarily to any useful result. The second version is clearly better here because it only sets the next timeout after doing everything else. But there is still a problem: Independent of the time the function needs to run it will wait an additional sixteen milliseconds to run the function again.</p>
<p>To mitigate this, the function needs to know how long it took to do its job and then substract that value from the waiting time:</p>
<pre><codeclass="language-js">let lastRun
let someValue = 42
function update () {
someValue++
const duration = Date.now() - lastRun
const time = duration > 16 ? 0 : 16 - time
setTimeout(update, time)
lastRun = Date.now()
}
lastRun = Date.now()
update()
</code></pre>
<p><code>Date.now()</code> returns the current time in milliseconds. With this information we can figure out how much time has passed since the last run. If more than sixteen milliseconds have passed since then just start the update immediately and crush that poor computer (or better slow down the execution time and be nice to the computer), otherwise wait as long as necessary to stay at around sixty runs per second.</p>
<p>Please note that Date.now() is not the best way to measure performance. To learn more about performance and high resolution time measurement, check out: <ahref="https://developer.mozilla.org/en-US/docs/Web/API/Performance">https://developer.mozilla.org/en-US/docs/Web/API/Performance</a></p>
<p>Cool. This way you can also slow everything down to a chill thirty frames per second by setting the interval to thirty-three milliseconds. But lets not go that path. Lets do what the cool kids with their shiny new browsers do. Lets use <ahref="https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame">requestAnimationFrame</a>.</p>
<p><code>requestAnimationFrame</code> takes your update function as an argument and will call it right before the next repaint. It also gives you the timestamp of the last call, so that you don't have to ask for another one, which potentially impacts your performance. Lets get down to the details:</p>
<p>This is the simplest version. It runs your update function as close as possible to the next repaint. This means it usually runs sixty times per second, but the rate might be different depending on the screen refresh rate of the computer it runs on. If your function takes longer than the duration between screen refreshes, it will simply skip some repaints because it is not asking for a repaint before it is finished. This way it will always stay in line with the refresh rate.</p>
<p>A function that does a lot of stuff might not need to run that often. Thirty times per second is usually enough to make things appear smooth and some other calculations might not be necessary every time. This brings us back to the timed function we had before. In this version we use the timestamp that <code>requestAnimationFrame</code> is giving us when calling our function:</p>
<pre><codeclass="language-js">let lastRun
function update (stamp) {
/* heavy work here */
lastRun = stamp
// maybe 30fps are enough so the code has 33ms to do its work
if (stamp - lastRun >= 33) {
requestAnimationFrame(update)
}
}
// makes sure the function gets a timestamp
requestAnimationFrame(update)
</code></pre>
<h2>Step Five: Event Handling</h2>
<p>People usually want to feel like they are in control of what they are doing. This brings us to a point where the game needs to handle input from the user. Input can be either a mouse movement, a mouse click or a key press. Key presses are also separated into pressing and releasing the key. I'll explain why later in this section.</p>
<p>If your game is the only thing running on that page (and it deserves that much attention, doesn't it?) input events can simply be bound to <code>document</code>. Otherwise they need to be bound to the canvas event directly. The latter can be more complicated with key events because key events work best with actual input fields. This means you need to insert one into the page, and make sure it stays focused so that it gets the events. Each click into the canvas would make it lose focus. To avoid that, you can use the following hack:</p>
<p>Or you simply put everything to its own page and bind the event listeners to <code>document</code>. It makes your life much easier.</p>
<p>Side note: People might wonder why I don't use addEventListener. Please use it if it makes you feel better. I don't use it here for simplicity reasons and it will not be a problem as long as each element has exactly one event listener for each event type.</p>
<h3>Mouse Movement</h3>
<p>Mouse movements are not really used in Freddy vs JSON but this post wouldn't be complete without explaining them. So this is how you do it:</p>
<p>This will be executed on every little movement of the mouse as long as it is on top of the canvas. Usually you want to <ahref="https://davidwalsh.name/javascript-debounce-function">debounce</a> that event handler because the event might fire at crazy rates. Another way would be to use it only for something very simple, like to save the mouse coordinates. That information can be used in a function that is not tied to the event firing, like our update function:</p>
<p>The <ahref="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent">MouseEvent object</a> contains a lot more useful information. I suggest you to check out the link and read about it.</p>
<p>This should draw two pixel wide boxes wherever you touch the canvas with your mouse. Yeah, a drawing program in ten lines! Photoshop, we're coming for you!</p>
<h3>Mouse Clicks</h3>
<p>But lets get back to reality. Mouse clicks are another important interaction:</p>
<p>The event object again contains all kind of useful information. It is the same type of object that you get from mouse movement. Makes life simpler, doesn't it?</p>
<p>Now to make use of the mouse clicks, lets adapt the former code example:</p>
<p><ahref="https://codesandbox.io/s/3qw6q7j535">Check it out on CodeSandbox</a></p>
<p>Now the boxes are only drawn while holding down the mouse button. Boom, one step closer to the ease of use of Photoshop! It is incredible, what you can do with it already. Just check out this incredible piece of art:</p>
<p><imgsrc="https://github.com/nkoehring/FreddyvsJSON/raw/master/blogpost/drawing.jpg"alt="incredible piece of art"></p>
<h3>Key Events</h3>
<p>The last important input comes from key presses. Okay, it is not really the last input type. Other ones would come from joysticks or gamepads. But there are some old-school people like me who still prefer using the keyboard to navigate their space ship.</p>
<p>Input handling is theoretically simple but in practice it is everything but. That's why this section explains not only how key events work but also how to get them right. Look forward to event handling, the relationship between velocity and acceleration, and frame rate agnostic timing...</p>
<p>The simplest version of key event handling looks like this:</p>
<p>But <code>keypress</code> is deprecated and should not be used. It is anyways better to separate the <code>keyPress</code> into two events: <code>KeyDown</code> and <code>KeyUp</code> and I'll explain why.</p>
<p>For now imagine you have that awesome space ship in the middle of the screen and want to make it fly to the right if the user presses <code>d</code> or <code>ArrowRight</code>:</p>
<pre><codeclass="language-js">class Game {
constructor(canvas, width, height) {
// we'll need those values
this.width = canvas.width = width;
this.height = canvas.height = height;
this.ctx = canvas.getContext("2d");
this.shipSize = 10;
this.shipHalf = this.shipSize / 2.0; // you'll need that a lot
<p><ahref="https://codesandbox.io/s/2w10vo897n">check it out on CodeSandbox</a></p>
<p>Okay, that is kinda working, at least if you press <code>d</code>. But the arrow key is somehow not working and the ship's movement feels a bit jumpy. That doesn't seem to be optimal.</p>
<p>The problem is that we're relying on repeated key events. If you press and hold a key, the <code>keypress</code> event is repeated a couple of times per second, depending on how you set your key repeat rate. There is no way to use that for a smooth movement because we can not find out how fast the users keys are repeating. Sure, we could try to measure the repeat rate, hoping the user holds the key long enough. But let's try to be smarter than that.</p>
<p>Lets recap: We hold the key, the ship moves. We leave the key, the movement stops. That is what we want. What a happy coincidence that these two events have ...erm.. events:</p>
<pre><codeclass="language-js">class Game {
constructor(canvas, width, height) {
// we'll need those values
this.width = canvas.width = width;
this.height = canvas.height = height;
this.ctx = canvas.getContext("2d");
this.shipSize = 10;
this.shipHalf = this.shipSize / 2.0; // you'll need that a lot
// position the ship in the center of the canvas
this.shipX = width / 2.0 - this.shipHalf;
this.shipY = height / 2.0 - this.shipHalf;
this.shipMoves = false;
// key is pressed down
document.onkeydown = event => {
const key = event.key;
switch (key) {
case "d":
case "ArrowRight":
this.shipMoves = "right";
break;
case "a":
case "ArrowLeft":
this.shipMoves = "left";
break;
case "w":
case "ArrowUp":
this.shipMoves = "up";
break;
case "s":
case "ArrowDown":
this.shipMoves = "down";
break;
}
};
document.onkeyup = () => {
this.shipMoves = false;
};
this.update();
}
// convenience matters
rect(color, x, y, w, h) {
this.ctx.fillStyle = color;
this.ctx.fillRect(x, y, w, h);
}
update() {
// move the ship
if (this.shipMoves) {
if (this.shipMoves === "right") this.shipX++;
else if (this.shipMoves === "left") this.shipX--;
else if (this.shipMoves === "up") this.shipY--;
else if (this.shipMoves === "down") this.shipY++;
<p><ahref="https://codesandbox.io/s/nr8r6myz60">check it out on CodeSandbox</a></p>
<p>I felt like adding all directions right away. Now the movement itself is decoupled from the key events. Instead of changing the coordinates directly on each event, a value is set to a movement direction and the main loop takes care of adapting the coordinates. That's great because we don't care about any key repeat rates anymore.</p>
<p>But there are still some problems here. First of all, the ship can only move in one direction at a time. Instead it should always be able to move in two directions at a time, like up- and leftwards. Then the movement stops if the switch from one key to another is too fast. That might happen in a heated situation between your ship and the enemies bullets. Also the movement is bound to the frame rate. If the frame rate drops or the screen refreshes on a different rate on the players computer, your ship becomes slower or faster. And last but not least the ship simply jumps to full speed and back to zero. For a more natural feeling it should instead accelerate and decelerate.</p>
<p>Lots of work. Lets tackle the problems one by one:</p>
<p>Bidirectional movements are easy to do. We just need a second variable. And to simplify things even more, we can set these variables to numbers instead of identifying strings. Here you see why:</p>
<pre><codeclass="language-js">class Game {
constructor(canvas, width, height) {
/* ... same as before ... */
this.shipMovesHorizontal = 0;
this.shipMovesVertical = 0;
// this time, the values are either positive or negative
// depending on the movement direction
document.onkeydown = event => {
const key = event.key;
switch (key) {
case "d":
case "ArrowRight":
this.shipMovesHorizontal = 1;
break;
case "a":
case "ArrowLeft":
this.shipMovesHorizontal = -1;
break;
case "w":
case "ArrowUp":
this.shipMovesVertical = -1;
break;
case "s":
case "ArrowDown":
this.shipMovesVertical = 1;
break;
}
};
// to make this work, we need to reset movement
// but this time depending on the keys
document.onkeyup = event => {
const key = event.key;
switch (key) {
case "d":
case "ArrowRight":
case "a":
case "ArrowLeft":
this.shipMovesHorizontal = 0;
break;
case "w":
case "ArrowUp":
case "s":
case "ArrowDown":
this.shipMovesVertical = 0;
break;
}
};
this.update();
}
/* more functions here */
update() {
// move the ship
this.shipX += this.shipMovesHorizontal;
this.shipY += this.shipMovesVertical;
/* drawing stuff */
}
}
</code></pre>
<p><ahref="https://codesandbox.io/s/v0l8v95nr5">Find the full version on CodeSandbox</a></p>
<p>This not only allows the ship to move in two directions at the same time, it also simplifies everything. But there's still the problem, that fast key presses don't get recognized well.</p>
<p>What actually happens in those stressful moments is correct from the code's point of view: If a key of the same dimension (horizontal or vertical) is pressed, set the movement direction, if it is released set movement to zero. But humans are not very exact. They might press the left arrow (or <code>a</code>) a split second before they fully released the right arrow (or <code>d</code>). This way, the function switches the movement direction for that split second but then stops because of the released key.</p>
<p>To fix this, the <code>keyup</code> handler needs a bit more logic:</p>
<p><ahref="https://codesandbox.io/s/x765pl1zm4">Check out the full code at CodeSandbox</a></p>
<p>Much better, isn't it? Whatever we do, the ship is flying in the expected direction. Time to tackle the last problems. Lets go with the easier one first: Acceleration.</p>
<p>For now, the ship simply has a fixed speed. Lets make it faster first, because we want action, right? For that, we'll define the maximum speed of the ship:</p>
<pre><codeclass="language-js">this.shipSpeed = 5 // pixel per frame
<p>This slowly accelerates the ship until full speed. But it still stops immediately. To decelerate the ship and also make sure the ship actually stops and doesn't randomly float around due to rounding errors, some more lines are needed. You'll find everything in <ahref="https://codesandbox.io/s/kxpn09n077">the final version on CodeSandbox</a>.</p>
<p>Now the last problem has be solved: Framerate-dependent movement. For now, all the values are tweaked in a way that they work nicely at the current speed. Lets assume at sixty frames per second. Now that poor computer has to install updates in the background or maybe it is just Chrome getting messy. Maybe the player has a different screen refresh rate. The result is a drop or increase of the frame rate. Lets take a drop down to the half as an example. Thirty frames per second is still completely smooth for almost everything. Movies have thirty frames per second and they do just fine, right? Yet our ship is suddenly only half as fast and that difference is very noticeable.</p>
<p>To prevent this, the movement needs to be based on actual time. Instead of a fixed value added to the coordinates each frame, a value is added that respects the time passed since the last update. The same is necessary for velocity changes. So instead of the more or less arbitrary five pixels at sixty frames per second we set the value in pixels per millisecond because everything is in millisecond precision.</p>
<p>This makes the next step rather easy: Count the amount of milliseconds since the last update and multiply it with the maximum speed and acceleration values:</p>
<pre><codeclass="language-js"> constructor () {
/* ... */
this.shipSpeed = 0.3 // pixels per millisecond
// how fast the ship accelerates
this.shipAcceleration = this.shipSpeed / 10.0
this.shipVelocityHorizontal = 0
this.shipVelocityVertical = 0
/* ... */
// this should always happen right before the first update call
// performance.now gives a high precision time value and is also
<p><ahref="https://codesandbox.io/s/j4rzoq5kqy">Check out the full version at CodeSandbox</a></p>
<p>If everything is the same as before you did everything right. Now independent of the frame rate you ship will move five pixels per millisecond. Unfortunately I didn't find a good way to test that except for changing the refresh rate of your screen or overwriting <code>requestAnimationFrame</code> so I left this part out of the post.</p>
<h2>The End</h2>
<p>Congratulations, you made a fully moving ship. This Post ends here but of course there is so much more to learn about game development. <ahref="https://nkoehring.github.io/FreddyvsJSON">Freddy vs JSON</a> adds some more elements but uses only techniques described in this article. Feel free to check out <ahref="https://github.com/nkoehring/FreddyvsJSON">its source code</a> and create a ton of games like it. Or completely different ones. Be creative and enjoy to use what you've just learned.</p>
