LunarLander documentation

1. Motivation
2. The engine
- 2.1. The main structure
- 2.2. The main game-loop
3. The game: Lunar Lander

1. Motivation

I want to create a game that can be played with unusual input methods. I was inspired by this video where Jonas Tyroller and Blackthornprod build a coop game that is played by scanning barcodes. It looked fun and forced the players to move around, because the barcodes were all over the room (or on their bodies even).

2. The engine

Initially I decided to not use a game engine but to build a static website for the game. This would allow the game to be as accessible as I can make it.

In an afterthought, I realized that what I was building was a (very crude) game engine. So here is what a game would look like:

A game is a javascript object. It will implement the following functions:

`init`: will only be called at the start of the game and allows for some setup.
`show`: draws the current state on the canvas.
`step`: updates the state, in recognition that some time has gone by.
`act_on_{input.command}`: takes an input string and adaptes the state.
`act_on_{input.keypress}`: takes an input keyevent and adaptes the state.

2.1. The main structure

The outermost structure of the project will be a html file.

2.1.1. head

We need to load the game before the engine, so the engine can call the game.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>LunarLander play</title>
    <link rel="icon" href="static/favicon.png" type="image/png">
    <link rel="stylesheet" href="play.css">
    <script src="game.js"></script>
    <script src="engine.js"></script>
    <meta name="viewport" content="width=device-width,initial-scale=1" />
  </head>
  <body>

Make the body as screen filling as possible.

html body {
  padding: 0px;
  margin: 0px;
}
html {
  height: 100%;
}
body {
  min-height: 100%;
}

The body will be a flexbox that holds the game-board (as big as possible) and the command-prompt (using as little place as possible, while still remaining easily usable).

body {
  display: flex;
  flex-direction: column;
}

2.1.2. game-board

The game-board is where all the visual information will end up.

I chose a canvas because this is supposed to allow drawing stuff on it. Perhaps one can do something more clever (with vector-graphics or webgl or vulcan perhaps)? For now the easiest solution suffice.

<div id="game-board-wrapper">
  <canvas id="game-board" tabindex='1'></canvas
</div>

The wrapper is there so the canvas size can be set to its size. The wrapper should be as big as possible, leaving just enough space for the command prompt.

The tabindex is there so the canvas can be focused, which in turn will enable acting on the game by keypress (instead of commands on the command prompt).

#game-board-wrapper {
  flex: 1;
}

2.1.2.1. resizing the game-board

When the browser is resized, then the game-board should be resized with it. There should be no scrollbars (because the players attention should be on the game, not on the browser).

Canvases are tricky. I can set the external width and height in css.

#game-board {
    width: 100%;
    height: 100%;
}

I did have difficulties with this css-only solution, though. A vertial scrollbar kept apearing. The only reliable solution I found was changing the height by hand (and javascript).

update_external_canvas_size = function() {
    var canvas = document.getElementById("game-board");
    var command_prompt = document.getElementById("command-prompt");

    // a magical number, found by trial and error,
    // so that there is no scroll bar appears on resize
    const additional_height = 6

    canvas.style.height = parseInt(window.innerHeight) - parseInt(command_prompt.clientHeight) - additional_height + "px";
}

But canvases also have an internal size, which corresponds to the resolution. It also has to be adapted when the size changes, or else everything gets blury.

update_internal_canvas_size = function() {
    var canvas = document.getElementById("game-board");
    // make the internal size match the external size
    canvas.width  = canvas.offsetWidth;
    canvas.height = canvas.offsetHeight;
}

Resizing the canvas also means that the content is lost. So we have to redraw it (given that there already is something to draw). And because we basically never want to update just internal or just external size, all the resizing and redrawing comes together in one function:

window.game_has_been_initialized = false;
update_canvas_size = function() {
    update_external_canvas_size();
    update_internal_canvas_size();
    // if there is already content, redraw it
    if (window.game_has_been_initialized) {
        window.game.show();
    }
}

So when should the size of the canvas be updated? Every time the window is resized.

window.onresize = update_canvas_size;

But also when the site is opened and all html-elements are loaded for the first time.

Here we can get away with waiting for the event DOMContentLoaded, which happens before css and images and anything external is loaded. There are many other events that can be listened to, in case this ceases to work.

window.addEventListener('DOMContentLoaded', update_canvas_size);

2.1.2.2. keypresses on the game-board

When the canvas is focused then pressing a key on the keyboard (keydown-event) should send a signal to the game, more precisely the act_on_input.keypress method. This is meant as an alternative way of playing the game, for those who don't want to do it via the command prompt.

Linking the canvas to game is not so trivial, because at this point in time the game has not been loaded yet. So we have to wait until it has.

link_keypress_events_on_canvas_to_the_game = function() {
    var canvas = document.getElementById("game-board");
    canvas.addEventListener('keydown', window.game.act_on_input.keypress, false);
}

window.addEventListener('DOMContentLoaded', link_keypress_events_on_canvas_to_the_game);

2.1.3. command-promt

The command-prompt is where the user can enter text (either with keyboard or with a scanner).

It will consist of 3 parts:

the label: Some text that tells the player what kind of input is expected here.
the input: A text field the player can put text into.
the submit button: A button so the player can tell the program to use the entered text.

There exist perfectly fine html-elements for this: form and input.

Normally a form would send the input to the server, but we don't have/need one: onsubmit="return false;"

Instead we want it to call a javascript function: onclick="execute_command()" calls the function execute_command when submit is pressed or enter is hit on the input field. The function will not be called with any arguments, So it will have to read out the text field itself.

The autofocus makes the initial cursor go there. This is crucial when all you have to interact with the game is a scanner.

<form id="command-prompt" onsubmit="return false;">
  <label>Command:</label>
  <input type="text" id="command_input" autofocus/>
  <input type="submit" onclick="execute_command()" value="Execute command"/>
</form>

Time to style our form: All 3 elements should be on the same line to show that they are related. The label and the submit button should use as little space as possible, moved to the left and right side of the page. The text field should stretch out between them, being as big as possible.

#command-prompt {
    display: flex;
    flex-direction: row;
    justify-content: space-around;

}
input[type="text"] {
    flex: 1;
}
input[type="submit"] label {
     /* Not really needed because 0 is the default anyway. */
    flex: 0;
}

On submit (via pressing enter or by click) hand over the input to the game to process and clear the field for the next input.

execute_command = function() {
    // read the command from the input field
    var command_string = document.getElementById("command_input").value;
    document.getElementById("command_input").value = "";
    window.game.act_on_input.command(command_string);
}

2.1.4. close all the tags

We are done with the html, so we close the elements that are still open.

</body>
</html>

2.2. The main game-loop

The main game loop is easy:

Calculate the time that has passed since the last iteration.
Calculate the next step (the next iteration of the games state).
show the current state to the player.

The time_delta will be in the SI unit of time: seconds

var last_iteration_timestamp; // will get it's inital value when the game is initialized

game_loop_iteration = function() {
    var current_iteration_timestamp = Date.now();
    var time_delta = (current_iteration_timestamp - last_iteration_timestamp) / 1000;

    window.game.step(time_delta);
    window.game.show();

    last_iteration_timestamp = current_iteration_timestamp;
}

Before we start that game loop, we have to give the game a chance to set itself up (init):

Also, we take a note that we have already done that. The game should never be drawn when it wasn't initialized, (even if we would like to, because the canvas size has changed).

start_the_main_game_loop = function() {

    // init
    window.game.init()
    window.last_iteration_timestamp = Date.now();
    window.game_has_been_initialized = true;

    // run step every so often
    setInterval(
        game_loop_iteration,
        50 // milliseconds
    );
}

All of this should be done after the main html elements are loaded, so everything we rely on is already there.

window.addEventListener('DOMContentLoaded', start_the_main_game_loop);

3. The game: Lunar Lander

As an example game we will implement a Lunar Lander game.

window.game = Object();

3.1. `init`

Without rotational friction the game gets quite frustrating because the player has to constantly fight to make the ship somewhat upright.

window.game.init = function() {
    var config = create_config();
    window.game.config = config;

    window.game.state = init_game_state(config);
}

config

create_config = function() {
    var config = {
        ship: {
            initial_width: 50,
            initial_height: 75,
            booster_duration: 1.0,
        },

        ground: {
            world_width: 3000,
            base_height: 700,
            resolution: 40,
            landing_place_start: undefined,
            landing_place_width: undefined,
        },

        gravity: 9.81,
        rotational_friction: 0.5,
    };

    config.ground.landing_place_start = random_number_between(0, config.ground.world_width - 1);
    config.ground.landing_place_width = 1.5 * config.ship.initial_width;

    return config;
}

state

init_game_state = function(config) {
    var current_time = Date.now();

    var state = {
        // TODO Find a better name for this.
        //      game.state.state brings nothing but confusion.
        state: "running",

        ship: {
            position: {
                x: 300,
                y: 300,
            },
            velocity: {
                x: 10,
                y: 0,
            },

            // the ship points upwards at a rotation of 0
            rotation: Math.PI * 1 / 16,
            rotational_speed: -0.01,
            booster: {
                last_activation: {
                    main: current_time,
                    left: current_time,
                    right: current_time,
                },
            },
            outline: {
                width: config.ship.initial_width,
                height: config.ship.initial_height,

                // all points relative to the ships position
                // and assuming that the ships rotation is 0
                // and assuming that the ships width and height are both 1
                hull: [
                    [+0.3,  0.0],
                    [+0.5, -0.1],
                    [ 0  , -1.0],
                    [-0.5, -0.1],
                    [-0.3,  0.0],
                    [ 0.0,  0.0],
                ]
            }
        },
        ground: undefined,
        landing_report: [],
    };
    state.ground = create_ground(config.ground);

    return state;
}

3.1.1. The height-map of the ground

We have some freedom of choice on how we want to represent the ground.

A function (mapping x-values to their y-values)?
An array (which would allow constant read time)?
A map (python-programmers would call it a dictionary)?

I chose a map (ground), that tells us the y-coordinate of the ground for a given x-coordinate. If the x-coordinate is not a key in the map, then the height can be interpolated from the neighbouring keys.

This gives us …

… higher flexibility then a function (adding a landing-place of constant height would be hard on a function).
… fast read access (even if it is not constant as it would be in an array).
… a low-poly look (depending on the resolution, which determines how often a key is in the map)
… a relativly compact data structure.

We only save keys from 0 to world_width, outside of that range we will have to use modulo arethmetic to wrap around.

create_ground = function(ground_parameters) {
    var world_width = ground_parameters.world_width;
    var ground = new Map();
    for (let x = 0; x <= world_width; x += ground_parameters.resolution) {
        ground.set(x, ground_function(x, ground_parameters.base_height));
    }
    ground = add_landing_place(ground, world_width, ground_parameters);
    return ground
}

We still haven't decided how the values of the ground map should be determined. The easiest way is probably some sinus-curves added together. The landing place is not considered here, it gets added later.

ground_function = function(x, base_height) {
    return base_height
        + Math.sin(x / 11) * 10
        + Math.sin(x / 31) * 30
        + Math.sin(x / 53) * 50
        + Math.sin(x / 83) * 70;
}

The landing_place is kind of bulldozed into the landscape: We just choose a location and set the height there to be constant.

It might happen that our landing place start left of the world_width and ends right of it. Therefore the landing place has to wrap around.

add_landing_place = function(ground, world_width, ground_parameters) {
    var landing_place_start = ground_parameters.landing_place_start;
    var landing_place_end = Math.floor(landing_place_start + ground_parameters.landing_place_width);
    // remove existing keys in the area
    for (var x = landing_place_start; x <= landing_place_end; x++) {
        ground.delete(modulo(x, world_width));
    }
    // set new keys at the border of the area.
    landing_place_end = landing_place_end % world_width;
    ground.set(landing_place_end, ground_parameters.base_height);
    ground.set(landing_place_start, ground_parameters.base_height);
    return ground
}

It is worth mentioning that there is nothing inherently special about the landing place. The ship can land anywhere on the ground if there is enough room and the slope isn't to high. With add_landing_place we do guarantee that there is at least one possible landing place, though.

3.2. `show`

In this section we will take the game object (which holds all the state) and draw it to the canvas.

There is a lot of optimisation potential here. I basically just used the first thing that worked. There is a very inspiring article on MDN about optimizing canvas rendering.

3.2.1. all

Drawing line art on a html-canvas is easy, there are lots of tutorials out there.

While our game is not very complicated there still is a lot to draw. To remain in controll we can put everything into it's own function.

We can even devide everything we draw into two categories:

stuff that is drawn relative to the screen:

the hud
which is always in the same corner of the canvas.

the pause_overlay
which covers the full screen
stuff that is drawn using it's in-game coordinates:
- the background (which is (space)black at the top little lighter near the ground)
- the ground
- the ship
- the ship's boosters
- the remains of the ship after a crash

window.game.show = function() {
    var canvas = document.getElementById("game-board");
    var ctxt = canvas.getContext("2d");

    // move the viewport so the correct part of the world is rendered to the canvas
    var canvas_coordinates = find_canvas_coordinates(this.state.ship.position, canvas.width, canvas.height);
    ctxt.translate(-canvas_coordinates.left, -canvas_coordinates.top);

    // draw everything that we know only the in-game coordinates of
    draw_background(ctxt, canvas_coordinates);
    draw_ground(ctxt, this.state.ground, this.config.ground.world_width, canvas_coordinates);
    draw_ship(ctxt, this.state.ship);
    draw_booster_flames(ctxt, this.config.ship, this.state.ship);
    if (this.state.state == "crashed") {
        draw_explosion(ctxt, this.state.ship);
    }

    // reset the transformation matrix to identity
    ctxt.setTransform(1, 0, 0, 1, 0, 0);

    // draw everything that will always stay at the same place with respect to the canvas.
    draw_hud(ctxt, this.state.landing_report);
    if (this.state.state == "paused") {
        draw_pause_overlay(ctxt, canvas.width, canvas.height);
    }

}

For the later category we have to choose which part of the world we would like to render to the canvas.

We can express that by describing the canvases border (left/right/top/bottom) in in-game coordinates: We convert to integers to get everything nice and round.

We expect the player to not move too much to the left or right, instead they will try to spend as much time as possible near a landing-place. Therefore we want the same amount of space on the left of the ship as on the right. This makes every horizontal movement immediatelly visable, because the player can se the ground move on the edges of the window.

How about the vertical movement? If possible, both the ground and the ship should be completely visable. So the vertical viewport should start somewhat below the ground and get as high as possible.

Only if the player raises high above the ground and comes close to the top of the window (say they are in the upper 20%) then the viewport should follow them, leaving the ground behind.

find_canvas_coordinates = function(ship_position, canvas_width, canvas_height) {

    var x_left = parseInt(ship_position.x - canvas_width / 2);
    var x_right = x_left + canvas_width;

    var y_top = parseInt(Math.min(0, ship_position.y - 0.20 * canvas_height));
    var y_bottom = y_top + canvas_height;

    return {
        left: x_left,
        right: x_right,
        top: y_top,
        bottom: y_bottom,
        width: canvas_width,
        height: canvas_height,
    }
}

3.2.2. draw the background

The background should give a nice contrast to the other game objects. It should also show that we are in space. Therefore the background is nearly all black with a hint of grey atmosphere close to the ground.

draw_background = function(ctxt, canvas_coordinates) {
    const gradient = ctxt.createLinearGradient(canvas_coordinates.left, canvas_coordinates.height, canvas_coordinates.left, 0);
    gradient.addColorStop(0.0, "#303030");
    gradient.addColorStop(1.0, "black");
    ctxt.fillStyle = gradient;
    ctxt.fillRect(canvas_coordinates.left, canvas_coordinates.top, canvas_coordinates.width, canvas_coordinates.height);
}

3.2.3. draw the pause-overlay

The pause overlay greys out everything else, making clear that there is currently no action there.

Idealy I would have liked to blur everything, but that is not easy on a canvas (though there might be a way I think: change the resolution of the canvas down and up again).

Therefore I chose to just use a mostly transparent white rectangle that is drawn over everything else.

To make it even more clear why nothing is happening there will be a big fat "PAUSE"-text in the center of the screen.

draw_pause_overlay = function(ctxt, canvas_width, canvas_height) {
    ctxt.fillStyle = 'rgba(255, 255, 255, 0.15)';
    ctxt.fillRect(0, 0, canvas_width, canvas_height);
    ctxt.textAlign = "center";
    ctxt.fillStyle = "white";
    ctxt.font = "100px sans-serif";
    ctxt.fillText(
        "PAUSE",
        canvas_width / 2,
        canvas_height / 2,
    );
}

3.2.4. draw the hud

The *h*eads-*u*p *d*isplay shows raw information to the player, allowing him an insight of the current game state. It is just a bunch of named values, colored red if they currently prevent a landing. This should help the player understand why he just crashed.

draw_hud = function(ctxt, landing_report) {
    // position the hud in the upper left corner
    const [hud_position_x, hud_position_y] = [10, 10];

    // this is a magic number
    // I tried to make it so that the columns don't overlap
    const hud_width = 260;

    const font_size = 20;
    ctxt.font = font_size + "px serif";

    landing_report.forEach((criterium, index) => {
        // name, a left alligned string
        ctxt.textAlign = "left";
        ctxt.fillStyle = "grey";
        ctxt.fillText(
            criterium.name+":",
            hud_position_x,
            hud_position_y + (index+1) * font_size
        );

        // value, a right alligned floating point with two decimals
        ctxt.textAlign = "right";
        if (criterium.status != "OK") {
            ctxt.fillStyle = "red";
        };
        ctxt.fillText(
            criterium.value.toFixed(2),
            hud_position_x + hud_width,
            hud_position_y + (index+1) * font_size
        );
    });
}

3.2.5. draw the ship

The ship is the main object of the game and should therefore clearly stand out. I went for a white, clear, simple silhouette, standing out from the dark background.

At some point I might revisite this decision, giving it the look of the original moon lander. This would complicate the code a bit, though.

The silhouette is usefull because it doubles as a collision shape (see chapter 3.3.7).

draw_ship = function(ctxt, ship_state) {
    ctxt.lineWidth = 3;

    ctxt.strokeStyle = "white";
    if (window.game.state.state == "landed") {
        ctxt.strokeStyle = "green";
    }

    var edge_coordinates = ship_edge_coordinates(ship_state);

    ctxt.beginPath();

    // start at th last point, which is where we will end up to close the loop.
    ctxt.moveTo(
        edge_coordinates[edge_coordinates.length -1][0],
        edge_coordinates[edge_coordinates.length -1][1],
    );
    edge_coordinates.forEach((point) => {
        var [x, y] = point;
        ctxt.lineTo(x, y);
    });
    ctxt.stroke();
}

3.2.6. draw the booster flames

The booster flames should be a clear indicator about the direction the ship is currently accelerating. They also should look cool, giving the player a sense of controll.

Their length will scale with the power the booster have left.

draw_booster_flames = function(ctxt, ship_config, ship_state) {
    var position = ship_state.position;
    var width = ship_state.outline.width;

    ctxt.translate(+ship_state.position.x, +ship_state.position.y);
    ctxt.rotate(ship_state.rotation);
    ctxt.translate(-ship_state.position.x, -ship_state.position.y);

    ctxt.lineWidth = 3;
    ctxt.strokeStyle = "#D70000";
    const ship_flame_distance = 10;
    const flame_length = 40;
    const tau = Math.PI * 2;
    const sideflame_angle = tau * 3/16;
    const sideflame_length = flame_length * 0.7
    ctxt.beginPath();
    var power;
    var real_flame_length;
    // main (down)
    power = remaining_booster_power(ship_config, ship_state, "main")
    if (0 < power) {
        real_flame_length = flame_length * power
        ctxt.moveTo(
            position.x - width * +0.25,
            position.y + ship_flame_distance
        );
        ctxt.lineTo(
            position.x - width * +0.15,
            position.y + ship_flame_distance + real_flame_length,
        );

        ctxt.moveTo(
            position.x - width *  0.00,
            position.y + ship_flame_distance,
        );
        ctxt.lineTo(
            position.x - width *  0.00,
            position.y + ship_flame_distance + real_flame_length,
        );

        ctxt.moveTo(
            position.x - width * -0.25,
            position.y + ship_flame_distance,
        );
        ctxt.lineTo(
            position.x - width * -0.15,
            position.y + ship_flame_distance + real_flame_length,
        );
    }
    // right
    power = remaining_booster_power(ship_config, ship_state, "right")
    if (0 < power) {
        real_flame_length = sideflame_length * power;
        ctxt.moveTo(
            position.x + width * 0.5,
            position.y,
        );
        ctxt.lineTo(
            position.x + width * 0.5 + real_flame_length * Math.cos(sideflame_angle),
            position.y + real_flame_length * Math.sin(sideflame_angle),
        );
    }
    // left
    power = remaining_booster_power(ship_config, ship_state, "left")
    if (0 < power) {
        real_flame_length = sideflame_length * power;
        ctxt.moveTo(
            position.x - width * 0.5,
            position.y,
        );
        ctxt.lineTo(
            position.x - width * 0.5 - real_flame_length * Math.cos(sideflame_angle),
            position.y + real_flame_length * Math.sin(sideflame_angle),
        );
    }
    ctxt.stroke();
}

The remaining_booster_power tells how much power the booster has left from it's last activation. It should be a number between 0 and 1. booster can be left/right/main.

remaining_booster_power = function(ship_config, ship_state, booster) {
    var time_of_last_activation = ship_state["booster"]["last_activation"][booster]
    var time_since_last_activation = (Date.now() - time_of_last_activation) / 1000;
    var remaining_power = (ship_config.booster_duration - time_since_last_activation) / ship_config.booster_duration;
    remaining_power = Math.max(0, remaining_power)
    return remaining_power
}

3.2.7. draw the ground

The ground is the main enemy in the game. It should be clearly visable against the rest of the game objects. At the same time it should look lifeless and empty.

draw_ground = function(ctxt, ground, world_width, canvas_coordinates) {

    var relevant_pseudo_keys = all_relevant_pseudo_keys(canvas_coordinates, world_width, ground.keys());

    ctxt.fillStyle = "#606060";  // a nice dark grey
    ctxt.beginPath();
    ctxt.moveTo(canvas_coordinates.left, canvas_coordinates.bottom);

    relevant_pseudo_keys.map((x) => {
        var y = ground.get(modulo(x, world_width));
        ctxt.lineTo(x, y);
    });

    ctxt.lineTo(canvas_coordinates.right, canvas_coordinates.bottom);
    ctxt.fill();
}

Find all the pseudokeys that are necessary to draw the ground. That is:

Find the biggest pseudokey smaller then canvas_coordinates.left,
find the smallest pseudokey bigger then canvas_coordinates.right and
find all the pseudokeys in between.

The 1. and 2. points are needed so we draw a bit over the left and right of the canvases border.

We assume that for every key in keys the following holds: 0 <= key < world_width

all_relevant_pseudo_keys = function(canvas_coordinates, world_width, keys) {
    // put the keys into an array,
    // because keys is likely an iteratior that can only be traversed once.
    var real_keys = Array.from(keys);
    real_keys.sort((a, b) => a - b); // sort defaults to alphabetical, not numerical

    var relevant_pseudokeys = [];

    // one pseudokey left of the canvas
    var latest_pseudokey = next_pseudo_key(canvas_coordinates.left, real_keys, world_width, "smaller", true);
    relevant_pseudokeys.push(latest_pseudokey);

    // all pseudokeys within the canvas (from left to right)
    while (latest_pseudokey < canvas_coordinates.right) {
        latest_pseudokey = next_pseudo_key(latest_pseudokey, real_keys, world_width, "bigger", false);
        relevant_pseudokeys.push(latest_pseudokey);

    }

    // one pseudokey right of the canvas
    relevant_pseudokeys.push(
        next_pseudo_key(canvas_coordinates.right, real_keys, world_width, "bigger", true)
    );

    return relevant_pseudokeys;
}

Find the next pseudo_key that is either "bigger" or "smaller" then x.

next_pseudo_key = function(x, real_keys, world_width, direction, equal_allowed) {
    // test the special case directly to get it out of the way.
    if (equal_allowed && real_keys.includes(x)) {
        return x;
    }

    // We will only search for "bigger" pseudokeys, "smaller" pseudokeys can be found the same way
    if (direction == "smaller") {
        // just mirror everything on the x=0 axis,
        // then search for a bigger key
        var mirrored_keys = real_keys.map(k => -k);
        return (-1) * next_pseudo_key(-x, mirrored_keys, world_width, "bigger", equal_allowed);
    }

    x_normalized = modulo(x, world_width);

    // we can assume that real_keys is a sorted array
    var smallest_key_bigger_then_x_normalized = real_keys.find(key => x_normalized < key);
    if (smallest_key_bigger_then_x_normalized === undefined) {
        // we have to wrap around and use the first key (which is the smallest one of them all)
        smallest_key = real_keys[0];
        var distance = smallest_key + world_width - x_normalized;
        return x + distance;
    } else {
        var distance = smallest_key_bigger_then_x_normalized - x_normalized;
        return x + distance;
    }

}

3.2.8. draw the explosion

Draw the explosion that happens when the ship crashes.

I tried around with differently colored circles of different sizes, hoping to make the impression of an explosion. It never looked good, but I did manage to get a nice fire effect.

draw_explosion = function(ctxt, ship_state) {
    var edge_coordinates = ship_edge_coordinates(ship_state);
    const flame_delta_x = 10;
    const flame_max_height = 1.5 * ship_state.outline.height;
    for (var i = 0; i < 30; i++) {
        var [flame_start_x, flame_start_y] = random_point_within_polygon(edge_coordinates);
        var flame_end_x = flame_start_x + random_number_between(-flame_delta_x, flame_delta_x);
        var flame_end_y = flame_start_y + random_number_between(-flame_max_height, 0);
        ctxt.strokeStyle = random_element(["red", "orange", "yellow"]);
        ctxt.lineWidth = random_number_between(1, 5);
        ctxt.beginPath();
        ctxt.moveTo(flame_start_x, flame_start_y);
        ctxt.lineTo(flame_end_x, flame_end_y);
        ctxt.stroke();
    }


}

To draw the flames we need to start at a random point within the ship.

Sampling a random point within a polygon is hard, suprisingly hard. There are some clever algorithms, but they involve a lot if geometry and edge cases.

We don't need to be perfect, though. Our distribution doesn't have to be equal on all points. It just has to look vaguely equal.

We will also assume that our polygon is convex. This might not be true for the ship if it exploded some time ago and the edges already collapsed into a concave shape. But it will hold true close enough for long enough.

So instead of doing some complicated math we will do something easy:

choose two random edge coordinates
take a random point between them.

This will not be reach all points. It will also favour points near the edges. But it is easy to understand, implement and a good enough approximation.

random_point_within_polygon = function(edge_coordinates) {
    var [x1, y1] = random_element(edge_coordinates);
    var [x2, y2] = random_element(edge_coordinates);
    t = Math.random();
    return [
        x1 + t * (x2 - x1),
        y1 + t * (y2 - y1),
    ]
}

3.3. `step`

3.3.1. on every frame …

This is the one function that is called on every tick/frame of the game. So obviously there is a big switch statement to decide what to do, based on the games state.

window.game.step = function(time_delta) {
    switch (this.state.state) {
    case 'running':
        run_physics(this.state.ship, this.config, time_delta);
        var landing_report = landing_criteria(this.state.ship);
        this.state.landing_report = landing_report;
        this.state.state = land_or_crash(landing_report);
        break;
    case 'landed':
        silently_finish_landing(this.state.ship);
        break;
    case 'crashed':
        collapse(this.state.ship, time_delta)
        break;
    case 'pause':
        // nothing to do but wait for the unpause
        break;
    default:
        console.error('Unknown state');
    }
}

3.3.2. test for win and loose conditions

We might run in a case where both the "landed"- and "crashed"- conditions are fullfilled. This could happen if the player is about to land the ship in one step, but has already gone through the ground in the next step. In this case we want to give the player the win, everything else would feel unfair to them. That's why we test for landing first.

land_or_crash = function(landing_report) {
    if (ship_has_landed(landing_report)) {
        return "landed"
    } else if (ship_has_crashed(landing_report)) {
        return "crashed";
    }
    return "running";
}

To check if the ship has landed we have to check a lot of things.

ship_has_landed = function(landing_report) {
    const has_status_OK = (criterium) => criterium.status == "OK";
    return landing_report.every(has_status_OK);
}

To check if the ship has crashed we simply look if it has gone through the ground. In python I would just return (ship_altitude < 0), but after reading the documentation on the mess that Booleans are in javascript I decided to be very explicit here.

ship_has_crashed = function(landing_report) {
    var ship_altitude = landing_report.find(criterium => criterium.name == "altitude").value;
    if (ship_altitude < 0) {
        return true;
    }
    return false;
}

3.3.3. report of all the landing criteria

landing_criteria = function(ship_state) {
    const landing_allowed_altitude = 5;
    const landing_allowed_rotation = Math.PI / 16;
    const landing_allowed_slope = Math.PI / 8;
    const landing_allowed_speed_x = 20;
    const landing_allowed_speed_y = 35;

    var [ship_altitude, ship_slope] = ship_altitude_and_slope(ship_state);
    var report = [
        {
            "name": "altitude",
            "value": ship_altitude,
            "max_value": landing_allowed_altitude
        },
        {
            "name": "ground slope",
            "value": ship_slope,
            "max_value": landing_allowed_slope
        },
        {
            "name": "rotation",
            "value": ship_state.rotation,
            "max_value": landing_allowed_rotation
        },
        {
            "name": "horizontal velocity",
            "value": ship_state.velocity.x,
            "max_value": landing_allowed_speed_x
        },
        {
            "name": "vertical velocity",
            "value": ship_state.velocity.y,
            "max_value": landing_allowed_speed_y
        }
    ];
    return report.map((criterium) => {
        var fullfilled = Math.abs(criterium.value) <= criterium.max_value;
        criterium.status = fullfilled ? "OK" : "FAIL";
        return criterium;
    });
}

3.3.4. during the game

Physics is pretty close to what you learned in school. I could probably do a bit better by giving the ship an explicit mass (which would be 1 at the moment).

run_physics = function(ship_state, config, time_delta) {
    // apply gravity
    ship_state.velocity.y += config.gravity * time_delta;
    // apply booster
    apply_boosters(config, ship_state, time_delta);
    // apply velocity
    ship_state.position.x += ship_state.velocity.x * time_delta;
    ship_state.position.y += ship_state.velocity.y * time_delta;
    // apply rotational_speed
    ship_state.rotation += ship_state.rotational_speed * time_delta;
    // apply rotational friction
    ship_state.rotational_speed = ship_state.rotational_speed * (config.rotational_friction ** time_delta);
}

The booster's physics is not super straight forward, so here it is encapsulated into it's own function.

apply_boosters = function(config, ship_state, time_delta) {
    var booster_power = remaining_booster_power(config.ship, ship_state, "main")
    const rotation_power = Math.PI / 30;
    // main
    if (0 < booster_power) {
        const acc_magnitude = 100;
        var acc_x = acc_magnitude *  Math.sin(ship_state.rotation) * booster_power * time_delta;
        var acc_y = acc_magnitude * -Math.cos(ship_state.rotation) * booster_power * time_delta;
        ship_state.velocity.x += acc_x;
        ship_state.velocity.y += acc_y;
    }
    // left
    var booster_power = remaining_booster_power(config.ship, ship_state, "left")
    if (0 < booster_power) {
        ship_state.rotational_speed += rotation_power * time_delta;
    }
    // right
    var booster_power = remaining_booster_power(config.ship, ship_state, "right")
    if (0 < booster_power) {
        ship_state.rotational_speed -= rotation_power * time_delta;
    }
}

3.3.5. after the landing

When the ship has landed it might still look like it hasn't landed properly. This is because the win-conditions only force it to be close to the ground and somewhat straight up. This looks bad.

So after the game is finished we automagically move the ship into a position where it looks like it sits perfectly on the ground. allow the ship to sink further until the final altitude of 0 has been reached.

silently_finish_landing = function(ship_state) {
    // TODO leider ist der ground_slope der krasseste slope unter dem gesammt schiff,
    // nicht nur unter dem Boden
    var [ship_altitude, ground_slope] = ship_altitude_and_slope(ship_state);

    addapt_ship_altitude(ship_state, ship_altitude);
    addapt_ship_angle(ship_state, ground_slope)
}

addapt_ship_altitude = function(ship_state, ship_altitude) {
    if (0 < ship_altitude) {
        ship_state.position.y += 1;
    }
}

addapt_ship_angle = function(ship_state, ground_slope) {
    const min_angle = Math.PI / 64;
    var ground_angle = Math.atan(ground_slope);
    var angle_difference = ground_angle - ship_state.rotation;
    if (min_angle < angle_difference) {
        ship_state.rotation += min_angle;
    }
    if (angle_difference < (-min_angle)) {
        ship_state.rotation -= min_angle;
    }
}

3.3.6. after the crash

So when the ship has crashed we would like to show it to the player as drasticly as possible, while still having the style from before.

But we don't have a fully fledged physics simulation where we can just take the ship, convert it into parts (or ragdolls), throw them into a random direction and let physics take over.

We can do a few things, though. We can let the ship's edge-points fall to the ground, giving the impression that the ship is collapsing.

collapse = function(ship_state, time_delta) {
    var indices_of_edges_above_ground = ship_edge_coordinates(
        ship_state,
    ).map((point, index) => {
        var [altitude, slope] = point_altitude_and_slope(point);
        return [index, altitude];
    }).filter(([index, altitude]) => {
        return 0 < altitude;
    })
    if (indices_of_edges_above_ground.length == 0) {
        return;
    }
    var [index, altitude] = random_element(indices_of_edges_above_ground)
    var collapse_speed = Math.log(altitude + 1);

    // To make that point fall we have to operate on the ships hull
    // which is not rotated.

    var [current_x, current_y] = ship_state.outline.hull[index];
    var new_point = [
        current_x + Math.sin(ship_state.rotation) * collapse_speed * time_delta,
        current_y + Math.cos(ship_state.rotation) * collapse_speed * time_delta
    ];
    ship_state.outline.hull[index] = new_point;
}

There was also the idea to randomly introduce new edges to the ship, which then could fall down to the ground in their own. This would give an effect like the ship was breaking appart.

I implemented this and unfortunatelly the effect was underwhelming. It just didn't look good.

3.3.7. collision-detection

Collision detection is hard when there is no geometry library at hand. But we have a few advantages:

We only need collisions between the ground and the ship.
We know that the ground is a function (so no caves and overhangs), so there is only one direction that needs to be tested: from the ship down.
the ship is convex (or we can assume a convex collision shape).

We can start out with a function that calculates the height and slope of the ground at a specific locaction.

ground_height_and_slope = function(x) {
    var ground = window.game.state.ground;
    var world_width = window.game.config.ground.world_width;

    // normalize x
    x = modulo(x, world_width);
    // from now on we can savely assume that 0 <= x < world_width

    // Do we know the height at x explicitly?
    var y = ground.get(x);
    if (y) {
        return [y, NaN];
    }
    // We do not, so now we have to find the closest points where we do.
    // Then we can interpolate.

    // To be more concrete: We need to find points x_0 and x_1 so that x_0 < x < x_1
    // where we know the heights at x_0 and x_1 (in other words, they are keys)
    // and so that x_0 is as high as possible (gnihihi)
    // and so that x_1 is as low as possible.

    var all_ground_keys = Array.from(window.game.state.ground.keys());
    all_ground_keys.sort((a, b) => a - b); // sort defaults to alphabetical, not numerical

    var x_0, x_1, y_0, y_1;
    // see if we are between two neighbouring keys
    var found_keys = false;
    for (let i = 1; i < all_ground_keys.length; i++) {
        x_0 = all_ground_keys[i-1];
        x_1 = all_ground_keys[i];
        if ((x_0 < x) && (x < x_1)) {
            found_keys = true;
            y_0 = ground.get(x_0);
            y_1 = ground.get(x_1);
            break;
        }
    }
    if (!found_keys) {
        // So this is a special case:
        // if the key is not between to neighbouring regular keys,
        // then it must be either lower then the lowest key higher then the highest key.
        // As we normalized x, we can be sure that it is exactly between the highest_key and the lowest key (wrapped around).
        var lowest_key = all_ground_keys[0];
        var highest_key = all_ground_keys[all_ground_keys.length - 1];
        x_0 = highest_key;
        x_1 = lowest_key;
        y_0 = ground.get(x_0);
        y_1 = ground.get(x_1);
        // do the wrapping around
        if (x < lowest_key) {
            x_0 -= world_width;
        } else if (highest_key < x) {
            x_1 += world_width;
        }
    }

    var slope_at_x = (y_0 - y_1) / (x_0 - x_1);
    var height_at_x = y_0 + slope_at_x * ( x - x_0 );
    return [height_at_x, slope_at_x];
}

If we know the height of the ground then we can now calculate the vertical distance between that ground and some point.

point_altitude_and_slope = function(point) {
    var [x, y] = point;
    var [ground_height, slope] = ground_height_and_slope(x);
    return [ground_height - y, slope];
}

A ship consists of more then one point however. If we have a list of points then we can calculate their shared distance to the ground as the minimum distance of the individual points to the ground.

points_altitude_and_slope = function(points) {
    var min_altitude = Number.POSITIVE_INFINITY;
    var biggest_slope = 0;
    points.forEach((point) => {
        var [altitude, slope] = point_altitude_and_slope(point);
        min_altitude = Math.min(min_altitude, altitude);
        // preserve the altitude of the slope
        // this will also filter out any NaN values
        if (Math.abs(biggest_slope) < Math.abs(slope)) {
            biggest_slope = slope;
        }
    });
    return [min_altitude, biggest_slope];
}

And because we mainly care for the ship and not some other more abstract points we will have a speciallized function that gives us the ship's altitude Because the ship is convex it is enough to test the edges of it.

ship_altitude_and_slope = function(ship_state) {
    var edge_points = ship_edge_coordinates(ship_state);
    return points_altitude_and_slope(edge_points);
}

This function is usefull for collision detection and for drawing

ship_edge_coordinates = function(ship_state) {
    return ship_state.outline.hull.map((point) => [
        // stretch to correct size
        ship_state.outline.width * point[0],
        ship_state.outline.height * point[1]
    ]).map((point) => [
        // rotate around origin
        Math.cos(ship_state.rotation) * point[0] - Math.sin(ship_state.rotation) * point[1],
        Math.sin(ship_state.rotation) * point[0] + Math.cos(ship_state.rotation) * point[1]
    ]).map((point) => [
        // translate to the actual position
        ship_state.position.x + point[0],
        ship_state.position.y + point[1]
    ]);
}

3.4. `act_on_input`

window.game.act_on_input = Object();

3.4.1. the single source of truth

key	command	what happens in the code
ArrowLeft	"rotate left"	window.game.act_on_input.rotate_left();
ArrowRight	"rotate right"	window.game.act_on_input.rotate_right();
ArrowUp	"accelerate"	window.game.act_on_{input.accelerate}();
Escape	"explode"	window.game.act_on_{input.explode}();
Backspace	"restart"	window.game.init();
Enter	"pause"	window.game.act_on_input.pause();

3.4.2. act on commands

In this last chapter we are already pretty familiar with literate code, so let's go one step further: meta-programming and code-generation.

Here we are a bit sneaky: We use python-code to generate the javascript-code from the above table. That way both of them will always be in sync. Lets see how it works.

for key, command, code in input_action_table:
    print(f'case "{command}":')
    print(f'{code}')
    print( 'break;')

case "rotate left":
window.game.act_on_input.rotate_left();
break;
case "rotate right":
window.game.act_on_input.rotate_right();
break;
case "accelerate":
window.game.act_on_input.accelerate();
break;
case "explode":
window.game.act_on_input.explode();
break;
case "restart":
window.game.init();
break;
case "pause":
window.game.act_on_input.pause();
break;

Now we can insert the generated code into our real code. This can be done via noweb syntax, which is supported by orgmode. If you want to see the details of the org-syntax then you can have a look at the original org file.

window.game.act_on_input.command = function(input) {
    switch (input) {
        // this is where the generated code will start
        case "rotate left":
        window.game.act_on_input.rotate_left();
        break;
        case "rotate right":
        window.game.act_on_input.rotate_right();
        break;
        case "accelerate":
        window.game.act_on_input.accelerate();
        break;
        case "explode":
        window.game.act_on_input.explode();
        break;
        case "restart":
        window.game.init();
        break;
        case "pause":
        window.game.act_on_input.pause();
        break;

        // this is where the generated code will end
        default:
            console.error("Invalid input: " + input)
    }
}

3.4.3. act on keypress

To allow playing on a keyboard we will catch certain keyevents and act as if a certain command was entered in the command prompt.

We will do the same trick as above and generate the relevant code from the table:

for key, command, code in input_action_table:
    print(f'case "{key}":')
    print(f'{code}')
    print( 'break;')

case "ArrowLeft":
window.game.act_on_input.rotate_left();
break;
case "ArrowRight":
window.game.act_on_input.rotate_right();
break;
case "ArrowUp":
window.game.act_on_input.accelerate();
break;
case "Escape":
window.game.act_on_input.explode();
break;
case "Backspace":
window.game.init();
break;
case "Enter":
window.game.act_on_input.pause();
break;

Then we insert that code into our real code:

window.game.act_on_input.keypress = function(event) {
    let game = window.game;
    switch (event.key) {
        // this is where the generated code will start
        case "ArrowLeft":
        window.game.act_on_input.rotate_left();
        break;
        case "ArrowRight":
        window.game.act_on_input.rotate_right();
        break;
        case "ArrowUp":
        window.game.act_on_input.accelerate();
        break;
        case "Escape":
        window.game.act_on_input.explode();
        break;
        case "Backspace":
        window.game.init();
        break;
        case "Enter":
        window.game.act_on_input.pause();
        break;

        // this is where the generated code will end
        default:
            console.error("No action set for key: " + event.key)
    }
}

3.4.4. adapt the game state

3.4.4.1. Rotate the ship

Note how you have to fire the left booster to rotate the ship right (clockwise).

window.game.act_on_input.rotate_left = function() {
    window.game.state.ship.booster.last_activation.right = Date.now();
}

window.game.act_on_input.rotate_right = function() {
    window.game.state.ship.booster.last_activation.left = Date.now();
}

3.4.4.2. Accelerate

window.game.act_on_input.accelerate = function() {
    window.game.state.ship.booster.last_activation.main = Date.now();
}

3.4.4.3. Explode

window.game.act_on_input.explode = function() {
    window.game.state.state = "crashed";
}

3.4.4.4. Pausing the game

Currently the game can only be paused while it is running, not when it is already won or lost. It wouldn't have any effect then anyway (except stopping the animation).

window.game.act_on_input.pause = function() {
    if (window.game.state.state == "running") {
        window.game.state.state = "paused";
    } else if (window.game.state.state == "paused") {
        window.game.state.state = "running";
    }
}

3.5. general helper functions

3.5.1. `modulo`

Anoyingly there are different interpretations of what a modulo operator should do. Unsuprisingly the javascript version (%) is unhelpfull when doing modulo arethmetic (like wrapping around when at the edge of the world). The results are especially suprising when using negative numbers:

-13 % 10 == -3

Therefore we will define our own modulo, which is implements euclidean division. Especially for 0 < n it follows that 0 <= modulo(x, n) < n. For example:

modulo(-13, 10) == 7

modulo = function(x, n) {
    return ((x % n) + n) % n;
}

3.5.2. randomnes

Since there is no builtin function to get a random number between a and b we will have to write our own.

random_number_between = function(a, b) {
    // 0 <= Math.random() < 1
    // a <= random_number_between(a, b) <= b
    return a + Math.floor(Math.random() * (1 + b - a) );
}

Another common problem is picking a random element from an array.

random_element = function(array) {
    return array[random_number_between(0, array.length - 1)];
}