Hunor Márton Borbély - freeCodeCamp.org

How to Code a Crossy Road Game Clone with React Three Fiber

Hunor Márton Borbély — Wed, 26 Feb 2025 21:20:27 +0000

In this tutorial, you’ll learn how to create a clone of the mobile game Crossy Road with React Three Fiber. In a previous tutorial, I taught you how to build this game using Three.js and vanilla JavaScript. And here, you’ll learn how to make the same game with React Three Fiber instead.

The goal of this game is to move a character through an endless path of static and moving obstacles. You have to go around trees and avoid getting hit by cars.

There's a lot to cover in this tutorial: we will start with setting up the scene, the camera, and the lights. Then you’ll learn how to draw the player and the map with the trees and the cars. We’ll also cover how to animate the vehicles, and we’ll add event handlers to move the player through the map. Finally, we’ll add hit detection between the cars and the player.

This article is a shortened version of the Crossy Road tutorial from my site JavaScriptGameTutorials.com. The extended tutorial is also available as a video on YouTube.

React Three Fiber vs Three.js
How to Set Up the Game
How to Render a Map
How to Animate the Cars
How to Move the Player
Hit Detection
Next Steps

React Three Fiber vs Three.js

So you might be wondering – what is React Three Fiber, and how does it compare to Three.js? React Three Fiber uses Three.js under the hood, but it gives us a different way to build up our game with React. It’s also easier to to set up, as React Three Fiber comes with sensible defaults for things like the camera.

React has became a leading front-end framework, and React Three Fiber lets you define a 3D scene using React's well-established patterns. You can break down the game into React components and use hooks for animation, event handling, and hit detection.

Under the hood, React Three Fiber still uses Three.js objects. In fact, in some cases, we will access the underlying Three.js objects and manipulate them directly for better performance. But as we build up the game, we use the familiar React patterns.

So which one should you use? If you are already familiar with React, then React Three Fiber might give more structure to your games. And after reading through this and building along with me, you’ll be better equipped to choose.

How to Set Up the Game

In this chapter, we’ll set up the drawing canvas, camera, and lights and render a box representing our player.

Initializing the Project

I recommend using Vite to initialize the project. To do so, go to your terminal and type npm create vite, which will create an initial project for you.

When generating the project, select React (because React Three Fiber uses React).

# Create app
npm create vite my-crossy-road-game
# Select React as framework
# Select JavaScript

# Navigate to the project
cd my-crossy-road-game

# Update react and react-dom
npm install react@latest react-dom@latest

# Install dependencies
npm install three @react-three/fiber

# Start development server
npm run dev

At the time of writing this article, Vite will use React 18 by default. Meanwhile, React 19 is out, and the latest version of React Three Fiber is only compatible with React 19. So let’s update React and react-dom with npm install react@latest react-dom@latest.

After initializing the project, navigate to the project folder and install the additional dependencies. We will use Three.js and React Three Fiber with npm install three @react-three/fiber.

Finally, you can go to the terminal and type npm run dev to start a development server. This way, you can see live the result of your coding in the browser.

The Drawing Canvas

Let’s create a new component called src/Game.jsx. This will be the root of our game.

The Scene component will contain the drawing canvas, the camera, and the lights. We’ll pass on the Player component as its child, which will render a box. Later, we will add the Map component, including the trees, cars, and trucks. This component is also where the score indicator and the controls come later.

import { Scene } from "./components/Scene";
import { Player } from "./components/Player";

export default function Game() {
  return (
    <Scene>
      <Player />
    Scene>
  );
}

The main.jsx file

To use the new Game component as our root, we need to replace the original App component in the src/main.jsx file.

This will give you an error for now because we didn’t implement the Scene and Player components.

Now that we’ve replaced the App component, we can delete the original App.jsx, App.css, and the assets folder.

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./index.css";
import Game from "./Game.jsx";

createRoot(document.getElementById("root")).render(
  <StrictMode>
    <Game />
  StrictMode>
);

Let’s also update the index.css file to make sure our drawing canvas fills the entire screen.

body {
  margin: 0;
  display: flex;
  min-height: 100vh;
}

#root {
  width: 100%;
}

The Player

Let's start adding the necessary objects to render the first scene. Let's add a simple box to represent the player. We already added the player to the scene, so let's see how to define this player.

The player will be a simple box. To draw a 3D object, we’ll define a geometry and a material. The geometry defines the object's shape, and the material defines its appearance. Here, we’re using box geometry to define a box. The box geometry takes three arguments: the width, depth, and height of the box along the x, y, and z axes.

export function Player() {
  return (
    <group>
      <mesh position={[0, 0, 10]}>
        <boxGeometry args={[15, 15, 20]} />
        <meshLambertMaterial color={0xffffff} />
      mesh>
    group>
  );
}

We have different options for the material. The main difference between them is how they react to light, if at all. Here, we're using meshLambertMaterial, a simple material that responds to light. We set the color property to white.

Then, we wrap the geometry and the material into a mesh, which we can add to the scene. We can also position this mesh by setting its X, Y, and Z positions. In the case of a box, these set the center position. By setting the Z position of this box, we’re elevating it above the ground by half its height. As a result, the bottom of the box will be standing on the ground.

We also wrap the mesh into a group element. This is not necessary at this point, but having this structure will be handy when animating the player. When it comes to player animation, we want to separate the horizontal and vertical movement. We want this to be able to follow the player with the camera as it moves but not to move the camera up and down when the player is jumping. We will move the group horizontally along the XY plane together with the camera and move the mesh vertically.

The Camera

Now, let's look into different camera options. There are two main camera options: the perspective camera, as you can see on the left in the image below, and the orthographic camera, which you can see on the right.

The perspective camera is the default camera in Three.js and is the most common camera type across all video games. It creates a perspective projection, which makes things further away appear smaller and things right in front of the camera appear bigger.

On the other hand, the orthographic camera creates parallel projections, which means that objects are the same size regardless of their distance from the camera. We’ll use an orthographic camera here to give our game more of an arcade look.

In Three.js, we place the 3D objects along the X, Y, and Z axes. We define the coordinate system in a way where the ground is on the XY plane so the player can move left and right along the x-axis, forward and backward along the y-axis, and when the player is jumping, it will go up along the z-axis.

We place the camera in this coordinate system to the right along the x-axis, behind the player along the y-axis, and above the ground. Then, the camera will look back at the origin of the coordinate system to the 0,0,0 coordinate, where the player will be placed initially.

The Lights

There are many types of lights in Three.js. Here, we're going to use an ambient light and a directional light.

You can see the result of ambient light only on the left side of the below image. The ambient light brightens the entire scene. It doesn't have a specific position or direction. You can think of it like the light on a cloudy day when it's bright, but there are no shadows. The ambient light is used to simulate indirect light.

Now, let's look at the directional light that you can see on the right of the image above. A directional light has a position and a target. It shines light in a specific direction with parallel light rays. Even though it has a position, you can rather think of it as the sun that is shining from very far away. The position here is more to define the direction of the light, but then all the other light rays are also parallel with this light ray. So you can think of it like the sun.

That's why we're combining an ambient light (so that we have a base brightness all around the scene) with a directional light (to illuminate specific sides of our objects with a brighter color).

The Scene

After reviewing the different camera and light options, let’s put them together in the Scene component. We set up the canvas with an orthographic camera and lights.

import { Canvas } from "@react-three/fiber";

export const Scene = ({ children }) => {
  return (
    <Canvas
      orthographic={true}
      camera={{
        up: [0, 0, 1],
        position: [300, -300, 300],
      }}
    >
      <ambientLight />
      <directionalLight position={[-100, -100, 200]} />
      {children}
    Canvas>
  );
};

We use the Canvas component from @react-three/fiber. This component will contain every 3D object on the scene, so it has a children prop.

We set the orthographic prop to true to use an orthographic camera and the camera prop to define the camera’s position and orientation. The camera props require vectors or coordinates that are defined by the x, y, and z values.

The up prop sets the camera’s up vector. We set it to [0, 0, 1] to make the z-axis the up vector. The position prop sets the camera’s position. We move the camera to the right along the x-axis, backward along the y-axis, and up along the z-axis.

We also add the lights. We can use React Three Fiber-specific elements within the Canvas element. We add the ambientLight and directionalLight components to add lights to the scene. We position the directional light to the left along the x-axis, backward along the y-axis, and up along the z-axis.

This is how our first scene comes together. We rendered a simple box.

How to Render a Map

Now, let's add all the other objects to the scene. In this chapter, we’ll define the map. The map will consist of multiple rows, each described by metadata. Each row can be a forest, a car, or a truck lane. We’ll go through each type and define the 3D objects representing them.

The map can be broken down into rows, and each row can be broken down into multiple tiles. The player will move from tile to tile. Trees are also placed on a distinct tile. Cars, on the other hand, do not relate to tiles. They move freely through the lane.

We define a file for the constants. Here, we define the number of tiles in each row. In this case, there are 17 ties per row, going from -8 to +8. The player will start in the middle at tile zero.

export const minTileIndex = -8;
export const maxTileIndex = 8;
export const tilesPerRow = maxTileIndex - minTileIndex + 1;
export const tileSize = 42;

The Starting Row

First, let's add the starting row. We’ll define a couple of components that we’re going to use to render the map, and we’ll render the initial row.

Let's create a new component called Map. Soon, we will add this group to the scene.

import { Grass } from "./Grass";

export function Map() {
  return (
    <>
      <Grass rowIndex={0} />
    
  );
}

Then, we set the map's content. Later, we will generate the 3D objects based on the metadata and use it to render the map. For now, let's just use the Grass component. We call the Grass component with the row index, so the grass component will position itself based on this row index.

Now, let's define the Grass component. The Grass component is the foundation and container of the forest rows and is also used for the starting row. It renders a group containing a flat, wide, green box. The dimensions of this box are determined by the constants tileSize and tilesPerRow. The box also has some height, so it sticks out compared to the road, which will be completely flat.

import { tilesPerRow, tileSize } from "../constants";

export function Grass({ rowIndex, children }) {
  return (
    <group position-y={rowIndex * tileSize}>
      <mesh>
        <boxGeometry args={[tilesPerRow * tileSize, tileSize, 3]} />
        <meshLambertMaterial color={0xbaf455} />
      mesh>
      {children}
    group>
  );
}

The grass can serve as a container for the trees in the row. That's why we wrap the green box into a group so that later, we can also add children to this group. We position the group along the y-axis based on the row index that we received from the Map component. For the initial lane, this is zero, but as we're going to have multiple lanes, we need to place them according to this position.

Now that we have the map container and the grass component, we can finally add the map to the scene.

import { Scene } from "./components/Scene";
import { Player } from "./components/Player";
import { Map } from "./components/Map";

export default function Game() {
  return (
    <Scene>
      <Player />
      <Map />
    Scene>
  );
}

How to Add a Forest Row

Now that we have an empty forest, let's add another row containing trees. We define the map's metadata and render the rows based on this metadata.

Let's define the map's metadata. The metadata is an array of objects that contain information about each row. Each row will contain a type that will determine the kind of the row and the rest of the properties depending on the row type.

export const rows = [
  {
    type: "forest",
    trees: [
      { tileIndex: -3, height: 50 },
      { tileIndex: 2, height: 30 },
      { tileIndex: 5, height: 50 },
    ],
  },
];

The metadata for a forest includes the type of “forest” and a list of trees. Each tree has a tile index, which represents which tile it is standing on. In this case, we have 17 tiles per row, going from -8 to +8. The trees also have a height, which is actually the height of the crown.

To render the rows, let’s extend the Map component to render the rows based on the metadata. We import the metadata and map each row to a separate Row component.

Note that the rowIndex is off by one compared to the array index because the first item in the metadata array will become the second row (after the starting row).

import { rows } from "../metadata";
import { Grass } from "./Grass";
import { Row } from "./Row";

export function Map() {
  return (
    <>
      <Grass rowIndex={0} />

      {rows.map((rowData, index) => (
        <Row key={index} rowIndex={index + 1} rowData={rowData} />
      ))}
    
  );
}

Now, let’s define the Row component. The Row component is essentially a switch case that renders the correct row based on the type property of the row. We only support the forest type for now, but we will extend this file later to support car and truck lanes.

import { Forest } from "./Forest";

export function Row({ rowIndex, rowData }) {
  switch (rowData.type) {
    case "forest": {
      return <Forest rowIndex={rowIndex} rowData={rowData} />;
    }
  }
}

The Forest component contains the row’s foundation, a Grass component, and the trees in the row.

The Grass component can receive children. We map trees’ metadata to Tree components and pass them on as children to the Grass component. Each tree gets its tileIndex, which will be used for positioning the tree within the row, and its height.

import { Grass } from "./Grass";
import { Tree } from "./Tree";

export function Forest({ rowIndex, rowData }) {
  return (
    <Grass rowIndex={rowIndex}>
      {rowData.trees.map((tree, index) => (
        <Tree
          key={index}
          tileIndex={tree.tileIndex}
          height={tree.height}
        />
      ))}
    Grass>
  );
}

Forest rows also have trees. For each item in the trees array, we render a tree. The Tree component will render a 3D object representing the tree. We pass on to this component the tile index that we will use to position the tree within the row and the height.

Since we’ve already added the map to the scene, the forest will appear on the screen. But first, we need to define how to render a tree. We are going to represent a tree with two boxes. We're going to have a box for the trunk and one for the crown.

import { tileSize } from "../constants";

export function Tree({ tileIndex, height }) {
  return (
    <group position-x={tileIndex * tileSize}>
      <mesh position-z={height / 2 + 20}>
        <boxGeometry args={[30, 30, height]} />
        <meshLambertMaterial color={0x7aa21d} />
      mesh>
      <mesh position-z={10}>
        <boxGeometry args={[15, 15, 20]} />
        <meshLambertMaterial color={0x4d2926} />
      mesh>
    group>
  );
}

These are both simple boxes, just like we had before with the player and also in the Grass component. The trunk is placed on top of the ground. We lift it along the Z-axis by half of its height, and the crown is placed on top of the trunk. The crown's height is also based on the height property. These two meshes are wrapped together into a group, and then we position this group along the X-axis based on the tile index property.

Car Lanes

Now, let's add another row type: car lanes. The process of adding car lanes will follow a similar structure. We define the lanes' metadata, including the vehicles, and then map them into 3D objects.

In the metadata, let's replace the first row with a car lane. The car lane will contain a single red car moving to the left. We have a direction property, which is a boolean flag. If this is true, that means the cars are moving to the right in the lane, and if it's false, then the vehicles are moving to the left. We also have a speed property, which defines how many units each vehicle takes every second.

Finally, we have an array of vehicles. Each car will have an initial tile index, which represents only its initial position because the cars will move later. Each car will also have a color property, which is a hexadecimal color value.

export const rows = [
  {
    type: "car",
    direction: false,
    speed: 1,
    vehicles: [{ initialTileIndex: 2, color: 0xff0000 }],
  },
];

Now, to render this lane type, we have to extend our logic to support car lanes. Let’s extend the Row Component with support for car lanes. If the type of a row is car we map it to a CarLane component.

import { Forest } from "./Forest";
import { CarLane } from "./CarLane";

export function Row({ rowIndex, rowData }) {
  switch (rowData.type) {
    case "forest": {
      return <Forest rowIndex={rowIndex} rowData={rowData} />;
    }
    case "car": {
      return <CarLane rowIndex={rowIndex} rowData={rowData} />;
    }
  }
}

The CarLane component renders the cars on the road. It has a similar structure to the Forest component.

It receives a rowData object as a prop, which contains the cars to be rendered. It wraps the cars in a Road component and maps over the rowData.vehicles array to render each car.

import { Road } from "./Road";
import { Car } from "./Car";

export function CarLane({ rowIndex, rowData }) {
  return (
    <Road rowIndex={rowIndex}>
      {rowData.vehicles.map((vehicle, index) => (
        <Car
          key={index}
          rowIndex={rowIndex}
          initialTileIndex={vehicle.initialTileIndex}
          direction={rowData.direction}
          speed={rowData.speed}
          color={vehicle.color}
        />
      ))}
    Road>
  );
}

The Road and Car functions are new here, so let's examine them next. The Road function returns the foundation and container of the car and truck lanes. Similar to the Grass component, it also returns a group containing a gray plane.

The size of the plane is also determined by the constants tileSize and tilesPerRow. Unlike the Grass component, though, it doesn't have any height. It's completely flat. The road will also serve as a container for the cars and trucks in the row, so that's why we wrap the plane into a group – so that we can add children to it.

import { tilesPerRow, tileSize } from "../constants";

export function Road({ rowIndex, children }) {
  return (
    <group position-y={rowIndex * tileSize}>
      <mesh>
        <planeGeometry args={[tilesPerRow * tileSize, tileSize]} />
        <meshLambertMaterial color={0x454a59} />
      mesh>
      {children}
    group>
  );
}

Now, let's look at the Car. The Car function returns a very simple 3D car model.

It contains a box for the body and a smaller box for the top part. We also have two wheel meshes. Because we never see the cars from underneath, we don't need to separate the wheels into left and right. We can just use one long box for the front wheels and another one for the back wheels.

import { tileSize } from "../constants";

export function Car({
  rowIndex,
  initialTileIndex,
  direction,
  speed,
  color,
}) {
  return (
    <group
      position-x={initialTileIndex * tileSize}
      rotation-z={direction ? 0 : Math.PI}
    >
      <mesh position={[0, 0, 12]}>
        <boxGeometry args={[60, 30, 15]} />
        <meshLambertMaterial color={color} />
      mesh>
      <mesh position={[-6, 0, 25.5]}>
        <boxGeometry args={[33, 24, 12]} />
        <meshLambertMaterial color={0xffffff} />
      mesh>
      <mesh position={[-18, 0, 6]}>
        <boxGeometry args={[12, 33, 12]} />
        <meshLambertMaterial color={0x333333} />
      mesh>
      <mesh position={[18, 0, 6]}>
        <boxGeometry args={[12, 33, 12]} />
        <meshLambertMaterial color={0x333333} />
      mesh>
    group>
  );
}

We group all these elements, position them based on the initialTileIndex property, and turn them based on the direction property. If the car goes to the left, we rotate it by 180°. When we set rotation values in Three.js. We have to set them in radians, so that's why we set it to Math.Pi, which is equivalent to 180°.

You can also find a more extended version of how to draw this car with textures in this article.

Based on the metadata, we can now render a map with several rows. Here’s an example with a few more lanes. Of course, feel free to define your own map.

export const rows = [
  {
    type: "car",
    direction: false,
    speed: 188,
    vehicles: [
      { initialTileIndex: -4, color: 0xbdb638 },
      { initialTileIndex: -1, color: 0x78b14b },
      { initialTileIndex: 4, color: 0xa52523 },
    ],
  },
  {
    type: "forest",
    trees: [
      { tileIndex: -5, height: 50 },
      { tileIndex: 0, height: 30 },
      { tileIndex: 3, height: 50 },
    ],
  },
  {
    type: "car",
    direction: true,
    speed: 125,
    vehicles: [
      { initialTileIndex: -4, color: 0x78b14b },
      { initialTileIndex: 0, color: 0xbdb638 },
    ],
  },
  {
    type: "forest",
    trees: [
      { tileIndex: -8, height: 30 },
      { tileIndex: -3, height: 50 },
      { tileIndex: 2, height: 30 },
    ],
  },
];

This article does not cover truck lanes, but they follow a similar structure. The code for it can be found at JavaScriptGameTutorials.com.

How to Animate the Cars

Let's move on and animate the cars in their lanes according to their speed and direction.

This is where things start to diverge from how you would typically use React. The React way would be to update a state or a prop and let React re-render the whole component. This is fast when working with HTML elements, but it is not very effective when working with 3D objects. We want to avoid re-rendering the whole scene and, instead, update the position of the underlying objects directly.

We only use React to set up the scene and the objects, and then we let Three.js do the heavy lifting. React Three Fiber is just a thin layer on top of Three.js, so we can access the underlying Three.js objects directly to update the position of the cars and trucks.

We are going to use a custom hook, useVehicleAnimation, to animate the vehicles. This hook will need a reference to the 3D object it should manipulate. Before defining this hook, let’s get a reference to the Three.js group, which represents the car. We use React’s useRef hook to store the reference and bind it to the group element.

Then, we pass on this reference to the useVehicleAnimation hook, along with the direction and speed of the car.

import { useRef } from "react";
import { tileSize } from "../constants";
import useVehicleAnimation from "../hooks/useVehicleAnimation";

export function Car({
  rowIndex,
  initialTileIndex,
  direction,
  speed,
  color,
}) {
  const car = useRef(null);
  useVehicleAnimation(car, direction, speed);

  return (
    <group
      position-x={initialTileIndex * tileSize}
      rotation-z={direction ? 0 : Math.PI}
      ref={car}
    >
      . . . 
    group>
  );
}

Let’s implement the useVehicleAnimation hook to animate the vehicles. It moves them based on their speed and direction until the end of the lane and then re-spawns them at the other end. This way, the vehicles move in an infinite loop.

This hook uses the useFrame hook that React Three Fiber provides. This hook is similar to setAnimationLoop in Three.js. It runs a function on every animation frame.

Conveniently, this function receives the time delta—the time that passed since the previous animation frame. We multiply this value by the vehicle’s speed to get the distance the car took during this time.

import { useFrame } from "@react-three/fiber";
import { tileSize, minTileIndex, maxTileIndex } from "../constants";

export default function useVehicleAnimation(ref, direction, speed) {
  useFrame((state, delta) => {
    if (!ref.current) return;
    const vehicle = ref.current;

    const beginningOfRow = (minTileIndex - 2) * tileSize;
    const endOfRow = (maxTileIndex + 2) * tileSize;

    if (direction) {
      vehicle.position.x =
        vehicle.position.x > endOfRow
          ? beginningOfRow
          : vehicle.position.x + speed * delta;
    } else {
      vehicle.position.x =
        vehicle.position.x < beginningOfRow
          ? endOfRow
          : vehicle.position.x - speed * delta;
    }
  });
}

We directly update the position.x property of the underlying Three.js group. If the vehicle reaches the end of the lane, we re-spawn it at the other end.

Note that the reference passed to the hook might be null because it is only set after the first render. If the reference is not set, we return early from the function. Then, the animation starts in the next frame.

How to Move the Player

Now, let's move on to animating the player. Moving the player on the map is more complex than moving the vehicles. The player can move in all directions, bump into trees, or get hit by cars, and it shouldn't be able to move outside the map.

In this chapter, we are focusing on two parts: collecting user inputs and executing the movement commands. Player movement is not instant – we need to collect the movement commands into a queue and execute them one by one. We are going to collect user inputs and put them into a queue.

Collecting User Inputs

To track the movement commands, we create a store for the player. We do not use a state management library, as we don’t need a reactive store. We simply define our state in a regular JavaScript file.

The store will keep track of the player’s position and movement queue. The player starts at the middle of the first row, and the move queue is initially empty.

We will also export two functions: queueMove adds the movement command to the end of the move queue, and the stepCompleted function removes the first movement command from the queue and updates the player's position accordingly.

export const state = {
  currentRow: 0,
  currentTile: 0,
  movesQueue: [],
};

export function queueMove(direction) {
  state.movesQueue.push(direction);
}

export function stepCompleted() {
  const direction = state.movesQueue.shift();

  if (direction === "forward") state.currentRow += 1;
  if (direction === "backward") state.currentRow -= 1;
  if (direction === "left") state.currentTile -= 1;
  if (direction === "right") state.currentTile += 1;
}

Now we can add event listeners for keyboard events to listen to the arrow keys. The useEventListeners hook listens to the arrow keys and calls the queueMove function of the player store with the corresponding direction.

import { useEffect } from "react";
import { queueMove } from "../stores/player";

export default function useEventListeners() {
  useEffect(() => {
    const handleKeyDown = (event) => {
      if (event.key === "ArrowUp") {
        queueMove("forward");
      } else if (event.key === "ArrowDown") {
        queueMove("backward");
      } else if (event.key === "ArrowLeft") {
        queueMove("left");
      } else if (event.key === "ArrowRight") {
        queueMove("right");
      }
    };

    window.addEventListener("keydown", handleKeyDown);

    // Cleanup function to remove the event listener
    return () => {
      window.removeEventListener("keydown", handleKeyDown);
    };
  }, []);
}

After defining the event listeners, we also have to import them into the Game component so that they work.

import { Scene } from "./components/Scene";
import { Player } from "./components/Player";
import { Map } from "./components/Map";
import useEventListeners from "./hooks/useEventListeners";

export default function Game() {
  useEventListeners();

  return (
    <Scene>
      <Player />
      <Map />
    Scene>
  );
}

Executing Movement Commands

So far, we have collected user inputs and put each command into the movesQueue array in the player component. Now, it's time to execute these commands one by one and animate the player.

Let's create a new hook called usePlayerAnimation. Its main goal is to take each move command from the moveQueue one by one, calculate the player's progress toward executing a step, and position the player accordingly.

This hook animates the player frame by frame. It uses the useFrame hook, just like the useVehicleAnimation hook. This time, however, we use a separate moveClock that measures each step individually. We pass on false to the clock constructor so it doesn’t start automatically. The clock starts at the beginning of a step. At each animation frame, first, we check if there are any more steps to take, and if there are and we’re not currently processing a step, we start the clock.

import * as THREE from "three";
import { useFrame } from "@react-three/fiber";
import { state, stepCompleted } from "../stores/player";
import { tileSize } from "../constants";

export default function usePlayerAnimation(ref) {
  const moveClock = new THREE.Clock(false);

  useFrame(() => {
    if (!ref.current) return;
    if (!state.movesQueue.length) return;
    const player = ref.current;

    if (!moveClock.running) moveClock.start();

    const stepTime = 0.2; // Seconds it takes to take a step
    const progress = Math.min(
      1,
      moveClock.getElapsedTime() / stepTime
    );

    setPosition(player, progress);

    // Once a step has ended
    if (progress >= 1) {
      stepCompleted();
      moveClock.stop();
    }
  });
}

. . .

We use the move clock to calculate the progress between the two tiles. The progress indicator can be a number between zero and one. Zero means that the player is still at the beginning of the step, and one means that it’s arrived at its new position.

At each animation frame, we call the setPosition function to set the player’s position according to the progress. Once we finish a step, we call the stepCompleted function to update the player's position and stop the clock. If there are any more move commands in the movesQueue, the clock will restart in the following animation frame.

Now that we know how to calculate the progress for each step, let's look into how to set the player's position based on the progress. The player will jump from tile to tile. Let's break this down into two parts: the movement's horizontal and vertical components.

The player moves from the current tile to the next tile in the direction of the move command. We calculate the player's start and end position based on the current tile and the direction of the move command. Then, we use linear interpolation with a utility function that Three.js provides. This will interpolate between the start and end positions based on the progress.

. . .

function setPosition(player, progress) {
  const startX = state.currentTile * tileSize;
  const startY = state.currentRow * tileSize;
  let endX = startX;
  let endY = startY;

  if (state.movesQueue[0] === "left") endX -= tileSize;
  if (state.movesQueue[0] === "right") endX += tileSize;
  if (state.movesQueue[0] === "forward") endY += tileSize;
  if (state.movesQueue[0] === "backward") endY -= tileSize;

  player.position.x = THREE.MathUtils.lerp(startX, endX, progress);
  player.position.y = THREE.MathUtils.lerp(startY, endY, progress);
  player.children[0].position.z = Math.sin(progress * Math.PI) * 8 + 10;
}

For the vertical component, we use a sine function to make it look like jumping. We are basically mapping the progress to the first part of a sine wave.

Below you can see what a sine wave looks like. It goes from 0 to 2 Pi. So if you multiply the progress value, which is going from 0 to 1 with Pi, then the progress will map into the first half of this sine wave. The sign function then will give us a value between zero and one.

To make the jump look higher, we can multiply this with a value. In this case, we multiply the result of the sine function by eight, so as a result, the player will have a jump where the maximum height of the jump will be eight units.

We also need to add the original Z position to the value – otherwise, the player will sink halfway into the ground after the first step.

It’s finally time to update the Player component to make it all come together. We create a new reference with useRef and assign it to the group element. Finally, we pass this reference to the usePlayerAnimation hook we just implemented.

import { useRef } from "react";
import usePlayerAnimation from "../hooks/usePlayerAnimation";

export function Player() {
  const player = useRef(null);
  usePlayerAnimation(player);

  return (
    <group ref={player}>
      <mesh position={[0, 0, 10]} castShadow receiveShadow>
        <boxGeometry args={[15, 15, 20]} />
        <meshLambertMaterial color={0xffffff} flatShading />
      mesh>
    group>
  );
}

If you did everything right, the player should be able to move around the game board, moving forward, backward, left, and right. But we haven't added any hit detection. So far, the player can move through trees and vehicles and even get off the game board. Let's fix these issues in the following steps.

Follow the Player with the Camera

We defined the camera in the Scene component. By default, it has a static position. Instead of that, we want to move it with the player. We could adjust its position at every animation frame just like the player, but it’s easier to attach the camera to the Player component so that they move together.

We can access the camera using the useThree hook from @react-three/fiber. This returns a Three.js camera object that we can add to the player group.

We already have a reference to the group representing the player. We can attach the camera to the player by adding it as a child of the player group. Because the player reference is undefined on the first render, we need to use the useEffect hook to attach the camera only once the player reference is set.

import { useRef, useEffect } from "react";
import { useThree } from "@react-three/fiber";
import usePlayerAnimation from "../hooks/usePlayerAnimation";

export function Player() {
  const player = useRef(null);
  const camera = useThree((state) => state.camera);

  usePlayerAnimation(player);

  useEffect(() => {
    if (!player.current) return;

    // Attach the camera to the player
    player.current.add(camera);
  });

  return (
    . . .
  );
}

Restricting Player Movement

Let’s make sure that the player can’t end up in a position that’s invalid. We will check if a move is valid by calculating where it will take the player. If the player would end up in a position outside of the map or in a tile occupied by a tree, we will ignore that move command.

First, we need to calculate where the player would end up if they made a particular move. Whenever we add a new move to the queue, we need to calculate where the player would end up if they made all the moves in the queue and take the current move command. We create a utility function that takes the player's current position and an array of moves and returns the player's final position.

For instance, if the player's current position is 0,0, staying in the middle of the first row, and the moves are forward and left, then the final position will be row 1 tile -1.

export function calculateFinalPosition(currentPosition, moves) {
  return moves.reduce((position, direction) => {
    if (direction === "forward")
      return {
        rowIndex: position.rowIndex + 1,
        tileIndex: position.tileIndex,
      };
    if (direction === "backward")
      return {
        rowIndex: position.rowIndex - 1,
        tileIndex: position.tileIndex,
      };
    if (direction === "left")
      return {
        rowIndex: position.rowIndex,
        tileIndex: position.tileIndex - 1,
      };
    if (direction === "right")
      return {
        rowIndex: position.rowIndex,
        tileIndex: position.tileIndex + 1,
      };
    return position;
  }, currentPosition);
}

Now that we have this utility function to calculate where the player will end up after taking a move, let's create another utility function to calculate whether the player would end up in a valid or invalid position. In this function, we use the calculateFinalPosition function that we just created. Then, we’ll check if the player would end up outside the map or on a tile occupied by a tree.

If the move is invalid, we return false. First, we check if the final position is before the starting row or if the tile number is outside the range of the tiles. Then, we check the metadata of the row the player will end up in. Here, the index is off by one because the row metadata doesn't include the starting row. If we end up in a forest row, we check whether a tree occupies the tile we move to. If any of this is true, we return false.

import { calculateFinalPosition } from "./calculateFinalPosition";
import { minTileIndex, maxTileIndex } from "../constants";
import { rows } from "../metadata";

export function endsUpInValidPosition(currentPosition, moves) {
  // Calculate where the player would end up after the move
  const finalPosition = calculateFinalPosition(
    currentPosition,
    moves
  );

  // Detect if we hit the edge of the board
  if (
    finalPosition.rowIndex === -1 ||
    finalPosition.tileIndex === minTileIndex - 1 ||
    finalPosition.tileIndex === maxTileIndex + 1
  ) {
    // Invalid move, ignore move command
    return false;
  }

  // Detect if we hit a tree
  const finalRow = rows[finalPosition.rowIndex - 1];
  if (
    finalRow &&
    finalRow.type === "forest" &&
    finalRow.trees.some(
      (tree) => tree.tileIndex === finalPosition.tileIndex
    )
  ) {
    // Invalid move, ignore move command
    return false;
  }

  return true;
}

Finally, let's extend the player's queueMove function with the endsUpInValidPosition function to check if a move is valid. If the endsUpInValidPosition function returns false, we cannot take this step. In this case, we return early from the function before the move is added to the movesQueue array. So we are ignoring the move.

import { endsUpInValidPosition } from "../utilities/endsUpInValidPosition";

export let state = {
  currentRow: 0,
  currentTile: 0,
  movesQueue: [],
};

export function queueMove(direction) {
  const isValidMove = endsUpInValidPosition(
    { rowIndex: state.currentRow, tileIndex: state.currentTile },
    [...state.movesQueue, direction]
  );

  if (!isValidMove) return; // Ignore move

  state.movesQueue.push(direction);
}

. . .

This way, as you can see, you can move around the map – but you can never move before the first row, you can't go too far to the left or too far to the right, and you also can’t go through a tree anymore.

Hit Detection

To finish the game, let's add hit detection. We check if the player gets hit by a vehicle, and if so, we show an alert popup.

We add a new hook that checks from the vehicles’ perspective if they hit the player. So far, the player and the vehicles have handled their own movement independently. They have no notion of each other. To handle hit detection, either the player needs to know about the vehicles or the vehicles need to know about the player.

We’ll choose the former approach because this way, we only need to store one reference to the player in the store, and all the vehicles can check against this reference. Let’s extend the player store with a ref property to store the player object’s reference. We also expose a setRef method that sets this reference.

import { endsUpInValidPosition } from "../utilities/endsUpInValidPosition";

export const state = {
  currentRow: 0,
  currentTile: 0,
  movesQueue: [],
  ref: null,
};

. . .

export function setRef(ref) {
  state.ref = ref;
}

Then, we call the setRef method in the Player component to set the reference to the player object. We already have the player reference, so we can pass its value to the setRef method in the useEffect hook once it is set.

import { useRef, useEffect } from "react";
import { useThree } from "@react-three/fiber";
import usePlayerAnimation from "../hooks/usePlayerAnimation";
import { setRef } from "../stores/player";

export function Player() {
  const player = useRef(null);
  const camera = useThree((state) => state.camera);

  usePlayerAnimation(player);

  useEffect(() => {
    if (!player.current) return;

    // Attach the camera to the player
    player.current.add(camera);

    // Set the player reference in the store
    setRef(player.current);
  });

  return (
    . . .
  );
}

Then, let’s define another hook to handle hit detection. We check if the player intersects with any of the vehicles. If they do, we end the game.

This hook is from the perspective of a vehicle. It receives the vehicle reference and the rowIndex. We check if the vehicle intersects with the player if the player is in the same row, the row before, or the row after the vehicle. We use the useFrame hook to run the hit detection logic on every frame.

Then we create bounding boxes for the player and the vehicle to check for an intersection. This might be a bit overkill, as the shape of our objects is known, but it is a nice generic way to handle hit detection.

If the bounding boxes intersect, we show an alert. Once the user clicks OK on the alert, we reload the page.

import * as THREE from "three";
import { useFrame } from "@react-three/fiber";
import { state as player } from "../stores/player";

export default function useHitDetection(vehicle, rowIndex) {
  useFrame(() => {
    if (!vehicle.current) return;
    if (!player.ref) return;

    if (
      rowIndex === player.currentRow ||
      rowIndex === player.currentRow + 1 ||
      rowIndex === player.currentRow - 1
    ) {
      const vehicleBoundingBox = new THREE.Box3();
      vehicleBoundingBox.setFromObject(vehicle.current);

      const playerBoundingBox = new THREE.Box3();
      playerBoundingBox.setFromObject(player.ref);

      if (playerBoundingBox.intersectsBox(vehicleBoundingBox)) {
        window.alert("Game over!");
        window.location.reload();
      }
    }
  });
}

Finally, we call this hook in the vehicle components. In the Car component, we pass the car reference and the rowIndex to the useHitDetection hook.

import { useRef } from "react";
import { tileSize } from "../constants";
import useVehicleAnimation from "../hooks/useVehicleAnimation";
import useHitDetection from "../hooks/useHitDetection";

export function Car({
  rowIndex,
  initialTileIndex,
  direction,
  speed,
  color,
}) {
  const car = useRef(null);
  useVehicleAnimation(car, direction, speed);
  useHitDetection(car, rowIndex);

  return (
    . . .
  );
}

Next Steps

Congratulations, you’ve reached the end of this tutorial, and we’ve covered all the main features of the game. We rendered a map, animated the vehicles, added event handling for the player, and added hit detection.

I hope you had great fun creating this game. This game, of course, is far from perfect, and there are various improvements you can make if you’d like to keep working on it.

You can find the extended tutorial with interactive demos on JavaScriptGameTutorials.com. There, we also cover how to add shadows and truck lanes and how to generate an infinite number of rows as the player moves forward. We also add UI elements for the controls and the score indicator, and we add a result screen with a button to reset the game.

Alternatively, you can find the extended tutorial on YouTube.

How to Code a Crossy Road Game Clone with Three.js

Hunor Márton Borbély — Thu, 20 Feb 2025 23:29:26 +0000

In this tutorial, you’ll learn how to create a clone of the mobile game Crossy Road with Three.js. The goal of this game is to move a character through an endless path of static and moving obstacles. You have to go around trees and avoid getting hit by cars.

This article is a shortened version of the Crossy Road tutorial from my site JavaScriptGameTutorials.com. The extended tutorial is also available as a video on YouTube.

How to Set Up the Game
How to Render a Map
How to Animate the Cars
How to Move the Player
Hit Detection
Next Steps

How to Set Up the Game

In this chapter, we’ll set up the drawing canvas, camera, and lights and render a box representing our player.

Initializing the Project

I recommend using Vite to initialize the project. To do so, go to your terminal and type npm create vite, which will create an initial project for you.

# Create app
npm create vite my-crossy-road-game

# Navigate to the project
cd my-crossy-road-game

# Install dependencies
npm install three

# Start development server
npm run dev

When generating the project, select Vanilla because we won't use any front-end framework for this project. Then navigate to the project folder Vite just created for you and install Three.js with npm install three. Finally, you can go to the terminal and type npm run dev to start a development server. This way, you can see live the result of your coding in the browser.

The Drawing Canvas

Now, let's look into this project. The entry point of this project is the index.html file in the root folder. Let's replace the div element with a canvas element with the ID game. This is the drawing canvas that Three.js will use to render the scene. This file also has a script tag that points to the main JavaScript file.

html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite Apptitle>
  head>
  <body>
    <canvas class="game">canvas>
    <script type="module" src="/src/main.ts">script>
  body>
html>

The main.js file

The main.js file is the root of our game. Let's replace its content. We’ll define a Three.js scene containing all the 3D elements, including the player, that we will soon define. The scene also includes a camera that we’ll use together with the renderer to render a static frame of it. We’ll define these in the following steps.

import * as THREE from "three";
import { Renderer } from "./Renderer";
import { Camera } from "./Camera";
import { player } from "./Player";
import "./style.css";

const scene = new THREE.Scene();
scene.add(player);

const camera = Camera();
player.add(camera);

const renderer = Renderer();
renderer.render(scene, camera);

The Player

Let's start adding the necessary objects to render the first scene. Let's add a simple box to represent the player. We already added the player to the scene in the main file, so let's see how to define this player.

In this file, we write a function that creates a 3D object and exports a property containing the player instance. The player is a singleton. There is only one player object in the game, and every other file can access it through this export.

import * as THREE from "three";

export const player = Player();

function Player() {
  const player = new THREE.Group();

  const body = new THREE.Mesh(
    new THREE.BoxGeometry(15, 15, 20),
    new THREE.MeshLambertMaterial({ color: "white" })
  );
  body.position.z = 10;
  player.add(body);

  return player;
}

Initially, the player will be a simple box. To draw a 3D object, we’ll define a geometry and a material. The geometry defines the object's shape, and the material defines its appearance. Here, we’re using box geometry to define a box. The box geometry takes three arguments: the width, depth, and height of the box along the x, y, and z axes.

We have different options for the material. The main difference between them is how they react to light, if at all. Here, we're using MeshLambertMaterial, a simple material that responds to light. We set the color property to white.

The Camera

With all this theory in mind, let's define our camera. We create a new file for the camera and export the camera function, which returns an orthographic camera that we'll use to render the scene.

import * as THREE from "three";

export function Camera() {
  const size = 300;
  const viewRatio = window.innerWidth / window.innerHeight;
  const width = viewRatio < 1 ? size : size * viewRatio;
  const height = viewRatio < 1 ? size / viewRatio : size;

  const camera = new THREE.OrthographicCamera(
    width / -2, // left
    width / 2, // right
    height / 2, // top
    height / -2, // bottom
    100, // near
    900 // far
  );

  camera.up.set(0, 0, 1);
  camera.position.set(300, -300, 300);
  camera.lookAt(0, 0, 0);

  return camera;
}

To define a camera, we need to define a camera frustum. This will determine how to project the 3D elements onto the screen. In the case of an orthographic camera, we define a box. Everything in the scene within this box will be projected onto the screen. In the image below, the green dot represents the camera position and the gray box around the scene represents the camera frustum.

In this function, we set up the camera frustum to fill the browser window, and the width or height will be 300 units, depending on the aspect ratio. The smaller value between width and height will be 300 units, and the other one will fill the available space. If the width is larger than the height, then the height is 300 units. If the height is larger, then the width is 300 units.

Then, we set the camera's position. We move the camera to the right along the x-axis with 300 units, then behind the player along the y-axis with -300 units, and finally above the ground. We also look back to the origin of the coordinate system, to the 0,0,0 coordinate, where the player is positioned initially. Finally, we set which axis is pointing upwards. Here, we set the z-axis to point upwards.

The Lights

After setting up the camera, let's set up the lights. There are many types of lights in Three.js. Here, we're going to use an ambient light and a directional light.

That's why we're combining an ambient light (so that we have a base brightness all around the scene) with a directional light (to illuminate specific sides of our objects with a brighter color).

After seeing what the lights look like, let's add an ambient and directional light to the scene in our main file. We also position the directional light to the left along the x-axis, behind the player along the y-axis, and above the ground. By default, the target of the directional light is going to be the 0,0,0 coordinate. We don't have to set that.

import * as THREE from "three";
import { Renderer } from "./Renderer";
import { Camera } from "./Camera";
import { player } from "./Player";
import "./style.css";

const scene = new THREE.Scene();
scene.add(player);

const ambientLight = new THREE.AmbientLight();
scene.add(ambientLight);

const dirLight = new THREE.DirectionalLight();
dirLight.position.set(-100, -100, 200);
scene.add(dirLight);

const camera = Camera();
player.add(camera);

const renderer = Renderer();
renderer.render(scene, camera);

Note that we add the lights to the scene, but we add the camera to the player. This way, when we animate the player, the camera will follow the player.

The Renderer

We have defined many things, but we still don’t see anything on the screen. As a final piece, we need to have a renderer to render the scene. A renderer renders the 3D scene into a canvas element.

In this function, we get the canvas element we defined in the HTML and set it as the drawing context. We also set a couple more parameters. We make the background of the 3D scene transparent with the alpha flag, set the pixel ratio, and set the size of the canvas to fill the entire screen.

import * as THREE from "three";

export function Renderer() {
  const canvas = document.querySelector("canvas.game");
  if (!canvas) throw new Error("Canvas not found");

  const renderer = new THREE.WebGLRenderer({
    alpha: true,
    antialias: true,
    canvas: canvas,
  });
  renderer.setPixelRatio(window.devicePixelRatio);
  renderer.setSize(window.innerWidth, window.innerHeight);

  return renderer;
}

This is how our first scene comes together. We rendered a simple box.

How to Render a Map

We define a file for the constants. Here, we define the number of tiles in each row. In this case, there are 17 ties per row, going from -8 to +8. The player will start in the middle at tile zero.

export const minTileIndex = -8;
export const maxTileIndex = 8;
export const tilesPerRow = maxTileIndex - minTileIndex + 1;
export const tileSize = 42;

The Starting Row

First, let's add the starting row. We’ll define a couple of components that we’re going to use to render the map, and we’ll render the initial row.

Let's create a new component called Map. This file will expose the map's metadata and the 3D objects representing it. Let's export a group called map. This container will contain all the 3D objects for each row. Soon, we will add this group to the scene.

import * as THREE from "three";
import { Grass } from "./Grass";

export const map = new THREE.Group();

const grass = Grass(0);
map.add(grass);

Then, we set the map's content. Later, we will generate the 3D objects based on the metadata and use it to render the map. For now, let's just call the Grass function, which will return another Three.js group. We call the grass function with the row index, so the grass component will position itself based on this row index. Then, we add the returned group to the map.

Now, let's define the Grass component. The Grass function returns the foundation and container of the forest rows and is also used for the starting row. It returns a group containing a flat, wide, green box. The dimensions of this box are determined by the constants tileSize and tilesPerRow. The box also has some height, so it sticks out compared to the road, which will be completely flat.

import * as THREE from "three";
import { tilesPerRow, tileSize } from "./constants";

export function Grass(rowIndex) {
  const grass = new THREE.Group();
  grass.position.y = rowIndex * tileSize;

  const foundation = new THREE.Mesh(
    new THREE.BoxGeometry(tilesPerRow * tileSize, tileSize, 3),
    new THREE.MeshLambertMaterial({ color: 0xbaf455 })
  );
  foundation.position.z = 1.5;
  grass.add(foundation);

  return grass;
}

Now that we have the map container and the grass component, we can finally add the map to the scene.

import * as THREE from "three";
import { Renderer } from "./Renderer";
import { Camera } from "./Camera";
import { player } from "./Player";
import { map } from "./Map";
import "./style.css";

const scene = new THREE.Scene();
scene.add(player);
scene.add(map);

const ambientLight = new THREE.AmbientLight();
scene.add(ambientLight);

const dirLight = new THREE.DirectionalLight();
dirLight.position.set(-100, -100, 200);
scene.add(dirLight);

const camera = Camera();
scene.add(camera);

const renderer = Renderer();
renderer.render(scene, camera);

How to Add a Forest Row

Now that we have an empty forest, let's add another row containing trees. We define the map's metadata and render the rows based on this metadata.

Back in the Map component, let's define the map's metadata. The metadata is an array of objects that contain information about each row. Each row will contain a type that will determine the kind of the row and the rest of the properties depending on the row type.

import * as THREE from "three";
import { Grass } from "./Grass";

export const metadata = [
  {
    type: "forest",
    trees: [
      { tileIndex: -3, height: 50 },
      { tileIndex: 2, height: 30 },
      { tileIndex: 5, height: 50 },
    ],
  },
];

export const map = new THREE.Group();

const grass = Grass(0);
map.add(grass);

To render the rows, we loop over this array and generate 3D objects for each row based on the row type. For the forest type, it calls the Grass function again, which will return a Three.js group. We call this Grass function with the row index so the Grass function can position itself along the y-axis. The row index is off by one compared to the array index because the first item in the metadata will become the second row right after the starting row, which is not part of the metadata.

import * as THREE from "three";
import { Grass } from "./Grass";
import { Tree } from "./Tree";

export const metadata = [
  {
    type: "forest",
    trees: [
      { tileIndex: -3, height: 50 },
      { tileIndex: 2, height: 30 },
      { tileIndex: 5, height: 50 },
    ],
  },
];

export const map = new THREE.Group();

const grass = Grass(0);
map.add(grass);

metadata.forEach((rowData, index) => {
  const rowIndex = index + 1;

  if (rowData.type === "forest") {
    const row = Grass(rowIndex);

    rowData.trees.forEach(({ tileIndex, height }) => {
      const three = Tree(tileIndex, height);
      row.add(three);
    });

    map.add(row);
  }
});

Forest rows also have trees. For each item in the trees array, we render a tree. The Tree function will return a 3D object representing the tree.

We pass on to this function the tile index that we will use to position the tree within the row and the height. We add the trees to the group the Grass function returned, and then we add the whole group returned by the Grass function to the map.

import * as THREE from "three";
import { tileSize } from "../constants";

export function Tree(tileIndex, height) {
  const tree = new THREE.Group();
  tree.position.x = tileIndex * tileSize;

  const trunk = new THREE.Mesh(
    new THREE.BoxGeometry(15, 15, 20),
    new THREE.MeshLambertMaterial({ color: 0x4d2926 })
  );
  trunk.position.z = 10;
  tree.add(trunk);

  const crown = new THREE.Mesh(
    new THREE.BoxGeometry(30, 30, height),
    new THREE.MeshLambertMaterial({ color: 0x7aa21d })
  );
  crown.position.z = height / 2 + 20;
  tree.add(crown);

  return tree;
}

Car Lanes

Now, let's add another row type: car lanes. The process of adding car lanes will follow a similar structure. We define the lanes' metadata, including the vehicles, and then map them into 3D objects.

In the Map component in the metadata, let's replace the first row with a car lane. The car lane will contain a single red car moving to the left. We have a direction property, which is a boolean flag. If this is true, that means the cars are moving to the right in the lane, and if it's false, then the vehicles are moving to the left. We also have a speed property, which defines how many units each vehicle takes every second.

import * as THREE from "three";
import { Grass } from "./Grass";
import { Tree } from "./Tree";

export const metadata = [
  {
    type: "car",
    direction: false,
    speed: 1,
    vehicles: [{ initialTileIndex: 2, color: 0xff0000 }],
  },
];

. . .

Now, to render this lane type, we have to extend our logic to support car lanes. We add another if block that is very similar to the rendering of the forest. In the case of a car type, we call the Road function, which will also return a Three.js group. We also call this function with the row index to position the group according to the lane.

Then, for each item in the vehicles array, we create a 3D object representing the car with the Car function. We add the cars to the group returned by the Road function, and we add the whole group to the map. For the car function, we also pass on the initial tile index that we will use to position the car within the row, the direction, and the color.

import * as THREE from "three";
import { Grass } from "./Grass";
import { Road } from "./Road";
import { Tree } from "./Tree";
import { Car } from "./Car";

export const metadata = [
  {
    type: "car",
    direction: false,
    speed: 1,
    vehicles: [{ initialTileIndex: 2, color: 0xff0000 }],
  },
];

export const map = new THREE.Group();

const grass = Grass(0);
map.add(grass);

metadata.forEach((rowData, index) => {
  const rowIndex = index + 1;

  if (rowData.type === "forest") {
    const row = Grass(rowIndex);

    rowData.trees.forEach(({ tileIndex, height }) => {
      const three = Tree(tileIndex, height);
      row.add(three);
    });

    map.add(row);
  }

  if (rowData.type === "car") {
    const row = Road(rowIndex);

    rowData.vehicles.forEach((vehicle) => {
      const car = Car(
        vehicle.initialTileIndex,
        rowData.direction,
        vehicle.color
      );
      row.add(car);
    });

    map.add(row);
  }
});

The Road and Car functions are new here, so let's examine them next. The Road function returns the foundation and container of the car and truck lanes. Similar to the Grass function, it also returns a group containing a gray plane.

The size of the plane is also determined by the constants tileSize and tilesPerRow. Unlike the grass function, though, it doesn't have any height. It's completely flat. The road will also serve as a container for the cars and trucks in the row, so that's why we wrap the plane into a group – so that we can add children to it.

import * as THREE from "three";
import { tilesPerRow, tileSize } from "../constants";

export function Road(rowIndex) {
  const road = new THREE.Group();
  road.position.y = rowIndex * tileSize;

  const foundation = new THREE.Mesh(
    new THREE.PlaneGeometry(tilesPerRow * tileSize, tileSize),
    new THREE.MeshLambertMaterial({ color: 0x454a59 })
  );
  road.add(foundation);

  return road;
}

Now, let's look at the Car. The Car function returns a very simple 3D car model.

import * as THREE from "three";
import { tileSize } from "./constants";

export function Car(initialTileIndex, direction, color) {
  const car = new THREE.Group();
  car.position.x = initialTileIndex * tileSize;
  if (!direction) car.rotation.z = Math.PI;

  const main = new THREE.Mesh(
    new THREE.BoxGeometry(60, 30, 15),
    new THREE.MeshLambertMaterial({ color })
  );
  main.position.z = 12;
  car.add(main);

  const cabin = new THREE.Mesh(
    new THREE.BoxGeometry(33, 24, 12),
    new THREE.MeshLambertMaterial({ color: "white" })
  );
  cabin.position.x = -6;
  cabin.position.z = 25.5;
  car.add(cabin);

  const frontWheel = new THREE.Mesh(
    new THREE.BoxGeometry(12, 33, 12),
    new THREE.MeshLambertMaterial({ color: 0x333333 })
  );
  frontWheel.position.x = 18;
  frontWheel.position.z = 6;
  car.add(frontWheel);

  const backWheel = new THREE.Mesh(
    new THREE.BoxGeometry(12, 33, 12),
    new THREE.MeshLambertMaterial({ color: 0x333333 })
  );
  backWheel.position.x = -18;
  backWheel.position.z = 6;
  car.add(backWheel);

  return car;
}

We group all these elements, position them based on the initialTileIndex property, and turn them based on the direction property. If the car goes to the left, we rotate it by 180°. When we set rotation values in Three.js. We have to set them in radians, so that's why we set it to Math.Pi, which is equivalent to 180°.

You can also find a more extended version of how to draw this car with textures in this article.

Based on the metadata, we can now render a map with several rows. Here’s an example with a few more lanes. Of course, feel free to define your own map.

. . .

export const metadata = [
  {
    type: "car",
    direction: false,
    speed: 188,
    vehicles: [
      { initialTileIndex: -4, color: 0xbdb638 },
      { initialTileIndex: -1, color: 0x78b14b },
      { initialTileIndex: 4, color: 0xa52523 },
    ],
  },
  {
    type: "forest",
    trees: [
      { tileIndex: -5, height: 50 },
      { tileIndex: 0, height: 30 },
      { tileIndex: 3, height: 50 },
    ],
  },
  {
    type: "car",
    direction: true,
    speed: 125,
    vehicles: [
      { initialTileIndex: -4, color: 0x78b14b },
      { initialTileIndex: 0, color: 0xbdb638 },
      { initialTileIndex: 5, color: 0xbdb638 },
    ],
  },
  {
    type: "forest",
    trees: [
      { tileIndex: -8, height: 30 },
      { tileIndex: -3, height: 50 },
      { tileIndex: 2, height: 30 },
    ],
  },
];

. . .

This article does not cover truck lanes, but they follow a similar structure. The code for it can be found at JavaScriptGameTutorials.com.

How to Animate the Cars

Let's move on and animate the cars in their lanes according to their speed and direction. To move the vehicles, we first need to be able to access them. So far, we have added them to the scene, and theoretically, we could traverse the scene and figure out which object represents a vehicle. But it's much easier to collect their references in our metadata and access them through these references.

Let's modify the Map generation. After generating a car, we not only add them to the container group but also save the reference together with their metadata. After this, we can go to the metadata and access each vehicle in the scene.

. . .

metadata.forEach((rowData, index) => {
  const rowIndex = index + 1;

  if (rowData.type === "forest") {
    const row = Grass(rowIndex);

    rowData.trees.forEach(({ tileIndex, height }) => {
      const three = Tree(tileIndex, height);
      row.add(three);
    });

    map.add(row);
  }

  if (rowData.type === "car") {
    const row = Road(rowIndex);

    rowData.vehicles.forEach((vehicle) => {
      const car = Car(
        vehicle.initialTileIndex,
        rowData.direction,
        vehicle.color
      );
      vehicle.ref = car; // Add a reference to the car object in metadata
      row.add(car);
    });

    map.add(row);
  }
});

Next, let's go to the main file and define an animate function that will be called on every animation frame. For now, we only call the animateVehicles function, which we will define next. Later, we will extend this function with logic to animate the player and to have hit detection.

import * as THREE from "three";
import { Renderer } from "./Renderer";
import { Camera } from "./Camera";
import { player } from "./Player";
import { map } from "./Map";
import { animateVehicles } from "./animateVehicles";
import "./style.css";

const scene = new THREE.Scene();
scene.add(player);
scene.add(map);

const ambientLight = new THREE.AmbientLight();
scene.add(ambientLight);

const dirLight = new THREE.DirectionalLight();
dirLight.position.set(-100, -100, 200);
scene.add(dirLight);

const camera = Camera();
scene.add(camera);

const renderer = Renderer();
renderer.setAnimationLoop(animate);

function animate() {
  animateVehicles();

  renderer.render(scene, camera);
}

We also move the renderer render call here to render the scene on every animation loop. To call this function on every frame, we pass it on to the renderer’s setAnimationLoop function. This is similar to requestAnimationFrame in plain JavaScript, except that it calls itself at the end of the function, so we don't have to call it again.

Now, let's implement the animateVehicles function. As this function is part of the animate function, this function is called on every animation frame. Here, we use a Three.js clock to calculate how much time passed between the animation frames. Then, we loop over the metadata, take every vehicle from every car or truck lane, and move them along the x-axis based on their speed, direction, and the time passed.

import * as THREE from "three";
import { metadata as rows } from "./Map";
import { minTileIndex, maxTileIndex, tileSize } from "./constants";

const clock = new THREE.Clock();

export function animateVehicles() {
  const delta = clock.getDelta();

  // Animate cars and trucks
  rows.forEach((rowData) => {
    if (rowData.type === "car" || rowData.type === "truck") {
      const beginningOfRow = (minTileIndex - 2) * tileSize;
      const endOfRow = (maxTileIndex + 2) * tileSize;

      rowData.vehicles.forEach(({ ref }) => {
        if (!ref) throw Error("Vehicle reference is missing");

        if (rowData.direction) {
          ref.position.x =
            ref.position.x > endOfRow
              ? beginningOfRow
              : ref.position.x + rowData.speed * delta;
        } else {
          ref.position.x =
            ref.position.x < beginningOfRow
              ? endOfRow
              : ref.position.x - rowData.speed * delta;
        }
      });
    }
  });
}

If a car reaches the end of the lane, we respawn it at the other end, depending on its direction. This creates an infinite loop in which cars go from left to right or right to left, depending on their direction. Once they reach the end of the lane, they start over from the beginning. With this function, we should have a scene where all the cars are moving in their lanes.

How to Move the Player

Collecting User Inputs

To check the movement commands, let's extend the player component with state. We keep track of the player's position and the movement queue. The player starts at the middle of the first row, and the move queue is initially empty.

. . .

export const position = {
  currentRow: 0,
  currentTile: 0,
};

export const movesQueue = [];

export function queueMove(direction) {
  movesQueue.push(direction);
}

export function stepCompleted() {
  const direction = movesQueue.shift();

  if (direction === "forward") position.currentRow += 1;
  if (direction === "backward") position.currentRow -= 1;
  if (direction === "left") position.currentTile -= 1;
  if (direction === "right") position.currentTile += 1;
}

Now, we can add event listeners for keyboard events to listen to the arrow keys. They all call the player's queueMove function, which we just defined for the player with the corresponding direction.

import { queueMove } from "./Player";

window.addEventListener("keydown", (event) => {
  if (event.key === "ArrowUp") {
    queueMove("forward");
  } else if (event.key === "ArrowDown") {
    queueMove("backward");
  } else if (event.key === "ArrowLeft") {
    queueMove("left");
  } else if (event.key === "ArrowRight") {
    queueMove("right");
  }
});

After defining the event listeners, we also have to import them into the main file so that they work.

import * as THREE from "three";
import { Renderer } from "./Renderer";
import { Camera } from "./Camera";
import { player } from "./Player";
import { map } from "./Map";
import { animateVehicles } from "./animateVehicles";
import "./style.css";
import "./collectUserInput"; // Import event listeners

. . .

Executing Movement Commands

So far, we have collected user inputs and put each command into the movesQueue array in the player component. Now, it's time to execute these commands one by one and animate the player.

Let's create a new function called animatePlayer. Its main goal is to take each move command from the moveQueue one by one, calculate the player's progress toward executing a step, and position the player accordingly.

This function animates the player frame by frame. It will also be part of the animate function. We also use a separate move clock that measures each step individually. We pass on false to the clock constructor so it doesn't start automatically. The clock only starts at the beginning of a step. At each animation frame, first, we check if there are any more steps to take, and if there are and we don't currently process a step, then we can start the clock. Once the clock is ticking we animate the player from tile to tile with each step.

import * as THREE from "three";
import { movesQueue, stepCompleted } from "./Player";

const moveClock = new THREE.Clock(false);

export function animatePlayer() {
  if (!movesQueue.length) return;

  if (!moveClock.running) moveClock.start();

  const stepTime = 0.2; // Seconds it takes to take a step
  const progress = Math.min(1, moveClock.getElapsedTime() / stepTime);

  setPosition(progress);

  // Once a step has ended
  if (progress >= 1) {
    stepCompleted();
    moveClock.stop();
  }
}

. . .

import * as THREE from "three";
import {
  player,
  position,
  movesQueue,
  stepCompleted,
} from "./components/Player";
import { tileSize } from "./constants";

. . .

function setPosition(progress) {
  const startX = position.currentTile * tileSize;
  const startY = position.currentRow * tileSize;
  let endX = startX;
  let endY = startY;

  if (movesQueue[0] === "left") endX -= tileSize;
  if (movesQueue[0] === "right") endX += tileSize;
  if (movesQueue[0] === "forward") endY += tileSize;
  if (movesQueue[0] === "backward") endY -= tileSize;

  player.position.x = THREE.MathUtils.lerp(startX, endX, progress);
  player.position.y = THREE.MathUtils.lerp(startY, endY, progress);
  player.children[0].position.z = Math.sin(progress * Math.PI) * 8 + 10;
}

For the vertical component, we use a sine function to make it look like jumping. We are basically mapping the progress to the first part of a sine wave.

We also need to add the original Z position to the value – otherwise, the player will sink halfway into the ground after the first step.

Now that we’ve defined the animatePlayer function, let's add it to the animate loop.

import * as THREE from "three";
import { Renderer } from "./Renderer";
import { Camera } from "./Camera";
import { DirectionalLight } from "./DirectionalLight";
import { player } from "./Player";
import { map, initializeMap } from "./Map";
import { animateVehicles } from "./animateVehicles";
import { animatePlayer } from "./animatePlayer";
import "./style.css";
import "./collectUserInput";

. . .

function animate() {
  animateVehicles();
  animatePlayer();

  renderer.render(scene, camera);
}

Restricting Player Movement

For instance, if the player's current position is 0,0, staying in the middle of the first row, and the moves are forward and left, then the final position will be row 1 tile -1.

export function calculateFinalPosition(currentPosition, moves) {
  return moves.reduce((position, direction) => {
    if (direction === "forward")
      return {
        rowIndex: position.rowIndex + 1,
        tileIndex: position.tileIndex,
      };
    if (direction === "backward")
      return {
        rowIndex: position.rowIndex - 1,
        tileIndex: position.tileIndex,
      };
    if (direction === "left")
      return {
        rowIndex: position.rowIndex,
        tileIndex: position.tileIndex - 1,
      };
    if (direction === "right")
      return {
        rowIndex: position.rowIndex,
        tileIndex: position.tileIndex + 1,
      };
    return position;
  }, currentPosition);
}

import { calculateFinalPosition } from "./calculateFinalPosition";
import { minTileIndex, maxTileIndex } from "./constants";
import { metadata as rows } from "./Map";

export function endsUpInValidPosition(currentPosition, moves) {
  // Calculate where the player would end up after the move
  const finalPosition = calculateFinalPosition(
    currentPosition,
    moves
  );

  // Detect if we hit the edge of the board
  if (
    finalPosition.rowIndex === -1 ||
    finalPosition.tileIndex === minTileIndex - 1 ||
    finalPosition.tileIndex === maxTileIndex + 1
  ) {
    // Invalid move, ignore move command
    return false;
  }

  // Detect if we hit a tree
  const finalRow = rows[finalPosition.rowIndex - 1];
  if (
    finalRow &&
    finalRow.type === "forest" &&
    finalRow.trees.some(
      (tree) => tree.tileIndex === finalPosition.tileIndex
    )
  ) {
    // Invalid move, ignore move command
    return false;
  }

  return true;
}

import * as THREE from "three";
import { endsUpInValidPosition } from "./endsUpInValidPosition";

. . .

export function queueMove(direction) {
  const isValidMove = endsUpInValidPosition(
    {
      rowIndex: position.currentRow,
      tileIndex: position.currentTile,
    },
    [...movesQueue, direction]
  );

  if (!isValidMove) return; // Return if the move is invalid

  movesQueue.push(direction);
}

. . .

Hit Detection

To finish the game, let's add hit detection. We check if the player gets hit by a vehicle, and if so, we show an alert popup.

Let's define another function to define hit detection. We check if the player intersects with any of the vehicles. In this function, we check which row the player is currently in. The index is off by one because the row metadata does not include the starting row. If the player is in the starting row, we get undefined. We ignore that case. If the player is in a car or truck lane, we loop over the vehicles in the row and check if they intersect with the player. We create bounding boxes for the player and the vehicle to check for intersections.

import * as THREE from "three";
import { metadata as rows } from "./Map";
import { player, position } from "./Player";

export function hitTest() {
  const row = rows[position.currentRow - 1];
  if (!row) return;

  if (row.type === "car" || row.type === "truck") {
    const playerBoundingBox = new THREE.Box3();
    playerBoundingBox.setFromObject(player);

    row.vehicles.forEach(({ ref }) => {
      if (!ref) throw Error("Vehicle reference is missing");

      const vehicleBoundingBox = new THREE.Box3();
      vehicleBoundingBox.setFromObject(ref);

      if (playerBoundingBox.intersectsBox(vehicleBoundingBox)) {
        window.alert("Game over!");
        window.location.reload();
      }
    });
  }
}

If the bounding boxes intersect, we show an alert. Once the user clicks OK on the alert, we reload the page. We call this function in the animate function, which will run it on every frame.

import * as THREE from "three";
import { Renderer } from "./Renderer";
import { Camera } from "./Camera";
import { player } from "./Player";
import { map } from "./Map";
import { animateVehicles } from "./animateVehicles";
import { animatePlayer } from "./animatePlayer";
import { hitTest } from "./hitTest";
import "./style.css";
import "./collectUserInput";

. . .

function animate() {
  animateVehicles();
  animatePlayer();
  hitTest(); // Add hit detection

  renderer.render(scene, camera);
}

Next Steps

I hope you had great fun creating this game. This game, of course, is far from perfect, and there are various improvements you can make if you’d like to keep working on it.

Alternatively, you can find the extended tutorial on YouTube.

JavaScript Tutorial – How to Set Up a Front End Development Project

Hunor Márton Borbély — Wed, 12 Feb 2025 21:44:03 +0000

Let’s say you plan to build a website. Before you start, you want to set up a few tools to make your life easier. But which tools should you have?

The JavaScript ecosystem is changing so fast that it can be overwhelming to pick the best tools to use. To solve this problem, in this article, I’m going to walk you through how to set up a front-end project from scratch.

We'll cover things like must-have editor extensions, adding JavaScript libraries to your project, why you'll use Node.js even if you want to do front-end development, and setting up an application bundler that will generate a live preview as you code in your browser.

You can also watch this article as a video on YouTube. Let's dive in.

How to Choose a Code Editor
How to Auto-format Your Code in VS Code
Why Do You Need Node for a Front-End Project?
How to Run Your Project
How to Add Libraries to Your JavaScript Project
How to Get Coding Tips While You Code
Initialize a Project with Vite
Summary

How to Choose a Code Editor

Let’s start with the foundations. As a web developer, you mostly edit text, so you need a good editor. So which one should you use?

Picking an editor is highly based on personal preference, as most editors have very similar features.

If you don’t have a personal preference, I highly recommend VS Code. Lately, it has become the de facto standard editor for web development.

One of the greatest features of all the mainstream editors is that you can add extensions to them. Let’s walk through two extensions that are must-haves.

How to Auto-format Your Code in VS Code

Prettier is an extension that makes your code more readable and more consistent.

Let’s say you copy-pasted some code, and it’s hard to read. The tabulation is off, a line is too long, and so on. Then you just save the file, and magically, everything looks as it should be.

This is what Prettier does. It formats the code based on best practices. It doesn't just fix tabulation and wrap the lines. It also adds parentheses to improve code readability, makes sure you are consistent with quotation marks, and many more.

To make it work in VS Code, we must first install the Prettier extension. To do so, go to the extensions panel in VS Code, search for Prettier, and then install it.

Installing this extension doesn't format your files automatically on save by default. The default behavior is that once you install this extension, you can right-click within a file and select Format Document. You can also select part of a file and choose Format Selection.

The first time you do this, you need to select the default formatter. VS Code already has a formatter, but it isn’t as powerful as Prettier. Now that you have two formatters, you have to let VS Code know that you want to use Prettier for formatting in the future.

If you wish to auto-format your files when you save them, you need to change the settings. Go to Settings in your VS Code preferences and search for the Format on Save option. By default, this is false, so make sure that you tick this checkbox. With this, Prettier formats your files every time you save them.

Formatting can be controversial, though. I highly recommend the default settings, especially for beginners. But if you prefer a different style, you can customize things.

You can indicate with comments to ignore specific lines and create a config file to list your preferences.

In the root folder of your project, you can create a file called .prettierrc and add a few options. A typical option could be if you prefer single quotes instead of double quotes in your files. Or if you don't want to have semi-colons at the end of your lines.

With this configuration, you will have a different format once you save your files.

{
  "singleQuote": true,
  "semi": false
}

There are many more options, of course. If you want to dig deeper, check out Prettier's documentation .

Why Do You Need Node for a Front-End Project?

Before we get to the second must-have extension, we need to set up a few other things. First, we need to talk about Node.js. What is Node, and why do you need it even if you work as a front-end developer?

Node is often associated with backend development, but that's not its only job. Node is a JavaScript runtime – this means it runs JavaScript files outside of the browser.

There are two ways of running JavaScript code. You can either have it as part of a website and run the entire website in a browser, or run only the Javascript file with a runtime like Node.

In the example below, we have a very simple Javascript file that prints "Hello World" to the console. If we have Node installed, we can go to the terminal, navigate to the folder where this file is, and then run it with Node like this. You can see that the file was executed, and the result is in the console.

That's what Node really is: a tool that runs JavaScript files on their own.

JavaScript mostly behaves the same way in both environments. But there are also differences in what JavaScript can do in a browser vs when it runs with Node.

For instance, when running in the browser, JavaScript can access and modify HTML elements. That's the main point of having JavaScript in the first place.

In Node, there's no HTML file. JavaScript runs on its own. On the other hand, in Node, JavaScript has access to your file system and can read and write your files.

For instance, you can run scripts on your machine to initialize a project. We are going to do that. You can run checks on your files and automatically correct the mistakes. Or you can run your test files.

In short, Node lets you run some tools that make your life much easier as a developer.

To install Node, go to nodejs.org and install it. If you are unsure if you already have Node, you can also go to your terminal and run node -v to check. If you get a version number, you have Node.

So, why do people associate Node primarily with backend development? If the backend code is in JavaScript, the servers must run it somehow without a browser. So yes, if you are a backend developer using JavaScript, then you're most probably going to use Node. But Node is much more than that.

How to Run Your Project

Now that we have Node, we can use a live server to see our site live in the browser as we develop it. Without this, you need to manually refresh the browser window every time you make a change.

These tools are called bundlers because they take all your files and turn them into a neat package you can run in the browser. So why do you need them?

They update your site live in the browser with hot reloading. When you save a file, you immediately see the result in your browser.
As web development tools have evolved, the browser won't understand your files when you use anything more advanced. For instance, are you using React? Then, you're using the JSX syntax – the one that looks like HTML. The JSX syntax is not part of JavaScript. You need a tool to convert it into plain JavaScript. Otherwise, it won't run in your browser. Or are you using TypeScript? You also need to turn that into JavaScript. Or, if you're using SCSS or any other CSS dialect, you need to convert it to plain CSS.
If you import libraries using the JavaScript module system, you need a live server to avoid CORS issues in your browser.

This is what bundlers do. They make sure that you can use modern-day tooling while you're developing your application, and they can also create a final production build that you can publish on the internet.

How do you pick a bundler? There are several options, and essentially, they all do the same thing. The difference between them is in their performance, configuration options, and ease of use.

The most used bundler is still webpack, one of the earliest bundlers in the field. But the one that seems to have taken over the throne and gained more and more popularity is Vite. Here's a chart from the latest edition of the State of JavaScript survey.

This chart shows that while most developers have used Webpack, they don’t necessarily love it. At the same time, Vite's popularity is rising while still maintaining a positive sentiment.

If you haven't checked out the State of JavaScript survey before, I highly recommend going through it. It gives you an excellent overview of the latest trends with JavaScript. You can learn which tools and libraries people love to use and which they will abandon soon. If you feel overwhelmed by all the changes in the JavaScript ecosystem, the results of this survey can be a great guide.

Once we have a folder for our project, let's navigate to it using our terminal. The easiest way to do this is to open the folder in VS Code and then use the built-in terminal. VS Code will open the terminal with the correct folder.

Then, you can run the project in the terminal with the following command. npx is a command line tool that comes with Node. This is one of the reasons we installed Node: to be able to run commands like this.

npx vite

The first time you run this script, it will ask you to install Vite. Say yes. Then, it will show you the URL of a local server, which you can open in a browser to view your project.

  VITE v6.1.0  ready in 162 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

Now, if you update a file and save the changes, the new version appears in the browser immediately. It generates a live preview of your site until you stop the script or close the terminal. You can keep it running while you're developing your site.

Once you have finished, you can press Ctrl+C to stop the script. If it gets desynchronized or you break it with an error, restart it by pressing Ctrl+C to stop it and rerunning the same script. So that's how you run a project with Vite.

How to Add Libraries to Your JavaScript Project

Now that we have Node, we can also use npm or Note Package Manager to add libraries to our project. npm is another tool included with Node. So how does it work?

First, I will walk you through setting things up step by step the manual way so it's clear how the different parts come together. Then, I will show you how to automate most of these steps.

Navigate to your current folder in the terminal and run the following command to initialize the project. This command initializes a package.json file with some metadata.

npm init --yes

At this point, this file is not very interesting. It contains the project name, description, version number, and so on. You can change these values.

Now, we can add libraries to our package with the npm install command. In a previous article, we used Three.js to render 3D boxes in the browser.

So, as an example, let's install Three.js. Go to your terminal again, make sure you are in the correct folder, and run the following command:

npm install three

This command will install Three.js. But how do you know that the keyword is three here, not Three.js?

When you don’t know the package name, you can just google npm and the name of the library you need. Or, if you don't even know the library name, you can also just search for an npm 3D library and see what Google comes up with.

We can go through each package one by one and pick one based on their capabilities and other info. These packages mostly come with descriptions and quick examples to give you an idea of what the library can do for you.

Another indicator you might want to look for is the weekly downloads and the date of the last update to ensure you select an actively maintained library that people still use.

Once you find the package you are looking for, you can see the command to install it at the top right corner: npm i three. The i here is just shorthand for install. Another way to learn how to install Three.js is to go to its official documentation and check the installation guide.

When we install a package, three things happen:

It adds the latest version of Three.js in our package.json file as a project dependency.
It also creates a package-lock file, which NPM uses to keep track of the dependencies. You should never edit the dependency section of your package.json file or the package-lock file manually. Instead, you should always use commands like npm install and uninstall to add, remove, or update packages.
Finally, the node_modules folder gets created. This folder contains the source code of Three.js. When we import Three.js in our project, it looks for it in this folder. The content of this folder is also something that you should never change. You can look into it if you're interested in the source code of the library that you're using, but you shouldn't change it.

If something goes wrong and you have an error with your dependencies that you can't figure out, then you can always safely delete the node_modules folder and the package-lock file and reinstall your dependencies based on the package.json file. This is not something that you should do, but you can always go back to having a clean slate.

Now that we have installed Three.js, we can create a simple website that displays a 3D box. It's a simple HTML file and a JavaScript file with the code for the 3D box. The key here is that we import Three.js with the import statement in the JavaScript file. This import will use the package that we just installed.

Then, we can run the project with Vite. Using imports means that we use the module system now. Running a project with the module syntax can be a bit tricky, as the browser gives you CORS errors by default. However, as we are using Vite to run our project, it works seamlessly without any questions. That’s one of the reasons we use Vite.

If you want to learn more about building 3D games with Three.js, check out my earlier article on building a minimalistic car in the browser.

How to Get Coding Tips While You Code

The second must-have editor extension is ESLint. While Prettier formatted the code, ESLint gives you coding tips.

It helps you catch basic mistakes and avoid patterns that can cause bugs or be misleading when you try to understand the code.

Here’s a simple example where you declare a variable, but then you have a typo, and you try to use another variable that doesn't exist. ESLint will highlight this for you. It will give you an error both at the variable declaration, saying that you created a variable you don't use, and add the usage, saying that you're trying to use a variable that is not declared. With ESLint, it's easy to spot that you made a typo.

ESLint, of course, is much more complex than just being able to catch simple errors. There are also less obvious use cases where you might not understand why ESLint is complaining. Then, you can always click the link in the error popup for more details explaining why this pattern is harmful and what you can do to avoid it.

So how can we use ESLint in our projects? This time, we need to have an extension and a configuration. First, as we did with Prettier, we must install the ESLint extension. Go to your extensions, search for ESLint, and install it.

We also need to set up ESLint for our project. Before we do that, we need to make sure that the project already has a package.json file. If you don't already have a package.json file, we first have to run npm init --yes to initialize the project. Then, we can generate an ESLint config with the following command:

npm init @eslint/config@latest

This script will ask you a few questions. Based on your answers, it will customize the configuration and the rules to check. For most cases, you can use the default option.

The first time, it will ask for permission to install ESLint. Say yes.
Then, it will ask you whether to use ESLint only for syntax checks or to find problems as well. Choose the second option to get the most help from ESLint.
Then select that you’ll use it with JavaScript modules. Modern web development projects use the JavaScript module system. We use JavaScript modules if we have imports and exports in our code.
Then, it will ask what framework we are using. If we select a framework, it will add framework-specific rules to our project. For instance, using it with React will force us to define the prop types. If we don't use a front-end framework, just vanilla JavaScript, then select "None of these".
Then, it will ask if the project is using TypeScript. Choose based on your preference.
It asks where you run the code. As we have a front-end project, select "Browser".
Then, it will ask if you want to install the additional dependencies that are required for the rules based on your selections. Select yes.
It will also ask what package manager we’re using. We haven't talked a lot about this, but there are multiple package managers that we can use. Select the default: npm.

These were a lot of questions. Let's see what happened after we ran this command.

After this step, we have ESLint and some other dependencies based on the answers in the package.json file as development dependencies. Development dependency means that ESLint won't be part of your website's final code, but we need it during development.

ESLint also became part of our node_modules folder, and there are many more packages here now. This is because a dependency can have other dependencies, and the dependencies of the dependencies will also be part of the node_modules folder.

ESLint also created a config file that sets up the rules based on your answers. We will see how to customize the rules.

Now that ESLint is working, you should also see errors in the code once something is off. If you go to your JavaScript file and try to use an undeclared variable, ESLint will highlight the issue.

ESLint is also highly customizable. For instance, we might not want to mark an unused variable as an error. First, we go to the error popup and select the identifier of this type of error. Then, we go to the ESLint config and override this error as follows. Here, we can reduce the severity to a warning or completely turn off this rule.

import globals from "globals";
import pluginJs from "@eslint/js";


/** @type {import('eslint').Linter.Config[]} */
export default [
  {languageOptions: { globals: globals.browser }},
  pluginJs.configs.recommended,
  {
    rules: {
      "no-unused-vars": "off", // Turn off the No Unused Variables rule
    }
  }
];

But if you're a beginner, I recommend following the rules that ESLint has by default. Sometimes, it might be annoying to fix all the seemingly harmless issues, but all these rules are based on industry best practices, so it's good to follow them. For more details, check out ESLint's documentation.

Initialize a Project with Vite

We walked through the step-by-step process of setting up a project. We used npm init to initialize the project, manually set up ESLint, and ran our project with Vite. Vite can also initialize the project with a sample application and all the necessary files, which is especially handy when we set up a React project.

Let's see how to set up a vanilla JavaScript and a React project. Let's navigate to a folder in the terminal that will contain our project. We don't need to create a project folder this time because the script will make it for us. Then, run the following command to initialize a project:

npm create vite@latest

This command asks you a few questions.

First, it will ask you for the project name, which will also be the name of the folder created as the project root.
Then, it will ask what framework you use. If you don't use any framework and want plain old JavaScript, choose "Vanilla." If you use React, choose React.
Then, it will ask you if you want to use TypeScript or JavaScript. Here, the default is TypeScript. If you're a beginner in web development, choose JavaScript. If you are more confident with your skills, then go with TypeScript. TypeScript is more complicated, but it has become the industry standard in web development, and most jobs require you to know it. As a beginner, you can go with JavaScript.

Now, we can navigate to the new folder created and check out what we have here. If you choose a vanilla JavaScript project, you can see it generated a simple application with HTML, CSS, and some JavaScript files. You can change or even delete these. You'll need an HTML file as an entry point, but you can replace the rest.

We can run this project with npx vite as we did before, but there’s a better way. For a real project, we want to add Vite as a development dependency to ensure consistency with the version we are using.

{
  "name": "my-project",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "devDependencies": {
    "vite": "^6.1.0"
  }
}

The package.json file shows that Vite has been added as a development dependency. To use this hardcoded version, we first have to install it via npm install. This command installs all the dependencies listed in the package.json file.

npm install

This package.json file now also has a scripts section. This section can define scripts to run your app locally, create a production build, or test your application. You can run them with npm run. So, for instance, to run the application, you can open the terminal with the correct folder and run the following command.

npm run dev

This runs the script labeled as “dev” in the scripts section, which will run the Vite version we just installed with npm install.

Vite does not install ESLint when you create a vanilla project, but you can always install it manually, as we did before with npm init @eslint/config@latest.

If you choose React as a framework when we initialize the project, we will have a couple more files. For instance, we have an ESLint config with the recommended React settings. We also have a Vite config that enables us to use React and a sample application that we can run.

To run this app, we need to install the dependencies. So, let's go to the terminal and run npm install. This will install all the dependencies, including React. Then, we can run this app with npm run dev, and we will have a working React application.

Summary

In this article, we set up and run a front-end project with Vite. We also covered how to find and add dependencies, how to have consistent and automatic formatting with Prettier, and how to avoid bugs with ESLint.

What happens once you finish developing your app? How do you upload it to the web and share it with the world? That's the topic of a future article.

SVG Toggle Button Tutorial – How to Handle Dark Mode with CSS and JavaScript

Hunor Márton Borbély — Fri, 08 Mar 2024 13:46:26 +0000

How can you detect dark mode in CSS and JavaScript? How can you manually override it with a toggle button? And how can you create a sun and moon icon with SVG?

In this tutorial, you will learn how to detect dark mode in CSS and JavaScript, and you will create a toggle button with SVG to override the default behavior. You will use plain HTML, CSS, and JavaScript, so you don't need any preliminary requirements before starting.

You can also watch this article as a video on YouTube.

How to Handle Dark Mode with CSS
How to Code a Sun Icon with SVG
How to Detect Dark Mode in JavaScript
How to Code a Moon Icon with SVG
How to Toggle Dark Mode with JavaScript
Next Steps

How to Handle Dark Mode with CSS

Let's say you have a simple website with some text. By default, you set the text color to be black and the background color to be white. Implementing dark mode for this site with CSS is very simple:

html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Dark Modetitle>
    <link rel="stylesheet" href="index.css" />
    <script src="index.js" defer>script>
  head>

  <body>
    <p>
      How to detect dark mode in CSS and in JavaScript? How can we override it
      manually with a toggle button? In this quick tutorial, we look into
      detecting dark mode in CSS and JavaScript, and then we create a toggle
      button with SVG to override the default behavior.
    p>
  body>
html>

A simple website with some text in dark mode

All you need to do is add a media query and set a condition. With this condition, you set the following CSS statements to be only valid if the preferred color scheme is dark.

Inside this media query, you can define the colors for dark mode. In this case, you flip the colors and set the text color to white and the background color to black:

body {
  font-family: Montserrat;
  margin: 50px;
  max-width: 500px;
}

@media (prefers-color-scheme: dark) {
  body {
    background-color: black;
    color: white;
  }
}

This will take the setting from your OS or browser setting. By default, it comes from the Operating System, but the browser can decide to override it. In Google Chrome, you can find this setting under 'Appearance'. By default, it follows the device setting.

What's great about the CSS solution is that if you change this setting while visiting the website, the styling will update automatically.

This way, you can set a custom style for the body element and any other elements as well.

It doesn't work in one case, though. You cannot style what's inside an HTML Canvas element with CSS. If you built up a game entirely from JavaScript using the Canvas API or Three.js, you must also set the colors for dark mode in JavaScript.

In the next steps, we will cover this and look into how to create an SVG toggle button to switch between light and dark modes.

How to Code a Sun Icon with SVG

Before you learn how to handle dark mode in JavaScript, let's take a quick detour and see how to code a dark mode toggle button with SVG. Detecting dark mode is one thing, but you should allow the user to manually toggle between light and dark modes.

Sun Icon

Check out my previous tutorial if you need a quick introduction to coding SVG icons. It contains many great examples from beginner to advanced levels. And if you are new to SVGs, don't worry. These are very simple examples.

So, let's start with the svg element. This will serve as a container for all the image elements. Set its size to 30 times 30:

The svg element

Then, add a circle. For a circle element, you have to set the center coordinates of the circle and its radius. The center coordinates are both 15, and the radius is 6. Then, set a color with the fill property:

<svg width="30" height="30">
  <circle cx="15" cy="15" r="6" fill="currentColor" />
svg>

We add a circle as the core of the sun

To set the color, you can use the currentColor property that takes over the current color setting from CSS. This will come in handy later when you toggle dark and light modes. The icon will switch colors automatically.

Then, add the sun rays. You need to use the line element for this, where you have to set the starting and end coordinates. You can also set the stroke color with the stroke property, the stroke-width to add thickness, and the stroke-linecap property to make the ends of the lines rounded:

<svg width="30" height="30">
  <circle cx="15" cy="15" r="6" fill="currentColor" />

  <line
    id="ray"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    x1="15"
    y1="1"
    x2="15"
    y2="4"
  >line>
svg>

We add a line element as a sunray

Now, once you have one ray, you can reuse the same ray to draw the others.

You can give this ray an id and reuse it with the use element. For the reused elements, you can set a rotation. Set the rotation angle and the center of rotation. You want to rotate the rays around the center of the sun, so set it to 15,15. Then, increment the rotation by 45 degrees for each ray:

<svg width="30" height="30">
  <circle cx="15" cy="15" r="6" fill="currentColor" />

  <line
    id="ray"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    x1="15"
    y1="1"
    x2="15"
    y2="4"
  >line>

  <use href="#ray" transform="rotate(45 15 15)" />
  <use href="#ray" transform="rotate(90 15 15)" />
  <use href="#ray" transform="rotate(135 15 15)" />
  <use href="#ray" transform="rotate(180 15 15)" />
  <use href="#ray" transform="rotate(225 15 15)" />
  <use href="#ray" transform="rotate(270 15 15)" />
  <use href="#ray" transform="rotate(315 15 15)" />
svg>

The finished sun icon

How to Detect Dark Mode in JavaScript

Before we get to the moon icon, let's see how to detect dark mode in JavaScript. This can be useful when building a game, like we did a couple weeks ago in the Gorillas JavaScript game tutorial.

In that game, we were drawing on an HTML Canvas element with JavaScript. We set all the colors with JavaScript. If we want to support dark mode, we can set the colors based on a darkMode variable. But how do we detect if we are in dark mode? How do we set the value of this variable?

The following code is an example snippet from the game tutorial above. Here we set the fill color before we draw a rectangle on the canvas. To learn more about drawing on a canvas element, check out this tutorial.

When drawing on a canvas element we set the colors from JavaScript. But how we detect dark mode?

Detecting dark mode in JavaScript is also very simple. Interestingly enough, this solution also depends on the CSS query selectors you used before.

You can create a matchMedia object with the same condition we used in CSS. This method can check if the document matches a media query. Pass on prefers-color-scheme: dark as an argument:

const darkModeMediaQuery = window.matchMedia("(prefers-color-scheme: dark)");

let darkMode = darkModeMediaQuery.matches;

. . .

function drawBuildings() {
  state.buildings.forEach((building) => {
    ctx.fillStyle = darkMode ? "#254D7E" : "#947285";
    ctx.fillRect(building.x, 0, building.width, building.height);
  });
}

Then, can check the matches property of this object. If it is true, then you are in dark mode. You can save this into a variable, and later, you can use this variable to decide what colors you should use when painting on the canvas element.

This variable, however, doesn't get refreshed automatically when you switch between light mode and dark mode. You need to add an event listener that detects if the settings change.

Here, we define a function that checks the matches property of the incoming object to decide if you just switched to bright or dark mode:

const darkModeMediaQuery = window.matchMedia("(prefers-color-scheme: dark)");

let darkMode = darkModeMediaQuery.matches;

darkModeMediaQuery.addEventListener("change", (e) => {
  if (e.matches) {
    darkMode = true;
  } else {
    darkMode = false;
  }
});

. . .

function drawBuildings() {
  state.buildings.forEach((building) => {
    ctx.fillStyle = darkMode ? "#254D7E" : "#947285";
    ctx.fillRect(building.x, 0, building.width, building.height);
  });
}

Now, if you set the colors based on this darkMode variable, you should see that the game's appearance changes once you switch between light and dark mode in the OS settings. Check out this demo to see it in action.

How to Code a Moon Icon with SVG

Before we discuss overriding the default OS setting with a toggle button, let's examine the other half of our toggle icon: Let's draw a moon.

The Sun and Moon icons

Start with an svg element of the same size and define a path inside it. You can define a path element by setting its d attribute. In this attribute, you build a path from a series of commands:

We define a path with a series of commands

You start with the move-to command to go to the initial position. This command consists of the letter M and the starting coordinate:

Using the move-to command within a path

Then, use an arc command to draw the outer arc of the moon. This command might look a bit scary because it has several properties. Let's see what we have:

The arc command and it's several properties

A command always continues the previous command, so this arc will draw the arc from the coordinates of the move-to command. Commands also end with the coordinates of the endpoint.

Here, you set where the arc ends. The rest of the properties are about how to draw an arc from the starting point to the endpoint:

The last two properties of the arc command show the endpoint of the arc

The first two properties are the horizontal and vertical radius of our arc. In our case, we want to have the arc of a circle, so we set the same value for both. With the third argument, you can set a rotation. When both radiuses are the same, this property makes no difference. You can leave it at zero:

Horiyontal and vertical radius of the arc

Then, we have the large arc flag property. With this, you can decide whether to go the long or short way to our end coordinate. You can see that you can reach the endpoint in multiple ways, even with the same radiuses.

There are two arcs – in the case of the first one, you go the long way and in the case of the second one, you will go the short way. This is a flag, so the value here can be 0 or 1:

The large arc flag decides if we should reach the endpoint the short way or the long way

Finally, there is the sweep flag. This basically sets whether you should draw the arc clockwise or counterclockwise. The two options mirror each other. In the first case, you set this to zero – in the second, you set it to one:

The sweep flag decides if we should go clockwise or counterclockwise

Now that you have one arc, you set up the other one. Here, you set the endpoint to the beginning. To the same coordinates as you used for the move-to command.

Then you can use the same radiuses, but you have to change the large arc flag and the sweep flag to end up with a moon:

<svg width="30" height="30">
  <path
    fill="currentColor"
    d="
      M 23, 5
      A 12 12 0 1 0 23, 25
      A 12 12 0 0 1 23, 5"
  />
svg>

The finished moon icon

How can you use these two icons in a button to toggle light mode and dark mode in JavaScript?

How to Toggle Dark Mode with JavaScript

If you want to override the system or browser settings for dark mode with a manual switch, you can't rely on the CSS media query anymore. This works for rendering the UI based on the settings, but you can't override it from JavaScript.

You can't override a CSS media query

Instead, you can define a dark-mode class and toggle it from JavaScript.

In CSS, define a class that will change the same settings the media query did before. Then, in JavaScript, you can use the same logic you had before to get the default setting and then add or remove this class.

You can set this class on our initial page load and toggle it if you click a button:

body {
  font-family: Montserrat;
  margin: 50px;
  max-width: 500px;
}

.dark-mode {
  background-color: black;
  color: white;
}

Now, how do you toggle this with a button? In your HTML file, add a button element with an event handler. Then, move both SVGs inside this button element and assign IDs for them. You will toggle the visibility of these icons from JavaScript:

html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Dark Modetitle>
    <link rel="stylesheet" href="index.css" />
    <script src="index.js" defer>script>
  head>

  <body>
    <p>
      How to detect dark mode in CSS and in JavaScript? How can we override it
      manually with a toggle button? In this quick tutorial, we look into
      detecting dark mode in CSS and JavaScript, and then we create a toggle
      button with SVG to override the default behavior.
    p>

    <button onclick="toggleDarkMode()">
      <svg width="30" height="30" id="light-icon">
        <circle cx="15" cy="15" r="6" fill="currentColor" />

        <line
          id="ray"
          stroke="currentColor"
          stroke-width="2"
          stroke-linecap="round"
          x1="15"
          y1="1"
          x2="15"
          y2="4"
        >line>

        <use href="#ray" transform="rotate(45 15 15)" />
        <use href="#ray" transform="rotate(90 15 15)" />
        <use href="#ray" transform="rotate(135 15 15)" />
        <use href="#ray" transform="rotate(180 15 15)" />
        <use href="#ray" transform="rotate(225 15 15)" />
        <use href="#ray" transform="rotate(270 15 15)" />
        <use href="#ray" transform="rotate(315 15 15)" />
      svg>
      <svg width="30" height="30" id="dark-icon">
        <path
          fill="currentColor"
          d="
          M 23, 5
          A 12 12 0 1 0 23, 25
          A 12 12 0 0 1 23, 5"
        />
      svg>
    button>
  body>
html>

You can also unset the default appearance of the button element in CSS, except the cursor property. You should have that as pointer:

. . .

button {
  all: unset;
  cursor: pointer;
}

. . .

Now, let's implement the event handler in JavaScript. First you need to access the SVG icons by ID:

const lightIcon = document.getElementById("light-icon");
const darkIcon = document.getElementById("dark-icon");

. . .

Then, add the dark-mode class to the body element in case you are in dark mode and hide one of the SVG icons based on the darkMode variable. You detect dark mode as you did before:

. . .

// Check if dark mode is preferred
const darkModeMediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
let darkMode = darkModeMediaQuery.matches;

// Set dark-mode class on body if darkMode is true and pick icon
if (darkMode) {
  document.body.classList.add("dark-mode");
  darkIcon.setAttribute("display", "none");
} else {
  lightIcon.setAttribute("display", "none");
}

. . .

And finally, can implement the function that flips the darkMode property. This function toggles the dark-mode class on the body element, and toggles the SVG icons:

. . .

// Toggle dark mode on button click
function toggleDarkMode() {
  // Toggle darkMode variable
  darkMode = !darkMode;

  // Toggle dark-mode class on body
  document.body.classList.toggle("dark-mode");

  // Toggle light and dark icons
  if (darkMode) {
    lightIcon.setAttribute("display", "block");
    darkIcon.setAttribute("display", "none");
  } else {
    lightIcon.setAttribute("display", "none");
    darkIcon.setAttribute("display", "block");
  }
}

Now, this works: by default, you still have the setting from the OS or browser. But once you click this button, it will override this manually.

Final look in light mode

Final look in dark mode

Next Steps

With all this in place, you have a functionality that takes the dark mode setting from the browser or the OS by default, and you can override it with a nice-looking toggle button. In the YouTube version of this tutorial, you can also learn how to use localStorage to save this setting for the next session.

If you want to learn more about SVGs, check out SVG-tutorial.com, where you can learn more about SVGs from beginner to advanced levels with many great examples.

If you want to use this behavior in a game, check out the Gorillas JavaScript game tutorial, where we build the entire game from scratch. It's a massive two-hour tutorial that covers drawing on a Canvas element with JavaScript and the whole game logic with plain JavaScript.

Subscribe to my channel for more JavaScript game development tutorials:

How to use the Fullscreen API in JavaScript

Hunor Márton Borbély — Thu, 22 Feb 2024 14:17:32 +0000

How do you run a game created for the web in fullscreen? In this quick tutorial, you'll see how to display a game or any other HTML element in fullscreen, how to exit fullscreen, and how to make a nice fullscreen toggle button in SVG.

Recently I published a long JavaScript game tutorial. While it was a very packed guide, there were still a few things we could not cover in it: how to display the game in fullscreen.

When you watch a video on YouTube, you have the option to also watch it on fullscreen. But did you know that the fullscreen feature isn't only for video elements?

In JavaScript, there’s a Fullscreen API. And it’s surprisingly simple to use. Here's a quick demo of what we're about to implement. Let's see how it works.

You can also watch this article as a video on YouTube.

How to Enter Fullscreen Mode

Let’s say we have a simple website with some text. And at the bottom, we have a button that will display the text in full screen. We are going to refine the look of this button, but first, let’s get work on the main logic.

A simple website with some text and a Toggle Fullscreen button

body {
  font-family: Montserrat;
  margin: 50px;
  max-width: 500px;
}

In the code above, we attached an event handler to the button in HTML. We can then implement the toggleFullscreen function logic in JavaScript.

In this function, all we have to do is call the requestFullScreen method on the document’s documentElement property. And that’s it:

function toggleFullscreen() {
  document.documentElement.requestFullscreen();
}

If you click the button, your website will pop into fullscreen.

How to Style the Fullscreen

Before we cover how to exit full screen and create a nice-looking toggle button, let’s see a few other things.

What you might notice right away is that, with more space, your content might get a bit lost on a full screen. Make sure you have a responsive styling that looks good on every screen size.

You can even style the layout specifically for fullscreen. In CSS you can set a media query that only applies the styling in case the display-mode is fullscreen.

For instance, you can change the font-size, or change the background-color to have a distinct look on full screen.

@media (display-mode: fullscreen) {
  body {
    background-color: #f9bb86;
    font-size: 1.2em;
  }
}

How to Display Games with the Canvas Element in Fullscreen

In this case, we want to make a game that uses the canvas element to be fullscreen – like the Gorillas game – we also need to resize the canvas element to fit the whole screen.

In this case, we can use the windows’s resize event. The event is triggered both when we simply resize the browser window, and when we enter or exit fullscreen mode.

With the resize event, we can resize the canvas element to fit the whole screen, update the scaling, adjust any other properties we need to change on resize and redraw the whole scene.

window.addEventListener("resize", () => {
  // Resize canvas element
  canvas.width = window.innerWidth;
  canvas.height = window.innerHeight;

  // Update scaling
  // . . .

  // Adjust size dependent properties
  // . . .

  // Redraw canvas
  draw();
});

If you check the source code of the Gorillas game on CodePen, you'll find similar steps.

How to Exit Fullscreen

Now that we know how to enter full screen, how do we exit from it?

By default, if you press the Escape key, the browser switches back to the normal view. In Google Chrome, you even get a notification at the top of the screen about this when you enter fullscreen mode.

Google Chrome shows a notification on top of the screen once you enter full screen

What if you want to exit fullscreen mode when you click the HTML button? Let’s change our button’s behavior to toggle fullscreen on or off.

function toggleFullscreen() {
  if (!document.fullscreenElement) {
    document.documentElement.requestFullscreen();
  } else {
    document.exitFullscreen();
  }
}

First, we start by checking if we are in fullscreen mode already. We can do this by checking the document’s fullscreenElement property. If it is undefined, then we enter fullscreen mode the same way we did before. And if we are already in fullscreen mode, then we can exit by calling the document’s exitFullscreen method.

It is really that simple. With a few lines of code, we can implement the logic for a fullscreen toggle button.

How to Code a Fullscreen Icon with SVG

If you follow my tutorials, you know I love creative coding, and drawing from code. So let’s update the look of our button, to make it look similar to what we have on YouTube.

Fullscreen icon

Let’s create an SVG image within our button. If you check the source code of YouTube, you will see that they also use an SVG.

Let’s define an SVG element within HTML. We'll set its size to 30 x 30 and define a path element:

. . .

<button onclick="toggleFullscreen()">
  <svg width="30" height="30">
    <path
      stroke="black"
      stroke-width="3"
      fill="none"
      d="
        M 10, 2 L 2,2 L 2, 10
        M 20, 2 L 28,2 L 28, 10
        M 28, 20 L 28,28 L 20, 28
        M 10, 28 L 2,28 L 2, 20"
    />
  svg>
button>

. . .

To style the path, we set its color with the stroke property, set its stroke-width, and made sure that we didn't end up with a filled shape. SVG paths by default are filled, so we need to set explicitly that we don’t want to fill this shape.

Using the move-to and line-to commands within an SVG path

Then we defined the path with a few move-to and line-to commands. We can set these commands as a string in the d attribute of the path element.

We started with a move-to command: M 10, 2. The letter M signifies that we have a move-to command, and the 10 and 2 are the x and y coordinates of this command. We moved to the start of one of the four lines.

Then we continued the path with a line-to command that moves to the corner, and then with another line-to command. The line-to command works in a similar way. It starts with the letter L, then we set an x, y coordinates where the line should go to.

Then we did the same with the other corners. We move to the next line segment with another move-to command and draw a line with two more line-to commands.

Drawing a path on a Canvas element with JavaScript has some similarities to defining a path in SVG

Note: If you read my previous tutorial on how to make the gorillas game, then you might have noticed that we had something similar there. We also drew paths with move to and line to. Except that there we were drawn on a canvas element with JavaScript, and now we have the commands as a string within the HTML file.

How to Toggle the Icon's Appearance

Now the SVG is looking great, but what if we want to have a different look when we are in fullscreen mode? On YouTube, when we enter fullscreen mode, the button switches to a different icon.

The two faces of the fullscreen icon

You can do this in different ways. The easiest way is probably to define another path, within the same SVG element with a different look. Then make this path transparent by default. We are going to toggle the visibility of these two paths in JavaScript.

. . .

<button onclick="toggleFullscreen()">
  <svg width="30" height="30">
    <path
      id="enter-fullscreen"
      stroke="black"
      stroke-width="3"
      fill="none"
      d="
        M 10, 2 L 2,2 L 2, 10
        M 20, 2 L 28,2 L 28, 10
        M 28, 20 L 28,28 L 20, 28
        M 10, 28 L 2,28 L 2, 20"
    />
    <path
      id="exit-fullscreen"
      stroke="transparent"
      stroke-width="3"
      fill="none"
      d="
        M 10, 2 L 10,10 L 2, 10
        M 20, 2 L 20,10 L 28, 10
        M 28, 20 L 20,20 L 20, 28
        M 10, 28 L 10,20 L 2, 20"
    />
  svg>
button>

. . .

This second path is very similar to the previous one. Except that we used different coordinates for some of the line-to commands.

Then we set unique IDs for both of these paths, and we update our toggle function in JavaScript. In JavaScript, we get a reference to these paths by ID, and then in the toggle button’s event handler, we can switch the visibility of these elements back and forth.

const enterFullscreen = document.getElementById("enter-fullscreen");
const exitFullscreen = document.getElementById("exit-fullscreen");

function toggleFullscreen() {
  if (!document.fullscreenElement) {
    document.documentElement.requestFullscreen();
    enterFullscreen.setAttribute("stroke", "transparent");
    exitFullscreen.setAttribute("stroke", "black");
  } else {
    document.exitFullscreen();
    enterFullscreen.setAttribute("stroke", "black");
    exitFullscreen.setAttribute("stroke", "transparent");
  }
}

Now if you click this button, it toggles the fullscreen mode and changes its own appearance.

Learn More

If you want to learn more about SVGs, check out SVG-Tutorial.com where you can find a lot of examples from the basics to more advanced levels. It’s a free site and you can also find the example that we discussed in this article.

To use the button to run a JavaScript game in full screen, check out the whole JavaScript Game Tutorial on how to remake the classic Gorillas game here on freeCodeCamp or on YouTube. It’s a massive tutorial that covers things from drawing on an HTML Canvas element, to the entire game logic, from event handling, through the animation loop, hit detection, and even AI logic, for the enemy gorilla.

You can subscribe to my channel for more JavaScript game development tutorials:

How to Draw with JavaScript on an HTML Canvas Element – Gorilla Example

Hunor Márton Borbély — Thu, 15 Feb 2024 16:30:12 +0000

Drawing from code can be fun for many reasons. You can generate art that follows a certain logic. You can create animations by moving only parts of an image. And you can even build up a whole game as I covered in this tutorial.

In my last article, we focused on the basics of drawing. Now, let's see a concrete example and explore how to use JavaScript to draw a Gorilla.

You don't need to have any prerequisites for this tutorial. Even if you missed the basics, you can start right away. We are only going to have some simple HTML and a plain JavaScript file that you can run directly in the browser.

By the end, you'll know how to draw a gorilla with JS.‌

How to Define a Canvas

To draw our gorilla, first let's define a simple HTML file with a Canvas element. Then we'll see how to access it from JavaScript.

In the HTML file, in the header, we'll add our JavaScript file. Note that I’m using the defer keyword to make sure the script only executes once the rest of the document is parsed.

In the body, we'll add a canvas element. We set its size to 500 x 500 and set an ID.

html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Gorillatitle>
    <script src="index.js" defer>script>
  head>
  <body>
    <canvas id="gorilla" width="500" height="500">canvas>
  body>
html>

Then, let's create a JavaScript file. In this file, we'll first get the canvas element by ID. Then, we'll get the rendering context of the canvas element. This is a built-in API with many methods and properties that we can use to draw on the canvas.

// The canvas element and its drawing context 
const canvas = document.getElementById("gorilla"); 
const ctx = canvas.getContext("2d");

. . .

Before we get to drawing, first let's make our life easier by turning the coordinate system upside down.

How to Turn the Coordinate System Upside Down

When we use canvas, we have a coordinate system with the origin at the top-left corner of the canvas that grows to the right and downwards. This is aligned with how websites work in general. Things go from left to right and top to bottom.

This is the default, but we can change it.

The gorilla with and without transforming and scaling the coordinate system

In our case, it is more convenient to go from the bottom to the top. Then the gorilla can stand at the bottom, and we don’t have to figure out where the bottom of the canvas is.

We can use the translate method to shift the entire coordinate system to the bottom-middle of the canvas. We'll move the coordinate system down along the Y-axis by the size of the canvas, and to the right along the X-axis by half the size of the canvas.

Once we do this, the Y-coordinate is still growing downwards. We can flip it using the scale method. Setting a negative number for the vertical direction will flip the entire coordinate system upside down.

// The canvas element and its drawing context 
const canvas = document.getElementById("gorilla"); 
const ctx = canvas.getContext("2d");

ctx.translate(250, 500);
ctx.scale(1, -1);

. . .

‌We have to do this before we paint anything on the canvas because the translate and scale methods do not actually move anything that's already on the canvas. But anything we paint after these method calls will be painted according to this new coordinate system.

How to Draw the Gorilla

Now let's look into drawing the gorilla. We'll break this down into multiple steps. First, we'll draw the body, then the legs, the arms, and finally the face of the gorilla.

We'll draw the gorilla in multiple steps

How to draw the body of the gorilla

We'll draw the body of the gorilla as a path. Paths start with the beginPath method and end with either calling the fill or the stroke method – or both.

In between, we'll build the path by calling path-building methods. In this case, to build up the body of the gorilla we'll use the moveTo and a bunch of lineTo methods.

The body of the gorilla. The image shows the path we're filling.

We'll set the fill style to black, and then we'll begin a path. Move to a starting position and then draw straight lines to draw the silhouette of the gorilla. Once we're finished, we'll fill the shape with the fill method.

. . .

ctx.fillStyle = "black";

// Draw the Body of the Gorilla
ctx.beginPath();
ctx.moveTo(-68, 72);
ctx.lineTo(-80, 176);

ctx.lineTo(-44, 308);
ctx.lineTo(0, 336);
ctx.lineTo(+44, 308);

ctx.lineTo(+80, 176);
ctx.lineTo(+68, 72);
ctx.fill();

. . .

In case you are wondering how I came up with these coordinates, I actually started with an initial sketch with pen and paper. I tried to estimate the coordinates, tried them with code, and then adjusted them until they started getting the right shape. Of course, you might have other methods as well.

How to draw the legs of the gorilla

We'll draw the legs the same way. We could even continue the same path we used before, but it might be easier to see what's happening if we break this down into separate paths.

Drawing the legs as two separate paths

. . .

// Draw the Left Leg
ctx.beginPath();
ctx.moveTo(0, 72);
ctx.lineTo(-28, 0);
ctx.lineTo(-80, 0);
ctx.lineTo(-68, 72);
ctx.fill();

// Draw the Right Leg
ctx.beginPath();
ctx.moveTo(0, 72);
ctx.lineTo(+28, 0);
ctx.lineTo(+80, 0);
ctx.lineTo(+68, 72);
ctx.fill();

. . .

The fill color in this case is also going to be black. Why? Because that's what we set the fillStyle property to, the last time we set its value. Every path that follows this statement will use this color until we change its value.

How to draw the arms of the gorilla

While the body and the legs are relatively simple parts of the gorilla, the arms are a bit more complicated. We'll draw them as a curve.

Drawing the arms as a curve

Let’s start with the left arm. The main part of this is actually only two lines of code. We'll use the moveTo method to move to the shoulder of the gorilla, then from there, we'll draw the arm as a quadratic curve with the quadraticCurveTo method.

A quadratic curve is a simple curve with one control point. As the curve goes from the starting point (which we'll set with moveTo), the curve bends towards this control point (set as the first two arguments of the quadraticCurveTo method) as it reaches its end position (set as the last two arguments).

. . .

ctx.strokeStyle = "black";
ctx.lineWidth = 70;

// Draw the Left Arm
ctx.beginPath();
ctx.moveTo(-56, 200);
ctx.quadraticCurveTo(-176, 180, -112, 48);
ctx.stroke();

// Draw the Right Arm
ctx.beginPath();
ctx.moveTo(+56, 200);
ctx.quadraticCurveTo(+176, 180, +112, 48);
ctx.stroke();

. . .

We'll draw the hands as strokes. Instead of ending the path with the fill method, we'll use the stroke method.

We'll also set up the styling differently. Instead of using the fillStyle property, here we'll set the color with strokeStyle and give thickness to the arms with the lineWidth property.

Drawing the right arm is the same, except the horizontal coordinates are flipped. The negative numbers have a positive sign now.

As a result, our gorillas should start to gain shape. They still don’t have a face, but we have the whole silhouette now.

How to draw the face of the gorilla

The face of the gorilla comes together from multiple different parts. First, we'll draw the facial mask with three circles.

We draw the facial mask as three circles

Unfortunately, we don’t have a simple fill circle method, as we have in the case of rectangles. We have to draw an arc instead.

An arc method can be called as part of a path. We'll start each circle with the beginPath method and end with the fill method.

. . .

ctx.fillStyle = "lightgray";

// Draw the Facial Mask
ctx.beginPath();
ctx.arc(0, 252, 36, 0, 2 * Math.PI);
ctx.fill();

ctx.beginPath();
ctx.arc(-14, 280, 16, 0, 2 * Math.PI);
ctx.fill();

ctx.beginPath();
ctx.arc(+14, 280, 16, 0, 2 * Math.PI);
ctx.fill();

. . .

The arc method has a lot of properties. This might look a bit scary, but we only need to focus on the first 3 when drawing circles:

The first two arguments are x and y, the center coordinates of the arc.
The third argument is the radius.
Then the last two arguments are the startAngle and the endAngle of the arc in radians. Because here we want to have a full circle and not an arc, we'll start with 0 and end at a full circle. A full circle in radians is two times Pi.

If these last two properties are confusing, don't worry about it. What's important is that when we draw circles, they are always 0 and 2 * Math.Pi.

We draw the eyes, the nostrils, and the mouth

Then we draw the eyes of the gorilla as two other circles. Here the center coordinates of the circles are the same as the bigger gray circles around them. Only their radius and their fill color are different.

. . .

ctx.fillStyle = "black";

// Draw the Left Eye
ctx.beginPath();
ctx.arc(-14, 280, 6, 0, 2 * Math.PI);
ctx.fill();

// Draw the Right Eye
ctx.beginPath();
ctx.arc(+14, 280, 6, 0, 2 * Math.PI);
ctx.fill();

. . .

Then for the nose, we'll draw two short lines as nostrils. They are part of the same path, and we'll call the moveTo method in between to get from one side to the other. Before calling stroke at the end of this path, we'll update the lineWidth property.

. . .

ctx.lineWidth = 6;

// Draw the Nostrils
ctx.beginPath();
ctx.moveTo(-14, 266);
ctx.lineTo(-6, 260);

ctx.moveTo(14, 266);
ctx.lineTo(+6, 260);
ctx.stroke();

. . .

And finally, we'll also add a path for the mouth. This could be part of the same path as the nose, because it has the same line width and color, but might be clearer to have them separate.

. . .

// Draw the Mouth
ctx.beginPath();
ctx.moveTo(-20, 230);
ctx.quadraticCurveTo(0, 245, 20, 230);
ctx.stroke();

Let's draw another quadratic curve. This is similar to the one we used for the arms. The start and endpoint of this curve are on the same level, but the control point is a bit higher so the middle of the mouth is higher than the two sides.

Next Steps

Now that we have a basic gorilla, what can we do with it? We can build a whole game around it. In this JavaScript Game Tutorial we rebuild the 1991 classic game, Gorillas.

Screenshot from the JavaScript Game Tutorial

For a deep dive, read the full tutorial where we build up a complete game with plain JavaScript. In this tutorial, we not only cover how to draw the gorillas and the city skyline but also implement the whole game logic. From event handling, through the animation loop, to hit detection.

For even more, you can also watch the extended tutorial on YouTube. In the YouTube version, we also cover how to make the buildings destructible, how to animate the hand of the gorilla to follow the drag movement while aiming, have nicer graphics, and we add AI logic, so you can play against the computer.

Check it out to learn more:

Embedded content

You can subscribe to my channel for more JavaScript game development tutorials:

How to Draw with JavaScript on an HTML Canvas Element – Beginner's Guide

Hunor Márton Borbély — Thu, 08 Feb 2024 00:08:11 +0000

There are many ways to code graphics for the web. You can create art with CSS. You can code an SVG image as part of an HTML file. Or you can generate graphics from JavaScript using the Canvas API.

In this article, we'll explore how to use JavaScript to draw some basic shapes. You don't need to have any prerequisites for this tutorial. We are only going to have a simple HTML and a plain JavaScript file that you can run directly in the browser.

You might be wondering – would anyone code an image from JavaScript? For one, you can generate graphics dynamically based on some variables. For instance, you can create a diagram. Or even better, we can create an entire game with JavaScript as we cover it in this tutorial.

https://www.freecodecamp.org/news/gorillas-game-in-javascript/

The following article focuses on part of the tutorial above, and teaches you the basics of drawing with JS.

The Canvas Element

To draw on the screen, first we need to define a canvas element in HTML.

html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Canvastitle>
    <script src="index.js" defer>script>
  head>

  <body>
    <canvas id="myCanvas" width="1000" height="1000">canvas>
  body>
html>

This element has an ID, so that we can access it in JavaScript. Here we also set its size. If the size is dynamic, we can also set this size in JavaScript as we do in the tutorial above.

We defined a element in HTML. How do we paint things on it?

Let's create a separate JavaScript file, where we'll add the rest of the code. We'll load this file with the script element above. Then in index.js, first, we'll get the canvas element by ID and get its rendering context.

const canvas = document.getElementById("myCanvas"); 
const ctx = canvas.getContext("2d"); 

. . .

This is a built-in API with many methods and properties that we can use to draw on the canvas. In the next few sections, we'll continue with this file and see a few examples of how to use this API.

How to Draw a Rectangle

Let’s look at a few quick examples. The most basic thing we can do is to fill a rectangle.

Using the fillRect` method to fill a rectangle

const canvas = document.getElementById("myCanvas");
const ctx = canvas.getContext("2d");

ctx.fillStyle = "#58A8D8";

ctx.fillRect(200, 200, 440, 320);

With the fillRect method, we specify the top left coordinate of our rectangle (200, 200), and we set its width and height (440, 320).

By default, the fill color is going to be black. We can change it by setting the fillStyle property.

The way canvas works is that we have to set up drawing parameters before we paint, and not the other way around. It’s not like we paint a rectangle, and then we can change its color. Once something is on the canvas, it stays as it is.

You can think of it like a real canvas, where you also pick the color with your brush before you start painting with it. Then once you've painted something you can either cover it, by painting something over it, or you can try to clear the canvas. But you can’t change existing parts, really. That’s why we set the color here up front and not afterward.

How to Fill a Path

We can of course draw more complicated shapes as well. We can define a path, like this:

Filling a path

const canvas = document.getElementById("myCanvas");
const ctx = canvas.getContext("2d");

ctx.fillStyle = "#58A8D8";

ctx.beginPath();
ctx.moveTo(200, 200);
ctx.lineTo(500, 350);
ctx.lineTo(200, 500);
ctx.fill();

Paths start with the beginPath method and end with either calling the fill or the stroke method – or both. In between, we build the path by calling path-building methods.

In this example, we draw a triangle. We move to the 200,200 coordinate with the moveTo method. Then we call the lineTo method to move to the right side of our shape. And then we continue the path, by calling the lineTo method again to 200,500.

None of this would be visible if we didn’t end with the fill method to fill the path we just built.

How to Draw a Stroke

In a very similar way, we can also draw a line. Here, we'll start with the beginPath method again. We'll also build up the shape with a moveTo and two lineTo methods. The coordinates here are the same. But in the end, we don’t call the fill but the stroke method. This, instead of filling the shape, will draw the line we built.

Drawing a stroke

const canvas = document.getElementById("myCanvas");
const ctx = canvas.getContext("2d");

ctx.strokeStyle = "#58A8D8";
ctx.lineWidth = 30;

ctx.beginPath();
ctx.moveTo(200, 200);
ctx.lineTo(500, 350);
ctx.lineTo(200, 500);
ctx.stroke();

Strokes have different styling properties. Instead of the fillStyle property, we set strokeStyle. To this property – and also to fillStyle – we can assign any color value that is valid in CSS. To set the line width we use the lineWidth property.

We can also build more complex paths. In the example below, we draw a curve.

Drawing a curve

const canvas = document.getElementById("myCanvas");
const ctx = canvas.getContext("2d");

ctx.strokeStyle = "#58A8D8";
ctx.lineWidth = 30;

ctx.beginPath();
ctx.moveTo(200, 300);
ctx.quadraticCurveTo(500, 400, 800, 300);
ctx.stroke();

A quadratic curve is a simple curve with one control point. As the curve goes from the starting point (which we set with moveTo), the curve bends towards this control point (set as the first two arguments of the quadraticCurveTo method) as it reaches its end position (set as the last two arguments).

Next Steps

With these very basic shapes, we can already get quite far. We use these methods to draw the gorillas in the Gorillas - JavaScript Game Tutorial.

We fill a path to draw the body and the legs of the gorillas, and use strokes to draw the arms and the face

Check it out to learn more:

Embedded content

You can subscribe to my channel for more JavaScript game development tutorials:

JavaScript Game Dev Tutorial – Build Gorillas with HTML Canvas + JavaScript

Hunor Márton Borbély — Tue, 30 Jan 2024 18:18:55 +0000

In this JavaScript game tutorial, you'll learn how to create a modern version of the 1991 classic game Gorillas using plain JavaScript and the HTML canvas element.

In this game, two gorillas throw explosive bananas at each other, and the first one to hit the other one wins the game.

We'll build out the whole game from scratch here. First, you'll learn how to draw on a canvas element with JavaScript. You'll see how to draw the background, the buildings, the gorillas, and the bomb. We won't use any images here – we'll draw everything using code.

Then we'll add some interactions and add event handlers. We'll also cover how to aim, how to animate the bomb across the sky, and how to detect if the bomb hit the other gorilla, or a building.

Throughout the tutorial, we'll be using plain JavaScript. To get the most out of this tutorial, you should have a basic understanding of JavaScript. But even if you are a beginner, you can still follow along and learn as you go.

In this article, we'll simplify a couple of steps. For more detail, you can also watch the extended tutorial on YouTube. In the YouTube version, we also cover how to make the buildings destructible, how to animate the hand of the gorilla to follow the drag movement while aiming, have nicer graphics, and we add AI logic, so you can play against the computer.

If you got stuck, you can also find the final source code of the game we are about to create on GitHub.

Background on the Game

Gorillas is a game from 1991. In this game, two gorillas are standing on the top of randomly generated buildings and take turns throwing explosive bananas at each other.

In each round, the players set the angle and velocity of the throw, and keep refining it, until they hit the other gorilla. The flying banana bomb is affected by gravity and the wind.

The original Gorillas game from 1991 (source: retrogames.cz)

We are going to implement a modern version of this game. The original game did not support a mouse. Every round, the players had to type in the angle and the velocity with a keyboard. We are going to implement it with mouse support, and nicer graphics.

You can try out the extended version of the game on CodePen. Give it a try before we get into it.

Project Setup

To implement this game, we are going to have a simple HTML, CSS, and JavaScript file. You can break down the JavaScript logic into multiple files if you want, but for the sake of simplicity, we have everything in one place.

Because we're using plain JavaScript and don’t use any libraries and third-party tools, we don’t need any compilers or builders. We can run things directly in the browser.

To simplify the process, I recommend installing the Live Server VS Code extension. With this extension installed, you can simply right-click the HTML file and select ‘Open with Live Server’. This will run a live version of the game in the browser.

This means we don’t have to hit refresh in the browser every time we make a change in the code. It’s enough that we save the changes in the file and the browser will refresh automatically.

Running the game with the Live Server VS Code extension

Overview of the Game Logic

Before we get to the details, let's walk through the main parts of the game.

The game is driven by the game state. This is a JavaScript object that serves as metadata for the game. From the size of buildings to the current position of the bomb, it includes many things.

The game state includes things like whose turn it is, are we aiming now, or is the bomb already flying in the air? And so on. These are all variables that we need to keep track of. When we draw the game scene, we'll draw it based on the game state.

Then we have the draw function. This function will draw almost everything we have on the screen. It paints the background, the buildings, the gorillas, and the banana bombs. This function paints the entire screen from top to bottom every time we call it.

We are going to add event handling to aim the bombs and we'll implement the throwBomb function that kicks off the animation loop. The animate function moves the bombs across the sky.

This function will be responsible for calculating the exact position of the bomb as it flies through the air at every animation cycle. On top of that, it also has to figure out when the movement ends. With every movement, we check if we hit a building or an enemy, or if the bomb got off-screen. We’ll add hit detection as well.

Now let's walk through our initial files.

The initial HTML file

Our initial HTML file will be very simple. In the header, we'll add a link to our stylesheet and our JavaScript file. Note that I’m using the defer keyword to make sure the script only executes once the rest of the document is parsed.

In the body, we'll add a canvas element. We are going to paint on this element with JavaScript. Almost everything we can see on the screen will be in this canvas element. Here's the code:

html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Gorillastitle>
    <link rel="stylesheet" href="index.css" />
    <script src="index.js" defer>script>
  head>
  <body>
    <canvas id="game">canvas>
  body>
html>

Later we are going to add more things into this file. We'll add info panels to show the angle and velocity of the current throw. But for now, that’s all we have.

The initial CSS file

Initially, our CSS is also very simple. We can’t style anything inside the canvas element, so here we only style the other elements we have.

body {
  margin: 0;
  padding: 0;
}

‌Later, when we add more elements in HTML, we will also update this file. For now, let’s make sure that our canvas can fit the whole screen. By default, browsers tend to add a little margin or padding around the body. Let’s remove that.

The Main Parts of Our JavaScript File

Most of the logic will be in our JavaScript file. Let's walk through the main parts of this file, and define a few placeholder functions:

We declare the game state object and a bunch of utility variables. This will contain the metadata of our game. For now, it's an empty object. We will initialize its value when we get to the newGame function.
Then we have references to every HTML element that we need to access from JavaScript. For now, we only have a reference to the element. We access this element by ID.
We initialize the game state and paint the scene by calling the newGame function. This is the only top-level function call. This function is responsible for both initializing the game and resetting it.
We define the draw function that draws the whole scene on the canvas element based on the game state. We will draw the background, the buildings, the gorillas, and the bomb.
We set up event handlers for the mousedown, mousemove, and mouseup events. We are going to use these for aiming.
The mouseup event will trigger the throwBomb function that kicks off the main animation loop. The animate function will manipulate the state in every animation cycle and call the draw function to update the screen.

// The state of the game
let state = {};
// ...

// References to HTML elements
const canvas = document.getElementById("game");
// ...

newGame();

function newGame() {
  // Initialize game state
  state = {
    // ...
  };

  // ...

  draw();
}

function draw() {
  // ...
}

// Event handlers
// ...

function throwBomb() {
  // ...
}

function animate(timestamp) {
  // ...
}

‌We will have a couple more utility functions, but they are less important. We'll discuss them as we go.

Game Phases

In the next step, we'll set up our initial game state. Before we get to the different parts of the state, let's talk about one of its most important properties: the game phase property.

The three game phases: the aiming phase, the in flight phase, and the celebrating phase

The game has three different phases. The game starts in the aiming phase, when the bomb is in the hand of a gorilla and the event handlers are active. ‌‌‌‌Then once you throw the bomb, the game moves on to the in flight phase. In this phase, the event handlers are deactivated and the animate function moves the bomb across the sky. We also add hit detection to know when should we stop the animation.

These two game phases repeat each other over and over again, until one of the gorillas hits the other. Once we hit the enemy, the game moves on to the celebrating phase. We draw a winning gorilla, show the congratulations screen, and a button to restart the game.

How to initialize the Game

The game is initialized by the newGame function. This resets the game state, generates a new level, and calls the draw function to draw the whole scene.

Let’s walk through what we have initially in the state object:

First, we have the game phase property that can be either aiming, in flight, or celebrating.
Then, the currentPlayer property tells us whose turn it is – the player on the left or the player on the right.
The bomb object describes the bomb’s current position and its velocity. Its initial position has to be aligned with the second building so we only set it once the level is generated.
The buildings array defines the position and size of the buildings that appear on the screen. We generate the metadata of the buildings with a utility function that we'll discuss later.

// The state of the game
let state = {};

. . .

newGame();

function newGame() {
  // Initialize game state
  state = {
    phase: "aiming", // aiming | in flight | celebrating
    currentPlayer: 1,
    bomb: {
      x: undefined,
      y: undefined,
      velocity: { x: 0, y: 0 },
    },
    buildings: generateBuildings(),
  };

  initializeBombPosition();

  draw();
}

‌We'll discuss the utility functions used above (generateBuildings and initializeBombPosition) in the next chapter as we draw the buildings and the bomb. For now, let's just add some placeholder functions to make sure we don't get an error from JavaScript.

function generateBuildings() {
  // ...
}

function initializeBombPosition() {
  // ...
}

Now that we have a skeleton of our application and we've initialized some of the states, let’s switch gears and start drawing on the canvas as we fill in the missing pieces of the state.

How to Draw the Scene

The draw function paints the whole canvas based on the state. It draws the background and the buildings, draws the gorillas, and draws the bomb. The function can also draw different gorilla variations depending on the state. The gorilla looks different while aiming, celebrating, or waiting for impact.

We will use this function both for painting the initial scene and throughout our main animation loop.

For the initial paint, some of the features we cover here won't be necessary. For instance, we'll also cover how to draw the celebrating gorilla, while we'll only see that once the game is over. But we'll still cover it because this way we won’t have to get back to this function once we start animating the state.

Everything we draw in this function is based on the state, and it doesn't matter to the function if the game is in the initial state, or if we are further into the game.

We defined a element in HTML. How do we paint things on it?

. . .

<body>
  <canvas id="game">canvas>
body>

. . .

In JavaScript first, we get the canvas element by ID. Then we set the size of the canvas to fill the whole browser window. And finally, we get its drawing context.

This is a built-in API with many methods and properties that we can use to draw on the canvas. Let's see a few examples of how to use this API.

. . . 

// The canvas element and its drawing context 
const canvas = document.getElementById("game"); 
canvas.width = window.innerWidth; 
canvas.height = window.innerHeight; 
const ctx = canvas.getContext("2d"); 

. . . 

function draw() {
  // ... 
} 

. . .

Example: Drawing a Rectangle

Let’s look at a few quick examples. These are not part of our game yet, they'll just serve as an introduction.

The most basic thing we can do is to fill a rectangle.

Using the fillRect method to fill a rectangle

const canvas = document.getElementById("game");
canvas.width = window.innerWidth;
canvas.height = window.innerHeight;
const ctx = canvas.getContext("2d");

ctx.fillStyle = "#58A8D8";

ctx.fillRect(200, 200, 440, 320);

With the fillRect method, we specify the top left coordinate of our rectangle (200, 200), and we set its width and height (440, 320).

By default, the fill color is going to be black. We can change it by setting the fillStyle property.

We are going to draw rectangles to fill the background and to show the buildings.

The background and the buildings are simple rectangles

Example: Filling a Path

We can of course draw more complicated shapes as well. We can define a path, like this:

Filling a path

const canvas = document.getElementById("game");
canvas.width = window.innerWidth;
canvas.height = window.innerHeight;
const ctx = canvas.getContext("2d");

ctx.fillStyle = "#58A8D8";

ctx.beginPath();
ctx.moveTo(200, 200);
ctx.lineTo(500, 350);
ctx.lineTo(200, 500);
ctx.fill();

Paths start with the beginPath method and end with either calling the fill or the stroke method – or both. In between, we build the path by calling path-building methods.

In this example, we draw a triangle. We move to the 300,300 coordinate with the moveTo method. Then we call the lineTo method to move to the right side of our shape. And then we continue the path, by calling the lineTo method again to 300,400.

None of this would be visible if we didn’t end with the fill method to fill the path we just built.

We are going to fill paths to draw our gorilla and our bomb.

We will use paths to draw the main body of the gorilla

‌Example: Drawing a Stroke

Drawing a stroke

const canvas = document.getElementById("game");
canvas.width = window.innerWidth;
canvas.height = window.innerHeight;
const ctx = canvas.getContext("2d");

ctx.strokeStyle = "#58A8D8";
ctx.lineWidth = 30;

ctx.beginPath();
ctx.moveTo(200, 200);
ctx.lineTo(500, 350);
ctx.lineTo(200, 500);
ctx.stroke();

We can also build more complex paths. In the example below, we draw a curve. We are going to cover this in a bit more detail when we draw the arms of the gorillas.

Drawing a curve

const canvas = document.getElementById("game");
canvas.width = window.innerWidth;
canvas.height = window.innerHeight;
const ctx = canvas.getContext("2d");

ctx.strokeStyle = "#58A8D8";
ctx.lineWidth = 30;

ctx.beginPath();
ctx.moveTo(200, 300);
ctx.quadraticCurveTo(500, 400, 800, 300);
ctx.stroke();

We are going to use the stroke method to draw the arms and the face of the gorilla.

We use the stroke method to draw the arms and the face of the gorilla

‌Now that we're finished with this introduction, let’s go back to our game and see what’s inside the draw function.

How to Turn the Coordinate System Upside Down

When we use canvas, we have a coordinate system with the origin at the top-left corner of the browser window that grows to the right and downwards. This is aligned with how websites work in general. Things go from left to right and top to bottom. This is the default, but we can change this.

The default coordinate system

When we talk about games, it is more convenient to go from the bottom to the top. For instance, when we draw buildings, they can start at the bottom, and we don’t have to figure out where the bottom of the window is.

We can use the translate method to shift the entire coordinate system to the bottom-left corner. We just need to move the coordinate system down along the Y-axis by the size of the browser window.

The coordinate system upside down

// The canvas element and its drawing context 
const canvas = document.getElementById("game"); 
canvas.width = window.innerWidth; 
canvas.height = window.innerHeight; 
const ctx = canvas.getContext("2d"); 

. . . 

function draw() { 
  ctx.save(); 
  // Flip coordinate system upside down 
  ctx.translate(0, window.innerHeight); 
  ctx.scale(1, -1); 

  // Draw scene 
  drawBackground(); 
  drawBuildings();
  drawGorilla(1);
  drawGorilla(2);
  drawBomb(); 

  // Restore transformation 
  ctx.restore(); 
}

‌Now let's implement the draw function. One of the first things we do is calling the translate and the scale methods to flip the coordinate system upside down.

We have to do this before we paint anything on the canvas because the translate and scale methods do not actually move anything on the canvas. If we painted anything on the canvas before, it would stay as it was.

Technically these methods change the transformation matrix. You can think of it as changing the coordinate system. Anything we paint after these methods will be painted according to this new coordinate system.

We also need to restore these transformations once we draw by calling the restore method. The restore method comes in a pair with the save method. save serves as a checkpoint that the restore method can get back to.

It's a common practice to start a drawing block by calling the save method and ending it with the restore method when we use transformations in between.

We need to call these two functions because the translate and scale methods accumulate. We are going to call the draw function multiple times. Without the save and restore methods, the coordinate system would keep on moving downwards each time we call the draw function, and it would eventually get completely off-screen.

Drawing the entire scene includes many parts. We'll break it down into separate draw functions. Now let’s start drawing by implementing these functions:

function drawBackground() {
  // ...
}

function drawBuildings() {
  // ...
}

function drawGorilla(player) {
  // ...
}

function drawBomb() {
  // ...
}

How to Draw the Game Elements

How to draw the background

When we draw on a canvas, the order matters. We'll start with the background, then we'll go layer by layer. In our case, the background is a simple rectangle.

The background sky

function drawBackground() {
  ctx.fillStyle = "#58A8D8";
  ctx.fillRect(0, 0, window.innerWidth, window.innerHeight);
}

We draw this rectangle the same way we did it in our introduction. First, we set the fill style, then we draw a rectangle with the fillRect method. Here we set the starting coordinates in the corner and set the size to fill the whole browser window.

We could also add a moon to the sky. Unfortunately, there's no fill circle method that would easily do this, so we'll skip it for now. On CodePen you can find a version that also draws a moon in the drawBackground function.

How to draw the buildings

Drawing the buildings has two parts. First, we need to generate metadata for the buildings when we initialize the level. Then we implement the drawBuildings function that paints the buildings based on this metadata.

The buildings and their metadata

Buildings Metadata

In the newGame function, we called the generateBuildings function to initialize the buildings property in our game state. We haven't implemented this function yet.

  . . .

  state = {
    phase: "aiming", // aiming | in flight | celebrating
    currentPlayer: 1,
    bomb: {
      x: undefined,
      y: undefined,
      velocity: { x: 0, y: 0 },
    },
    buildings: generateBuildings(),
  };

  . . .

‌Let's see how this function works. Each building is defined by its x position, its width, and its height.

The x coordinate is always aligned to the previous building. We check where the previous building ends, and we add a little gap. In case there is no previous building – because we're adding the first one – then we start at the beginning of the screen at 0.

function generateBuildings() {
  const buildings = [];
  for (let index = 0; index < 8; index++) {
    const previousBuilding = buildings[index - 1];

    const x = previousBuilding
      ? previousBuilding.x + previousBuilding.width + 4
      : 0;

    const minWidth = 80;
    const maxWidth = 130;
    const width = minWidth + Math.random() * (maxWidth - minWidth);

    const platformWithGorilla = index === 1 || index === 6;

    const minHeight = 40;
    const maxHeight = 300;
    const minHeightGorilla = 30;
    const maxHeightGorilla = 150;

    const height = platformWithGorilla
      ? minHeightGorilla + Math.random() * (maxHeightGorilla - minHeightGorilla)
      : minHeight + Math.random() * (maxHeight - minHeight);

    buildings.push({ x, width, height });
  }
  return buildings;
}

Then the function generates a random building width within a predefined range. We set the minimum and maximum width, and pick a random number in between.

We generate a random building height in a similar way with one difference: the height of a building also depends on whether a gorilla is standing on top of it or not.

If a gorilla is standing on top of the building, then the height range is smaller. We want to have relatively higher buildings in between the two gorillas so that they can’t just see each other in a straight line.

We'll know if a gorilla is standing on the building because they always stand on top of the same buildings. The second one from the left, and the second to last. If the building index matches these positions, we set the height based on a different range.

Then we push these three values as an object into the buildings array, and at the final line we return this array from the function. This will set be buildings array in our game state.

How to draw the the buildings

Now that we have the metadata for the buildings, we can draw them on the screen.

The drawBuildings function is a very simple one. We iterate over the array we just generated and draw a simple rectangle for each. We use the same fillRect method we used to draw the sky. We call this function with the attributes of the building (the Y position is 0 because the building starts at the bottom of the screen).

function drawBuildings() {
  state.buildings.forEach((building) => {
    ctx.fillStyle = "#152A47";
    ctx.fillRect(building.x, 0, building.width, building.height);
  });
}

Once we are done with this, we should see a line of buildings. The metadata is regenerated every time we start the game. Every time we refresh the browser window, we see a different background.

Randomly generated buildings

‌How to draw the gorillas

Drawing the gorillas is one of the most complicated and most fun parts of this game. Finally, we are not just drawing rectangles – we're drawing paths.

The different variations of the gorillas

Gorillas also have different variations depending on the game state. The gorilla looks different while aiming, waiting for the incoming bomb, and celebrating after a successful hit.

In the draw function, we call the drawGorilla function twice. We draw two gorillas: one on the second rooftop and one on the second to last rooftop. They are mostly identical, but they mirror each other while aiming. When the left one is aiming, it raises its left hand, and when the right one is aiming, it raises its right hand.

function draw() {
  ctx.save();
  // Flip coordinate system upside down
  ctx.translate(0, window.innerHeight);
  ctx.scale(1, -1);

  // Draw scene
  drawBackground();
  drawBuildings();
  drawGorilla(1);
  drawGorilla(2);
  drawBomb();

  // Restore transformation
  ctx.restore();
}

‌We'll break down drawing the gorilla into multiple steps as well. We'll use different functions to draw the main body, to draw the arms, and to draw the face of the gorilla.

To make things easier, we'll translate our coordinate system again. We translate the coordinate system to the middle of the rooftop the gorilla stands on. This way we can draw both gorillas the same way. We only need to translate the origin of our coordinate system to a different building.

Moving the origin of the coordinate system to the top of the building the gorilla stands on

‌As an argument, the drawGorilla function receives which player are we currently drawing. To draw the gorilla one on the left, we translate to the top of the second building, and to draw the one on the right we translate to the top of the second to last building.

function drawGorilla(player) {
  ctx.save();
  const building =
    player === 1
      ? state.buildings.at(1) // Second building
      : state.buildings.at(-2); // Second last building

  ctx.translate(building.x + building.width / 2, building.height);

  drawGorillaBody();
  drawGorillaLeftArm(player);
  drawGorillaRightArm(player);
  drawGorillaFace();

  ctx.restore();
}

‌Because we're using the translate method, this function starts with saving the current coordinate system and ends with restoring it.

Now let's look into the functions that draw the different parts of a gorilla.

function drawGorillaBody() {
  // ...
}

function drawGorillaLeftArm(player) {
  // ...
}

function drawGorillaRightArm(player) {
  // ...
}

function drawGorillaFace() {
  // ...
}

How to draw the body of the gorilla

We draw the body of the gorilla as a path. We drew a path in our introduction to drawing on a canvas. We use the moveTo and a bunch of lineTo methods to draw the main part of the gorilla.

We set the fill style to black, and then we begin a path. We move to a coordinate in the middle and then we draw straight lines to draw the silhouette of the gorilla. Once we're finished, we fill the shape with the fill method.

The body, the head, and the legs of the gorilla. The image on the right shows the path we're filling.

function drawGorillaBody() {
  ctx.fillStyle = "black";

  ctx.beginPath(); 

  // Starting Position
  ctx.moveTo(0, 15); 

  // Left Leg
  ctx.lineTo(-7, 0);
  ctx.lineTo(-20, 0); 

  // Main Body
  ctx.lineTo(-13, 77);
  ctx.lineTo(0, 84);
  ctx.lineTo(13, 77); 

  // Right Leg
  ctx.lineTo(20, 0);
  ctx.lineTo(7, 0);

  ctx.fill();
}

How to draw the arms of the gorilla

While the body was a relatively simple part of the gorilla, the hands are a bit more complicated. They come in different variations and we draw them as a curve.

Let’s start with the left arm. The main part of this is actually only two lines. We'll use the moveTo method to move to the shoulder of the gorilla, then from there, we'll draw the arm as a quadratic curve with the quadraticCurveTo method.

The different coordaintes of a curve

function drawGorillaLeftArm(player) {
  ctx.strokeStyle = "black";
  ctx.lineWidth = 18;

  ctx.beginPath();
  ctx.moveTo(-13, 50);

  if (
    (state.phase === "aiming" && state.currentPlayer === 1 && player === 1) ||
    (state.phase === "celebrating" && state.currentPlayer === player)
  ) {
    ctx.quadraticCurveTo(-44, 63, -28, 107);
  } else {
    ctx.quadraticCurveTo(-44, 45, -28, 12);
  }

  ctx.stroke();
}

What makes this function complicated is that it has two variations of the same curve. By default, the hands go down next to the body (second case above).

If we are in the aiming phase, the currentPlayer is player number 1, and we are drawing player 1, then the left hand goes up (first case above). The left hand also goes up in case the we draw the celebrating gorilla (also first case above).

In these cases, we start the from the same point (the curve starts with the same moveTo method), but we set different coordinates for the control point and end point of the curve.

We draw the hands as strokes. So instead of ending the path with the fill method, we use the stroke method instead.

We also set it up differently. Instead of using the fillStyle property, here we set the color with strokeStyle and give thickness to the arm with the lineWidth property.

The different arm variations of the gorillas in aiming, in flight, and celebrating phase

Drawing the right arm is the same, except the horizontal coordinates and some conditions are flipped. We could merge these two functions, but for clarity, I kept them separate.

function drawGorillaRightArm(player) {
  ctx.strokeStyle = "black";
  ctx.lineWidth = 18;

  ctx.beginPath();
  ctx.moveTo(+13, 50);

  if (
    (state.phase === "aiming" && state.currentPlayer === 2 && player === 2) ||
    (state.phase === "celebrating" && state.currentPlayer === player)
  ) {
    ctx.quadraticCurveTo(+44, 63, +28, 107);
  } else {
    ctx.quadraticCurveTo(+44, 45, +28, 12);
  }

  ctx.stroke();
}

As a result, our gorillas should start to gain shape. They still don’t have a face, but they have hands now. And to reflect our game state, the one on the left has his hands up, preparing to throw the bomb.

You can test our solution by changing the game state. You can change the currentPlayer and the game phase properties to see the different variations.

How to draw the face of the gorilla

The face of the gorilla comes together from a few straight lines. We'll draw the two eyes and the mouth as a straight line. For each, we'll use pair of moveTo and a lineTo method. Because each line segment uses the same strokeStyle and lineWidth, we can draw them as one single path.

The finished gorillas

function drawGorillaFace() {
  ctx.strokeStyle = "lightgray";
  ctx.lineWidth = 3;

  ctx.beginPath();

  // Left Eye
  ctx.moveTo(-5, 70);
  ctx.lineTo(-2, 70);

  // Right Eye
  ctx.moveTo(2, 70);
  ctx.lineTo(5, 70);

  // Mouth
  ctx.moveTo(-5, 62);
  ctx.lineTo(5, 62);

  ctx.stroke();
}

With this, we have our finished gorillas with all the variations. There’s only one thing that’s missing from the screen: the banana bomb.

How to draw the bomb

Now we'll draw the bomb. The bomb is going to be a simple circle. But before we get to draw it, first we have to figure out where it is.

How to initialize the bomb’s position

If we look back at our newGame function, we can see that the metadata of the bomb has a position and a velocity. The position so far is still undefined. Before we get to drawing the bomb, first let’s figure out its position.

function newGame() {
  // Initialize game state
  state = {
    phase: "aiming", // aiming | in flight | celebrating
    currentPlayer: 1,
    bomb: {
      x: undefined,
      y: undefined,
      velocity: { x: 0, y: 0 },
    },
    buildings: generateBuildings(),
  };

  initializeBombPosition();

  draw();
}

‌At the end of the newGame function, we also call the initializeBombPosition function before drawing the scene. Let’s implement this function.

The initializeBombPosition places the bomb in the hand of the gorilla that throws the bomb this turn. We have to call this function after we generate our building metadata because the bomb’s position depends on the position of the gorilla, and that depends on the building it stands on.

First, we look up which building we need to align with. If it’s the first player’s turn, then the bomb has to be in the left hand of the gorilla on the left. And if it’s the second player’s turn, then it has to be in the right hand of the gorilla on the right.

First, we'll calculate the midpoint of the rooftop we need (gorillaX and gorillaY), then offset the position to match the left or right hand of the gorilla.

Calculating the position of the bomb

function initializeBombPosition() {
  const building =
    state.currentPlayer === 1
      ? state.buildings.at(1) // Second building
      : state.buildings.at(-2); // Second last building

  const gorillaX = building.x + building.width / 2;
  const gorillaY = building.height;

  const gorillaHandOffsetX = state.currentPlayer === 1 ? -28 : 28;
  const gorillaHandOffsetY = 107;

  state.bomb.x = gorillaX + gorillaHandOffsetX;
  state.bomb.y = gorillaY + gorillaHandOffsetY;
  state.bomb.velocity.x = 0;
  state.bomb.velocity.y = 0;
}

We'll also initialize the velocity again here. Later we are going to call this function at the beginning of every turn and then we need it to initialize these values.

How to draw the bomb

Now that the bomb is in the right place, let’s draw it. Unfortunately, we don’t have a simple fill circle method, as we have in the case of rectangles. We have to draw an arc instead.

An arc method can be called as part of a path. We'll start with the beginPath method and end with the fill method.

The arc method has a lot of properties. This might look a bit scary, but we only need to focus on the first 3 when drawing circles:

The first two arguments are x and y, the center coordinates of the arc. We'll set them to match the position of the bomb that we know from the state.
The third argument is the radius. Here we'll set it to 6.
Then the last two arguments are the startAngle and the endAngle of the arc in radians. Because here we want to have a full circle and not an arc, we'll start with 0 and end at a full circle. A full circle in radians is two times Pi.

If these last two properties are confusing, don't worry about it. What's important is that when we draw circles, they are always 0 and 2 * Math.Pi.

function drawBomb() {
  ctx.fillStyle = "white";
  ctx.beginPath();
  ctx.arc(state.bomb.x, state.bomb.y, 6, 0, 2 * Math.PI);
  ctx.fill();
}

The final scene with the bomb in place

Now we have everything on the screen. We drew the background, the buildings, the gorillas, and the bomb. But things are not centered on the screen. Let’s fix that.

How to Fit the Size of the City to the Browser Window

So far, we've aligned everything to the left side of the screen. Because the size of the buildings is random, the entire size of the city might be shorter or wider than the size of the browser window. It could even happen that we don’t see the second gorilla because it’s entirely off-screen. Or if the browser window is too wide, then we have a huge gap on the right side of the window.

To fix this, let’s match the size of the city with the width of the browser window.

To do this, let’s add a scale property to our state. In the newGame function, let’s add the scale property to the state object, and call a new function named calculateScale to set its value. This function call has to come after we generate our buildings because the scaling depends on the size of the city. It also has to come before we initialize the bomb position, because later that will depend on the scaling.

function newGame() {
  // Initialize game state
  state = {
    scale: 1,
    phase: "aiming", // aiming | in flight | celebrating
    currentPlayer: 1,
    bomb: {
      x: undefined,
      y: undefined,
      velocity: { x: 0, y: 0 },
    },
    buildings: generateBuildings(),
  };

  calculateScale();

  initializeBombPosition();

  draw();
}

The calculateScale function is relatively simple. We calculate the total width of the city and divide the inner width of the browser window by this value. This will give us a ratio. It will tell how the width of our city relates to the width of the browser window.

Calculating the ratio between the size of the city and the size of the browser window

function calculateScale() {
  const lastBuilding = state.buildings.at(-1);
  const totalWidthOfTheCity = lastBuilding.x + lastBuilding.width;

  state.scale = window.innerWidth / totalWidthOfTheCity;
}

Then we have to use this new scale property at a few places. The most important is to change the scaling of the entire game in the draw function.

At the beginning of this function – where we flip the coordinate system – now we have another scale method call that applies this scaling. Because this is at the beginning of the draw function, everything we draw after this will be scaled.

function draw() {
  ctx.save();
  // Flip coordinate system upside down
  ctx.translate(0, window.innerHeight);
  ctx.scale(1, -1);
  ctx.scale(state.scale, state.scale);

  // Draw scene
  drawBackground();
  drawBuildings();
  drawGorilla(1);
  drawGorilla(2);
  drawBomb();

  // Restore transformation
  ctx.restore();
}

‌And finally, we need to adjust how we draw our background. Earlier when we drew the background, we filled the entire screen by setting its width and height based on the window’s innerWidth and innerHeight properties. Now as everything is scaled, they don’t match the size of the browser window anymore. Whenever we use these properties, we need to adjust them by our scaling factor.

function drawBackground() {
  ctx.fillStyle = "#58A8D8";
  ctx.fillRect(
    0,
    0,
    window.innerWidth / state.scale,
    window.innerHeight / state.scale
  );
}

Matching the size of the city to the size of the browser window

How to resize the window

Now the 8 buildings we drew fit nicely with the size of our screen – but what happens if we resize the window? We are going to have the same problems we had before.

As a finishing touch, let’s handle the window resize event. This event handler resizes the canvas element to fit the new window size, recalculates the scaling, readjusts the position of the bomb, and redraws the entire scene based on the new scaling.

Readjusting the bomb position does not make a difference yet, but later we will update this function and it will rely on the new scaling.

window.addEventListener("resize", () => {
  canvas.width = window.innerWidth;
  canvas.height = window.innerHeight;
  calculateScale();
  initializeBombPosition();
  draw();
});

So far we've just drawn a static scene. It’s time to make things interactive.

How the Gorilla Can Throw the Bomb

Throwing the bomb has two different parts. First, we have to aim. We grab the bomb with the mouse and drag it to set the throwing angle and the velocity. While dragging, we need to display the angle and velocity in info panels at the top of the screen. We'll also paint the throw trajectory on the screen. This is the aiming phase.

The aiming phase

Then once we release the mouse, the bomb flies across the sky. We are going to have an animation loop that moves the bomb across the sky. This is the in flight phase.

The in flight phase

‌In this phase, this animation loop will also include hit detection. We need to know if the bomb hit the enemy, a building, or went out of the screen. If we hit a building, or the bomb goes off-screen, we switch players and get back to the aiming phase again. If we hit the enemy, then we get to the celebrating phase. We then draw the celebrating variant of the current player’s gorilla and we show the congratulations screen.

The celebrating phase

Now let’s go through these parts in detail.

How to aim

In the aiming phase, we can drag the bomb to set its angle and velocity – like we throw a bird in Angry Birds. We are going to set up event handlers for this.

Aiming

While aiming, we are going to show the current angle and velocity at the top-left or the top-right corner of the screen (depending on the player). We are also going to draw the throw trajectory on the screen to show in which direction the bomb will fly.

Info panels showing the angle and the velocity

In the original 1991 game, we had to type in the angle and velocity with the keyboard, as it had no mouse support. Here, we are going to aim with the mouse – but we still add the same UI elements on the screen. We'll update these fields as we are moving the mouse while dragging.

Info panels in the top left and top right corner of the screen

We'll add these info panels in HTML. We could draw these text fields on the canvas as well, but it might be easier to use plain old HTML and CSS.

We'll add two divs, one for player 1 and one for player 2. Both include a header with the player number. We'll also add two paragraphs for the angle and the velocity. The info panels must come after the canvas element because otherwise, the canvas would cover them.

html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Gorillastitle>
    <link rel="stylesheet" href="index.css" />
    <script src="index.js" defer>script>
  head>
  <body>
    <canvas id="game">canvas>

    <div id="info-left">
      <h3>Player 1h3>
      <p>Angle: <span class="angle">0span>°p>
      <p>Velocity: <span class="velocity">0span>p>
    div>

    <div id="info-right">
      <h3>Player 2h3>
      <p>Angle: <span class="angle">0span>°p>
      <p>Velocity: <span class="velocity">0span>p>
    div>
  body>
html>

We'll assign two different IDs and appropriate class names. We'll use these names both for styling and for accessing these elements in JavaScript.

In the CSS, we'll move these panels into position and set some styling for the texts. We also want to ensure the user cannot select the text on the screen. Otherwise, you might end up accidentally selecting these text fields while aiming.

body {
  margin: 0;
  padding: 0;
  font-family: monospace;
  font-size: 14px;
  color: white;
  user-select: none;
  -webkit-user-select: none;
}
#info-left {
  position: absolute;
  top: 20px;
  left: 25px;
}
#info-right {
  position: absolute;
  top: 20px;
  right: 25px;
  text-align: right;
}

Then finally, in JavaScript we'll add some references to angle and velocity fields somewhere at the beginning of our file.

. . .

// Left info panel
const angle1DOM = document.querySelector("#info-left .angle");
const velocity1DOM = document.querySelector("#info-left .velocity");

// Right info panel
const angle2DOM = document.querySelector("#info-right .angle");
const velocity2DOM = document.querySelector("#info-right .velocity");

. . .

When we add event handling, we'll update the content of these elements with the mouse movement. For now, let's just leave it like that.

The grab area of the bomb

We are going to set up event handlers to drag the bomb. But what can we even drag? The whole canvas element is one single element. We could attach an event handler to it, but then we could start dragging the bomb by clicking anywhere on the screen. We don’t want that.

The grab area of the bomb

Instead, we define another element in HTML that will serve as the grab area. We add the bomb-grab-area element. This is not going to include the bomb that we see on screen – that is already part of the canvas – but it will be an invisible area around it, serving as an event target.

  . . .

  <body>
    <canvas id="game">canvas>

    <div id="info-left">
      <h3>Player 1h3>
      <p>Angle: <span class="angle">0span>°p>
      <p>Velocity: <span class="velocity">0span>p>
    div>

    <div id="info-right">
      <h3>Player 2h3>
      <p>Angle: <span class="angle">0span>°p>
      <p>Velocity: <span class="velocity">0span>p>
    div>

    <div id="bomb-grab-area">div>
  body>

  . . .

We'll also add some styling to it with CSS. We want it to have an absolute position and to be an invisible circle with a slightly bigger radius than the bomb (so it’s easier to grab it). We can set the exact position in JavaScript.

We'll also change the cursor once the mouse is on top of it to grab. While this element is invisible, you can still notice that your mouse is at the right place by the changing cursor.

. . .

#bomb-grab-area {
  position: absolute;
  width: 30px;
  height: 30px;
  border-radius: 50%;
  background-color: transparent;
  cursor: grab;
}

Then finally in JavaScript, we need to do two things before we set up event handling. First, get a reference to it somewhere at the beginning of the file.

. . .

// The bomb's grab area 
const bombGrabAreaDOM = document.getElementById("bomb-grab-area");

. . .

Then we need to move it to the correct position. We already have a function that initializes the bomb position on the canvas. We can extend the initializeBombPosition function to position this HTML element as well.

We'll move the grab area to the same place as the bomb on the screen, but its coordinates are a bit different. The content of the canvas is scaled, but any other HTML element is not. We need to adjust the coordinates by the scaling. Also, note that we'll set the grabAreaRadius variable to be half of the size we defined for this element in CSS.

function initializeBombPosition() {
  const building =
    state.currentPlayer === 1
      ? state.buildings.at(1) // Second building
      : state.buildings.at(-2); // Second last building

  const gorillaX = building.x + building.width / 2;
  const gorillaY = building.height;

  const gorillaHandOffsetX = state.currentPlayer === 1 ? -28 : 28;
  const gorillaHandOffsetY = 107;

  state.bomb.x = gorillaX + gorillaHandOffsetX;
  state.bomb.y = gorillaY + gorillaHandOffsetY;
  state.bomb.velocity.x = 0;
  state.bomb.velocity.y = 0;

  // Initialize the position of the grab area in HTML
  const grabAreaRadius = 15;
  const left = state.bomb.x * state.scale - grabAreaRadius;
  const bottom = state.bomb.y * state.scale - grabAreaRadius;
  bombGrabAreaDOM.style.left = `${left}px`;
  bombGrabAreaDOM.style.bottom = `${bottom}px`;
}

‌Once we've added this, we won’t see any difference on the screen, because this item is invisible. But once we hover over the bomb, we'll see that the cursor changes to grab.

Event handling

Now with everything set up, we can finally set up the event handling. This is going to be a simple drag-and-drop implementation where we listen to the mousedown, mousemove, and mouseup events.

First, we'll set up some top-level variables somewhere at the beginning of the file. We have a boolean variable that tells us if we are currently dragging or not, and two variables that tell us where the drag started, in case we are dragging.

. . .

let isDragging = false;
let dragStartX = undefined;
let dragStartY = undefined;

. . .

We add the first event handler for the mousedown event on the grab area of the bomb. Being able to set this event handler is the reason we added the bomb-grab-area element earlier.

This event handler only does anything if we are in the aiming phase. If that is true, we set the isDragging variable to true, save the current mouse position, and set the mouse cursor permanently to grabbing (so that the cursor stays as grabbing even if we leave the grab area).

bombGrabAreaDOM.addEventListener("mousedown", function (e) {
  if (state.phase === "aiming") {
    isDragging = true;

    dragStartX = e.clientX;
    dragStartY = e.clientY;

    document.body.style.cursor = "grabbing";
  }
});

Then we'll add an event handler for the mousemove event. Note that now the event target is not the grab area of the bomb, but the window object. This is because while we are dragging we can easily move the mouse outside the grab area – or even outside the browser window – and we still want this event handler to work.

This event handler first checks if we are currently dragging. If not, then it doesn’t do anything. If we are dragging, then it calculates the delta of the mouse position since the mousedown event and sets it as the velocity of the bomb.

window.addEventListener("mousemove", function (e) {
  if (isDragging) {
    let deltaX = e.clientX - dragStartX;
    let deltaY = e.clientY - dragStartY;

    state.bomb.velocity.x = -deltaX;
    state.bomb.velocity.y = +deltaY;
    setInfo(deltaX, deltaY);

    draw();
  }
});

When we release the mouse, we want the bomb to move the opposite way as we drag the mouse, so we need to set the horizontal and vertical velocity with a negative sign. But then with a double twist, we switch back the vertical velocity (the Y coordinate), to have a positive sign because we flipped the coordinate system.

Event handlers still assume that the coordinate system grows downwards. Within the canvas, it goes in the opposite direction.

This event handler also calls a utility function to show the angle and the velocity at the info panels we just added in HTML. Then we call the draw function again. For now, calling the draw function here does not change anything on the screen, but soon we will update the drawBomb function to draw the throwing trajectory.

The setInfo button updates the UI elements we defined in HTML. We already have references to these elements at the top of our file, so here we only need to update their content as we drag the bomb.

. . .

// Left info panel
const angle1DOM = document.querySelector("#info-left .angle");
const velocity1DOM = document.querySelector("#info-left .velocity");

// Right info panel
const angle2DOM = document.querySelector("#info-right .angle");
const velocity2DOM = document.querySelector("#info-right .velocity");

. . .

‌But there is a bit of a complication. From the mousemove event, we got the vertical and horizontal components of the velocity. But on the UI we want to display the angle and the total velocity of the throw. We need to use some trigonometry to calculate these values.

Calculating the total velocity and the angle from the horizontal and verical movement of the mouse

‌For the velocity, we'll calculate the hypotenuse of an imaginary triangle made up of the horizontal and vertical components of the velocity. For the angle, we'll use the arc sine function (the inverse of the sine function). We'll also make sure to update the correct info panel depending on whose turn it is, and we'll round the values.

function setInfo(deltaX, deltaY) {
  const hypotenuse = Math.sqrt(deltaX ** 2 + deltaY ** 2);
  const angleInRadians = Math.asin(deltaY / hypotenuse);
  const angleInDegrees = (angleInRadians / Math.PI) * 180;

  if (state.currentPlayer === 1) {
    angle1DOM.innerText = Math.round(angleInDegrees);
    velocity1DOM.innerText = Math.round(hypotenuse);
  } else {
    angle2DOM.innerText = Math.round(angleInDegrees);
    velocity2DOM.innerText = Math.round(hypotenuse);
  }
}

At this point, while the scene should stay the same as it is, the values in the left info panel should update as we drag.

Finally, we'll add the event handler for the mouseup event, again on the window object. It only does anything if we are currently dragging. Then it notes that we are not dragging anymore, changes the cursor back to default, and calls the throwBomb function.

window.addEventListener("mouseup", function () {
  if (isDragging) {
    isDragging = false;

    document.body.style.cursor = "default";

    throwBomb();
  }
});

The throwBomb function switches the game phase to in flight and kicks off the animation of the bomb. We are going to cover this function in the next chapter, but before we get there, let's update one more thing.

How to draw the throw trajectory

While we are aiming, we can also draw the throwing trajectory. The throwing trajectory is the visualized form of the velocity and the angle.

The throwing trajectory shows the angle and velocity in a visual form

‌To do this, let’s go back to the drawBomb function and make some changes. If we are in the aiming phase, we'll draw a straight line from the center of the bomb to the velocity.

function drawBomb() {
  // Draw throwing trajectory
  if (state.phase === "aiming") {
    ctx.strokeStyle = "rgba(255, 255, 255, 0.7)";
    ctx.setLineDash([3, 8]);
    ctx.lineWidth = 3;

    ctx.beginPath();
    ctx.moveTo(state.bomb.x, state.bomb.y);
    ctx.lineTo(
      state.bomb.x + state.bomb.velocity.x,
      state.bomb.y + state.bomb.velocity.y
    );
    ctx.stroke();
  }

  // Draw circle
  ctx.fillStyle = "white";
  ctx.beginPath();
  ctx.arc(state.bomb.x, state.bomb.y, 6, 0, 2 * Math.PI);
  ctx.fill();
}

We'll draw this line as a path, as we did before. We'll start it with the beginPath method and end it with the stroke method. In between we'll use the moveTo and the lineTo method.

There’s one new thing here though: the setLineDash method. With this setting, we can draw a dotted line. We'll set that after every 3 pixels of line, and we want to have 8 pixels of gap. The 3-pixel dash matches the lineWidth, so the dashes will look like dots.

Now we've finished everything about the aiming phase. It’s time to throw the bomb.

How to Animate the Incoming Bomb

Once we release the mouse after the aim, the bomb flies across the sky. We'll add an animation loop that moves the bomb, calculates its position with every animation cycle, and checks if we hit something.

Animating the bomb

Earlier, we saw that the event handler of the mouseup event ends with calling the throwBomb function. Let's implement this function.

This function first kicks off the in flight phase. Then it resets the previousAnimationTimestamp variable. This is a new utility variable needed for the animation loop. We'll cover it in a second. Then we start the animation loop, by calling requestAnimationFrame with the animate function as an argument. Let’s dig deeper into this animate function.

. . . 

let previousAnimationTimestamp = undefined; 

. . .

function throwBomb() {
  state.phase = "in flight";
  previousAnimationTimestamp = undefined;
  requestAnimationFrame(animate);
}

The animation loop

The animate function moves the bomb and calls the draw function to repaint the screen over and over again until we hit the enemy, a building, or the bomb goes off the screen.

By calling this function with requestAnimationFrame the way you see below, the animate function will run around 60 times every second. The constant repainting of the screen will appear as a continuous animation. Because this function is running so frequently, we're only moving the bomb little by little each time.

The animation loop

‌This function keeps track of how much time has passed since its last call. We are going to use this information to precisely calculate how much should we move the bomb.

Functions invoked with the requestAnimationFrame function receive the current timestamp as an attribute. At the end of every cycle, we save this timestamp value into the previousAnimationTimestamp variable, so that in the next cycle we can calculate how much time has passed between two cycles. In the code below, this is the elapsedTime variable.

The first cycle is an exception because, at that point, we didn’t have a previous cycle yet. At the beginning of each throw, the value of previousAnimationTimestamp is undefined (we made sure it's undefined in the throwBomb function). In this case, we skip a render and we'll only render the scene on the second cycle, where we already have all the values we need. This is the part at the very beginning of the animate function.

function animate(timestamp) {
  if (previousAnimationTimestamp === undefined) {
    previousAnimationTimestamp = timestamp;
    requestAnimationFrame(animate);
    return;
  }
  const elapsedTime = timestamp - previousAnimationTimestamp;

  moveBomb(elapsedTime); 

  // Hit detection
  let miss = false; // Bomb hit a building or got out of the screen
  let hit = false; // Bomb hit the enemy

  // Handle the case when we hit a building or the bomb got off-screen
  if (miss) {
    // ...
    return;
  } // Handle the case when we hit the enemy
  if (hit) {
    // ... 
    return;
  }

  draw();

  // Continue the animation loop
  previousAnimationTimestamp = timestamp;
  requestAnimationFrame(animate);
}

‌Inside the function, we are going to move the bomb every cycle by calling the moveBomb function. We'll pass on the elapsedTime variable so it can precisely calculate by how much should it move the bomb.

In every cycle, we also detect if we hit an enemy, or if we missed and the bomb hit a building or got off screen. If none of that happens, then we need to repaint the scene and request another animation frame to continue the animation loop. But if we missed the enemy or got a hit, then we'll stop the animation loop by returning from the function. By returning early from the function, we never reach the last line, which would trigger the next animation cycle. The loop stops.

How to move the bomb

We move the bomb by calling the moveBomb function in the animation loop. This function calculates the new x and y position of the bomb in every cycle.

The new x and y values are calculated based on the velocity. But the vertical and horizontal velocity can be a relatively high number.

We don’t want the bomb to cross the screen with lightning speed, so to slow down the movement we'll multiply the values by a very small number. This multiplier also takes into consideration the elapsed time, so the animation will look consistent even if the animation cycles are not triggered at equal intervals.

With every cycle, the velocity of the bomb is also adjusted by gravity. We'll gradually increase the motion of the bomb towards the ground. We'll also adjust the vertical velocity by a small constant that also depends on the time passed.

function moveBomb(elapsedTime) {
  const multiplier = elapsedTime / 200; // Adjust trajectory by gravity

  state.bomb.velocity.y -= 20 * multiplier; // Calculate new position

  state.bomb.x += state.bomb.velocity.x * multiplier;
  state.bomb.y += state.bomb.velocity.y * multiplier;
}

Hit detection

Our animation loop keeps moving the bomb to infinity. But once we hit a building, the enemy, or the bomb got off-screen, we should stop this motion.

We need to detect these cases and handle them appropriately. If the bomb gets off-screen or we hit a building we should move on to the next player and get back to the aiming phase. In case we hit the enemy, we should move on to the celebrating phase and announce the winner.

In all these cases, we can stop the loop by returning early from the animate function. In these cases, the animate function does not reach its last line which would trigger another animation cycle.

How to improve hit detection precision

While we already slowed down the movement of the bomb to have a nice animation on screen, the bomb can still be a bit too fast for hit detection.

When the bomb is in flight, it can move by more than 10 pixels at a time. If we do hit detections only once per animation cycle, then we are completely blind to what happens during these 10-pixel movements. The bomb can easily go through parts of the gorilla without us noticing that we should have had a hit, or go through the corner of a building without any impact.

We need to break down each animation cycle into multiple segments to improve hit detection

To solve this, we are not only going to do hit detection once per every animation cycle, but multiple times. We'll break down every movement into smaller segments, and with every tiny movement, we need to check if we have a hit.

We'll still render the scene once per animation cycle, but before calling the draw function, we'll break down the movement into 10 segments with a loop.

Break down movement and hit detection to 10 segments in each animation cycle

If we break down each animation cycle into ten segments, that also means that now we call the moveBomb function ten times more. We need to slow it down even more. Because this function moves the bomb according to the time passed, it’s enough if we divide its time attribute also by ten.

This way the bomb moves across the sky with the same speed, but we have ten times more precision with hit detection. In the example below, we wrap calling the moveBomb function and the hit detection logic into a for loop.

function animate(timestamp) {
  if (!previousAnimationTimestamp) {
    previousAnimationTimestamp = timestamp;
    requestAnimationFrame(animate);
    return;
  }

  const elapsedTime = timestamp - previousAnimationTimestamp;

  const hitDetectionPrecision = 10;
  for (let i = 0; i < hitDetectionPrecision; i++) {
    moveBomb(elapsedTime / hitDetectionPrecision);

    // Hit detection
    const miss = checkFrameHit() || checkBuildingHit();
    const hit = checkGorillaHit();

    // Handle the case when we hit a building or the bomb got off-screen
    if (miss) {
      // ...
      return;
    }

    // Handle the case when we hit the enemy
    if (hit) {
      // ...
      return;
    }
  }

  draw();

  // Continue the animation loop
  previousAnimationTimestamp = timestamp;
  requestAnimationFrame(animate);
}

In the example above we've also introduced some utility functions for hit detection. In the next steps let’s implement these functions.

function checkFrameHit() {
  // ...
}

function checkBuildingHit() {
  // ...
}

function checkGorillaHit() {
  // ...
}

How to detect if the bomb is off the screen

We've missed the target if we reach the edge of the screen or if we hit a building. Checking if we've reached the edge of the screen is a very easy thing to do.

Checking if the bomb went off-screen

‌We only need to check if the bomb went out on the left side, the bottom, or the right side of the screen. If the bomb goes through the top of the screen, that’s okay. Gravity will eventually pull it back.

Note that because of the scaling, the right side of the screen is not the same as the window’s innerWidth value. We have to adjust that by the scaling factor.

function checkFrameHit() {
  if (
    state.bomb.y < 0 ||
    state.bomb.x < 0 ||
    state.bomb.x > window.innerWidth / state.scale
  ) {
    return true; // The bomb is off-screen
  }
}

If the bomb went out of the screen, we return true to signal to the animate function that we can stop the animation loop.

How to detect if the bomb hit a building

We also miss the target if the bomb hits a building. We can iterate over the buildings array and check if any side of the bomb is within the rectangle of the building. We need to check that:

The right side of the bomb is on the right of the left side of the building,
The left side of the bomb is on the left of the right side of the building,
And that the bottom of the bomb is below the top of the building.

Detecting if the bomb hit a building

function checkBuildingHit() {
  for (let i = 0; i < state.buildings.length; i++) {
    const building = state.buildings[i];
    if (
      state.bomb.x + 4 > building.x &&
      state.bomb.x - 4 < building.x + building.width &&
      state.bomb.y - 4 < 0 + building.height
    ) {
      return true; // Building hit
    }
  }
}

If all this is true, then we know that the bomb hit the building. If we get a hit, the function ends with returning true. This will also signal to the animate function that we can stop the animation loop.

How to detect if the bomb hit the enemy

Now that we can detect if the bomb went off-screen and we have hit detection for buildings, it’s time to detect if we hit the enemy.

We are going to have a different approach this time. Detecting if we got a hit with traditional geometric calculations would be much more complicated, because the gorillas are not built with basic rectangles and circles.

Screenshot of the game once we hit the enemy

Instead, we can use the isPointInPath method that conveniently tells us if a point – in this case, the center of the bomb – is within a path.

This method tells us if a point is within the current or previous path. So before calling the method, we need to recreate the gorilla. The gorilla is not only one single path, so we have to test against the most relevant path, the main body of the gorilla.

Conveniently – and with some smart planning – we already have a function that paints the body of the gorilla as a single path. We call the drawGorillaBody function right before isPointInPath. But the drawGorillaBody function paints with coordinates relative to the rooftop of a building, so before calling it, we need to translate the coordinate system.

Depending on the current player, we'll calculate which building the enemy stands on, and translate the coordinate system to top of that. Because of this translation, we also use the save and restore methods.

function checkGorillaHit() {
  const enemyPlayer = state.currentPlayer === 1 ? 2 : 1;
  const enemyBuilding =
    enemyPlayer === 1
      ? state.buildings.at(1) // Second building
      : state.buildings.at(-2); // Second last building

  ctx.save();

  ctx.translate(
    enemyBuilding.x + enemyBuilding.width / 2,
    enemyBuilding.height
  );

  drawGorillaBody();
  let hit = ctx.isPointInPath(state.bomb.x, state.bomb.y);

  drawGorillaLeftArm(enemyPlayer);
  hit ||= ctx.isPointInStroke(state.bomb.x, state.bomb.y);

  drawGorillaRightArm(enemyPlayer);
  hit ||= ctx.isPointInStroke(state.bomb.x, state.bomb.y);

  ctx.restore();

  return hit;
}

Similarly, we can also detect if we hit one of the arms of the gorilla. The arms are drawn as a stroke, so in this case instead of isPointInPath we'll use the isPointInStroke method. This detection would not have worked if we did not increase the hit detection precision earlier, because the bomb could easily jump over the arm.

With this function, we have every piece of the hit detection. The animation loop stops in case we hit a building, the enemy, or the bomb gets off-screen. It’s time to handle what’s next in these cases.

How to handle the result of hit detection

Once we have proper hit detection, it's time to finally handle the cases when we hit a building, the enemy, or the bomb goes off-screen. We'll update the animate function one last time. The only thing new below is the code block of the two if statements inside the loop.

If we hit the edge of the screen or a building, that means we've missed the target. In this case, we'll switch players and get back to the aiming phase. We'll also re-initialize the bomb position to move it to the new player’s hand.

Once we've missed the enemy, we switch players

Then we'll simply call the draw function to handle the rest. The beauty of this structure is that we only need to change the game state and the draw function can repaint the whole scene according to it.

Then we'll return from the animate function to stop the animation loop. The event handlers are active again (because we are back in the aiming phase), and the next player can take a shot.

function animate(timestamp) {
  if (!previousAnimationTimestamp) {
    previousAnimationTimestamp = timestamp;
    requestAnimationFrame(animate);
    return;
  }

  const elapsedTime = timestamp - previousAnimationTimestamp;

  const hitDetectionPrecision = 10;
  for (let i = 0; i < hitDetectionPrecision; i++) {
    moveBomb(elapsedTime / hitDetectionPrecision); // Hit detection

    const miss = checkFrameHit() || checkBuildingHit();
    const hit = checkGorillaHit();

    // Handle the case when we hit a building or the bomb got off-screen
    if (miss) {
      state.currentPlayer = state.currentPlayer === 1 ? 2 : 1; // Switch players
      state.phase = "aiming";
      initializeBombPosition();
      draw();
      return;
    }

    // Handle the case when we hit the enemy
    if (hit) {
      state.phase = "celebrating";
      announceWinner();
      draw();
      return;
    }
  }

  draw();

  // Continue the animation loop
  previousAnimationTimestamp = timestamp;
  requestAnimationFrame(animate);
}

If we hit the enemy, we need to switch to the celebrating phase. We'll announce the winner with a function that we are about to cover in the next section. Then we repaint the scene with a celebrating gorilla and return to stop the animation loop.

Once we hit the enemy the draw function repaints the scene with a celebrating gorilla

‌To make sure our code does not throw an error, let's add a placeholder for the announceWinner function.

function announceWinner() { 
    // ... 
}

How to announce the winner

Once we hit the enemy, we should announce the winner. For this, we'll add another info panel in HTML that includes who won the game and a restart button. At the bottom of the now-finished HTML file, you can find the congratulations panel.

The congratulations panel announcing the winner

html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Gorillastitle>
    <link rel="stylesheet" href="index.css" />
    <script src="index.js" defer>script>
  head>
  <body>
    <canvas id="game">canvas>

    <div id="info-left">
      <h3>Player 1h3>
      <p>Angle: <span class="angle">0span>°p>
      <p>Velocity: <span class="velocity">0span>p>
    div>

    <div id="info-right">
      <h3>Player 2h3>
      <p>Angle: <span class="angle">0span>°p>
      <p>Velocity: <span class="velocity">0span>p>
    div>

    <div id="bomb-grab-area">div>

    <div id="congratulations">
      <h1><span id="winner">?span> won!h1>
      <button id="new-game">New Gamebutton>
    div>
  body>
html>

This panel is hidden by default and it only shows up at the end of the game. When it shows up, it should be in the middle of the screen. We'll update our CSS file according to this.

Note that we added display: flex to the body element with a few more properties to center everything on the screen. Then we set position: absolute for the congratulations element and hide it by default.

body {
  margin: 0;
  padding: 0;
  font-family: monospace;
  font-size: 14px;
  color: white;
  user-select: none;
  -webkit-user-select: none;
  display: flex;
  justify-content: center;
  align-items: center;
}

#info-left {
  position: absolute;
  top: 20px;
  left: 25px;
}

#info-right {
  position: absolute;
  top: 20px;
  right: 25px;
  text-align: right;
}

#bomb-grab-area {
  position: absolute;
  width: 30px;
  height: 30px;
  border-radius: 50%;
  background-color: transparent;
  cursor: grab;
}

#congratulations {
  position: absolute;
  visibility: hidden;
}

Then finally we can use this panel to announce the winner once the game ends in JavaScript. We already call the announceWinner function in our animate function so it’s time to implement it.

First, somewhere at the beginning of the file, we'll set up some references for the congratulations panel itself and the winner field.

. . .

// Congratulations panel
const congratulationsDOM = document.getElementById("congratulations");
const winnerDOM = document.getElementById("winner");

. . .

Then in the announceWinner function, we'll set the content of the winner field to say the current player and show the congratulations panel.

function announceWinner() {
  winnerDOM.innerText = `Player ${state.currentPlayer}`;
  congratulationsDOM.style.visibility = "visible";
}

With this piece, we finally can play the game until the end. We can aim, the bomb flies across the sky, and the gorillas take turns until one of them wins the game. The only missing piece is resetting the game for another round.

How to reset for another round

As a final finishing touch, let’s add an event handler for the 'New Game' button on our congratulations panel to be able to reset the game. We've already added a button with the ID new-game in our HTML.

In JavaScript first, we'll create a reference to this button and then add an event handler for it. This event handler simply calls the newGame function.

. . .

// Congratulations panel
const congratulationsDOM = document.getElementById("congratulations");
const winnerDOM = document.getElementById("winner");
const newGameButtonDOM = document.getElementById("new-game");

. . .

newGameButtonDOM.addEventListener("click", newGame);

The newGame function should reset everything and generate a new level so we can start a new game. At this point, though, our newGame function does not reset everything. It does not reset the HTML elements we introduced in the meantime.

As a very last step, we'll make sure that the congratulations element is hidden once we start a new game, and reset the angle and velocity values in the left and right info panels to 0.

function newGame() {
  // Initialize game state
  state = {
    scale: 1,
    phase: "aiming", // aiming | in flight | celebrating
    currentPlayer: 1,
    bomb: {
      x: undefined,
      y: undefined,
      velocity: { x: 0, y: 0 },
    },
    buildings: generateBuildings(),
  };

  calculateScale();

  initializeBombPosition();

  // Reset HTML elements
  congratulationsDOM.style.visibility = "hidden";
  angle1DOM.innerText = 0;
  velocity1DOM.innerText = 0;
  angle2DOM.innerText = 0;
  velocity2DOM.innerText = 0;

  draw();
}

Next Steps

While we now have a full two-player game, we can do a lot more. On YouTube I also cover how to make the buildings destructible, how to animate the hand of the gorilla to follow the drag movement while aiming, and we spend more time adding detailed graphics. There's also a whole chapter on how to add computer logic to the game, so that you can play against the computer.

Check it out to learn more:

SVG Tutorial – How to Code Images with 12 Examples

Hunor Márton Borbély — Mon, 04 Dec 2023 12:29:00 +0000

Have you ever needed an icon for your website, but you couldn't quite find the right one? Or perhaps you wanted to have a simple diagram, but didn't want to learn a whole new library just for that?

Well, good news – you can do all that and more without ever leaving your favorite code editor or using any third party tools or libraries.

Since HTML5, we can include the code of an SVG image inside an HTML document. We don’t even need to use the image tag that refers to a separate file. We can inline the code of an image right inside the HTML. We can do this because SVGs have a very similar syntax to HTML.

This opens up a lot of cool options. Suddenly we can access parts of an image from JavaScript or set the style from CSS. We can animate parts of an image from JavaScript or make it interactive. Or we can turn things around and generate graphics from code.

For more complicated images, you will still use a designer tool. But the next time you need a simple icon, a diagram, or animation, maybe you can code it yourself.

So how do SVGs look like under the surface? In this tutorial, we go through the source code of a few SVGs to cover the foundations.

The following examples are from svg-tutorial.com. You can also watch this article as a video with even more fun examples.

The SVG tag

First, we have to talk about the svg tag itself. This tag contains the image elements and defines the frame of our image. It sets the inner size and the outer size of the image.

The width and height property define how much space the image takes up in the browser. There’s often a viewBox property as well. This defines a coordinate system for the elements inside the image. These two can be confusing because they both define a size.

You can think of the width and height of an SVG as an external size and the viewBox as an internal size.

The size defined by width and height is how the rest of HTML thinks of the image and how big it appears in the browser. The size defined by viewBox is how the image elements think of the image when they position themselves inside of it.

In the next example we have three SVGs that have the very same content. A circle element with the same center coordinate and same radius. They appear quite different, though.

The very same circle can appear different based on the size of the image and the viewBox property

At the example in the middle, the size defined by width and height matches the one defined by the viewbox. In the first example we see what happens if the width and height are smaller. The image simply shrinks down as all the coordinates and sizes defined within the image still align to the viewbox.

In the last example we see what happens if the viewbox is focusing on only part of the image. Things appear bigger in this case, but the actual size of the image is still defined by the width and height property.

The viewBox also defines the center of the coordinate system in which the image items place themselves.

The first two numbers define which coordinate should be at the top left corner of the image. Coordinates grow to the right and downwards. In this article, we will center the coordinate systems. The 0,0 coordinate will always be in the middle of the image.

One note before we start: while we can inline SVG images in an HTML file, that doesn’t mean we can freely combine any SVG tag with any HTML tag.

The SVG tag represents the frame of the image and every SVG element has to come within an SVG tag. The same is true in the opposite direction. HTML tags can’t be within an SVG tag, so we can’t have a div or a header tag inside an SVG. But don’t worry, there are similar tags available.

How to Make a Christmas Ornament with SVG

Let’s start with a simple Christmas tree ornament. Here we'll only use simple shapes. A rectangle, and two circles.

We'll position and style these elements with attributes. For the circle, we define the center position and for the rectangle, we define the top left corner. These positions are always related to the coordinate system defined by the viewBox.

Christmas Ornament made out of circles and a rectangle. On the right you can see the coordinates we use in this example.

<html>
  <svg width="200" height="200" viewBox="-100 -100 200 200”>
    0" cy="20" r="70" fill="#D1495B" />

    <circle
      cx="0"
      cy="-75"
      r="12"
      fill="none"
      stroke="#F79257"
      stroke-width="2"
    />

    <rect x="-17.5" y="-65" width="35" height="20" fill="#F79257" />
  svg>
html>

Remember, we moved the center of the coordinate system to the middle of the image and the X-axis grows to the right and the Y-axis grows towards the bottom.

We also have presentational attributes that style our shapes. Unlike in HTML, we do not use background-color to set a color for a shape but we use the fill attribute.

And to set a border for a shape we use stroke and stroke-width. Note how we use the circle element both to draw a ring and a ball with different attributes.

How to Build a Christmas Tree with SVG

Let’s move on to a Christmas tree. We can’t always use basic shapes to assemble our image. A polygon is the simplest way to draw a freeform shape. Here we set a list of points that are connected with straight lines.

Christmas Tree made out of polygons and a rectangle

<html>
  <svg width="200" height="200" viewBox="-100 -100 200 200">
    <polygon points="0,0 80,120 -80,120" fill="#234236" />
    <polygon points="0,-40 60,60 -60,60" fill="#0C5C4C" />
    <polygon points="0,-80 40,0 -40,0" fill="#38755B" />
    <rect x="-20" y="120" width="40" height="30" fill="brown" />
  svg>
html>

You might be wondering how we know before starting to code where our coordinates should be.

To be honest, this requires a bit of imagination. You can start with pen and paper and draw a draft first to get an estimate. Or you can just make a guess then adjust your values until it looks good.

How to Make a Gingerbread Figure with SVG

Let’s move on with a gingerbread figure. Since our SVG is living inside an HTML file now, we can assign CSS classes to each tag and move some attributes to CSS.

We can only move the presentation attributes, though. Position attributes and attributes that define the shape still have to stay in the HTML. But we can move colors, stroke, and font attributes to CSS.

Gingerbread figure example. On the right you can see how would it look if the stroke-width were one

<svg class="gingerbread" width="200" height="200" viewBox="-100 -100 200 200">
  <circle class="body" cx="0" cy="-50" r="30" />

  <circle class="eye" cx="-12" cy="-55" r="3" />
  <circle class="eye" cx="12" cy="-55" r="3" />
  <rect class="mouth" x="-10" y="-40" width="20" height="5" rx="2" />

  <line class="limb" x1="-40" y1="-10" x2="40" y2="-10" />
  <line class="limb" x1="-25" y1="50" x2="0" y2="-15" />
  <line class="limb" x1="25" y1="50" x2="0" y2="-15" />

  <circle class="button" cx="0" cy="-10" r="5" />
  <circle class="button" cx="0" cy="10" r="5" />
svg>

.gingerbread .body {
  fill: #cd803d;
}

.gingerbread .eye {
  fill: white;
}

.gingerbread .mouth {
  fill: none;
  stroke: white;
  stroke-width: 2px;
}

.gingerbread .limb {
  stroke: #cd803d;
  stroke-width: 35px;
  stroke-linecap: round;
}

We already saw the fill and some of the stroke properties, but here’s another one – the stroke-linecap. This can make our line cap round.

Note that the legs and the arms are simple lines here. If we remove the line cap and set a smaller stroke-width, then we can see that these are simple lines. But by setting a thick stroke width and a round line cap we can shape legs and arms for our figure.

Also note the rx property at the rectangle defining the mouth. This will make the edges round. You can think of it as border-radius if you like.

How to Make a Star with SVG

Let’s move on to a star. A star is a simple shape, so we can define it as a bunch of polygons and set each point individually. But then we would need to know each coordinate.

Instead of that, we can just define one wing as a group, then repeat it five times with a rotation to get the star's shape. We use the transform attribute to set a rotation.

Star shape made out of transformed polygons. On the right we can see the coordianates of one arm of the star

<svg width="200" height="200" viewBox="-100 -100 200 200">      
  <g transform="translate(0 5)">
    <g>
      <polygon points="0,0 36,-50 0,-100" fill="#EDD8B7" />
      <polygon points="0,0 -36,-50 0,-100" fill="#E5C39C" />
    g>
    <g transform="rotate(72)">
      <polygon points="0,0 36,-50 0,-100" fill="#EDD8B7" />
      <polygon points="0,0 -36,-50 0,-100" fill="#E5C39C" />
    g>
    <g transform="rotate(-72)">
      <polygon points="0,0 36,-50 0,-100" fill="#EDD8B7" />
      <polygon points="0,0 -36,-50 0,-100" fill="#E5C39C" />
    g>
    <g transform="rotate(144)">
      <polygon points="0,0 36,-50 0,-100" fill="#EDD8B7" />
      <polygon points="0,0 -36,-50 0,-100" fill="#E5C39C" />
    g>
    <g transform="rotate(-144)">
      <polygon points="0,0 36,-50 0,-100" fill="#EDD8B7" />
      <polygon points="0,0 -36,-50 0,-100" fill="#E5C39C" />
    g>
  g>
svg>

In this example, each wing consists of two polygons. They need to be rotated the same way, so we can group them with a g tag and rotate them together.

You can think of the g tag as the div tag in HTML. On its own, it does not represent anything. But it can contain other elements and attributes defined on the group tag apply to its children.

Groups can be embedded. With the outer group we translate the whole star downwards by 5 units.

How to Make a Snowflake with SVG

Grouping elements is a nice trick, but we had to repeat the same code for each wing five times.

Instead of repeating the same code over and over again, we can also create a definition for a shape and reuse it by id. Here we define a branch of a snowflake then use it six times with different rotations.

Snowflake made out of reused image elements. On the right we can see the coordainates use for an arm

<svg width="200" height="200" viewBox="-100 -100 200 200">
  <defs>
    <path
      id="branch"
      d="
        M 0 0 L 0 -90
        M 0 -20 L 20 -34
        M 0 -20 L -20 -34
        M 0 -40 L 20 -54
        M 0 -40 L -20 -54
        M 0 -60 L 20 -74
        M 0 -60 L -20 -74"
      stroke="#E5C39C"
      stroke-width="5"
    />
  defs>

  <use href="#branch" />
  <use href="#branch" transform="rotate(60)" />
  <use href="#branch" transform="rotate(120)" />
  <use href="#branch" transform="rotate(180)" />
  <use href="#branch" transform="rotate(240)" />
  <use href="#branch" transform="rotate(300)" />
svg>

The branch is defined as a path. The path is the most powerful SVG tag. We can define pretty much anything with paths, and if you open any SVG file, you will see mostly paths.

The shape of the path is defined by the d attribute. Here we define several drawing commands. A command always starts with a letter defining the command type and ends with a coordinate.

Here we only have the two most simple commands, move to (M) and line to (L). The move to command moves the cursor to a point without drawing a line and the line to command draws a straight line from the previous point.

A command always continues the previous command, so when we draw a line we only define the endpoint. The starting point will be the previous command’s endpoint.

This path is a bit unusual because there are several move to commands in it to draw the main branch and each side branch with the same path.

How to Draw a Forest with SVG

Rotation is not the only way we can generate images from simple shapes. In this example, we define a tree shape and then place it at various positions in different sizes to draw a forest.

Forest made out of reused image elements

First, we create a background out of a rectangle and a circle. Then we define a tree shape from a simple polygon and a line.

Then we can reuse it in a similar way as we did in the snowflake example. We move it to the defs section, wrap it into a group element, set an ID for it, and then reuse it with the use element.

Here we also position the reused elements by setting an x and y coordinate and to add some perspective to the image we use the scale transformation.

<svg width="200" height="200" viewBox="-100 -100 200 200">
  <defs>
    <g id="tree">
      <polygon points="-10,0 10,0 0 -50" fill="#38755b" />
      <line x1="0" y1="0" x2="0" y2="10" stroke="#778074" stroke-width="2" />
    g>
  defs>

  <rect x="-100" y="-100" width="200" height="200" fill="#F1DBC3" />
  <circle cx="0" cy="380" r="350" fill="#F8F4E8" />

  <use href="#tree" x="-30" y="25" transform="scale(2)" />
  <use href="#tree" x="-20" y="40" transform="scale(1.2)" />
  <use href="#tree" x="40" y="40" />
  <use href="#tree" x="50" y="30" transform="scale(1.5)" />
svg>

How to Make a Curvy Tree with SVG

The path element becomes really powerful when we start using curves. One of them is the quadratic Bézier curve that not only defines an endpoint for a segment but also has a control point. The control point is an invisible coordinate towards which the line is bending, but not touching it.

Christmas Tree made using Quadratic Bézier curves

<svg width="200" height="400" viewBox="-100 -200 200 400">
  <path
    d="
      M 0 -80
      Q 5 -75 0 -70
      Q -10 -65 0 -60
      Q 15 -55 0 -50
      Q -20 -45 0 -40
      Q 25 -35 0 -30
      Q -30 -25 0 -20
      Q 35 -15 0 -10
      Q -40 -5 0 0
      Q 45 5 0 10
      Q -50 15 0 20
      Q 55 25 0 30
      Q -60 35 0 40
      Q 65 45 0 50
      Q -70 55 0 60
      Q 75 65 0 70
      Q -80 75 0 80
      Q 85 85 0 90
      Q -90 95 0 100
      Q 95 105 0 110
      Q -100 115 0 120
      L 0 140
      L 20 140
      L -20 140"
    fill="none"
    stroke="#0C5C4C"
    stroke-width="5"
  />
svg>

Here we have a series of quadratic Béziers curves (Q) where the control points get further and further away from the center of the tree as the path goes down.

How to Make a Bell with SVG

While the quadratic bezier curve (Q) is great when we want to bend a line, often it’s not flexible enough.

With a cubic Bezier (C), we not only one have one control point but two. The first control point sets the initial direction of the curve and the second one defines from which direction the curve should arrive to its endpoint.

If these directions match the directions of the line before and the line after the curve, then we have a smooth transition between the path segments.

With Cubic Bézier curves we can set two control points

The next example uses both quadratic and cubic Béziers to form a bell. Here the bottom of this bell is defined with straight lines. Then a quadratic Béziers starts the bell cloak. Next a cubic Bezier smoothly continues the quadratic bezier as it forms the top of the bell. Then we reach the bottom part with another quadratic bezier.

Bell example made out of different curves and straight lines

<svg width="200" height="200" viewBox="-100 -100 200 200">
  <g stroke="black" stroke-width="2">
    <circle cx="0" cy="-45" r="7" fill="#4F6D7A" />
    <circle cx="0" cy="50" r="10" fill="#F79257" />
    <path
      d="
        M -50 40
        L -50 50
        L 50 50
        L 50 40
        Q 40 40 40 10
        C 40 -60 -40 -60 -40 10   
        Q -40 40 -50 40"
      fill="#FDEA96"
    />
 g>
svg>

How to Write Text Along a Path

Drawing shapes is not the only use case for paths. We can also use them to render text along an invisible path. We can define a path in the definitions section and use it in a textPath element to make the text go around the circle. Here we use arc again, but you can use any other path and the text will follow the stroke.

With the text-path property we can make a text follow a path

<svg width="200" height="200" viewBox="-100 -100 200 200">
  <defs>
    <path id="text-arc" d="M 0, 50 A 50 50 0 1 1 1,50" />
  defs>

  <text
    fill="#0c5c4c"
    font-family="Tahoma"
    font-size="0.77em"
    font-weight="bold"
  >
    <textPath href="#text-arc">
      Happy Holidays! Happy Holidays! Happy Holidays!
    textPath>
  text>
svg>

How to Animate an SVG with CSS

To continue our forest example, we can add a snowing effect with a similar animation. We can animate the transform property from CSS.

Animation effect made with SVG and CSS

We extend our forest example with simple reusable snowflakes and add a bunch of them to the scene with various CSS classes to set some variation in speed and appearance. Then we add animation in CSS to make them look like falling snow. It’s a bit glitchy and not the most sophisticated animation, but you get the idea.

<svg width="200" height="200" viewBox="-100 -100 200 200">
  <defs>
    <g id="tree">
      <polygon points="-10,0 10,0 0 -50" fill="#38755b" />
      <line x2="0" y2="10" stroke="#778074" stroke-width="2" />
    g>
    <circle id="big" cx="0" cy="0" r="5" fill="white" />
    <circle id="small" cx="0" cy="0" r="3" fill="white" />
  defs>

  <rect x="-100" y="-100" width="200" height="200" fill="#F1DBC3" />
  <circle cx="0" cy="380" r="350" fill="#F8F4E8" />

  <use href="#tree" x="-30" y="25" transform="scale(2)" />
  <use href="#tree" x="-20" y="40" transform="scale(1.2)" />
  <use href="#tree" x="40" y="40" />
  <use href="#tree" x="50" y="30" transform="scale(1.5)" />

  <use href="#big" x="0" y="0" class="flake fast" />
  <use href="#big" x="-50" y="-20" class="flake fast opaque" />
  <use href="#big" x="30" y="-40" class="flake fast" />
  <use href="#big" x="50" y="-20" class="flake fast opaque" />
  <use href="#big" x="30" y="50" class="flake slow" />
  <use href="#big" x="-70" y="-80" class="flake slow opaque" />
  <use href="#big" x="30" y="50" class="flake slow" />
  <use href="#big" x="90" y="-80" class="flake slow opaque" />
  <use href="#small" x="10" y="-50" class="flake slow" />
  <use href="#small" x="-50" y="-60" class="flake slow opaque" />
  <use href="#small" x="30" y="70" class="flake slow" />
  <use href="#small" x="10" y="-80" class="flake slow opaque" />
svg>

.flake {
  animation-duration: inherit;
  animation-name: snowing;
  animation-iteration-count: infinite;
  animation-timing-function: linear;
}

.flake.opaque {
  opacity: 0.7;
}

.flake.slow {
  animation-duration: 5s;
}

.flake.fast {
  animation-duration: 3s;
}

@keyframes snowing {
  from {
    transform: translate(0, -100px);
  }
  to {
    transform: translate(0, 100px);
  }
}

How to Make a Clock That Shows the Actual Time

SVG elements can be manipulated from JavaScript the same way as any other HTML tag.

Clock example made with SVG and JavaScript

In this example, we are using a short code snipped to show the actual time on a clock. We access the hour and minute hands in JavaScript with getElementById then set their transform attribute with a rotation that reflects the current time. Below you see the actual SVG showing the current time.

For a more detailed tutorial on how to make a clock with SVG and JavaScript, check out How to Code an Animated Watch.

<svg width="200" height="200" viewBox="-100 -100 200 200">
  <rect x="-100" y="-100" width="200" height="200" fill="#CD803D" />

  <circle r="55" stroke="#FCCE7B" stroke-width="10" fill="white" />

  <circle
    r="45"
    stroke="#B6705F"
    stroke-width="6"
    stroke-dasharray="6 17.56194490192345"
    stroke-dashoffset="3"
    fill="none"
  />

  <g stroke="#5f4c6c" stroke-linecap="round">
    <line id="hours" y2="-20" stroke-width="8" />
    <line id="minutes" y2="-35" stroke-width="6" />
  g>
svg>

window.addEventListener("DOMContentLoaded", () => {
  const hoursElement = document.getElementById("hours");
  const minutesElement = document.getElementById("minutes");

  const hour = new Date().getHours() % 12;
  const minute = new Date().getMinutes();

  hoursElement.setAttribute("transform", `rotate(${(360 / 12) * hour})`);
  minutesElement.setAttribute("transform", `rotate(${(360 / 60) * minute})`);
});

How to make a Data-driven Diagram with SVG and React

SVGs also work well with frontend libraries. Here’s an example of a React component that generates a data-driven diagram.

In this example we have two things. We are generating a list of rectangles to create a column diagram based on some arbitrary data. And we also generate a series of coordinates for a polyline.

We can use JavaScript to generate a Data-Driven Diagram

For simple use cases, you can code your own diagram like this. But if you need more complex diagrams then check out the D3 library. The D3 library uses SVG under to hood to create all sorts of diagrams.

function Diagram() {
  const dataPoints = [3, 4, 7, 5, 3, 6];
  const sineWave = Array.from({ length: 115 })
    .map((item, index) => `${index - 55},${Math.sin(index / 20) * 20 + 10}`)
    .join(" ");

  return (
    <svg width="200" height="200" viewBox="-100 -100 200 200">
      {dataPoints.map((dataPoint, index) => (
        <rect
          key={index}
          x={index * 20 - 55}
          y={50 - dataPoint * 10}
          width="15"
          height={dataPoint * 10}
          fill="#CD803D"
        />
      ))}

      <polyline points={sineWave} fill="none" stroke="black" stroke-width="5" />
    svg>
  );
}

Next Steps – Making SVGs Interactive with JavaScript

Under the hood, SVGs can be quite confusing at first. Lots of coordinates, letters and strange parameters. Once you understand their foundations, though, you can use them to your advantage and start coding images.

And we are just getting started. Adding JavaScript to the mix will introduce a whole new level.

For more examples check out svg-tutorial.com or my YouTube tutorial with 12 more examples on how to use SVGs for your next project!

Embedded content

JavaScript Game Tutorial – Build a Stick Hero Clone with HTML Canvas + JavaScript

Hunor Márton Borbély — Thu, 16 Nov 2023 19:00:55 +0000

In this tutorial, you'll learn how to create a game that's inspired by Stick Hero – using plain JavaScript and HTML canvas.

We are going to recreate Stick Hero, a mobile game published by KetchApp. We'll go through how the game works in general, how to use JavaScript to draw on a element, how to add game logic and animate the game, and how event handling works.

By the end of this guide, you will have built the entire game using plain JavaScript.

Throughout the tutorial, we will be using JavaScript to manipulate the game state and the HTML canvas element to render the game scene. To get the most out of this tutorial, you should have a basic understanding of JavaScript. But even if you are a beginner, you can still follow along and learn as we go.

Let's get started and build our own Stick Hero game using JavaScript and HTML canvas!

If you prefer video format, you can also watch this tutorial on YouTube.

The Stick Hero Game
Game Phases
The Main Parts of the Game
How to Initialize the Game
The Draw Function
Event Handling
The Main Animation Loop
Summary

The Stick Hero Game

In this game, you control a hero who walks from platform to platform by stretching a stick that serves as a bridge. If the stick is the right size, then the hero can safely cross to the next platform. But if the stick is too short or too long, then the hero will fall down.

You can find a playable version of the game we are about to create on CodePen where you can also see the final source code. Give it a try before we get into the details.

You can also check out the original game both on iOS and Android.

Game Phases

The game has five different phases that loop over and over again untilo the hero falls.

Initially, the game is waiting for user input, and nothing is happening.
Then once the player holds the mouse down, the game is stretching a stick upwards until the mouse is released.
Then once the mouse is released the stick starts turning and it falls down, hopefully on the next platform.
If that’s the case, then the hero walks along the stick to the next platform.
Finally, once the hero reaches the next platform, the whole scene transitions to the left to center the hero and the next platform ahead. Then the whole loop restarts from the beginning. The game waits for user input, and once the player holds down the mouse a new stick is drawn.

In a less favorable scenario, the same phases follow each other, but in the walking phase if the other end of the stick doesn’t fall on the next platform, then the hero will only walk until the edge of the stick, and then fall down.

The phases of the game

The Main Parts of the Game

How do we realize this in code? This game has essentially three parts. Game state, the draw function, and the animate function.

We have a game state that is a collection of variables defining every bit of the game. It includes the current phase, the position of the hero, the coordinates of the platforms, the size and rotation of the sticks, and so on.

let phase = "waiting"; // waiting | stretching | turning | walking | transitioning | falling
let lastTimestamp; // The timestamp of the previous animation cycle

let heroX; // Changes when moving forward
let heroY; // Only changes when falling
let sceneOffset; // Moves the whole game

let platforms = [];
let sticks = [];

let score = 0;

...

Then we will have two main functions: one that paints the scene on the screen based on this state (this will be the draw function), and one that will change this state gradually so that it looks like an animation (this will be the animate function). Finally, we're also going to have event handling that will kick off the animation loop.

How to Initialize the Game

To start, let’s initialize the project with a simple HTML, CSS, and JavaScript file. We'll establish the outline of the code and then initialize the state of the game.

The HTML

The HTML part of this game is very simple. Most of the game will live inside the element. We are going to use JavaScript to draw on this canvas. We also have a div element that will display the score and a restart button.

In the header, we also load our CSS and JavaScript files. Note the defer tag when loading the script. This will execute the script only after the rest of the HTML is loaded, so we can access parts of the HTML (like the canvas element) right away in our script.

html>
<html>
  <head>
    <title>Stick Herotitle>
    <link rel="stylesheet" href="index.css" />
    <script src="index.js" defer>script>
  head>

  <body>
    <div class="container">
      <canvas id="game" width="375" height="375">canvas>
      <div id="score">div>
      <button id="restart">RESTARTbutton>
    div>
  body>
html>

The CSS

The CSS won’t contain too many things either. We paint the game on the canvas element and the content of the canvas element cannot be styled with CSS. Here we only style the position of our canvas, our score element and the reset button.

Note, that the reset button by default is invisible. We are going to make it visible using JavaScript once the game ends.

html,
body {
  height: 100%;
}

body,
.container {
  display: flex;
  justify-content: center;
  align-items: center;
}

.container {
  position: relative;
  font-family: Helvetica;
}

canvas {
  border: 1px solid;
}

#score {
  position: absolute;
  top: 30px;
  right: 30px;
  font-size: 2em;
  font-weight: 900;
}

#restart {
  position: absolute;
  display: none;
}

The Outline of Our JavaScript File

And finally, the JavaScript part is where all the magic lives. For simplicity, I have put everything in one file, but feel free to break it down into multiple files.

We are going to introduce a few more variables and a few more functions, but this is the outline of this file. The following things are included:

We define various variables that together make up the game state. More on their values in the section on how to initialize state.
We are going to define a few variables as configuration, like the size of the platforms and how fast the hero should move. We cover them in the drawing section and at the main loop.
A reference to the element in HTML, and getting the drawing context of it. This will be used by the draw function.
A reference to the score element and the restart button in HTML. We will update the score each time the hero traverses to a new platform. And we show the reset button once the game is over.
We initialize the game state and paint the scene by calling the resetGame function. This is the only top-level function call.
We define the draw function that will draw the scene on the canvas element based on the state.
We set up event handlers for the mousedown and mouseup events.
We define the animate function that will manipulate the state.
And we will have a few utility functions that we will discuss later.

// Game state
let phase = "waiting"; // waiting | stretching | turning | walking | transitioning | falling
let lastTimestamp; // The timestamp of the previous animation cycle

let heroX; // Changes when moving forward
let heroY; // Only changes when falling
let sceneOffset; // Moves the whole game

let platforms = [];
let sticks = [];

let score = 0;

// Configuration
...

// Getting the canvas element
const canvas = document.getElementById("game");

// Getting the drawing context
const ctx = canvas.getContext("2d");

// Further UI elements
const scoreElement = document.getElementById("score");
const restartButton = document.getElementById("restart");

// Start game
resetGame();

// Resets game state and layout
function resetGame() {
  ...

  draw();
}

function draw() {
  ...
}

window.addEventListener("mousedown", function (event) {
  ...
});

window.addEventListener("mouseup", function (event) {
  ...
});

function animate(timestamp) {
  ...
}

...

How to Initialize the State

To start the game, we call the same function as we use for resetting it – the resetGame function. It initializes/resets the state of the game and calls the draw function to paint the scene.

The game state includes the following variables:

phase: The current phase of the game. Its initial value is waiting.
lastTimestamp: Used by the animate function to determine how much time has passed since the last animation cycle. We'll cover it later in more detail.
platforms: An array containing the metadata of each platform. Each platform is represented by an object with an x and a w property representing their X position and width. The first platform is always the same – as defined here – to make sure it has a reasonable size and position. The following platforms are generated by a utility function. As the game progresses, more and more platforms are generated on the fly.
heroX: The X position of the hero. By default, the hero stands close to the edge of the first platform. This value will change during the walking phase.
heroY: The Y position of the hero. By default, it is zero. It only changes if the hero is falling.
sceneOffset: As the hero moves forward, we need to shift the entire screen backwards to keep the hero centered on the screen. Otherwise the hero will walk off the screen. In this variable, we keep track of by how much should we shift back the entire screen. We will update this value during the transitioning phase. By default its value is 0.
sticks: Metadata of the sticks. While the hero can only stretch one stick at a time, we also need to store the previous sticks in order to be able to render them. Therefore the sticks variable is also an array.

Each stick is represented by an object with the x, length, and rotation properties. The x property represents the starting position of the stick that always matches the corresponding platform’s top-right corner. Its length property will grow in the stretching phase, and its rotation property will go from 0 to 90 in the turning phase. Or from 90 to 180 in the falling phase.

Initially, the sticks array has one ‘invisible’ stick with 0 length. Every time the hero reaches a new platform, a new stick is added to the array.

score: The score of the game. It shows how many platforms the hero reached. By default it is 0.

function resetGame() {
  // Reset game state
  phase = "waiting";
  lastTimestamp = undefined;

  // The first platform is always the same
  platforms = [{ x: 50, w: 50 }];
  generatePlatform();
  generatePlatform();
  generatePlatform();
  generatePlatform();

  // Initialize hero position
  heroX = platforms[0].x + platforms[0].w - 30; // Hero stands a bit before the edge
  heroY = 0;

  // By how much should we shift the screen back
  sceneOffset = 0;

  // There's always a stick, even if it appears to be invisible (length: 0)
  sticks = [{ x: platforms[0].x + platforms[0].w, length: 0, rotation: 0 }];

  //Score
  score = 0;

  // Reset UI
  restartButton.style.display = "none"; // Hide reset button
  scoreElement.innerText = score; // Reset score display

  draw();
}

At the end of this function, we also reset the UI by making sure the reset button is hidden and the score is displayed as 0.

Once we've initialized the state of the game and reset the UI, the resetGame function calls the draw function to paint the screen for the first time.

The resetGame function calls a utility function that generates a random platform. In this function, we define what is the minimum distance between two platforms (minumumGap) and what is the maximum distance (maximumGap). We also define what is the minimum width of a platform and what is the maximum width.

Based on these ranges and the existing platformsk, we generate the metadata of a new platform.

function generatePlatform() {
  const minimumGap = 40;
  const maximumGap = 200;
  const minimumWidth = 20;
  const maximumWidth = 100;

  // X coordinate of the right edge of the furthest platform
  const lastPlatform = platforms[platforms.length - 1];
  let furthestX = lastPlatform.x + lastPlatform.w;

  const x =
    furthestX +
    minimumGap +
    Math.floor(Math.random() * (maximumGap - minimumGap));
  const w =
    minimumWidth + Math.floor(Math.random() * (maximumWidth - minimumWidth));

  platforms.push({ x, w });
}

The Draw Function

The draw function paints the whole canvas based on the state. It shifts the whole UI by the offset, puts the hero in position, and paints the platforms and the sticks.

Compared to the working demo linked at the beginning of the article, here we will only go through a simplified version of the draw function. We won't cover painting a background, and we'll simplify the hero’s appearance.

We will use this function both for painting the initial scene and throughout our main animation loop.

For the initial paint, some of the features we cover here won't be necessary. For instance, we don’t have any sticks on the scene yet. We'll still cover them, because this way we won’t have to rewrite this function once we start animating the state.

Everything we draw in this function is based on the state, and it doesn't matter if the state is in an initial state, or if we are further into the game.

We defined a element in HTML. But how do we paint things on it? In JavaScript first, we get the canvas element and then get its context somewhere at the beginning of our file. Then we can use this context to execute drawing commands.

We also define a few variables upfront as configuration. We do this because we need to use these values at different parts of our game and we want to maintain consistency.

canvasWidth and canvasHeight represent the size of the canvas element in HTML. They have to match with what we set in HTML. We use these values at various places.
platformHeight represents the height of the platforms. We use these values when drawing the platforms themselves, but also when positioning the hero and the sticks.

The draw function repaints the whole screen from scratch every time. First, let’s make sure that it’s empty. Calling the clearRect function on the drawing context with the correct arguments makes sure we erase everything from it.

...

class="container">
  <canvas id="game" width="375" height="375">canvas>
  <div id="score">div>
  <button id="restart">RESTARTbutton>


...

...

// Getting the canvas element
const canvas = document.getElementById("game");

// Getting the drawing context
const ctx = canvas.getContext("2d");

...

// Configuration
const canvasWidth = 375;
const canvasHeight = 375;
const platformHeight = 100;

...

function draw() {
  ctx.clearRect(0, 0, canvasWidth, canvasHeight);

  ...
}

...

How to Frame the Scene

We also want to make sure that the scene has the correct framing. When we use canvas, we have a coordinate system with the center at the top left corner of the screen that grows to the right and downwards. In HTML we set the width and height attributes both to 375 pixels.

By default the center of the coordinate system is at the top left corner

Initially, the 0, 0 coordinate is at the top-left corner of the screen, but as the hero moves forward the whole scene should shift to the left. Otherwise, we would run out of the screen.

As the game progresses, we update the sceneOffset value to keep track of this shift in the main loop. We can use this variable to translate the whole layout. We call the translate command to shift the scene on the X-axis.

function draw() {
  ctx.clearRect(0, 0, canvasWidth, canvasHeight);

  // Save the current transformation
  ctx.save();

  // Shifting the view
  ctx.translate(-sceneOffset, 0);

  // Draw scene
  drawPlatforms();
  drawHero();
  drawSticks();

  // Restore transformation to the last save
  ctx.restore();
}

It’s important that we do this before we paint anything on the canvas, because the translate command does not actually move anything on the canvas. Anything we painted before on the canvas will stay as it was.

Instead, the translate command shifts the coordinate system. The 0, 0 coordinate won’t be at the top left corner anymore, but it will be out of the screen on the left. Anything we paint after will be painted according to this new coordinate system.

This is exactly what we want. As we progress in the game, the hero will increase its X coordinate. By moving the coordinate system backwards, we make sure that it will be painted within the screen.

Once we use the translate command, the center of the coordinate system will shift to the left

The translate commands accumulate. This means that if we call the translate command twice, the second doesn’t just override the first one, but will add a shift on top of the first command.

We are going to call the draw function in a loop, so it’s important that we reset this transformation every time we draw. Also, we always start with the 0, 0 coordinate in the top left corner. Otherwise, the coordinate system will be shifted to the left infinitely.

We can restore transformations by calling the restore command once we don’t want to be in this shifter coordinate system anymore. The restore command resets transitions and many other settings to the state the canvas was at the last save command. That’s why we often start a painting block by saving the context and end it by restoring it.

How to Draw the Platforms

So that was just the framing, but we haven’t painted anything yet. Let’s start with a simple one, drawing platforms. The metadata of the platforms is stored in the platforms array. It contains the starting position of the platform and its width.

We can iterate over this array and fill a rectangle by setting the starting position, and the width and the height of the platform. We do this by calling the fillRect function with the X, Y coordinates and the width and the height of the rectangle to fill. Note that the Y coordinate is upside down – it's growing from top to bottom.

Drawing the platform

// Example state of platforms
let platforms = [
  { x: 50, w: 50 },
  { x: 90, w: 30 },
];

...

function drawPlatforms() {
  platforms.forEach(({ x, w }) => {
    // Draw platform
    ctx.fillStyle = "black";
    ctx.fillRect(x, canvasHeight - platformHeight, w, platformHeight);
  });
}

What is interesting about canvas, or at least it was surprising to me, is that once you paint something on the canvas you can’t modify it. It’s not like you paint a rectangle, and then you can change its color. Once something is on the canvas it stays as it is.

Like with a real canvas, once you've painted something you can either cover it, by painting something over it, or you can try to clear the canvas. But you can’t change existing parts really. That’s why we set the color here up front and not afterward (with the fillStyle property).

How to Draw the Hero

We won't cover the hero part in detail in this tutorial, but you can find the source code of the demo above on CodePen. Drawing more advanced shapes is a bit more complicated with the canvas element, and I’m going to cover drawing in more detail in a future tutorial.

For now, let’s simply use a red rectangle as a placeholder for the hero. Again, we use the fillRect function and pass on a X, Y coordinate and the width and the height of the hero.

The X and Y positions will be based on the heroX and heroY state. The hero’s X position is relative to the coordinate system, but its Y position is relative to the top of the platform (it has a value of 0 once on top of a platform). We need to adjust the Y position to be on the top of the platform.

function drawHero() {
  const heroWidth = 20;
  const heroHeight = 30;

  ctx.fillStyle = "red";
  ctx.fillRect(
    heroX,
    heroY + canvasHeight - platformHeight - heroHeight,
    heroWidth,
    heroHeight
  );
}

How to Draw the Sticks

Then let’s see how to paint the sticks. Sticks are a bit trickier because they can be rotated.

The sticks are stored in an array in a similar fashion as the platforms but have different attributes. They all have a starting position, a length, and a rotation. The last two changes in the main game loop, and the first one – the position – should fit the top-right corner of a platform.

Based on the length and rotation, we could use some trigonometry and calculate the end position of the stick. But it’s much more interesting if we transform the coordinate system again.

We can use the translate command again, to set the center of the coordinate system to the edge of the platform. Then we can use the rotate command to rotate the coordinate system around this new center.

After using the translate and rotate commands, the coordinate system will be twisted around a new center

// Example state of sticks
let sticks = [
  { x: 100, length: 50, rotation: 60 }
];

...

function drawSticks() {
  sticks.forEach((stick) => {
    ctx.save();

    // Move the anchor point to the start of the stick and rotate
    ctx.translate(stick.x, canvasHeight - platformHeight);
    ctx.rotate((Math.PI / 180) * stick.rotation);

    // Draw stick
    ctx.lineWidth = 2;
    ctx.beginPath();
    ctx.moveTo(0, 0);
    ctx.lineTo(0, -stick.length);
    ctx.stroke();

    // Restore transformations
    ctx.restore();
  });
}

After the translate and rotate commands, the starting point of the stick will be at the 0, 0 coordinate and the coordinate system will be rotated.

In this example, we draw a line upwards – both its beginning and its end have the same X coordinate. Only the Y coordinate is changing. Yet the line is heading to the right because the whole coordinate system has turned. Now upwards is in a diagonal direction. It’s a bit mind-twisting, but you can get used to it.

While we draw a line along the Y axis, the line will appear diagonal because of the transformed coordinate system

The actual drawing of the line is also interesting. There’s no simple line-drawing command so we have to draw a path.

We get a path by connecting multiple points. We can connect them with arcs, curves, and straight lines. In this case, we have a very simple one. We just begin a path (beginPath), move to a coordinate (moveTo), then draw a straight line to the next coordinate (lineTo). Then we finish it with the stroke command.

We can also finish the path with the fill command, but that only makes sense with shapes.

Note that because we shift and turn the coordinate system here again, at the end of this function we need to restore transformations (and save the transformation matrix at the beginning of this function). Otherwise, all upcoming drawing commands would be twisted like this.

Event Handling

Now that we have drawn the scene, let’s kick off the game by handling user interactions. Handling events is the easiest part of the game. We are listening to the mousedown and the mouseup event, and we handle the click event of the restart button.

Once the user holds the mouse down, we initiate the stretching phase by setting the phase variable to stretching. We reset the timestamp that the main event loop is going to use (we get back to this later), and we trigger the main event loop by requesting an animation frame for the animate function.

All these are only happening if the current state of the game is waiting. In any other case, we ignore the mousedown event.

let phase = "waiting";
let lastTimestamp;

...

const restartButton = document.getElementById("restart");

...

window.addEventListener("mousedown", function () {
  if (phase == "waiting") {
    phase = "stretching";
    lastTimestamp = undefined;
    window.requestAnimationFrame(animate);
  }
});

window.addEventListener("mouseup", function () {
  if (phase == "stretching") {
    phase = "turning";
  }
});

restartButton.addEventListener("click", function (event) {
  resetGame();
  restartButton.style.display = "none";
});

...

Handling the mouseup event is even simpler. If we are currently stretching a stick, then we stop that and move to the next phase when the stick falls down.

Finally, we also add an event handler for the restart button. The reset button is hidden by default and will be only visible once the hero has fallen. But we can already define its behavior, and once it appears it will work. If we click reset, we call the resetGame function to reset the game and hide the button.

That’s all the event handling we have. The rest now depends on the main animation loop that we just invoked with a requestAnimationFrame.

The Main Animation Loop

The main loop is the most complicated part of the game. This is a function that will keep changing the state of the game and calling the draw function to repaint the whole screen based on this state.

As it’s going to be called 60 times every second, the constant repainting of the screen will make it look like a continuous animation. Because this function is running so frequently, we only change the game state little by little each time.

This animate function gets triggered as a requestAnimationFrame call by the mousedown event (see above). With its last line, it keeps invoking itself until we don’t stop it by returning from the function.

There are only two cases when we would stop the loop: when moved to the waiting phase and there’s nothing to animate, or when the hero falls down and the game is over.

This function keeps track of how much time has passed since its last call. We are going to use this information to precisely calculate how the state should change. Like when the hero is walking, we need to calculate exactly how many pixels it moves based on its speed and the time passed since the last animation cycle.

let lastTimestamp;

...

function animate(timestamp) {
  if (!lastTimestamp) {
    // First cycle
    lastTimestamp = timestamp;
    window.requestAnimationFrame(animate);
    return;
  }

  let timePassed = timestamp - lastTimestamp;

  switch (phase) {
    case "waiting":
      return; // Stop the loop
    case "stretching": {
      sticks[sticks.length - 1].length += timePassed / stretchingSpeed;
      break;
    }
    case "turning": {
      sticks[sticks.length - 1].rotation += timePassed / turningSpeed;
      ...
      break;
    }
    case "walking": {
      heroX += timePassed / walkingSpeed;
      ...
      break;
    }
    case "transitioning": {
      sceneOffset += timePassed / transitioningSpeed;
      ...
      break;
    }
    case "falling": {
      heroY += timePassed / fallingSpeed;
      ...
      break;
    }
  }

  draw();
  lastTimestamp = timestamp;

  window.requestAnimationFrame(animate);
}

How to Calculate the Time Passed Between Two Renders

Functions invoked with the requestAnimationFrame function receive the current timestamp as an attribute. At the end of every cycle, we save this timestamp value into the lastTimestamp attribute, so that in the next cycle we can calculate how much time passed between two cycles. In the code above, this is the timePassed variable.

The first cycle is an exception because at that point, we didn’t have a previous cycle yet. Initially, the value of lastTimestamp is undefined. In this case, we skip a render and we only render the scene on the second cycle, where we already have all the values we need. This is the part at the very beginning of the animate function.

How to Animate Part of the State

In each phase, we animate a different part of the state. The only exception is the waiting phase because then we have nothing to animate. In that case, we return from the function. This will break the loop, and the animation will stop.

In the stretching phase – when the player is holding the mouse down – we need to grow the stick as the time passes. We calculate how much longer it should be based on the time passed and a speed value that defines how much time it takes for the stick to grow one pixel.

A very similar thing is happening in every other phase as well. In the turning phase, we change the rotation of the stick based on the time passed. In the walking phase, we change the horizontal position of the hero based on time. In the transitioning phase, we change the offset value of the whole scene. In the falling phase, we change the vertical position of the hero.

Each of these phases has its own speed configuration. These values tell how many milliseconds it takes to grow the stick by one pixel, turn the stick by one degree, walk one pixel, and so on.

// Configuration
const stretchingSpeed = 4; // Milliseconds it takes to draw a pixel
const turningSpeed = 4; // Milliseconds it takes to turn a degree
const walkingSpeed = 4;
const transitioningSpeed = 2;
const fallingSpeed = 2;

...

How to Move On to the Next Phase

In most of these phases, we also have a threshold value that ends the phase and triggers the next one. The waiting and stretching phases are the exceptions because their end is based on user interaction. |The waiting phase ends with the mousedown event and the stretching phase ends with the mouseup event.

The turning phase stops when the stick falls flat and its rotation reaches 90 degrees. The walking phase ends when the hero reaches the edge of the next platform or the end of the stick. And so on.

If these thresholds are reached, the main game loop sets the game to the next phase and in the next loop, it will act accordingly. Let’s see these in more detail.

The waiting phase

If we are in the waiting phase and nothing is happening, we return from the function. This return statement means that we never reach the end of the function and there won’t be another request for an animation frame. The loop stops. We need the user input handler to trigger another loop.

In the waiting phase nothing happens

function animate(timestamp) {
    ...

  switch (phase) {
    case "waiting":
      return; // Stop the loop

    ...

  }

    ...
}

The stretching phase

In the stretching phase, we increase the length of the last stick based on the time passed and wait until the user releases the mouse. The last stick is always the one in front of the hero. After every view transition, a new stick is added to the current platform.

In the stretching phase we increase the last stick's length

function animate(timestamp) {
    ...

  switch (phase) {
        ...
    case "stretching": {
      sticks[sticks.length - 1].length += timePassed / stretchingSpeed;
            break;
    }
        ...
  }

  ...
}

The turning phase

In the turning phase, we change the rotation of the last stick. We only do it until the stick reaches 90 degrees because that means the stick has reached a flat position. Then we set the phase to walking, so the next requestAnimationFrame will adjust the hero and not the stick.

In the turning phase we increase the last stick's rotation

Once the stick reaches 90 degrees, then if the stick falls on the next platform, we also increase the score value. We increase the score state and update the innerText attribute of the scoreElement (see the outline of the JavaScript file chapter). Then we generate a new platform to be sure that we never run out of them.

If the stick didn’t fall on the next platform, we don’t increase the score and we don’t generate a new platform. We also don’t trigger the falling phase yet either, because first the hero still tries to walk along the stick.

function animate(timestamp) {
  ...

  switch (phase) {
    ...
    case "turning": {
      sticks[sticks.length - 1].rotation += timePassed / turningSpeed;

      if (sticks[sticks.length - 1].rotation >= 90) {
        sticks[sticks.length - 1].rotation = 90;

        const nextPlatform = thePlatformTheStickHits();
        if (nextPlatform) {
          score++;
          scoreElement.innerText = score;

          generatePlatform();
        }

        phase = "walking";
      }
      break;
    }
    ...
  }

  ...
}

This phase uses a utility function to figure out whether the stick will land on the platform or not. It calculates the right end position of the last stick and checks if this position falls between the left and right edge of a platform. If it does, it returns the platform, if not then it returns undefined.

function thePlatformTheStickHits() {
  const lastStick = sticks[sticks.length - 1];
  const stickFarX = lastStick.x + lastStick.length;

  const platformTheStickHits = platforms.find(
    (platform) => platform.x < stickFarX && stickFarX < platform.x + platform.w
  );

  return platformTheStickHits;
}

The walking phase

In the walking phase, we move the hero forward. The end of this phase depends on whether the stick reaches the next platform or not. To determine this, we use the same utility function we just defined above.

In the walking phase we increase the hero's X position

If the end of the stick falls on a platform, then we limit the hero’s position to the edge of that platform. Then once it’s reached, we go to the transitioning phase. If the end of the stick didn’t fall on a platform, though, we limit the hero's forward movement until the end of the stick and then we start the falling phase.

function animate(timestamp) {
  ...

  switch (phase) {
    ...
    case "walking": {
      heroX += timePassed / walkingSpeed;

      const nextPlatform = thePlatformTheStickHits();
      if (nextPlatform) {
        // If the hero will reach another platform then limit its position at its edge
        const maxHeroX = nextPlatform.x + nextPlatform.w - 30;
        if (heroX > maxHeroX) {
          heroX = maxHeroX;
          phase = "transitioning";
        }
      } else {
        // If the hero won't reach another platform then limit its position at the end of the pole
        const maxHeroX =
          sticks[sticks.length - 1].x +
          sticks[sticks.length - 1].length;
        if (heroX > maxHeroX) {
          heroX = maxHeroX;
          phase = "falling";
        }
      }
      break;
    }
    ...
  }

  ...
}

The transitioning phase

In the transitioning phase, we move the whole scene. We want to hero to stand at the same position on the screen where it initially stood, but now it’s standing on a different platform. This means that we have to calculate by how much we should shift the whole scene back to achieve the same position. Then just set the phase to waiting and we wait for another mouse event.

In the transitioning phase we shift the whole view

function animate(timestamp) {
    ...

  switch (phase) {
        ...
    case "transitioning": {
      sceneOffset += timePassed / transitioningSpeed;

      const nextPlatform = thePlatformTheStickHits();
      if (nextPlatform.x + nextPlatform.w - sceneOffset < 100) {
        sticks.push({
          x: nextPlatform.x + nextPlatform.w,
          length: 0,
          rotation: 0,
        });
        phase = "waiting";
      }
      break;
    }
        ...
  }

  ...
}

We know we've reached the right position when the right side of the platform – shifted by the offset – reaches the first platform's original right-side position. If we look back at initializing the platform, we see that the first platform always has an X position of 50 and its width is also always 50. This means that its right end will be at 100.

At the end of this phase, we also added a new stick to the sticks array with initial values.

The falling phase

In the failing scenario, two things are changing: the hero’s position and the last stick’s rotation. Then once the hero has fallen out of the screen, we stop the game loop again by returning from the function.

In the falling phase we both increase the Y position of the hero and the rotation of the last stick

function animate(timestamp) {
    ...

  switch (phase) {
        ...
    case "falling": {
      heroY += timePassed / fallingSpeed;

      if (sticks[sticks.length - 1].rotation < 180) {
        sticks[sticks.length - 1].rotation += timePassed / turningSpeed;
      }

      const maxHeroY = platformHeight + 100;
      if (heroY > maxHeroY) {
        restartButton.style.display = "block";
        return;
      }
      break;
    }
        ...
  }

  ...
}

So that’s the main loop – how the game moves from phase to phase, changing a range of variables. At the end of every cycle the function calls the draw function to update the scene and requests another frame. If you did everything right, you should have a working game now!

Summary

In this tutorial, we covered a lot. We learned how to paint basic shapes on a canvas element with JavaScript and we implemented a whole game.

Despite the length of this article, there are still a few things we did not cover here. You can check out the source code of this game for additional features on CodePen. These include:

How to make the game fit the whole browser window and translate the screen accordingly.
How to draw a background to the scene and how to draw a more detailed version of our hero.
We add a double score zone to the middle of each platform. If the end of the stick falls into this very small region, the hero scores two points.

I hope you enjoyed this tutorial. Stay tuned for more here on freeCodeCamp and on my YouTube channel.

How TypeScript Helps You Write Better Code

Hunor Márton Borbély — Fri, 03 Nov 2023 15:16:26 +0000

TypeScript is taking over the web. In this article I'll give you a high-level overview of the benefits of TypeScript and how can it help you create websites with fewer bugs.

You'll learn how TypeScript helps with handling edge cases, catching typos, refactoring code, and how types make code easier to understand.

The latest State of JavaScript survey found that developers spend more time writing TypeScript than JavaScript code. GitHub’s own survey states a more modest claim, saying that TypeScript is only the 4th most used language on the platform – behind JavaScript – yet its usage grew by almost 40% in a year. Why is this shift happening?

Graph showing percentage of their time devs spend writing JavaScript vs TypeScript

If you prefer video format you can also watch this article as a video with a bit more content.

What are Types?

You may know that in JavaScript (as in other programming languages), there are various data types like strings, numbers, arrays, objects, functions, booleans, undefined and null values. These are all types.

But JavaScript is dynamically typed, which means that variables can change types. You can set the value of a variable to a string in one line and set the same variable to a number in another line, for example:

let value = 'Hello';
value = 3;

On the one hand, this is a benefit of the language. It means that it's simple and very flexible. You don't have to restrict yourself by setting types.

On the other hand, you can easily shoot yourself in the foot if you are not careful enough. When you write JavaScript, it is your responsibility to use the right type of value in your code.

If you accidentally use the wrong types, you will run into errors. Have you tried getting the length of undefined? Don't try, it throws you an error. But maybe you had an edge case that changed your value and you didn't realize it:

value = 3;
...
console.log(value.length); // TypeError: Cannot read properties of undefined

Because the variables can change type at any time, JavaScript only checks if your code will work when you run it. You don't know you have an error until you run the code.

And if you only have an error in a very rare edge case, maybe you don't even realize that your code might fail for a very long time. When you write the code, JavaScript doesn't warn you that you might have an issue.

TypeScript, on the other hand, is statically typed. This means that variables can't change type. This makes the code more predictable and it allows TypeScript to analyze the code as you write it and spot mistakes as they occur (so they don't show up as errors in your code later).

Alright, now that you have a basic understanding of what types are and how JavaScript and TypeScript differ in how they handle them, let's dive into the main partf of the tutorial.

You're Already Using TypeScript

Let’s review the basics: TypeScript gives you type information. It tells you the types of your variables, the type of the arguments you need to pass on to your functions, and what kind of data they will return.

But what if I tell you that you're already using TypeScript, even in plain JavaScript?

Let’s take this quick example. This is a plain JavaScript file in VS Code. Because VS Code and TypeScript are both made by Microsoft, VS Code already comes with built-in TypeScript features.

When you hover over your variables, VS Code will tell their type whenever possible

function getGreeting(str) {
    return `Hello ${str}!`;
}

let input = 'Bob'; // Type: string
let greeting = getGreeting(input); // Type: string
let greetingLength = greeting.length; // Type: number

console.log(greeting, greetingLength);

If you hover over the input variable, VS Code will tell you that its type is a string. This is quite clear, as we've assigned a string to it in the very same line.

But if we go further and check the type of greeting it also says it’s a string. This is a bit more interesting. Greeting’s value comes from a function. How do we know that it’s a string?

VS Code, with the help of TypeScript, analyses the function, checks every possible return path, and concludes that the only thing that this function can return is a string.

Of course, this is a very simple example. But even if we had a more complex logic, with multiple different return statements, TypeScript would still analyze every different path and would tell you what the possible return values are.

To stick a little longer with this example, if we hover over the length variable we are going to see that its type is a number. This might seem obvious again, but the logic behind it is smarter than it looks.

The length property of a string is a number. But this is only true if we are looking at a string. In this case, we know that it is a string because TypeScript already figured out that the return type of our function is a string. There are multiple steps here behind the scenes.

So the first reason why TypeScript is awesome: you can see the types of values just by hovering over them. And this even works to some extent in plain JavaScript.

Checking the required arguments for built-in functions

Let’s see another example. This code is still in JavaScript, we still don’t define types explicitly, but the TypeScript parser can still derive the types.

Here we have an input value, again we hardcode it to ‘bob’, and then we capitalize the string. We take the first character, make it upper case, then add the rest of the string in lower case.

You can check the signature of JavaScript functions in VS Code

let input = 'bob';
let formattedInput = 
    input.charAt(0).toUpperCase() + input.slice(1).toLowerCase();
let formattedLength = formattedInput.length;

console.log(greeting, greetingLength);

We can check the function signature of these functions. We can see that charAt requires a number parameter, toUpperCase does not require any parameters, and the slice function has two optional parameters that can be either a number or undefined.

These are TypeScript annotations. The question marks mean that a value is optional, and the pipe characters mean that a type could be either this or that.

In summary, we know that our formatted input is of type string.

Where JavaScript can’t figure out the types anymore

Let’s extract the logic that capitalizes our input into a function. The types should remain the same, right? Well, not exactly. Now our capitalized input is of type any.

After we extracted the logic that capitalizes the input, the return value is now of type 'any'

function capitalize(str) {
    return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
}

let input = 'bob';
let formattedInput = capitalize(input); // Type: any
let formattedLength = formattedInput.length;

Interesting! What happened? Our function should always return a string, right? If you look at the entire code base in this specific case, then yes. It should return a string.

But we have to look at the function in isolation. We can’t assume what it will receive. We could also pass on a number to it and in that case, it would fail. You can’t read the first character of a number or turn it to lower or upper case.

In JavaScript we can’t state that we need a string here, so we can’t be sure that the function returns a string. In TypeScript we are going to specify the type of this parameter to avoid any confusion.

You might notice that the previous example with the getGreeting function was different. There, no matter what the input was, the function always returned a string. Here, however, the output depends on the input.

What About Edge Cases in JavaScript?

Could we avoid getting an error in case we get the wrong input in JavaScript? Yes.

Checking the type early and returning before the function can fail is one way to make our function fail-safe. This is still JavaScript, and the typeof operator is part of JavaScript.

Now this function won't fail. But I introduced a bug.

After adding an early return statement to our capitalize function, the type of the returned value changed from any to string or undefined

function capitalize(str) {
    if (typeof str !== 'string') return;
    return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
}

let input = 'bob';
let formattedInput = capitalize(input); // Type: string or undefined
let formattedLength = formattedInput.length;

If we check the function signature or the type of the new value, it has changed from any to string | undefined.

In one way that is very neat. We limited the possible return values and we have a better understanding of what the function does, just by looking at the returned value. On the other hand, in case it returns undefined, the application will fail in the very next line. You can’t check the length of undefined.

Of course, we could have also returned an empty string as a fallback and then we wouldn’t have this problem. We're working with strings here. But this is a great example of a topic that is very easy to overlook in JavaScript and which can cause you a lot of headaches later: edge cases.

What if you didn’t write the capitalize function and you didn’t know how exactly it works?

Maybe it is also located in a different file and you simply assumed that it would always return a string. Maybe the function you use is much longer and much more complicated.

Maybe you checked the function, but only the last line of it and say ‘Okay, this function returns a string’. And you completely miss that in a different line – that can also be in the middle of the function – there is another return statement that returns a different type of value.

The point here is that edge cases can happen and it’s very easy to miss them. It’s a typical source of bugs when developers cover the happy path of an application, but they are less attentive when covering edge cases.

In JavaScript, you need to be mindful of edge cases, test different scenarios and user inputs, and write thorough unit tests to make sure your logic doesn’t fail.

Wouldn’t it be nice if the editor would tell you that you have a problem?

Turn the Code into TypeScript

So after all this introduction, let’s finally turn this code into TypeScript. To do so, let’s simply change the extension from .js to .ts and see what happens.

Right away, we'll see an error saying that our formattedInput might be undefined. And that doesn’t work well with getting the length of the value. We already caught the bug that caused trouble earlier and we didn’t even invest any time in adding types to our code.

After changing the extension to .ts an error is revealing that our capitalized value might be undefined

function capitalize(str) {
    if (typeof str !== 'string') return;
    return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
}

let input = 'bob';
let formattedInput = capitalize(input);
let formattedLength = formattedInput.length; // Error

Before fixing this error, let’s turn on strict mode. By default, TypeScript can be very permissive, but we also get less value out of it without strict mode.

For this, we need a tsconfig.json file at the root of our project. This might seem a bit scary now, but this file is most probably generated for you automatically when you create a project with any of the frameworks. What’s important for now is that we have strict mode set to true.

{
    "compilerOptions": {
      "target": "ESNext",
      "module": "ESNext",
      "strict": true,
      "esModuleInterop": true,
      "skipLibCheck": true,
      "forceConsistentCasingInFileNames": true,
      "lib": ["DOM", "ESNext"],
      "moduleResolution": "node",
      "noImplicitAny": true,
      "allowSyntheticDefaultImports": true,
      "baseUrl": "./src",
      "paths": {
        "*": ["src/*"]
      },
      "outDir": "./dist",
      "rootDir": "./src",
      "strictPropertyInitialization": false,
      "noEmit": false,
    },
    "include": ["src/**/*.ts", "src/index.js"],
    "exclude": ["node_modules"]
  }

This will show more errors because with this setting we have to define the types of our function arguments.

After turning on strict mode, we have to set the type of function arguments

function capitalize(str) { // Error
    if (typeof str !== 'string') return;
    return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
}

let input = 'bob';
let formattedInput = capitalize(input);
let formattedLength = formattedInput.length; // Error

So let’s specify that our capitalize function requires a string by setting the argument to str: string. And that’s all the types we need to add in this case because that’s the only one TypeScript couldn’t figure out itself.

Setting the type of the function's argument to string

function capitalize(str: string) {
    if (typeof str !== 'string') return;
    return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
}

let input = 'bob';
let formattedInput = capitalize(input);
let formattedLength = formattedInput.length; // Error

One misconception about TypeScript is that you have to add types to everything. While that’s not a bad practice it is not strictly necessary. TypeScript is very smart. It analyses the code and figures out the types of as many things as possible.

We can of course specify types at other places. We can specify that we need our formattedInput value to be a string by setting let formattedInput: string. This is our whole problem here. We thought it was a string, but in some cases, it wasn’t.

After setting the type of the 'formattedInput' variable, the error changed

function capitalize(str: string) {
    if (typeof str !== 'string') return;
    return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
}

let input = 'bob';
let formattedInput: string = capitalize(input); // Error
let formattedLength = formattedInput.length;

This highlights our problem right away. We want it to be a string, but our function might return undefined. We can read in the popover that undefined cannot be assigned to type string.

We can go further, by saying we want this function to return a string. This again will change the error. Now the problem is not that we can’t assign the returned value to a string variable, but that the function itself returns an incorrect value.

After setting the return type of the capitalize function, the error changed again

function capitalize(str: string): string {
    if (typeof str !== 'string') return; // Error
    return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
}

let input = 'bob';
let formattedInput: string = capitalize(input);
let formattedLength = formattedInput.length;

To solve this, let’s delete this whole line. Earlier we added this line for type checking, but now, we let TypeScript do the whole type checking for us. The function signature already states that this property has to be a string, there’s no need to check it again. Our code got simpler, and at the same time safer.

So another reason why TypeScript is amazing is that it forces you to think of edge cases. Not just to think of them, but also to handle them. Something that’s very easy to overlook in JavaScript.

Refactoring the Code

Now that we've got the basics, let’s go on to our third topic: refactoring. Let’s update our greeting function a bit, and let’s say it now takes two arguments: a first name and a last name. Imagine that this is a utility function that is used in many places in a huge, complex project:

Our new updated 'getGreeting' function that receives a first name and a last name

export function getGreeting(firstName: string, lastName: string) {
    const formattedFirstName = capitalize(firstName);
    const formattedLastName = capitalize(lastName);
    return `Hello ${formattedFirstName} ${formattedLastName}!`;
}

function capitalize(str: string): string {
    return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
}

What if we decide that we need to refactor this code? Instead of passing on two strings, we want to pass in an object that has the first name and last name properties.

In TypeScript, we can precisely define the shape of an object. We can define that we have to pass on a person parameter that should be an object with a firstName and a lastName property, that both have to be strings.

We can define a type for this argument. We say that we have a Person type with capital P by convention. This type describes an object with the firstName and lastName properties that are both strings.

We can even add more things if we want, like adding a birthday property that has a type Date. But let’s make this optional because we don’t want to deal with it for now.

Adding a question mark here makes this property optional. We can set it, but we don’t have to. But when we try to use it, we also can’t assume that it does exist.

After changing the function argument type, the editor highlights the parts we need to change

type Person = {
    firstName: string,
    lastName: string,
    birthDay?: Date
}

export function getGreeting(person: Person) {
    const formattedFirstName = capitalize(firstName);
    const formattedLastName = capitalize(lastName);
    return `Hello ${formattedFirstName} ${formattedLastName}!`;
}

function capitalize(str: string): string {
    return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
}

Now we can set that our person argument is of type Person.

As we do this change the editor lights up in red. It says that I’m trying to use variables that don’t exist. In this function, I’m referring to firstName and lastName, and there’s only a person object now.

Even more, the other files in the file explorer light up as well, saying that I called the function with two arguments even though it expects only one.

Let’s fix the error in this file and replace firstName and lastName with person.firstName and person.lastName. TypeScript is very picky about using variables that don’t exist.

To give you an even better example: What if I made a typo here? What if I miss a letter from firstName? This could be a very easily overlooked problem in JavaScript. Here, though, it’s not only highlighted that there’s no such property on a Person, but it even suggests that you might want to use firstName instead.

If we make a typo, the editor suggests corrections

type Person = {
    firstName: string,
    lastName: string,
    birthDay?: Date
}

export function getGreeting(person: Person) {
    const formattedFirstName = capitalize(person.frstName);
    const formattedLastName = capitalize(person.lastName);
    return `Hello ${formattedFirstName} ${formattedLastName}!`;
}

function capitalize(str: string): string {
    return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
}

Then, let’s fix the errors in the other files. As you can see the files with an error are already highlighted in the file explorer. This is of course a very simple example, but imagine you have a huge project and this function is called in a hundred different places. Of course, you can be thorough and fix all of them one by one, but in JavaScript, it would be very easy to miss one of them.

When updating the function calls, TypeScipt gives you errors if we make mistakes

import { getGreeting } from "./utils";

let greeting = getGreeting({ firstName: 'bob', lastName:  'marley' });

console.log(greeting);

Now here, the error says that we pass on two parameters, but only one is expected. If we simply delete the second argument it says we pass on a string, but it expected an object of type Person. If we pass on an object with the first name only, it will still complain that we're missing the last name. If we add the last name, but again with a typo, then again it will say that we have a wrong property and it even suggests that we might have made a typo here.

TypeScript is very precise about what our issue is, and we can easily figure out how to fix it.

Now let’s fix the other file. Instead of inlining the argument, we can also define it as a variable and TypeScript will recognize that an object of this shape fits the criteria of this function.

If we want to be sure that our variable is of type Person, we can also import the type and set it to this object. First, we need to export it, in the utility file, and then can import it just as our function, then assign it to our object.

We can also use our Person type in other files

import { Person, getGreeting } from "./utils";

let person: Person = {
    firstName: 'bob',
    lastName: 'dylan'
}

let greeting = getGreeting(person);

console.log(greeting);

Summary

TypeScript can be much more complicated than this. But that’s the gist of it. For the most part you define your own types and TypeScript makes sure that you use them correctly.

In summary, there are three main reasons you want to consider using TypeScript:

You get type information about functions
You know what they return
You know what they expect from you, even without looking at the function itself

TypeScript makes sure that you wire together your application correctly. It forces you to call functions with the right arguments and it forces you to think about edge cases.

TypeScript helps a lot during refactoring. It doesn’t let you miss any part of your code that you need to change and it doesn’t let you get away with typos.

SVG + JavaScript Tutorial – How to Code an Animated Watch

Hunor Márton Borbély — Thu, 23 Dec 2021 17:19:15 +0000

Since SVG images can be inlined in HTML, we can manipulate them with JavaScript. This means that we can animate parts of an image from code, make it interactive, or turn things around and generate graphics from data.

In this example, we are going to create a watch. We will use SVG to paint the watch, and use JavaScript to animate the hands.

This tutorial is a bit more advanced, going in-depth with some of the less obvious SVG properties and focusing on animation with JavaScript. If you'd like to get a more general overview of SVGs, then check out my earlier article where we walk through the code of 7 simple SVG images.

You can also watch this article as a video with a bit more content. In the video we also cover interaction.

SVG in HTML

In the previous article, we learned that SVG images can be inlined in an HTML document. We talked about the SVG tag itself, which defines the size of the image, and the placement of the image elements.

Image elements are placed within the image by their position. The viewBox defines how these positions should be interpreted.

The first two numbers of the property set the position at the top-left corner. Together with the size defined by the last two numbers, they form a coordinate system.

<html>
  <head>
    <title>Watchtitle>
    <link rel="stylesheet" href="./index.css" />
  head>

  <body>
    <svg width="200" height="200" viewBox="-100 -100 200 200">
      <circle
        cx="0"
        cy="0"
        r="90"
        fill="transparent"
        stroke="#f0f0c9"
        stroke-width="7"
      />
    svg>

    <script src="./index.js">script>
  body>
html>

In this example, we center the coordinate system. The 0,0 coordinate is in the middle of the image. We set with the viewBox that the top-left corner should be the -100,-100 coordinate and both the width and height should be 200 units.

In this example, the size defined by width and height and the size defined by viewBox are the same. This means that one unit within the image will be one pixel in the browser. This is not always true. If the two don't match then the image scales up or scales down.

How to Make the Watch's Minute and Hour Hands

Now that we've established our foundations, let's start coding the watch itself. We start with the minute and hour hands.

There are many ways to draw these little lines. We could draw each line one by one, but probably the most effective way to draw it is to draw a circle with a special dash property.

The circle tag in our initial example has a center position, a radius for the size, a fill and border color, and a border width.

SVG elements often have similar styling options as HTML elements with CSS. But these options have different property names. You can think of the fill property as background-color in CSS. And the stroke and stroke-width properties are also similar to the border-color and border-width properties. Just keep in mind that they are not exactly the same.

We will also use the fill property for setting text color, and we will use the stroke property to set the color of a line.

Now how do we turn a continuous circle into minute markers? You might be familiar with the border-style property in CSS. Mostly you would use a solid border, but you can also have a dotted or a dashed one. These border styles are not very common, as you don’t have that many options to fine-tune them in CSS.

The border-style property in CSS for HTML elements

In SVG we have similar possibilities with much more customization options. We can use the stroke-dasharray, the stroke-dashoffset, and the pathLength properties.

Let’s have a few examples. In the first example, we set a single number as stroke-dasharray. This will result in a dashed border where the line segment and the gap both have the same length.

The stroke-dasharray property for SVG

This property is an array though. If we set two numbers, then the first one will be the length of the line segment, and the second will be the length of the gap. You can even set more than two numbers, and then the length of the line and the gap will always take the next number. Until it runs out of the array and then it starts at the beginning.

We will set two numbers. One for the length of the minute marker, and one for the gap between them. The sum of these two should be exactly the length of one minute on the circle. We know that one hour is 60 minutes. So we can calculate the circumference of the circle, then divide it by 60 to get the length of one minute.

But there’s a better way. Instead of calculating the circumference of the circle, we can go the other way. We can set the pathLength property.

This property is a bit tricky. It does not resize the circle but affects how the dasharray property is interpreted. The dashes will be drawn as if the circle had a circumference defined by pathLength.

So let’s set the pathLength to 60, representing 60 minutes. Now the sum of the line and gap segment has to be 1 in total. I set it to 0.2 and 0.8 in this example.

Using the pathLength property. Note that the sum of the two numbers at the stroke-dasharray property is one, matching the length of one minute.

Now we are almost done, but one little piece is still missing. The dashing starts at the wrong position. To fix it we have to shift it by half of the line segment’s length using the stroke-dashoffset property.

The dash offset property can be a bit counterintuitive, as a positive value here shifts the dashing backwards. You can also set it to a positive number to shift it forward.

Example with and without stroke-dashoffset

In the same way, we can set an hour marker. We add a new circle tag with almost the same properties. The only thing that is different is the color and we have longer gaps in the dash array.

. . .

    <svg width="200" height="200" viewBox="-100 -100 200 200">
      <circle
        cx="0"
        cy="0"
        r="90"
        fill="transparent"
        stroke="#0f0e0e"
        stroke-width="7"
        stroke-dasharray="0.2 0.8"
        stroke-dashoffset="0.1"
        pathLength="60"
      />

      <circle
        cx="0"
        cy="0"
        r="90"
        fill="transparent"
        stroke="#f0f0c9"
        stroke-width="7"
        stroke-dasharray="0.2 4.8"
        stroke-dashoffset="0.1"
        pathLength="60"
      />
    svg>

. . .

It's important to note here that layering in SVG matters. Tags added later in the document will be on top of the previous ones. If we add these two circles in the opposite order, then the minutes would fully cover the hour markers.

As SVG lives in HTML now, we can move some of these properties from CSS. We can’t move all the properties though. There’s a difference between properties defining the style and those defining the shape of an element.

The radius, for instance, defines the shape of the circle, so it has to stay with the SVG code. The fill and stroke properties on the other hand we can move.

. . .

    <svg width="200" height="200" viewBox="-100 -100 200 200">
      <circle class="minute_marker" r="90" pathLength="60" />
      <circle class="hour_marker" r="90" pathLength="60" />
    svg>

. . .

.hour_marker {
  fill: transparent;
  stroke: #f0f0c9;
  stroke-width: 7;
  stroke-dasharray: 0.2, 4.8;
  stroke-dashoffset: 0.1;
}

.minute_marker {
  fill: transparent;
  stroke: #0f0e0e;
  stroke-width: 7;
  stroke-dasharray: 0.2, 0.8;
  stroke-dashoffset: 0.1;
}

How to Draw the Watch Hands

Let's add the hands that show the time. Initially, we draw these to point upwards, then turn them into position with JavaScript.

We use the line element to draw the hands. To define a line element we have to set the starting and ending coordinates, along with a stroke color and the stroke-width property.

To make things a bit nicer, we can also add the stroke-linecap property to have rounded line caps. These styling properties we add with CSS.

. . . 

    <svg width="200" height="200" viewBox="-100 -100 200 200">
      <circle class="minute_marker" r="90" pathLength="60" />
      <circle class="hour_marker" r="90" pathLength="60" />

      <line class="hand" x1="0" y1="0" x2="0" y2="-50" />
      <line class="hand hand--thick" x1="0" y1="-12" x2="0" y2="-50" />

      <line class="hand" x1="0" y1="0" x2="0" y2="-80" />
      <line class="hand hand--thick" x1="0" y1="-12" x2="0" y2="-80" />

      <line class="hand hand--second" x1="0" y1="12" x2="0" y2="-80" />
    svg>

. . .

. . .

.hand {
  stroke: #ffffff;
  stroke-width: 2;
  stroke-linecap: round;
}

.hand--thick {
  stroke-width: 7;
}

.hand--second {
  stroke: yellow;
}

How to Point the Watch Hands in the Right Direction

Now how do we turn these lines into position? If we assign an ID to an element we can access it and manipulate it from JavaScript.

Which element should we assign an ID, though? We have two elements for one hand. To solve this problem we can group these two line elements in a group tag. You can think of a group tag as the div element in HTML.

We can assign an ID to this group, then we can rotate the whole group into position from JavaScript.

. . .

    <svg width="800" height="800" viewBox="-100 -100 200 200">
      <circle class="minute_marker" r="90" pathLength="60" />
      <circle class="hour_marker" r="90" pathLength="60" />

      <g id="hour_hand">
        <line class="hand" x1="0" y1="0" x2="0" y2="-50" />
        <line class="hand hand--thick" x1="0" y1="-12" x2="0" y2="-50" />
      g>

      <g id="minute_hand">
        <line class="hand" x1="0" y1="0" x2="0" y2="-80" />
        <line class="hand hand--thick" x1="0" y1="-12" x2="0" y2="-80" />
      g>

      <g id="second_hand">
        <line class="hand hand--second" x1="0" y1="12" x2="0" y2="-80" />
      g>
    svg>

. . .

In the JavaScript file, first, we get the hand elements by ID. Then we create a Date object and we get the current hour, minute, and second. And finally, we set the elements' transform attribute based on these values.

const hoursElement = document.getElementById("hour_hand");
const minutesElement = document.getElementById("minute_hand");
const secondsElement = document.getElementById("second_hand");

const date = new Date();

const hour = date.getHours();
const minute = date.getMinutes();
const second = date.getSeconds();

hoursElement.setAttribute("transform", `rotate(${(360 / 12) * hour})`);
minutesElement.setAttribute("transform", `rotate(${(360 / 60) * minute})`);
secondsElement.setAttribute("transform", `rotate(${(360 / 60) * second})`);

The transform attribute can include multiple transformations like scaling, translating, or skewing.

We are setting the rotate transformation, which requires a number. This number is a rotation between 0 and 360 degrees. For the hour hand, we divide 360 by 12 to get how much rotation we need per hour and multiply it with the current hour. This should turn the hour hand towards the current hour.

For the minute and second hand, we do the same thing, except we divide 360 by 60, as one hour consists of 60 minutes and 1 minute is 60 seconds.

Luckily for us, the transformation center by default is the origin, the 0,0 coordinate. If this wouldn’t be the case we could set another transformation origin, but because of our viewBox settings, we don’t need that.

How to Animate the Watch Hands**

Now, this should already show the current time, but our image is static. To keep up with time we can use the requestAnimationFrame function to move the hands.

const hoursElement = document.getElementById("hour_hand");
const minutesElement = document.getElementById("minute_hand");
const secondsElement = document.getElementById("second_hand");

function animate() {
  const date = new Date();

  const hour = date.getHours() % 12;
  const minute = date.getMinutes();
  const second = date.getSeconds();

  hoursElement.setAttribute("transform", `rotate(${(360 / 12) * hour})`);
  minutesElement.setAttribute("transform", `rotate(${(360 / 60) * minute})`);
  secondsElement.setAttribute("transform", `rotate(${(360 / 60) * second})`);

  requestAnimationFrame(animate);
}

requestAnimationFrame(animate);

We move the rotation logic into an animate function, and use the requestAnimationFrame function.

First, we trigger it by calling requestAnimationFrame outside the animate function. Then, to keep on with the animation we also request another frame at the end of every animation cycle.

If you want to have a smoother animation, then you can refine the positioning. Instead of having discrete positions for the hands, we can define them in a way that they can point to split seconds, minutes, and hours.

const hoursElement = document.getElementById("hour_hand");
const minutesElement = document.getElementById("minute_hand");
const secondsElement = document.getElementById("second_hand");

function animate() {
  const date = new Date();

  const hour = date.getHours() + date.getMinutes() / 60;
  const minute = date.getMinutes() + date.getSeconds() / 60;
  const second = date.getSeconds() + date.getMilliseconds() / 1000;

  hoursElement.setAttribute("transform", `rotate(${(360 / 12) * hour})`);
  minutesElement.setAttribute("transform", `rotate(${(360 / 60) * minute})`);
  secondsElement.setAttribute("transform", `rotate(${(360 / 60) * second})`);

  requestAnimationFrame(animate);
}

requestAnimationFrame(animate);

The hour hand won’t get its position only based on the hour, but it will make a slight turn based on the current minutes as well.

The minute hand will consider the current second in its rotation. And the second hand will also consider milliseconds. This way our hands will have a continuous movement. They won’t jump from second to second, but they will animate.

Next steps – How to Make the Watch Interactive

Now if we check the result, we should have a smoothly animated watch.

To go further, you can also add a calendar window showing the current date, with the text element. And to take it to the next level you can even add an event handler for this element, which toggles its content between the current date and the AM/PM indicator.

If you are stuck, check out the video below, where we also cover this part.

Mixing SVG with JavaScript opens up a lot of cool options. You can animate things, add interactions, and generate graphics. Can't wait to see what you come up with.

Three.js Tutorial - How to Build a Simple Car with Texture in 3D

Hunor Márton Borbély — Mon, 22 Mar 2021 13:47:23 +0000

Putting together a 3D scene in the browser with Three.js is like playing with Legos. We put together some boxes, add lights, define a camera, and Three.js renders the 3D image.

In this tutorial, we're going to put together a minimalistic car from boxes and learn how to map texture onto it.

First, we'll set things up – we'll define the lights, the camera, and the renderer. Then we'll learn how to define geometries and materials to create 3D objects. And finally we are going to code textures with JavaScript and HTML Canvas.

How to Setup the Three.js Project

Three.js is an external library, so first we need to add it to our project. I used NPM to install it to my project then imported it at the beginning of the JavaScript file.

import * as THREE from "three"; 

const scene = new THREE.Scene();

. . .

First, we need to define the scene. The scene is a container that contains all the 3D objects we want to display along with the lights. We are about to add a car to this scene, but first let's set up the lights, the camera, and the renderer.

How to Set Up the Lights

We'll add two lights to the scene: an ambient light and a directional light. We define both by setting a color and an intensity.

The color is defined as a hex value. In this case we set it to white. The intensity is a number between 0 and 1, and as both of them shine simultaneously we want these values somewhere around 0.5.

. . . 

const ambientLight = new THREE.AmbientLight(0xffffff, 0.6);
scene.add(ambientLight);

const directionalLight = new THREE.DirectionalLight(0xffffff, 0.8);
directionalLight.position.set(200, 500, 300);
scene.add(directionalLight); 

. . .

The ambient light is shining from every direction, giving a base color for our geometry while the directional light simulates the sun.

The directional light shines from very far away with parallel light rays. We set a position for this light that defines the direction of these light rays.

This position can be a bit confusing so let me explain. Out of all the parallel rays we define one in particular. This specific light ray will shine from the position we define (200,500,300) to the 0,0,0 coordinate. The rest will be in parallel to it.

As the light rays are in parallel, and they shine from very far away, the exact coordinates don't matter here – rather, their proportions do.

The three position-parameters are the X, Y, and Z coordinates. By default, the Y-axis points upwards, and as it has the highest value (500), that means the top of our car receives the most light. So it will be the brightest.

The other two values define by how much the light is bent along the X and Z axis, that is how much light the front and the side of the car will receive.

How to Set Up the Camera

Next, let's set up the camera that defines how we look at this scene.

There are two options here – perspective cameras and orthographic cameras. Video games mostly use perspective cameras, but we are going to use an orthographic one to have a more minimal, geometric look.

In my previous article, we discussed the differences between the two cameras in more detail. Therefore in this one, we'll only discuss how to set up an orthographic camera.

For the camera, we need to define a view frustum. This is the region in the 3D space that is going to be projected to the screen.

In the case of an orthographic camera, this is a box. The camera projects the 3D objects inside this box toward one of its sides. Because each projection line is in parallel, orthographic cameras don't distort geometries.

. . .

// Setting up camera
const aspectRatio = window.innerWidth / window.innerHeight;
const cameraWidth = 150;
const cameraHeight = cameraWidth / aspectRatio;

const camera = new THREE.OrthographicCamera(
  cameraWidth / -2, // left
  cameraWidth / 2, // right
  cameraHeight / 2, // top
  cameraHeight / -2, // bottom
  0, // near plane
  1000 // far plane
);
camera.position.set(200, 200, 200);
camera.lookAt(0, 10, 0);

. . .

To set up an orthographic camera, we have to define how far each side of the frustum is from the viewpoint. We define that the left side is 75 units away to the left, the right plane is 75 units away to the right, and so on.

Here these units don't represent screen pixels. The size of the rendered image will be defined at the renderer. Here these values have an arbitrary unit that we use in the 3D space. Later on, when defining 3D objects in the 3D space, we are going to use the same units to set their size and position.

Once we define a camera we also need to position it and turn it in a direction. We are moving the camera by 200 units in each dimension, then we set it to look back towards the 0,10,0 coordinate. This is almost at the origin. We look towards a point slightly above the ground, where our car's center will be.

How to Set Up the Renderer

The last piece we need to set up is a renderer that renders the scene according to our camera into our browser. We define a WebGLRenderer like this:

. . .

// Set up renderer
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.render(scene, camera);

document.body.appendChild(renderer.domElement);

Here we also set up the size of the canvas. This is the only place where we set the size in pixels since we're setting how it should appear in the browser. If we want to fill the whole browser window, we pass on the window's size.

And finally, the last line adds this rendered image to our HTML document. It creates an HTML Canvas element to display the rendered image and adds it to the DOM.

How to Build the Car in Three.js

Now let's see how can we can compose a car. First, we will create a car without texture. It is going to be a minimalistic design – we'll just put together four boxes.

How to Add a Box

First, we create a pair of wheels. We will define a gray box that represents both a left and a right wheel. As we never see the car from below, we won't notice that instead of having a separate left and right wheel we only have one big box.

We are going to need a pair of wheels both in the front and at the back of the car, so we can create a reusable function.

. . . 

function createWheels() {
  const geometry = new THREE.BoxBufferGeometry(12, 12, 33);
  const material = new THREE.MeshLambertMaterial({ color: 0x333333 });
  const wheel = new THREE.Mesh(geometry, material);
  return wheel;
}

. . .

We define the wheel as a mesh. The mesh is a combination of a geometry and a material and it will represent our 3D object.

The geometry defines the shape of the object. In this case, we create a box by settings its dimensions along the X, Y, and Z-axis to be 12, 12, and 33 units.

Then we pass on a material that will define the appearance of our mesh. There are different material options. The main difference between them is how they react to light.

In this tutorial, we'll use MeshLambertMaterial. The MeshLambertMaterial calculates the color for each vertex. In the case of drawing a box, that's basically each side.

We can see how that works, as each side of the box has a different shade. We defined a directional light to shine primarily from above, so the top of the box is the brightest.

Some other materials calculate the color, not only for each side but for each pixel within the side. They result in more realistic images for more complex shapes. But for boxes illuminated with directional light, they don't make much of a difference.

How to Build the Rest of the Car

Then in a similar way let's let's create the rest of the car. We define the createCar function that returns a Group. This group is another container like the scene. It can hold Three.js objects. It is convenient because if we want to move around the car, we can simply move around the Group.

. . .

function createCar() {
  const car = new THREE.Group();

  const backWheel = createWheels();
  backWheel.position.y = 6;
  backWheel.position.x = -18;
  car.add(backWheel);

  const frontWheel = createWheels();
  frontWheel.position.y = 6;  
  frontWheel.position.x = 18;
  car.add(frontWheel);

  const main = new THREE.Mesh(
    new THREE.BoxBufferGeometry(60, 15, 30),
    new THREE.MeshLambertMaterial({ color: 0x78b14b })
  );
  main.position.y = 12;
  car.add(main);

  const cabin = new THREE.Mesh(
    new THREE.BoxBufferGeometry(33, 12, 24),
    new THREE.MeshLambertMaterial({ color: 0xffffff })
  );
  cabin.position.x = -6;
  cabin.position.y = 25.5;
  car.add(cabin);

  return car;
}

const car = createCar();
scene.add(car);

renderer.render(scene, camera);

. . .

We generate two pairs of wheels with our function, then define the main part of the car. Then we'll add the top of the cabin as the forth mesh. These are all just boxes with different dimensions and different colors.

By default every geometry will be in the middle, and their centers will be at the 0,0,0 coordinate.

First, we raise them by adjusting their position along the Y-axis. We raise the wheels by half of their height – so instead of sinking in halfway to the ground, they lay on the ground. Then we also adjust the pieces along the X-axis to reach their final position.

We add these pieces to the car group, then add the whole group to the scene. It's important that we add the car to the scene before rendering the image, or we'll need to call rendering again once we've modified the scene.

How to Add Texture to the Car

Now that we have our very basic car model, let's add some textures to the cabin. We are going to paint the windows. We'll define a texture for the sides and one for the front and the back of the cabin.

When we set up the appearance of a mesh with a material, setting a color is not the only option. We can also map a texture. We can provide the same texture for every side or we can provide a material for each side in an array.

As a texture, we could use an image. But instead of that, we are going to create textures with JavaScript. We are going to code images with HTML Canvas and JavaScript.

Before we continue, we need to make some distinctions between Three.js and HTML Canvas.

Three.js is a JavaScript library. It uses WebGL under the hood to render 3D objects into an image, and it displays the final result in a canvas element.

HTML Canvas, on the other hand, is an HTML element, just like the div element or the paragraph tag. What makes it special, though, is that we can draw shapes on this element with JavaScript.

This is how Three.js renders the scene in the browser, and this is how we are going to create textures. Let's see how they work.

How to Draw on an HTML Canvas

To draw on a canvas, first we need to create a canvas element. While we create an HTML element, this element will never be part of our HTML structure. On its own, it won't be displayed on the page. Instead, we will turn it into a Three.js texture.

Let's see how can we draw on this canvas. First, we define the width and height of the canvas. The size here doesn't define how big the canvas will appear, it's more like the resolution of the canvas. The texture will be stretched to the side of the box, regardless of its size.

function getCarFrontTexture() {
  const canvas = document.createElement("canvas");
  canvas.width = 64;
  canvas.height = 32;
  const context = canvas.getContext("2d");

  context.fillStyle = "#ffffff";
  context.fillRect(0, 0, 64, 32);

  context.fillStyle = "#666666";
  context.fillRect(8, 8, 48, 24);

  return new THREE.CanvasTexture(canvas);
}

Then we get the 2D drawing context. We can use this context to execute drawing commands.

First, we are going to fill the whole canvas with a white rectangle. To do so, first we set the fill style to be while. Then fill a rectangle by setting its top-left position and its size. When drawing on a canvas, by default the 0,0 coordinate will be at the top-left corner.

Then we fill another rectangle with a gray color. This one starts at the 8,8 coordinate and it doesn't fill the canvas, it only paints the windows.

And that's it – the last line turns the canvas element into a texture and returns it, so we can use it for our car.

function getCarSideTexture() {
  const canvas = document.createElement("canvas");
  canvas.width = 128;
  canvas.height = 32;
  const context = canvas.getContext("2d");

  context.fillStyle = "#ffffff";
  context.fillRect(0, 0, 128, 32);

  context.fillStyle = "#666666";
  context.fillRect(10, 8, 38, 24);
  context.fillRect(58, 8, 60, 24);

  return new THREE.CanvasTexture(canvas);
}

In a similar way, we can define the side texture. We create a canvas element again, we get its context, then first fill the whole canvas to have a base color, and then draw the windows as rectangles.

How to Map Textures to a Box

Now let's see how can we use these textures for our car. When we define the mesh for the top of the cabin, instead of setting only one material, we set one for each side. We define an array of six materials. We map textures to the sides of the cabin, while the top and bottom will still have a plain color.

. . .

function createCar() {
  const car = new THREE.Group();

  const backWheel = createWheels();
  backWheel.position.y = 6;
  backWheel.position.x = -18;
  car.add(backWheel);

  const frontWheel = createWheels();
  frontWheel.position.y = 6;
  frontWheel.position.x = 18;
  car.add(frontWheel);

  const main = new THREE.Mesh(
    new THREE.BoxBufferGeometry(60, 15, 30),
    new THREE.MeshLambertMaterial({ color: 0xa52523 })
  );
  main.position.y = 12;
  car.add(main);

  const carFrontTexture = getCarFrontTexture();

  const carBackTexture = getCarFrontTexture();

  const carRightSideTexture = getCarSideTexture();

  const carLeftSideTexture = getCarSideTexture();
  carLeftSideTexture.center = new THREE.Vector2(0.5, 0.5);
  carLeftSideTexture.rotation = Math.PI;
  carLeftSideTexture.flipY = false;

  const cabin = new THREE.Mesh(new THREE.BoxBufferGeometry(33, 12, 24), [
    new THREE.MeshLambertMaterial({ map: carFrontTexture }),
    new THREE.MeshLambertMaterial({ map: carBackTexture }),
    new THREE.MeshLambertMaterial({ color: 0xffffff }), // top
    new THREE.MeshLambertMaterial({ color: 0xffffff }), // bottom
    new THREE.MeshLambertMaterial({ map: carRightSideTexture }),
    new THREE.MeshLambertMaterial({ map: carLeftSideTexture }),
  ]);
  cabin.position.x = -6;
  cabin.position.y = 25.5;
  car.add(cabin);

  return car;
}

. . .

Most of these textures will be mapped correctly without any adjustments. But if we turn the car around then we can see the windows appear in the wrong order on the left side.

Right side and left side before and after fixing the texture

This is expected as we use the texture for the right side here as well. We can define a separate texture for the left side or we can mirror the right side.

Unfortunately, we can't flip a texture horizontally. We can only flip a texture vertically. We can fix this in 3 steps.

First, we turn the texture around by 180 degrees, which equals PI in radians. Before turning it, though, we have to make sure that the texture is rotated around its center. This is not the default – we have to set that the center of rotation is halfway. We set 0.5 on both axes which basically means 50%. Then finally we flip the texture upside down to have it in the correct position.

Wrap-up

So what did we do here? We created a scene that contains our car and the lights. We built the car from simple boxes.

You might think this is too basic, but if you think about it many mobile games with stylish looks are actually created using boxes. Or just think about Minecraft to see how far you can get by putting together boxes.

Then we created textures with HTML canvas. HTML canvas is capable of much more than what we used here. We can draw different shapes with curves and arcs, but then again sometimes a minimal design is all that we need.

And finally, we defined a camera to establish how we look at this scene, as well as a renderer that renders the final image into the browser.

Next Steps

If you want to play around with the code, you can find the source code on CodePen. And if you want to move forward with this project, then check out my YouTube video on how to turn this into a game.

In this tutorial, we create a traffic run game. After defining the car we draw the race track, we add game logic, event handlers, and animation.

Three.js Tutorial – How to Render 3D Objects in the Browser

Hunor Márton Borbély — Wed, 03 Feb 2021 23:06:37 +0000

If you have ever wanted to build a game with JavaScript, you might have come across Three.js.

Three.js is a library that we can use to render 3D graphics in the browser. The whole thing is in JavaScript, so with some logic you can add animation, interaction, or even turn it into a game.

In this tutorial, we will go through a very simple example. We'll render a 3D box, and while doing so we'll learn the fundamentals of Three.js.

Three.js uses WebGL under the hood to render 3D graphics. We could use plain WebGL, but it's very complex and rather low level. On the other hand, Three.js is like playing with Legos.

In this article, we'll go through how to place a 3D object in a scene, set up the lighting and a camera, and render the scene on a canvas. So let’s see how we can do all this.

Define the Scene Object

First, we have to define a scene. This will be a container where we place our 3D objects and lights. The scene object also has some properties, like the background color. Setting that is optional though. If we don't set it, the default will be black.

import * as THREE from "three";

const scene = new THREE.Scene();
scene.background = new THREE.Color(0x000000); // Optional, black is default

...

Geometry + Material = Mesh

Then we add our 3D box to the scene as a mesh. A mesh is a combination of a geometry and a material.

...

// Add a cube to the scene
const geometry = new THREE.BoxGeometry(3, 1, 3); // width, height, depth
const material = new THREE.MeshLambertMaterial({ color: 0xfb8e00 });
const mesh = new THREE.Mesh(geometry, material);
mesh.position.set(0, 0, 0); // Optional, 0,0,0 is the default
scene.add(mesh);

...

What is a Geometry?

A geometry is a rendered shape that we’re building - like a box. A geometry can be build from vertices or we can use a predefined one.

The BoxGeometry is the most basic predefined option. We only have to set the width, height, and depth of the box and that’s it.

You might think that we can't get far by defining boxes, but many games with minimalistic design use only a combination of boxes.

There are other predefined geometries as well. We can easily define a plane, a cylinder, a sphere, or even an icosahedron.

How to Work with Material

Then we define a material. A material describes the appearance of an object. Here we can define things like texture, color, or opacity.

In this example we are only going to set a color. There are still different options for materials. The main difference between most of them is how they react to light.

The simplest one is the MeshBasicMaterial. This material doesn't care about light at all, and each side will have the same color. It might not be the best option, though, as you can’t see the edges of the box.

The simplest material that cares about light is the MeshLambertMaterial. This will calculate the color of each vertex, which is practically each side. But it doesn't go beyond that.

If you need more precision, there are more advanced materials. The MeshPhongMaterial not only calculates the color by vertex but by each pixel. The color can change within a side. This can help with realism but also costs in performance.

It also depends on the light settings and the geometry if it has any real effect. If we render boxes and use directional light, the result won't change that much. But if we render a sphere, the difference is more obvious.

How to Position a Mesh

Once we have a mesh we can also position it within the scene and set a rotation by each axis. Later if we want to animate objects in the 3D space we will mostly adjust these values.

For positioning we use the same units that we used for setting the size. It doesn't matter if you are using small numbers or big numbers, you just need to be consistent in your own world.

For the rotation we set the values in radians. So if you have your values in degrees you have to divide them by 180° then multiply by PI.

How to Add Light

Then let's add lights. A mesh with basic material doesn’t need any light, as the mesh will have the set color regardless of the light settings.

But the Lambert material and Phong material require light. If there isn't any light, the mesh will remain in darkness.

...

// Set up lights
const ambientLight = new THREE.AmbientLight(0xffffff, 0.6);
scene.add(ambientLight);

...

We'll add two lights - an ambient light and a directional light.

First, we add the ambient light. The ambient light is shining from every direction, giving a base color for our geometry.

To set an ambient light we set a color and an intensity. The color is usually white, but you can set any color. The intensity is a number between 0 and 1. The two lights we define work in an accumulative way so in this case we want the intensity to be around 0.5 for each.

The directional light has a similar setup, but it also has a position. The word position here is a bit misleading, because it doesn’t mean that the light is coming from an exact position.

The directional light is shining from very far away with many parallel light rays all having a fixed angle. But instead of defining angles, we define the direction of a single light ray.

In this case, it shines from the direction of the 10,20,0 position towards the 0,0,0 coordinate. But of course, the directional light is not only one light ray, but an infinite amount of parallel rays.

Think of it as the sun. On a smaller scale, light rays of the sun also come down in parallel, and the sun’s position isn't what matters but rather its direction.

And that’s what the directional light is doing. It shines on everything with parallel light rays from very far away.

...

const dirLight = new THREE.DirectionalLight(0xffffff, 0.6);
dirLight.position.set(10, 20, 0); // x, y, z
scene.add(dirLight);

...

Here we set the position of the light to be from above (with the Y value) and shift it a bit along the X-axis as well. The Y-axis has the highest value. This means that the top of the box receives the most light and it will be the shiniest side of the box.

The light is also moved a bit along the X-axis, so the right side of the box will also receive some light, but less.

And because we don’t move the light position along the Z-axis, the front side of the box will not receive any light from this source. If there wasn't an ambient light, the front side would remain in darkness.

There are other light types as well. The PointLight, for instance, can be used to simulate light bulbs. It has a fixed position and it emits light in every direction. And the SpotLight can be used to simulate the spotlight of a car. It emits light from a single point into a direction along a cone.

How to Set up the Camera

So far, we have created a mesh with geometry and material. And we have also set up lights and added to the scene. We still need a camera to define how we look at this scene.

There are two options here: perspective cameras and orthographic cameras.

Video games mostly use perspective cameras, because how they work is similar to how you see things in real life. Things that are further away appear to be smaller and things that are right in front of you appear bigger.

With orthographic projections, things will have the same size no matter how far they are from the camera. Orthographic cameras have a more minimal, geometric look. They don't distort the geometries - the parallel lines will appear in parallel.

For both cameras, we have to define a view frustum. This is the region in the 3D space that is going to be projected to the screen. Anything outside of this region won't appear on the screen. This is because it is either too close or too far away, or because the camera isn't pointed towards it.

With perspective projection, everything within the view frustum is projected towards the viewpoint with a straight line. Things further away from the camera appear smaller on the screen, because from the viewpoint you can see them under a smaller angle.

...

// Perspective camera
const aspect = window.innerWidth / window.innerHeight;
const camera = new THREE.PerspectiveCamera(
  45, // field of view in degrees
  aspect, // aspect ratio
  1, // near plane
  100 // far plane
);

...

To define a perspective camera, you need to set a field of view, which is the vertical angle from the viewpoint. Then you define an aspect ratio of the width and the height of the frame. If you fill the whole browser window and you want to keep its aspect ratio, then this is how you can do it.

Then the last two parameters define how far the near and far planes are from the viewpoint. Things that are too close to the camera will be ignored, and things that are too far away will be ignored as well.

...

// Orthographic camera
const width = 10;
const height = width * (window.innerHeight / window.innerWidth);
const camera = new THREE.OrthographicCamera(
  width / -2, // left
  width / 2, // right
  height / 2, // top
  height / -2, // bottom
  1, // near
  100 // far
);

...

Then there’s the orthographic camera. Here we are not projecting things towards a single point but towards a surface. Each projection line is in parallel. That’s why it doesn’t matter how far objects are from the camera, and that’s why it doesn’t distort geometries.

For orthographic cameras, we have to define how far each plane is from the viewpoint. The left plane is therefor five units to the left, and the right plane is five units to the right, and so on.

...

camera.position.set(4, 4, 4);
camera.lookAt(0, 0, 0);

...

Regardless of which camera are we using, we also need to position it and set it in a direction. If we are using an orthographic camera the actual numbers here don’t matter that much. The objects will appear the same size no matter how far away they are from the camera. What matters, though, is their proportion.

Through this whole tutorial, we saw all the examples through the same camera. This camera was moved by the same unit along every axis and it looks towards the 0,0,0 coordinate. Positioning an orthographic camera is like positioning a directional light. It's not the actual position that matters, but its direction.

How to Render the Scene

So we managed to put together the scene and a camera. Now only the final piece is missing that renders the image into our browser.

We need to define a WebGLRenderer. This is the piece that is capable of rendering the actual image into an HTML canvas when we provide a scene and a camera. This is also where we can set the actual size of this canvas – the width and height of the canvas in pixels as it should appear in the browser.

import * as THREE from "three";

// Scene
const scene = new THREE.Scene();

// Add a cube to the scene
const geometry = new THREE.BoxGeometry(3, 1, 3); // width, height, depth
const material = new THREE.MeshLambertMaterial({ color: 0xfb8e00 });
const mesh = new THREE.Mesh(geometry, material);
mesh.position.set(0, 0, 0);
scene.add(mesh);

// Set up lights
const ambientLight = new THREE.AmbientLight(0xffffff, 0.6);
scene.add(ambientLight);

const directionalLight = new THREE.DirectionalLight(0xffffff, 0.6);
directionalLight.position.set(10, 20, 0); // x, y, z
scene.add(directionalLight);

// Camera
const width = 10;
const height = width * (window.innerHeight / window.innerWidth);
const camera = new THREE.OrthographicCamera(
  width / -2, // left
  width / 2, // right
  height / 2, // top
  height / -2, // bottom
  1, // near
  100 // far
);

camera.position.set(4, 4, 4);
camera.lookAt(0, 0, 0);

// Renderer
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.render(scene, camera);

// Add it to HTML
document.body.appendChild(renderer.domElement);

And finally, the last line here adds this rendered canvas to our HTML document. And that’s all you need to render a box. It might seem a little too much for just a single box, but most of these things we only have to set up once.

If you want to move forward with this project, then check out my YouTube video on how to turn this into a simple game. In the video, we create a stack building game. We add game logic, event handlers and animation, and even some physics with Cannon.js.

If you have any feedback or questions on this tutorial, feel free to Tweet me @HunorBorbely or leave a comment on YouTube.

Hunor Márton Borbély - freeCodeCamp.org

How to Code a Crossy Road Game Clone with React Three Fiber

Table of Contents

React Three Fiber vs Three.js

How to Set Up the Game

Initializing the Project

The Drawing Canvas

The main.jsx file

The Player

The Camera

The Lights

The Scene

How to Render a Map

The Starting Row

How to Add a Forest Row

Car Lanes

How to Animate the Cars

How to Move the Player

Collecting User Inputs

Executing Movement Commands

Follow the Player with the Camera

Restricting Player Movement

Hit Detection

Next Steps

How to Code a Crossy Road Game Clone with Three.js

Table of Contents

How to Set Up the Game

Initializing the Project

The Drawing Canvas

The main.js file

The Player

The Camera

The Lights

The Renderer

How to Render a Map

The Starting Row

How to Add a Forest Row

Car Lanes

How to Animate the Cars

How to Move the Player

Collecting User Inputs

Executing Movement Commands

Restricting Player Movement

Hit Detection

Next Steps

JavaScript Tutorial – How to Set Up a Front End Development Project

Table of Contents

How to Choose a Code Editor

How to Auto-format Your Code in VS Code

Why Do You Need Node for a Front-End Project?

How to Run Your Project

How to Add Libraries to Your JavaScript Project

How to Get Coding Tips While You Code

Initialize a Project with Vite

Summary

Subscribe for more tutorials on Web Development:

SVG Toggle Button Tutorial – How to Handle Dark Mode with CSS and JavaScript

Table of Contents

How to Handle Dark Mode with CSS

How to Code a Sun Icon with SVG

How to Detect Dark Mode in JavaScript

How to Code a Moon Icon with SVG

How to Toggle Dark Mode with JavaScript

Next Steps

How to use the Fullscreen API in JavaScript

Table of Contents:

How to Enter Fullscreen Mode

How to Style the Fullscreen

How to Display Games with the Canvas Element in Fullscreen

How to Exit Fullscreen

How to Code a Fullscreen Icon with SVG

How to Toggle the Icon's Appearance

Learn More

How to Draw with JavaScript on an HTML Canvas Element – Gorilla Example

Table of Contents:

How to Define a Canvas

How to Turn the Coordinate System Upside Down

How to Draw the Gorilla

How to draw the body of the gorilla

How to draw the legs of the gorilla