That repetition doesn’t just waste time – it slows down your development and creates maintenance headaches across projects.

This guide walks you through a set of reusable, modular Unity packages you can drop into any project to speed up development. You’ll build them once as packages and install them via Git wherever you need them, instead of reimplementing the same systems every time.

The article covers four core packages:

1. com.core.initializer – Finds and initializes your game controllers at runtime (MVC-style) so startup and dependencies centralized.

2. com.core.data – Handles local (and optionally cloud) save data using MemoryPack binary serialization and a provider abstraction so you can switch or extend storage backends.

3. com.core.ui – Manages popups and full-screen UIs in a consistent way so you can show dialogs, panels, and screens without duplicating logic.

4. com.core.dotween – Wraps the DoTween tween engine as a Unity package so com.core.ui (and other packages) can reference it for animations.

In this tutorial, we’ll build all four packages step by step. The Initializer, Data, UI, and DoTween packages are all documented so you can easily follow along. All packages are also upload to github which you can find the links at the end.

Table of Contents

• What You Will Learn

• Prerequisites

• Set Up Your Development Project

• Package 1: The Initializer Package

• Package 2: The Data Package

• Package 3: The DoTween Package

• Package 4: The UI Package

• Summary

What You Will Learn

• How to create a Unity package with the Package Manager

• How to set up the package structure

• How to built a centralized initialization flow for your packages

• How to use UniTask for async initialization on Unity's main thread

• How the Data package uses IDataProvider and MemoryPack for local save/load

• How the UI package uses popups (stack) and screens (single active) with DoTween animations

Prerequisites

Before you start, make sure you have:

• Unity installed (any Long Term Support version compatible with the packages. The referenced packages target Unity 6000.3)

• Git installed

• Jetbrains Rider or Visual Studio Community installed

• Know how to use Unity game engine

• Know C# and async/await structures

You will use the Unity Package Manager to create packages, then upload and install them via Git in other projects.

Set Up Your Development Project

Create a new Unity project if you don’t already have one. We’ll use it as a playground to build and test your packages. This project (and not the packages themselves) is your development environment.

Package 1: The Initializer

The first package is com.core.initializer. It finds all your controllers, runs their async initialization before the first scene loads, and lets the rest of the game access them via a single handler.

What com.core.initializer Does

• Early initialization: Runs at RuntimeInitializeLoadType.BeforeSceneLoad, so all controllers exist and are initialized before the first scene loads.

• Central access: Stores each controller by its type and exposes them through a type-safe getter.

• Completion signaling: Exposes a static event (ControllersInitialized) and a UniTaskCompletionSource (InitializationCompleted) so you can run code only after all controllers have finished initializing.

Create the Initializer Package

To start, open Window → Package Manager (under Package Management). Then click the + button and choose Create package.

Name the package com.core.initializer (or your preferred name).

Unity creates the essential package files for you.

You can edit package.json and the assembly definition (asmdef) names to match your naming. The full set of changes is not listed here. The final package is available on GitHub (linked at the end).

Add the UniTask Dependency

Unity runs on the main thread, and C# Tasks can be problematic in that context. They don’t know about the Unity Editor's play state and keep running after exiting play mode for example. So you’ll need to handle these cases manually. For these reasons, this package uses UniTask instead of C# Tasks for async operations.

Git-based dependencies are supported at the project level but not at the package level. Add UniTask via OpenUPM by following the manual installation steps.

Add UniTask as a dependency in package.json of initializer package:

"dependencies": {
  "com.cysharp.unitask": "2.5.10"
}

Also reference UniTask in the asmdef file.

You’ll need to follow this dependency flow for the rest of the packages you create.

Implement the Package Structure

The initializer uses an MVC-like architecture. Controllers handle both initialization and game logic. You could later split initialization into services and keep business logic in controllers (for example, an MVCS-style setup). This tutorial keeps things simple and uses only controllers.

Target layout:

• Runtime/Interface/ – IController

• Runtime/Helper/ – Creator (reflection-based instance creation)

• Runtime/ – ControllerHandler (orchestrates initialization)

All controllers implement the IController interface. The Initialize method returns a UniTask so initialization can be async on the main thread.

using Cysharp.Threading.Tasks;

namespace com.core.initializer
{
    public interface IController
    {
        bool IsInitialized { get; }

        UniTask Initialize();
    }
}

Create the Creator Helper

You’ll need to find all types that implement IController, create instances of them at runtime, and also find MonoBehaviours that implement IController (since those cannot be created via reflection). The Creator class does both.

using System;
using System.Collections.Generic;
using System.Linq;
using UnityEngine;

namespace com.core.initializer
{
    public static class Creator
    {
        /// <summary>
        /// Creates instances of every type which inherits from T interface.
        /// </summary>
        public static IEnumerable<T> CreateInstancesOfType<T>(params Type[] exceptTypes)
        {
            var interfaceType = typeof(T);

            var result = AppDomain.CurrentDomain.GetAssemblies().SelectMany(x => x.GetTypes()).Where
                (
                 x => interfaceType.IsAssignableFrom(x) &&
                      !x.IsInterface                    &&
                      !x.IsAbstract                     &&
                      exceptTypes.All(type => !x.IsSubclassOf(type) && x != type)
                ).Select(Activator.CreateInstance);

            return result.Cast<T>();
        }

        public static IEnumerable<T> GetMonoControllers<T>() => UnityEngine.Object.FindObjectsByType<MonoBehaviour>(FindObjectsInactive.Include, FindObjectsSortMode.None).OfType<T>();
    }
}

Using reflection at runtime has some overhead. You can optimize this later with baking the reflection in editor and using it at runtime. For MonoBehaviours, FindObjectsByType is used here for simplicity. In a larger project, you might use a dependency injection solution such as VContainer or Reflex.

Implement the ControllerHandler

The ControllerHandler uses Creator to gather all IController instances (both reflection-created and MonoBehaviours), initializes them in order, and exposes an event and a UniTaskCompletionSource so the rest of the game can wait for startup to finish.

using System;
using System.Collections.Generic;
using System.Linq;
using Cysharp.Threading.Tasks;
using UnityEngine;

namespace com.core.initializer
{
    public class ControllerHandler
    {
        public static readonly UniTaskCompletionSource InitializationCompleted = new();

        public static event Action ControllersInitialized;

        private static Dictionary<Type, IController> _controllers = new();

        [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
        public static async void Initialize()
        {
            var controllers = Creator.CreateInstancesOfType<IController>(typeof(MonoBehaviour)).ToList();
            controllers.AddRange(Creator.GetMonoControllers<IController>());

            Debug.Log("Initializing controller");

            foreach (var controller in controllers)
            {
                Debug.Log($"<color=yellow>Initializing {controller.GetType().Name}</color>");
                await controller.Initialize();
                _controllers.Add(controller.GetType(), controller);
                Debug.Log($"<color=green>Initialized {controller.GetType().Name}</color>");
            }

            Debug.Log("<color=green>All controllers are initialized</color>");
            ControllersInitialized?.Invoke();
            InitializationCompleted?.TrySetResult();
        }

        public static T GetController<T>() where T : class, IController => _controllers[typeof(T)] as T;
    }
}

How to Test the Initializer

1. Create a class that implements IController (or a MonoBehaviour that implements it).

2. Implement Initialize() with your setup logic (you can use await and UniTask).

3. After initialization, access the controller with:
   var myController = ControllerHandler.GetController<MyController>();

You can also subscribe to ControllerHandler.ControllersInitialized or await ControllerHandler.InitializationCompleted.Task to run code after all controllers are ready.

There are some limitations here. First, it can be hard to handle dependencies between different controllers. Second, it’s easy to run into circular dependencies.

When you check the GitHub repo, a DI framework may already be implemented to address these limitations. Make sure to open an issue if you want this feature.

Package 2: The Data Package

com.core.data handles local saving with a binary serializer. The package uses MemoryPack for fast, binary serialization and defines an IDataProvider interface so you can plug in different providers (local, cloud, or hybrid).

Package dependency: com.cysharp.memorypack (version 1.10.0). Add it to your project via OpenUPM and add it to package.json and the asmdef for com.core.data.

Create a new package and name it com.core.data. Use a structure such as:

• Runtime/Interface/ – IDataProvider

• Runtime/Providers/ – LocalDataProvider

• Runtime/ – optional sample DataController (in your game assembly) that implements IController and uses an IDataProvider

All data providers use the IDataProvider interface.

using Cysharp.Threading.Tasks;

namespace com.core.data
{
    public interface IDataProvider
    {
        bool     IsInitialized { get; }
        void     Save<T>(string key, T data);
        T        Load<T>(string key, T defaultValue = default);
        bool     HasKey(string  key);
        string[] GetKeys();
        UniTask  Delete(string key);
        UniTask  DeleteAll();
    }
}

You will use UniTask in the data package as well. Add com.cysharp.unitask to package.json since both IController and IDataProvider uses it.

Here’s the DataController:

using System;
using System.Collections.Generic;
using System.Text;
using com.core.data;
using com.core.initializer;
using Cysharp.Threading.Tasks;
using UnityEngine;

namespace com.core.data
{
    public class DataController : IController
    {
        private const string PLAYER_VERSION_KEY = "player-version-key";

        private IDataProvider _provider;

        public bool IsInitialized { get; private set; }

        public UniTask Initialize()
        {
            _provider = new LocalDataProvider();
            SaveUserVersion();
            IsInitialized = true;
            return UniTask.CompletedTask;
        }

        private void SaveUserVersion()
        {
            var versionHistory = Load(PLAYER_VERSION_KEY, new List<string>());
            var sb             = new StringBuilder();
            versionHistory.ForEach(vh => sb.Append(vh + Environment.NewLine));
            Debug.Log($"[DataController] Player version history: {sb}");

            if (!versionHistory.Contains(Application.version))
            {
                Debug.Log($"[DataController] Player's current version: {Application.version}");
                versionHistory.Add(Application.version);
                Save(PLAYER_VERSION_KEY, versionHistory);
            }
        }

        public void Save<T>(string key, T data) => _provider.Save(key, data);

        public T Load<T>(string key, T defaultValue = default) => _provider.Load(key, defaultValue);

        public bool         HasKey(string key)  => _provider.HasKey(key);
        public string[]     GetKeys()           => _provider.GetKeys();
        public UniTask      Delete(string key)  => _provider.Delete(key);
        public UniTask      DeleteAll()         => _provider.DeleteAll();
        public List<string> GetVersionHistory() => Load(PLAYER_VERSION_KEY, new List<string>());
    }
}

The controller delegates all logic to LocalDataProvider, which uses MemoryPack to serialize and write bytes to a "Data" folder under Application.persistentDataPath. The controller also keeps the user's app version history, which is useful for upgrade prompts or blocking old versions.

Here’s the full implementation:

using System;
using System.Collections.Generic;
using System.IO;
using System.Text;
using Cysharp.Threading.Tasks;
using MemoryPack;
using UnityEngine;

namespace com.core.data
{
    public class LocalDataProvider : IDataProvider
    {
        private const    string StorageFolderName = "Data";
        private readonly string _storagePath;

        private static readonly UTF8Encoding KeyEncoding = new(false);

        public bool IsInitialized => true;

        public LocalDataProvider()
        {
            _storagePath = Path.Combine(Application.persistentDataPath, StorageFolderName);
            EnsureStorageDirectoryExists();
        }

        public void Save<T>(string key, T data)
        {
            if (string.IsNullOrEmpty(key)) { Debug.LogWarning("[LocalDataProvider] Save called with null or empty key."); return; }
            if (data == null) { Debug.LogWarning("[LocalDataProvider] Save called with null data."); Delete(key).Forget(); return; }
            try
            {
                byte[] bin = MemoryPackSerializer.Serialize(data);
                WriteBytes(key, bin);
            }
            catch (Exception ex) { Debug.LogError($"[LocalDataProvider] Save failed for key '{key}': {ex.Message}"); throw; }
        }

        public T Load<T>(string key, T defaultValue = default)
        {
            if (string.IsNullOrEmpty(key)) { Debug.LogWarning("[LocalDataProvider] Load called with null or empty key."); return defaultValue; }
            if (!ReadBytes(key, out byte[] bin)) return defaultValue;
            try { return MemoryPackSerializer.Deserialize<T>(bin) ?? defaultValue; }
            catch (Exception ex) { Debug.LogError($"[LocalDataProvider] Load failed for key '{key}': {ex.Message}"); return defaultValue; }
        }

        public bool HasKey(string key) => !string.IsNullOrEmpty(key) && File.Exists(GetFilePath(key));

        public UniTask Delete(string key)
        {
            if (string.IsNullOrEmpty(key)) return UniTask.CompletedTask;
            try { var filePath = GetFilePath(key); if (File.Exists(filePath)) File.Delete(filePath); }
            catch (Exception ex) { Debug.LogError($"[LocalDataProvider] Delete failed for key '{key}': {ex.Message}"); }
            return UniTask.CompletedTask;
        }

        public UniTask DeleteAll()
        {
            try
            {
                if (!Directory.Exists(_storagePath)) return UniTask.CompletedTask;
                foreach (string file in Directory.GetFiles(_storagePath))
                {
                    try { File.Delete(file); }
                    catch (Exception ex) { Debug.LogWarning($"[LocalDataProvider] Could not delete file '{file}': {ex.Message}"); }
                }
            }
            catch (Exception ex) { Debug.LogError($"[LocalDataProvider] DeleteAll failed: {ex.Message}"); }
            return UniTask.CompletedTask;
        }

        public string[] GetKeys()
        {
            if (!Directory.Exists(_storagePath)) return Array.Empty<string>();
            var keys = new List<string>();
            foreach (string file in Directory.GetFiles(_storagePath))
            {
                try { string key = DecodeKeyFromFileName(Path.GetFileName(file)); if (key != null) keys.Add(key); }
                catch { Debug.LogWarning($"[LocalDataProvider] Could not read file '{file}'."); }
            }
            return keys.ToArray();
        }

        private void EnsureStorageDirectoryExists() { if (!Directory.Exists(_storagePath)) Directory.CreateDirectory(_storagePath); }
        private void WriteBytes(string key, byte[] bin) { EnsureStorageDirectoryExists(); File.WriteAllBytes(GetFilePath(key), bin); }
        private bool ReadBytes(string key, out byte[] bin) { string filePath = GetFilePath(key); if (!File.Exists(filePath)) { bin = null; return false; } bin = File.ReadAllBytes(filePath); return true; }
        private string GetFilePath(string key) => Path.Combine(_storagePath, EncodeKeyToFileName(key));
        private static string EncodeKeyToFileName(string key) { byte[] bytes = KeyEncoding.GetBytes(key); string base64 = Convert.ToBase64String(bytes); return base64.Replace('+', '-').Replace('/', '_'); }
        private static string DecodeKeyFromFileName(string fileName) { try { string base64 = fileName.Replace('-', '+').Replace('_', '/'); return KeyEncoding.GetString(Convert.FromBase64String(base64)); } catch { return null; } }
    }
}

You can implement another IDataProvider (for example JSON via Newtonsoft or PlayerPrefs) and swap it in your DataController.

In production, you might use a local and a cloud provider and sync data based on the player's online status. The com.core.data GitHub repo may be updated with cloud saving and syncing. You can open an issue if you need that feature.

Package 3: com.core.dotween

com.core.dotween is a Unity package wrapper around DOTween (Demigiant). DoTween is a widely used, production-ready tween engine. The UI package uses it for popup show/hide animations.

DOTween is not available on OpenUPM, so you’ll typically need to download it from the Unity Asset Store and import it into your project (for example, under Assets/Plugins).

Then you’ll run the DOTween setup window(it should pop automatically after importing) and click Create ASMDEF so assembly definition files are generated and you can reference them from other packages.

Next, create a new package (for example, com.core.dotween) and move the Demigiant folder from Assets/Plugins into the package folder so that com.core.ui (or any other package) can depend on com.core.dotween via Package Manager or Git.

After that, reference com.core.dotween in com.core.ui's asmdef(You will create the UI package right after this) so you can use DG.Tweening namespace in BasePopup and other UI scripts.

com.core.dotween has no external dependencies – it only wraps the DOTween asset.

Package 4: The UI Package

com.core.ui centralizes how you show popups and full-screen UIs. It contains:

• Popups – Modal or non-modal dialogs (confirm/cancel, alerts, forms) with a consistent API so you don’t duplicate panel logic in every screen. Popups are stacked – the top one is closed first.

• Screens – Full-screen panels (for example, loading, main menu). Only one screen is active at a time, and switching a screen hides the current one and shows the new one.

Create a new package named com.core.ui with a structure such as:

• Runtime/Interface/ – IUI

• Runtime/UIs/ – BasePopup, BaseScreen

• Runtime/ – UIController, UIParent

• Runtime/Resources/UIPrefabs/ – UIParent prefab, and subfolders Popups and Screens

Add com.core.dotween, com.core.initializer, and com.cysharp.unitask as dependencies in package.json and asmdef.

Popups work like a stack: each popup is shown on top of the previous one and closed from top to bottom. Screens are single-active: only one screen is visible at a time. UIController hides the current one when you show another. UIController is the single point of contact for both screens and popups and handles stacking, caching, and background placement.

IUI Interface

Both BasePopup and BaseScreen implement IUI:

using System;
using Cysharp.Threading.Tasks;

namespace com.core.ui
{
    public interface IUI
    {
        event Action<IUI> Showed;
        event Action<IUI> Hidden;

        UniTask ShowAsync();
        UniTask HideAsync();
    }
}

IUI is a very basic interface with 2 async Show/Hide methods and 2 events to be fired upon completion of those methods.

BasePopup

BasePopup uses DoTween to animate scale on show/hide and exposes events and overridable animation methods:

using System;
using Cysharp.Threading.Tasks;
using DG.Tweening;
using UnityEngine;

namespace com.core.ui
{
    public abstract class BasePopup : MonoBehaviour, IUI
    {
        public event Action<IUI> StartedShowing;
        public event Action<IUI> Showed;
        public event Action<IUI> Hidden;

        [SerializeField] private float   openingTime  = 0.35f;
        [SerializeField] private float   closingTime  = 0.25f;
        [SerializeField] private Vector3 initialScale = new(0.75f, 0.75f, 0.75f);
        [SerializeField] private Ease   openingEase  = Ease.OutBack;
        [SerializeField] private Ease   closingEase  = Ease.InBack;

        protected virtual Tweener PlayShowAnimation(Action completedCallback) => transform.DOScale(Vector3.one, openingTime).SetEase(openingEase).SetUpdate(true).OnComplete(() => completedCallback?.Invoke());
        protected virtual Tweener PlayHideAnimation(Action completedCallback) => transform.DOScale(initialScale, closingTime).SetEase(closingEase).SetUpdate(true).OnComplete(() => completedCallback?.Invoke());

        public UniTask ShowAsync()
        {
            StartedShowing?.Invoke(this);
            transform.SetAsLastSibling();
            var utcs = new UniTaskCompletionSource();
            transform.localScale = initialScale;
            gameObject.SetActive(true);

            PlayShowAnimation(() => OnAnimationShowed(utcs));
            return utcs.Task;
        }

        public void Show() => ShowAsync().Forget();

        public UniTask HideAsync()
        {
            var utcs = new UniTaskCompletionSource();
            PlayHideAnimation(() => OnAnimationCompleted(utcs));
            return utcs.Task;
        }

        private void OnAnimationShowed(UniTaskCompletionSource utcs)
        {
            Showed?.Invoke(this);
            utcs.TrySetResult();
        }

        private void OnAnimationCompleted(UniTaskCompletionSource utcs)
        {
            transform.SetAsFirstSibling();
            gameObject.SetActive(false);
            Hidden?.Invoke(this);
            utcs.TrySetResult();
        }

        public void Hide() => HideAsync().Forget();
    }
}

You can see that DoTween is the core component in this class and a lot of parameters are configurable like opening/closing times and easings. Notice how DoTween completion callbacks are utilized to fire Showed and Hidden events.

Another important thing here is the usage of SetUpdate(true) for animations. This makes animations to ignore timescale. I found that most of the time it's best to ignore the timescale for animations but if you don't want this then feel free to change it.

BaseScreen

BaseScreen only enables/disables the GameObject and raises events. There’s no animation:

using System;
using Cysharp.Threading.Tasks;
using UnityEngine;

namespace com.core.ui
{
    public abstract class BaseScreen : MonoBehaviour, IUI
    {
        public event Action<IUI> Showed;
        public event Action<IUI> Hidden;

        public virtual UniTask ShowAsync()
        {
            gameObject.SetActive(true);
            Showed?.Invoke(this);
            return UniTask.CompletedTask;
        }

        public UniTask HideAsync()
        {
            gameObject.SetActive(false);
            Hidden?.Invoke(this);
            return UniTask.CompletedTask;
        }
    }
}

You will notice that BaseScreen doesn't need UniTask since it is not performing any async operations but it is still beneficial to have this since it doesn't cause any overheads and if we ever need an animation for any of our screens like popups, we have it ready.

UIController

UIController implements IController, instantiates UIParent from Resources, and provides APIs to push/pop popups and show/hide screens. It caches popup and screen instances by type and loads prefabs from Resources:

• UIParent: Resources/UIPrefabs/UIParent

• Popups: Resources/UIPrefabs/Popups/<TypeName>.prefab

• Screens: Resources/UIPrefabs/Screens/<TypeName>.prefab

using System;
using System.Collections.Generic;
using com.core.initializer;
using Cysharp.Threading.Tasks;
using UnityEngine;
using Object = UnityEngine.Object;

namespace com.core.ui
{
    public class UIController : IController
    {
        private const string UI_PARENT_PATH    = "UIPrefabs/UIParent";
        private const string POPUPS_RESOURCES  = "UIPrefabs/Popups";
        private const string SCREENS_RESOURCES = "UIPrefabs/Screens";

        private readonly Stack<BasePopup>             _popupStack  = new();
        private readonly Dictionary<Type, BasePopup>  _popupCache  = new();
        private readonly Dictionary<Type, BaseScreen> _ScreenCache = new();

        private BaseScreen _currentScreen;
        private UIParent   _uiParent;

        public bool IsInitialized { get; private set; }

        public UniTask Initialize()
        {
            var uiParentPrefab = Resources.Load<UIParent>(UI_PARENT_PATH);
            if (uiParentPrefab == null)
            {
                Debug.LogError($"[UIController] UIParent prefab not found at {UI_PARENT_PATH}. Ensure it exists in a Resources folder.");
                return UniTask.CompletedTask;
            }

            _uiParent      = Object.Instantiate(uiParentPrefab);
            _uiParent.name = "UIParent";

            Object.DontDestroyOnLoad(_uiParent.gameObject);

            IsInitialized = true;
            return UniTask.CompletedTask;
        }

        public async UniTask<TPopup> PushPopupAsync<TPopup>() where TPopup : BasePopup
        {
            var popup = GetOrCreatePopup<TPopup>();
            _popupStack.Push(popup);
            var popupTask = popup.ShowAsync();
            UpdateBackgroundForTopPopup();
            await popupTask;
            return popup;
        }

        public void PushPopup<TPopup>() where TPopup : BasePopup => PushPopupAsync<TPopup>().Forget();

        public async UniTask PopPopupAsync()
        {
            if (_popupStack.Count == 0)
            {
                Debug.LogWarning("[UIController] PopPopup called but popup stack is empty.");
                return;
            }

            var top = _popupStack.Pop();
            await top.HideAsync();
            UpdateBackgroundForTopPopup();
        }

        public void PopPopup() => PopPopupAsync().Forget();

        public BasePopup PeekPopup() => _popupStack.Count > 0 ? _popupStack.Peek() : null;

        public async UniTask<TScreen> ShowScreenAsync<TScreen>() where TScreen : BaseScreen
        {
            var screen = GetOrCreateScreen<TScreen>();

            if (_currentScreen == screen && screen.gameObject.activeSelf) return screen;
            if (_currentScreen != null   && _currentScreen != screen && _currentScreen.gameObject.activeSelf) await _currentScreen.HideAsync();

            _currentScreen = screen;
            await screen.ShowAsync();
            return screen;
        }

        public async UniTask HideScreenAsync<TScreen>() where TScreen : BaseScreen
        {
            var type = typeof(TScreen);
            if (!_ScreenCache.TryGetValue(type, out var screen))
            {
                Debug.LogWarning($"[UIController] HideScreenAsync<{type.Name}> called but Screen was never shown (not in cache).");
                return;
            }

            await screen.HideAsync();

            if (_currentScreen == screen) _currentScreen = null;
        }

        public void ShowScreen<TScreen>() where TScreen : BaseScreen => ShowScreenAsync<TScreen>().Forget();
        public void HideScreen<TScreen>() where TScreen : BaseScreen => HideScreenAsync<TScreen>().Forget();

        private TPopup GetOrCreatePopup<TPopup>() where TPopup : BasePopup
        {
            var type = typeof(TPopup);
            if (_popupCache.TryGetValue(type, out var cached) && cached != null) return (TPopup)cached;

            var prefab = LoadPopupPrefab<TPopup>();
            if (prefab == null)
            {
                Debug.LogError($"[UIController] Popup prefab for {type.Name} not found at {POPUPS_RESOURCES}/{type.Name}. Ensure the prefab exists in a Resources folder.");
                return null;
            }

            var instance = UnityEngine.Object.Instantiate(prefab, _uiParent.PopupParent);
            instance.gameObject.SetActive(false);

            var popup = instance.GetComponent<TPopup>();
            _popupCache[type] = popup;

            return popup;
        }

        private TScreen GetOrCreateScreen<TScreen>() where TScreen : BaseScreen
        {
            var type = typeof(TScreen);
            if (_ScreenCache.TryGetValue(type, out var cached) && cached != null) return (TScreen)cached;

            var prefab = LoadScreenPrefab<TScreen>();
            if (prefab == null)
            {
                Debug.LogError($"[UIController] Screen prefab for {type.Name} not found at {SCREENS_RESOURCES}/{type.Name}. Ensure the prefab exists in a Resources folder.");
                return null;
            }

            var instance = UnityEngine.Object.Instantiate(prefab, _uiParent.ScreenParent);
            instance.gameObject.SetActive(false);

            var screen = instance.GetComponent<TScreen>();
            _ScreenCache[type] = screen;

            return screen;
        }

        private TPopup  LoadPopupPrefab<TPopup>() where TPopup : BasePopup     => LoadViewPrefab<TPopup>(POPUPS_RESOURCES);
        private TScreen LoadScreenPrefab<TScreen>() where TScreen : BaseScreen => LoadViewPrefab<TScreen>(SCREENS_RESOURCES);

        private static T LoadViewPrefab<T>(string resourcesPath) where T : MonoBehaviour
        {
            var type = typeof(T);
            var path = $"{resourcesPath}/{type.Name}";
            var go   = Resources.Load<GameObject>(path);
            return go != null ? go.GetComponent<T>() : null;
        }

        private void UpdateBackgroundForTopPopup()
        {
            var backgroundGO = _uiParent.BackgroundGO;
            if (backgroundGO == null) return;

            if (_popupStack.Count > 0)
            {
                var topPopup = _popupStack.Peek();
                if (topPopup != null && topPopup.gameObject.activeSelf)
                {
                    // Position background one step behind the top popup
                    var topPopupIndex = topPopup.transform.GetSiblingIndex();
                    backgroundGO.SetActive(true);
                    backgroundGO.transform.SetSiblingIndex(Mathf.Max(0, topPopupIndex - 1));
                }
                else
                {
                    // Top popup is inactive, hide background
                    backgroundGO.SetActive(false);
                }
            }
            else
            {
                // No popups in stack, hide background
                backgroundGO.SetActive(false);
            }
        }
    }
}

Usage:

var ui = ControllerHandler.GetController<UIController>();
await ui.PushPopupAsync<MyPopup>();
await ui.PopPopupAsync();
await ui.ShowScreenAsync<MainMenuScreen>();
await ui.HideScreenAsync<LoadingScreen>();

UIController also updates the background GameObject so it indexes behind the top popup.

It uses GetOrCreatePopup<TPopup>() / GetOrCreateScreen<TScreen>() to load and cache prefabs from Resources/UIPrefabs/Popups/<TypeName> and Resources/UIPrefabs/Screens/<TypeName>, pushes popups onto a stack, and shows/hides screens with async methods.

UIParent is a MonoBehaviour that holds references to ScreenParent, PopupParent, and BackgroundGO:

using UnityEngine;

namespace com.core.ui
{
    public class UIParent : MonoBehaviour
    {
        [SerializeField] private Transform  screensParent;
        [SerializeField] private Transform  popupsParent;
        [SerializeField] private GameObject backgroundGO;

        public Transform  ScreenParent => screensParent;
        public Transform  PopupParent  => popupsParent;
        public GameObject BackgroundGO => backgroundGO;
    }
}

UIParent prefab has a canvas and UIParent script attached:

There are a couple limitations here as well. First, popups and screens must live under Resources/UIPrefabs/Popups and Resources/UIPrefabs/Screens. Second, prefab name must match the script/type name (for example, TestPopup prefab name for a script named TestPopup).

Summary

In this article, you set up a Unity project and walked through creating four reusable packages:

• com.core.initializer – You created the package, added UniTask, defined IController, used the Creator helper to find and create controllers (including MonoBehaviours), and implemented ControllerHandler to run initialization at BeforeSceneLoad and expose controllers via GetController<T>().

• com.core.data – You use IDataProvider and LocalDataProvider with MemoryPack for binary local save/load, and the DataController that implements IController and tracks version history.

• com.core.dotween – You wrap the DoTween asset as a package so other packages (like com.core.ui) can reference it for animations.

• com.core.ui – You created a modular UI package that you can use in your games to handle popups and full size screens. You can also extend this to add other UI types in the future.

Building these as separate packages keeps your code modular and speeds up development across projects. You can install each package via Git into any Unity project.

Example manifest.json file to implement these packages:

{
  "dependencies"    : {
	"com.core.data"       : "https://github.com/TalhaCagatay/com.core.data.git#v0.1.0",
	"com.core.initializer": "https://github.com/TalhaCagatay/com.core.initializer.git#v0.1.0",
	"com.core.dotween"    : "https://github.com/TalhaCagatay/com.core.dotween.git#v0.1.0",
	"com.core.ui"         : "https://github.com/TalhaCagatay/com.core.ui.git#v0.1.0"
  },
  "scopedRegistries": [
	{
	  "name"  : "package.openupm.com",
	  "url"   : "https://package.openupm.com",
	  "scopes": [
		"com.cysharp.unitask",
		"com.cysharp.memorypack"
	  ]
	}
  ]
}

Resources:

• com.core.initializer on GitHub

• com.core.data on GitHub

• com.core.dotween on Github

• com.core.ui on Github

• Example game that I developed and used many modular systems like the ones you built in this article.

Whether you are building a pixel-art indie game or a high-fidelity 3D world, understanding how resolution works is essential.

It affects how your art assets scale, how your UI appears, and how your game feels on different screens. Yet, many developers still treat resolution as a simple number instead of a design decision.

Let’s learn what resolutions are and why it matters for game developers.

What we will Cover

• What Resolution Really Means

• The Evolution of Resolution in Gaming

• DPI, Scaling, and Texture Clarity

• Resolution vs. Performance

• Aspect Ratio and Display Diversity

• The Art of Testing in 4K and HDR

• Preparing for Next-Gen Displays

• Conclusion

What Resolution Really Means

Resolution defines how many pixels a screen can display horizontally and vertically.

A monitor labelled 1920x1080 has 1920 pixels across and 1080 down, which equals over two million pixels in total. More pixels mean more visual detail but also more rendering work for the GPU.

In game development, that tradeoff is constant. Rendering at higher resolutions improves clarity but reduces frame rates unless your code and assets are optimized.

Many developers solve this by offering resolution scaling options in their games, letting players balance visual quality and performance.

It’s also important to distinguish between screen size and resolution. A 27-inch monitor and a 15-inch laptop can both run at 1080p, but the larger display will have bigger, less dense pixels.

This is where pixel density comes in. High-density displays pack more pixels per inch, creating smoother edges and sharper textures even at the same resolution.

The Evolution of Resolution in Gaming

Games have evolved alongside display technology.

Early consoles ran at 240p, then 480p during the SD era. The jump to HD with 720p and 1080p transformed game visuals. Suddenly, developers had to think about anti-aliasing, texture resolution, and UI scaling in new ways.

Today, 4K and HDR have become the standard for modern consoles and PCs. Developers now design with higher fidelity in mind, baking in lighting systems, shaders, and art pipelines that scale up to Ultra HD.

That’s why testing on different display resolutions isn’t just good practice, it’s critical for consistent player experience.

If you want to see how your game performs on large high-resolution displays, try testing it on a modern TV for PS5. These screens are optimized for 4K and 120Hz refresh rates, giving you a realistic look at how your game will appear in a living-room setup.

They also help you spot UI scaling issues, frame pacing problems, and HDR color mismatches that might go unnoticed on a typical monitor.

DPI, Scaling, and Texture Clarity

For web developers, DPI mostly affects how images scale. But for game developers, DPI connects directly to texture resolution and how art assets are perceived at different screen sizes.

A sprite that looks crisp on a 1080p monitor might appear tiny or blurry on a 4K display if not properly scaled. Engines like Unity and Unreal handle this with dynamic scaling options, but understanding the underlying math helps.

When your display density doubles, each asset needs four times as many pixels to appear at the same size and sharpness. If you do not plan for this, your carefully crafted textures might look soft or misaligned on higher-resolution displays.

This is why UI systems in modern engines rely on resolution-independent units. In Unity, Canvas Scaler helps ensure your interface looks the same on every device. In Unreal, DPI scaling rules allow developers to maintain consistent HUD layouts. Getting this right means your game remains legible on everything from handhelds to 8K TVs.

Resolution vs Performance

The biggest cost of higher resolution is GPU load. Rendering in 4K means pushing four times as many pixels as 1080p. Without proper optimization, frame rates can drop sharply.

That’s why many AAA games use resolution scaling techniques like temporal upsampling or DLSS. These methods render frames at a lower resolution and then use AI or interpolation to upscale them without losing clarity.

As a developer, you should test your game across multiple resolutions and aspect ratios. This helps ensure your render pipeline, shaders, and assets adapt smoothly. Tools like NVIDIA Nsight or Unreal’s built-in profiler show how resolution affects frame time and GPU usage.

If your game includes video content or cinematic sequences, also remember that video compression behaves differently at higher resolutions. Encoding 4K video requires significantly more bandwidth and storage, which can affect your build size and performance during playback.

Aspect Ratio and Display Diversity

Aspect ratio determines the shape of the display.

Most modern games target 16:9, but 21:9 ultrawide and 32:9 super-ultrawide displays are becoming more popular. Developers must ensure their camera framing and UI layouts adapt accordingly.

When a game is locked to one ratio, black bars or stretching can occur. To fix this, adjust your camera’s field of view dynamically or provide safe viewport settings.

Engines like Unreal let you script these adjustments easily, while Unity’s Cinemachine system handles FOV scaling automatically.

Even TVs now vary in aspect ratio capabilities, especially with new mini LED and OLED technologies. Testing across multiple ratios ensures your game looks balanced and cinematic on every screen.

The Art of Testing in 4K and HDR

4K and HDR introduce new layers of visual complexity. HDR displays show a wider range of brightness and color depth, which means lighting and textures can look completely different compared to SDR monitors. To handle this, calibrate your color grading pipeline and use tone mapping tools within your engine.

When working with HDR assets, always test your output on real hardware. Emulators and monitors often fail to reproduce true HDR contrast. A proper HDR-certified TV helps you identify overexposure, color clipping, and banding issues before release.

Preparing for Next-Gen Displays

The display industry continues to evolve fast. 8K and high refresh rate panels are already entering mainstream markets.

For developers, this means thinking ahead. Designing scalable rendering systems, supporting dynamic resolution, and maintaining flexible UI layouts are now essential parts of modern game design.

As displays get sharper, player expectations rise too. Textures, shaders, and post-processing all need to support higher levels of detail without compromising performance. By understanding how resolution interacts with your pipeline, you can future-proof your games for years to come.

Conclusion

Resolution is more than a number on a settings menu. It is a design constraint, a performance factor, and a creative opportunity. As a game developer, mastering resolution helps you build experiences that look sharp, play smoothly, and scale across every device.

The next time you polish your textures or fine-tune your rendering settings, remember that every pixel counts. Understanding how resolution, scaling, and density interact will not only make your games more beautiful but also more accessible to every player, whether they’re gaming on a laptop, a monitor, or the living-room tv that brings your visuals to life in stunning detail.

Hope you enjoyed this article. Find me on Linkedin or visit my website.

But creating even a simple game can teach lessons that no tutorial ever could. Games force you to think about performance, user input, structure, and creative problem-solving all at once.

When I started building small 2D games as weekend projects, I didn’t realize how much they would sharpen my overall coding skills. From learning how to organize complex systems to handling real-time input, every part of game development stretched my thinking.

Whether you’re a web developer, mobile engineer, or hobby coder, building games will make you a stronger problem solver.

Here are ten programming skills you’ll learn along the way.

Table of Contents

• 1. Thinking in Systems

• 2. Writing Event-Driven Code

• 3. Optimizing for Performance

• 4. Debugging Complex States

• 5. Handling User Input Responsively

• 6. Building Reusable Game Loops and Engines

• 7. Managing Complexity Through Components

• 8. Learning the Math That Actually Matters

• 9. Sharpening Your Design and UX Instincts

• 10. Embracing Creative Problem Solving

• Conclusion

1. Thinking in Systems

Every game is a set of systems working together. You might have a physics system that controls movement, a rendering system that draws the visuals, and an AI system that decides how enemies react.

Each one depends on the others, but they must remain separate enough to be managed and improved without breaking the rest of the game.

This is exactly what developers deal with in larger software projects. Building a game helps you understand modular design and why separating logic into smaller, independent parts makes everything easier to scale and debug.

You stop writing long scripts that try to do everything and instead start thinking in terms of systems that talk to each other through clear rules.

2. Writing Event-Driven Code

Games live and breathe on events. A button press, a collision, or a timer hitting zero are all events that trigger actions.

When you code a game, you quickly learn to think in event loops. This helps you understand how asynchronous code works in real life.

If you’ve struggled with JavaScript event listeners or backend message queues, building a small game is the perfect way to get comfortable with them.

Every time a player jumps, attacks, or collects an item, you’re writing code that listens for an event and reacts in real time. That experience makes you a better developer, even outside of gaming.

3. Optimizing for Performance

Unlike websites, games can’t afford to lag. A delay of even a few milliseconds can break the experience.

When you write games, you learn to measure performance constantly. You start thinking about memory usage, CPU load, and rendering time.

You might experiment with how often to update physics calculations or how to reuse textures instead of loading them every frame.

Those small optimizations become second nature, and later, when you’re building a web app or a backend service, you’ll know exactly where to look when something feels slow.

4. Debugging Complex States

Games are full of moving parts that interact in unpredictable ways. Maybe a character disappears after jumping twice, or a power-up triggers twice because of overlapping timers. These problems force you to learn structured debugging.

You’ll get used to adding logs, reproducing edge cases, and isolating bugs by breaking large systems into smaller ones. The patience and process you develop while debugging a tricky game bug translate perfectly to real-world software.

You become the kind of developer who doesn’t panic when something goes wrong because you’ve already handled far more chaotic code in your side projects.

5. Handling User Input Responsively

When you build a game, user input becomes one of your main concerns. You want the player’s actions to feel instant.

That means learning how to manage input devices like keyboards, mice, or best PC controllers. You’ll discover how to debounce actions, prevent lag, and detect simultaneous keypresses. You might even test your code with the best PC controller to make sure it feels smooth and accurate.

This focus on responsiveness changes how you approach every future project. You begin to see every button click or touch gesture as part of a feedback loop that should feel immediate and natural.

6. Building Reusable Game Loops and Engines

After writing a few games, you’ll realize that many parts of your code repeat. The main loop that updates the world, the input handlers, and the collision checks all follow patterns. This realization leads to a powerful skill: abstraction.

You start building small frameworks or reusable components that handle these repetitive tasks. In doing so, you learn the same lessons that professional developers learn when they design APIs or internal tools.

The discipline of turning messy scripts into organized, reusable code teaches you about structure and design in a way that theory never can.

7. Managing Complexity Through Components

Game developers often use something called an Entity-Component-System (ECS) architecture. It’s a way of organizing objects in a game so they can share behavior without heavy inheritance trees. For example, a player and an enemy might both have movement and health components, but different AI logic.

This pattern is very similar to how modern front-end frameworks work. If you use React, you already think in components. Building games strengthens that habit.

You start to see every system, UI, physics, AI, as a component that can be composed and reused. It’s one of the most powerful ways to manage complexity in any large codebase.

8. Learning the Math That Actually Matters

Many developers shy away from math, but games make it practical. When you need to move a character along a curve, calculate projectile motion, or detect collisions, you’re forced to use geometry, trigonometry, and vectors.

The best part is that you learn it through doing, not memorizing formulas. You begin to understand how angles, distances, and forces interact in a way that feels visual and intuitive. Later, when you face algorithmic problems or data visualizations, that math background helps you approach them with confidence.

9. Sharpening Your Design and UX Instincts

Good games feel right. The jump height, the delay between actions, the feedback when you collect a coin, every small detail affects how enjoyable the game feels.

When you design these experiences, you’re learning about user experience design without even realizing it.

You begin to think about things like timing, feedback, and accessibility. You learn how to make interactions satisfying and clear.

The same mindset applies when you build apps or websites. You start designing not just for functionality but for how it feels to use.

10. Embracing Creative Problem Solving

Games are rarely built in a straight line. You’ll face problems that don’t have clear answers.

Maybe you need a way to fake physics without heavy computation or make AI feel smarter than it is. These challenges train you to think creatively.

You’ll often come up with unconventional but clever solutions. That kind of flexible problem-solving becomes one of your most valuable programming skills.

When something breaks in production or a feature seems impossible under current constraints, you’ll know how to find a creative way around it because you’ve done it before in your own projects.

Conclusion

Building games is more than a hobby. It’s an accelerated crash course in becoming a better developer. You’ll write cleaner code, understand systems thinking, and develop a sharp sense for performance and design. You’ll also have fun in the process, which keeps your motivation alive longer than any tutorial series can.

Each project you build will teach you something new about programming. The lessons won’t come from books but from the moments you struggle, test, and finally see your creation come to life. Build something that teaches you back, and you’ll grow as both a coder and a creator.

Hope you enjoyed this article. Connect with me on Linkedin or visit my website.

Developers now have access to a wide variety of frameworks that make it easier to design, test, and launch games without having to build everything from scratch. Choosing the right framework can save months of effort, improve performance, and help you reach a wider audience.

In this article, we will look at the top five game development frameworks that stand out in the industry. Each one has its own strengths, community support, and use cases.

Whether you are a beginner making your first project or a studio working on the next big release, these frameworks can help you create world-class games.

Table of Contents

• Unity

• Unreal Engine

• Phaser

• Godot Engine

• Cocos2d-x

• Choosing the Right Framework

• Conclusion

Unity

Unity is one of the most popular game development frameworks in the world. It supports both 2D and 3D game development and is used by indie developers as well as large studios.

Unity’s biggest advantage is its flexibility. You can build a small mobile game, a full PC or console title, or even virtual reality and augmented reality experiences.

One of the reasons Unity is so widely used is its massive asset store. Developers can purchase or download free models, animations, scripts, and tools, which reduces the amount of custom work required.

The engine uses C# as its primary scripting language, which makes it approachable for developers with a background in programming.

Unity also offers strong cross-platform support. A single project can be exported to multiple platforms, including Android, iOS, Windows, macOS, PlayStation, Xbox, and even the web. For studios that want to maximize their reach, this is a critical feature.

Unity’s community and learning resources are another major strength. With thousands of tutorials, courses, and forums, new developers rarely feel stuck for long. This strong ecosystem makes Unity one of the best choices for anyone serious about building world-class games.

Unreal Engine

If Unity is known for flexibility, Unreal Engine is famous for raw power and graphical quality.

Unreal, developed by Epic Games, is widely used in AAA game studios and is the framework behind many of the most visually stunning games on the market. Its advanced rendering capabilities, physics system, and blueprint visual scripting make it a top choice for developers aiming for high-end graphics and performance.

Unreal Engine uses C++ for programming but also provides a node-based scripting system called Blueprints. This allows designers and artists who are not strong in coding to still build complex gameplay mechanics. For many teams, this blend of power and accessibility is ideal.

Unreal is also well-suited for projects outside of traditional games. It is used in industries such as film, architecture, and automotive design because of its ability to create realistic real-time 3D environments. This versatility makes it more than just a game engine.

The licensing model is another interesting factor. Unreal Engine can be used for free until your game earns a certain amount of revenue, making it accessible to both small and large developers. For anyone targeting high-quality visuals and professional-grade features, Unreal Engine is a natural choice.

Phaser

Phaser is a JavaScript-based framework designed for making 2D browser games. While Unity and Unreal focus on large-scale projects, Phaser excels in simplicity and speed for smaller games.

It allows developers to create interactive, fast, and lightweight games that can run directly in web browsers without needing downloads or installations.

Phaser’s strength is in 2D game development. It has built-in features for animations, physics, input handling, and asset management. Because it uses JavaScript, it’s easy to pick up for web developers who want to expand into game creation.

Many indie developers and educational platforms use Phaser to teach programming through games, which shows how approachable it is.

Another advantage of Phaser is its active community and open-source nature. Developers share plugins, examples, and tutorials that make it easier for beginners to learn. Phaser games can also be ported to mobile devices using tools like Cordova or Capacitor, which extends their reach beyond browsers.

For those looking to create casual, educational, or lightweight games that can reach millions through browsers, Phaser is one of the best frameworks available.

Godot Engine

Godot is an open-source game development framework that has quickly gained popularity. It stands out because of its flexibility, ease of use, and strong community-driven growth.

One of Godot’s unique features is its custom scripting language, GDScript, which is similar to Python and easy to learn. Developers can also use C# and C++ if they prefer.

Godot supports both 2D and 3D game development, and it has a well-designed scene system that makes organizing complex projects much easier. The engine is lightweight, which means it can run smoothly on low-end hardware, making it an attractive option for indie developers working on limited resources.

Another benefit of Godot is its licensing. Since it’s open-source and licensed under the MIT license, there are no royalties or fees required, even for commercial projects. This makes it a cost-effective choice for small studios and independent creators.

The Godot community has been growing rapidly, with many developers contributing new features and improvements. Tutorials, documentation, and community support have also improved, making it much easier for beginners to get started.

For developers who value freedom, low cost, and strong tools, Godot is a powerful option.

Cocos2d-x

Cocos2d-x is another popular open-source framework, mainly known for 2D game development. It’s written in C++ but also supports Lua and JavaScript scripting. Many mobile games, especially in Asia, have been built using Cocos2d-x because of its lightweight structure and fast performance.

Cocos2d-x is especially well-suited for mobile platforms like Android and iOS. It offers built-in physics, animations, audio, and scene management, making it a full solution for 2D game developers. Its focus on performance ensures smooth gameplay, even on devices with limited processing power.

Another reason developers choose Cocos2d-x is its flexibility in design. Since it’s open-source, teams can modify the engine itself to fit their project’s needs. This level of control is not always possible with larger commercial engines.

Cocos2d-x also benefits from an active community and strong documentation. Many developers find it easier to learn compared to larger frameworks, which makes it an excellent starting point for those focused on 2D games.

Choosing the Right Framework

Selecting the best framework depends on your goals and resources.

If you want maximum reach across platforms and a wide range of features, Unity is a safe bet. For high-end graphics and AAA-level projects, Unreal Engine shines.

If you are aiming for browser-based casual games, Phaser is an excellent choice. For developers who value open-source freedom and a supportive community, Godot is growing fast. And if your focus is mobile 2D development, Cocos2d-x provides the performance and control you need.

One often overlooked factor in game development is the hardware you use for testing and building your projects. While high-end systems can help speed up workflows, many developers start with modest setups.

Thanks to the growing availability of budget-friendly components like cheap motherboards for gaming, even small studios can assemble a capable machine for development without breaking the bank. This means that powerful tools like Unity or Unreal are no longer limited to large companies with expensive equipment.

Conclusion

Game development has become more accessible than ever before. With frameworks like Unity, Unreal Engine, Phaser, Godot, and Cocos2d-x, developers at all levels have the tools needed to create world-class games.

Each framework has its own advantages, whether it is high-end graphics, simplicity, or open-source freedom. The key is to choose the one that best matches your project goals, team skills, and target platforms.

Hope you enjoyed this article. Connect with me on Linkedin or visit my website.

In this guide, you’ll learn what Phaser is and then use it to build the popular Snake game. The snake moves on a grid. It eats food to grow. It dies if it hits a wall or itself. The full project fits in two files, and the code is split into small blocks so it’s easy to follow.

By the end, you’ll be able to understand and copy the code, run it, and tweak it. You’ll also learn why each part exists and how it fits into the Phaser way of doing things.

Play the game here to get a feel for what you’ll be building.

Table of Contents

• What is Phaser.js?

• Project Setup

• Grid, Colors, and Game Config

• Scene State and Helper Functions

• Preload and Create

• Initialize the Game

• Reading Input Each Frame

• Stepping the Snake, Eating, and Drawing

• Spawning Food and Increasing Speed

• Game Over and Restart

• How the Whole Thing Fits Together

• Useful Next Steps

• Final Thoughts

What is Phaser.js?

Phaser is a free JavaScript library for 2D games. You write plain JavaScript and let Phaser do the heavy lifting. You don’t need a build system or a game engine installer. You can start with a single HTML file and one JavaScript file.

Phaser organizes code into scenes. A scene has three common steps. You load assets in preload, you set up images and variables in create, and you update your game each frame in update. That small loop is the core of most arcade games.

Now let’s setup the project.

Project Setup

Create a folder with two files named index.html and main.js. The HTML page loads Phaser from a CDN and then loads your script.

<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Phaser Snake</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <style>body { margin: 0; background: #111; }</style>
  </head>
  <body>
    <div id="game"></div>
    <script src="https://cdn.jsdelivr.net/npm/phaser@3/dist/phaser.min.js"></script>
    <script src="main.js"></script>
  </body>
</html>

This page adds a container div and includes Phaser 3 from jsDelivr. Your main.js file will create the game and attach it to that div.

Grid, Colors, and Game Config

Snake is easiest on a grid. You choose a tile size and a number of tiles wide and high. You also define colors for the background, the snake, and the food. Then you create a Phaser game config that points to your scene functions.

// main.js (part 1)

// Size of one grid tile in pixels
const TILE = 16;

// Number of tiles across (columns) and down (rows)
// Game area = 40 * 16px wide (640px) and 30 * 16px tall (480px)
const COLS = 40;                 
const ROWS = 30;                 

// Total pixel width and height of the game canvas
const WIDTH = COLS * TILE;
const HEIGHT = ROWS * TILE;

// Colors for background, snake head, snake body, and food
const COLORS = {
  bg: 0x1d1d1d,   // dark gray background
  head: 0x30c452, // bright green head
  body: 0x2aa04a, // darker green body
  food: 0xe94f37, // red food
};

// Directions represented as x and y offsets on the grid
// For example, moving left means x decreases by 1, y stays the same
const DIR = {
  left:  { x: -1, y:  0, name: 'left'  },
  right: { x:  1, y:  0, name: 'right' },
  up:    { x:  0, y: -1, name: 'up'    },
  down:  { x:  0, y:  1, name: 'down'  },
};

// Phaser game configuration
// - type: Phaser will use WebGL if possible, otherwise Canvas
// - parent: attach game canvas to <div id="game">
// - width/height: set canvas size
// - backgroundColor: dark background from COLORS
// - scene: defines which functions run during preload, create, and update
const config = {
  type: Phaser.AUTO,
  parent: 'game',
  width: WIDTH,
  height: HEIGHT,
  backgroundColor: COLORS.bg,
  scene: { preload, create, update }
};

// Create a new Phaser game with the config
new Phaser.Game(config);

The config tells Phaser to create a canvas, set its size, and use your scene functions. Phaser.AUTO selects WebGL if possible and falls back to Canvas.

Scene State and Helper Functions

You need to store the snake’s body as grid cells, the rectangles that draw those cells, the direction of travel, the queued input, the food cell, the score, and the movement timer. A few helper functions keep the math clean.

// main.js (part 2)

// Snake state
let snake;           // Array of grid cells [{x, y}, ...]; index 0 = head
let snakeRects;      // Array of Phaser rectangles drawn at snake cell positions
let direction;       // Current direction of snake movement (object from DIR)
let nextDirection;   // Next direction chosen by player input (applied on step)
let food;            // Current food cell {x, y}
let score = 0;       // Current score count
let scoreText;       // Phaser text object that displays the score
let moveEvent;       // Phaser timer event to move snake at fixed intervals
let speedMs = 130;   // Delay in milliseconds between moves (lower = faster)

// Input state
let cursors;         // Phaser helper object for arrow keys
let spaceKey;        // Phaser Key object for Space bar (restart the game)

/**
 * Convert a grid cell (x,y) to its pixel center (px,py) on the canvas.
 * Example: (0,0) -> (8,8) if TILE=16. Ensures rectangles are centered.
 */
function gridToPixelCenter(x, y) {
  return { px: x * TILE + TILE / 2, py: y * TILE + TILE / 2 };
}

/**
 * Pick a random grid cell that is not occupied by any cell in excludeCells.
 * - Creates a Set of occupied cells as "x,y" strings for fast lookup.
 * - Keeps generating random cells until it finds a free one.
 * Used to place food so it never spawns on the snake.
 */
function randomFreeCell(excludeCells) {
  const occupied = new Set(excludeCells.map(c => `${c.x},${c.y}`));
  while (true) {
    const x = Math.floor(Math.random() * COLS);
    const y = Math.floor(Math.random() * ROWS);
    if (!occupied.has(`${x},${y}`)) return { x, y };
  }
}

/**
 * Check if direction 'a' is exactly the opposite of direction 'b'.
 * Example: left vs right, or up vs down.
 * This prevents the snake from instantly turning 180° into itself.
 */
function isOpposite(a, b) {
  return a.x === -b.x && a.y === -b.y;
}

gridToPixelCenter converts a grid cell to the center point in pixels so rectangles line up. randomFreeCell finds a cell not used by the snake. isOpposite helps block instant reversals that would cause a crash.

Preload and Create

This game uses simple vector rectangles, so there are no images to load. You still define the scene functions since Phaser calls them by name from your config.

// main.js (part 3)

/**
 * preload()
 * Runs once before the game starts.
 * Used for loading images, sounds, and other assets.
 * In this version, we use simple colored rectangles (no assets needed).
 */
function preload() {
  // No assets to load in this version.
}

/**
 * create()
 * Runs once after preload. Sets up the game scene.
 * - Prepares keyboard input
 * - Calls initGame() to build the snake, food, score UI, and start movement
 */
function create() {
  // Phaser helper that gives us arrow key input (up, down, left, right)
  cursors = this.input.keyboard.createCursorKeys();

  // Register the Space bar key to restart the game later
  spaceKey = this.input.keyboard.addKey(Phaser.Input.Keyboard.KeyCodes.SPACE);

  // Initialize the game state (snake, food, score, timer)
  // Using call(this) so that initGame runs in the context of the scene
  initGame.call(this);
}

The create step sets up keyboard input. It then calls initGame to build the first snake, place food, and start the timer. The call(this) ensures the helper function can use the scene’s this.

Initialize the Game

On a fresh start or a restart, you need to clear old timers and shapes, reset the score, build a short snake in the middle, draw it, place food, and start the movement loop.

// main.js (part 4)

/**
 * initGame()
 * Called when the game first starts or after pressing Space to restart.
 * - Clears old state (snake, food, timers)
 * - Resets score
 * - Creates a new snake in the center of the grid
 * - Spawns the first food
 * - Sets up score text
 * - Starts the timed loop that moves the snake
 */
function initGame() {
  // If an old movement timer exists, stop it (avoid multiple timers running)
  if (moveEvent) moveEvent.remove(false);

  // If old snake rectangles exist, destroy them to clean the screen
  if (snakeRects) snakeRects.forEach(r => r.destroy());

  // Reset the score and snake direction
  score = 0;
  direction = DIR.right;     // Snake starts moving to the right
  nextDirection = DIR.right; // Player input queue also points right

  // Find the starting position near the center of the grid
  const startX = Math.floor(COLS / 2);
  const startY = Math.floor(ROWS / 2);

  // Snake starts with 3 segments, head + 2 body pieces
  snake = [
    { x: startX,     y: startY },     // head (middle)
    { x: startX - 1, y: startY },     // body segment left of head
    { x: startX - 2, y: startY },     // tail further left
  ];

  // Create rectangle objects in Phaser to visually draw the snake
  snakeRects = snake.map((cell, i) => {
    const { px, py } = gridToPixelCenter(cell.x, cell.y); // convert grid to pixel center
    const color = i === 0 ? COLORS.head : COLORS.body;    // head is a brighter green
    const rect = this.add.rectangle(px, py, TILE - 2, TILE - 2, color); // slightly smaller for spacing
    rect.setOrigin(0.5, 0.5);                             // center anchor point
    return rect;
  });

  // Spawn food at a random free cell (not overlapping snake)
  food = randomFreeCell(snake);
  const { px, py } = gridToPixelCenter(food.x, food.y);

  // If food already exists from a previous run, remove it first
  if (this.foodRect) this.foodRect.destroy();

  // Draw the new food as a red rectangle
  this.foodRect = this.add.rectangle(px, py, TILE - 2, TILE - 2, COLORS.food);

  // If score text does not exist yet, create it
  // Otherwise (on restart), just reset its value
  if (!scoreText) {
    scoreText = this.add.text(8, 6, 'Score: 0', { fontFamily: 'monospace', fontSize: 18, color: '#fff' });
    this.add.text(8, 28, 'Arrows to move. Space to restart.', { fontFamily: 'monospace', fontSize: 14, color: '#aaa' });
  } else {
    scoreText.setText('Score: 0');
  }

  // Reset speed and create a repeating timer
  // Every "speedMs" milliseconds, stepSnake() will run to move the snake
  speedMs = 130;
  moveEvent = this.time.addEvent({
    delay: speedMs,
    loop: true,
    callback: () => stepSnake.call(this) // .call(this) keeps Phaser scene context
  });

  // If a "Game Over" message exists from the last run, remove it
  if (this.gameOverText) {
    this.gameOverText.destroy();
    this.gameOverText = null;
  }
}

The rectangles are one or two pixels smaller than the tile so you get a neat gap between cells. The time event calls stepSnake on a fixed rhythm. This rhythm is separate from the frame rate, which keeps movement stable across machines.

Reading Input Each Frame

You will read the arrow keys in update. You don’t move the snake here. You only set the next direction. Movement happens on the timer so the game has a steady pace.

// main.js (part 5)

/**
 * update()
 * This runs every frame (Phaser’s game loop).
 * - Reads player input from arrow keys
 * - Updates "nextDirection" so the snake will turn on the next step
 * - Listens for Space bar press to restart the game if it’s over
 */
function update() {
  // Check if LEFT arrow is pressed AND it’s not the opposite of current direction
  if (cursors.left.isDown && !isOpposite(DIR.left, direction)) {
    nextDirection = DIR.left;

  // Check if RIGHT arrow is pressed
  } else if (cursors.right.isDown && !isOpposite(DIR.right, direction)) {
    nextDirection = DIR.right;

  // Check if UP arrow is pressed
  } else if (cursors.up.isDown && !isOpposite(DIR.up, direction)) {
    nextDirection = DIR.up;

  // Check if DOWN arrow is pressed
  } else if (cursors.down.isDown && !isOpposite(DIR.down, direction)) {
    nextDirection = DIR.down;
  }

  // If the game is over (a "Game Over" text exists)
  // AND the Space bar was just pressed → restart the game
  if (this.gameOverText && Phaser.Input.Keyboard.JustDown(spaceKey)) {
    initGame.call(this); // Reset everything (snake, food, score, timer)
  }
}

This pattern prevents the snake from skipping cells if the frame rate spikes. It also makes the game feel fair. Your key presses get picked up, but the body moves on the beat set by the timer.

Stepping the Snake, Eating, and Drawing

This function is the heart of the game. It picks up the queued input, computes the next head cell, checks collisions, moves or grows the snake, updates the score, and refreshes colors.

// main.js (part 6)

/**
 * stepSnake()
 * This function runs every "tick" (based on the timer).
 * - Moves the snake forward by one cell
 * - Checks for collisions (wall or self)
 * - Handles eating food (grow + score)
 * - Updates the snake's rectangles on the screen
 */
function stepSnake() {
  // Apply the direction chosen in update() (queued by player input)
  direction = nextDirection;

  // Get the current head of the snake
  const head = snake[0];

  // Create a new head position by moving one cell in the current direction
  const newHead = { x: head.x + direction.x, y: head.y + direction.y };

  // === Collision Check #1: Wall ===
  // If the new head is outside the grid, the game ends
  if (newHead.x < 0 || newHead.x >= COLS || newHead.y < 0 || newHead.y >= ROWS) {
    return endGame.call(this);
  }

  // === Collision Check #2: Self ===
  // If the new head overlaps any snake cell, the game ends
  for (let i = 0; i < snake.length; i++) {
    if (snake[i].x === newHead.x && snake[i].y === newHead.y) {
      return endGame.call(this);
    }
  }

  // === Check if food was eaten ===
  const ate = newHead.x === food.x && newHead.y === food.y;

  // Add the new head cell to the front of the snake array
  snake.unshift(newHead);

  if (!ate) {
    // Case: Snake did NOT eat food → keep length the same
    // Remove last cell from snake array (tail)
    snake.pop();

    // Reuse the last rectangle object for performance
    const tailRect = snakeRects.pop();
    const { px, py } = gridToPixelCenter(newHead.x, newHead.y);
    tailRect.setPosition(px, py);       // Move it to the new head position
    snakeRects.unshift(tailRect);       // Put it at the front of the rectangle list
  } else {
    // Case: Snake DID eat food → grow longer
    // Create a new rectangle for the new head (since length increases)
    const { px, py } = gridToPixelCenter(newHead.x, newHead.y);
    const headRect = this.add.rectangle(px, py, TILE - 2, TILE - 2, COLORS.head);
    snakeRects.unshift(headRect);

    // Increase score and update text
    score += 10;
    scoreText.setText(`Score: ${score}`);

    // Place new food somewhere else
    placeFood.call(this);

    // Speed up slightly as difficulty curve
    maybeSpeedUp.call(this);
  }

  // === Update Colors ===
  // Ensure only index 0 is drawn as the "head" (bright green),
  // and the next segment becomes part of the "body"
  if (snakeRects[1]) snakeRects[1].setFillStyle(COLORS.body);
  snakeRects[0].setFillStyle(COLORS.head);
}

The movement rule is simple. Add a head in the current direction. If you did not eat, remove the tail. If you ate, keep the tail to grow by one. To draw this, you reuse the last rectangle when you only move. You move it to the head’s new pixel location and put it at the front of the list. When you grow, you create a new rectangle for the new head.

Spawning Food and Increasing Speed

After eating, you need to place food in a new free cell. You can also nudge the speed so the game gets harder over time.

// main.js (part 7)

/**
 * placeFood()
 * Spawns food at a new random cell that is NOT part of the snake.
 * - Uses randomFreeCell() to avoid collisions with the snake
 * - Moves the existing red rectangle (foodRect) to the new spot
 */
function placeFood() {
  // Pick a random free cell on the grid (not occupied by the snake)
  food = randomFreeCell(snake);

  // Convert that cell into pixel coordinates
  const { px, py } = gridToPixelCenter(food.x, food.y);

  // Move the existing food rectangle to the new position
  this.foodRect.setPosition(px, py);
}

/**
 * maybeSpeedUp()
 * Makes the game a little harder each time food is eaten.
 * - Decreases the move delay (snake moves faster)
 * - Restarts the timer with the new speed
 * - Stops speeding up once a lower bound (70ms) is reached
 */
function maybeSpeedUp() {
  // Only speed up if current speed is above the minimum threshold
  if (speedMs > 70) {
    // Make the snake faster by reducing the delay
    speedMs -= 3;

    // Remove the old movement timer
    moveEvent.remove(false);

    // Create a new timer with the updated speed
    moveEvent = this.time.addEvent({
      delay: speedMs,            // shorter delay = faster movement
      loop: true,                // repeat forever until game over
      callback: () => stepSnake.call(this) // keep "this" as the scene
    });
  }
}

There is a lower bound for speed so the game does not become unreadable. You can tune these numbers to match the feel you want.

Game Over and Restart

When the snake hits a wall or itself, the run ends. You stop the timer and show a message. Pressing space restarts the game.

// main.js (part 8)

/**
 * endGame()
 * Called when the snake hits a wall or itself.
 * - Stops the movement timer (snake no longer moves)
 * - Displays a "Game Over" message with the final score
 * - Waits for the player to press Space (handled in update()) to restart
 */
function endGame() {
  // Stop the movement timer so the snake no longer steps forward
  moveEvent.remove(false);

  // Define text style for the "Game Over" message
  const style = {
    fontFamily: 'monospace',
    fontSize: 28,
    color: '#fff',
    align: 'center'
  };

  // Message shows "Game Over", final score, and restart instructions
  const msg = `Game Over\nScore: ${score}\nPress Space to Restart`;

  // Add text to the center of the screen
  // .setOrigin(0.5, 0.5) makes the text anchor at its center
  this.gameOverText = this.add.text(WIDTH / 2, HEIGHT / 2, msg, style).setOrigin(0.5, 0.5);
}

The update function you wrote earlier listens for space using JustDown, so the restart happens only once per key press.

How the Whole Thing Fits Together

You now have the full loop of a Phaser scene. The preload is empty in this version because rectangles do not need assets. The create step connects keyboard input and calls initGame. The timer created in initGame keeps time for movement.

The update step reads keys every frame and sets a future direction. The stepSnake function runs on the timer. It moves the head, checks for a crash, handles growth, reuses shapes for performance, and updates the score. When the run ends, endGame stops the timer and shows a clear message. A single key press calls initGame to start fresh.

This style maps well to many other small games. If you can express your game state as data and move it on a schedule, you can draw it with simple shapes or sprites. Phaser’s time events give you a clean heartbeat. Its input system gives you easy key handling. Its drawing API makes it quick to show rectangles, text, or images.

Useful Next Steps

There are many small features you can add without changing the core. You can store a high score in localStorage. You can add simple sounds when you eat or when the game ends by loading audio in preload and calling this.sound.play in the right places.

You can make the world wrap at the edges by replacing the wall check with modulo math so the snake appears on the opposite side. You can theme the game by swapping rectangle colors or replacing rectangles with images.

Each of these additions builds on the same base. Keep the grid logic simple. Keep the state in clear arrays and objects. Move on a fixed timer. Draw based on the state. That’s the pattern.

Final Thoughts

You started with a blank page and ended with a working browser game. You set up Phaser, built a scene, and used a timer to drive movement. You learned how to handle input in a safe way, how to grow the snake, how to detect collisions, and how to draw with rectangles. You kept the code tidy with small helper functions and clear names.

From here, you can branch out to other grid games like Tetris or Minesweeper, or you can try a different style like Pong or Breakout. The structure will be similar. A scene to set things up, a timer or physics step to move things along, and a few rules that define the fun. That’s the beauty of Phaser for beginners.

If you’re into online gaming, GameBoost is the place to be. Discover GTA Modded Accounts packed with exclusive upgrades. You’ll also find accounts for other fan-favorite titles like Fortnite, Grow a Garden, Clash of Clans, and more – all in one trusted marketplace.

In this tutorial, you’ll learn how to build tic-tac-toe using Phaser.js, a fast, fun, and open source framework for making 2D games in the browser.

If you’re new to Phaser.js, don’t worry. We’ll walk through everything step-by-step. By the end, you’ll have a working game that you can play, share, or build upon.

You can play the game here to get a feel of what you are going to build.

Table of Contents

• What is Phaser.js?

• Project Setup

• How to Set Up the Game Configuration

• How to Preload Assets

• How to Create the Game Scene

• How to Draw the Grid

• How to Initialize and Reset the Game

• How to Handle Player Input

• How to Place Marks on the Board

• How to Check for a Winner

• How to Detect a Draw

• How to Draw the Winning Line

• Final Thoughts

What is Phaser.js?

Phaser.js is a free and open-source JavaScript game framework. It helps developers create HTML5 games that work across web browsers. Phaser handles things like rendering graphics, detecting input, and running the game loop.

You can use Phaser to make simple games like Pong and Tic-Tac-Toe or advanced platformers and role playing games. It supports both Canvas and WebGL rendering, so your games will run smoothly on most devices.

Project Setup

Create a folder for your project and add two files: index.html and game.js. The HTML file loads Phaser and the JavaScript file contains the game logic. Here is the repository with the finished code.

Here’s what the index.html file should look like:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>Tic Tac Toe — Phaser 3</title>
  <meta name="viewport" content="width=device-width,initial-scale=1" />
  <style>
    html, body { height: 100%; margin: 0; background: #0f172a; display: grid; place-items: center; }
    #game { box-shadow: 0 10px 30px rgba(0,0,0,.35); border-radius: 12px; overflow: hidden; }
    .hint { color: #e2e8f0; margin-top: 10px; font-size: 14px; text-align: center; opacity: .85; }
  </style>
  <script src="https://cdn.jsdelivr.net/npm/phaser@3.60.0/dist/phaser.min.js"></script>
</head>
<body>
  <div id="game"></div>
  <div class="hint">Click a cell to play. Tap “Restart” to start over.</div>
  <script src="./game.js"></script>
</body>
</html>

This sets up a simple HTML page, loads Phaser from a CDN, and points to your game.js file. The #game container is where Phaser will insert the game canvas.

How to Set Up the Game Configuration

Phaser games are built from a configuration object that defines things like width, height, background color, and which functions to call for loading, creating, and updating the game.

(() => {
  const GRID = 3;
  const CELL = 120;
  const BOARD = GRID * CELL;
  const HUD = 72;
  const WIDTH = BOARD;
  const HEIGHT = BOARD + HUD;

  let scene;
  let board;
  let currentPlayer;
  let gameOver;

  let gridGfx;
  let overlayGfx;
  let marks = [];
  let statusText;
  let restartText;

  const config = {
    type: Phaser.AUTO,
    parent: "game",
    width: WIDTH,
    height: HEIGHT,
    backgroundColor: "#ffffff",
    scale: { mode: Phaser.Scale.FIT, autoCenter: Phaser.Scale.CENTER_BOTH },
    scene: { preload, create, update }
  };

  new Phaser.Game(config);

We start by defining constants for the grid size and cell size. The config object tells Phaser to create a game with these dimensions and use the preload, create, and update functions we will define.

How to Preload Assets

Since we are drawing everything with Phaser’s graphics and text tools, we do not need to load any external images or sounds.

  function preload() {
    // No assets to load
  }

This is a placeholder that lets Phaser call preload before the game starts.

How to Create the Game Scene

The create function runs once at the start of the scene. Here we draw the grid, set up the initial state, and add UI elements.

  function create() {
    scene = this;

    gridGfx = scene.add.graphics({ lineStyle: { width: 4, color: 0x000000 } });
    overlayGfx = scene.add.graphics();
    drawGrid();

    initGame();

    statusText = scene.add.text(WIDTH / 2, BOARD + 12, "Player X's turn", {
      fontSize: "20px",
      color: "#111",
      fontFamily: "Arial, Helvetica, sans-serif"
    }).setOrigin(0.5, 0);

    restartText = scene.add.text(WIDTH / 2, BOARD + 38, "Restart", {
      fontSize: "18px",
      color: "#2563eb",
      fontFamily: "Arial, Helvetica, sans-serif"
    }).setOrigin(0.5, 0).setInteractive({ useHandCursor: true });

    restartText.on("pointerup", hardReset);

    scene.input.on("pointerdown", onPointerDown, scene);
  }

We created two Graphics objects: one for the static grid and another for the win line. Then we called drawGrid() and initGame() to set up the game board. The status text and restart button are placed below the grid. We also listened for clicks on the board with pointerdown.

How to Draw the Grid

The grid is made up of two vertical and two horizontal lines.

  function drawGrid() {
    gridGfx.strokeLineShape(new Phaser.Geom.Line(CELL, 0, CELL, BOARD));
    gridGfx.strokeLineShape(new Phaser.Geom.Line(CELL * 2, 0, CELL * 2, BOARD));
    gridGfx.strokeLineShape(new Phaser.Geom.Line(0, CELL, BOARD, CELL));
    gridGfx.strokeLineShape(new Phaser.Geom.Line(0, CELL * 2, BOARD, CELL * 2));
  }

We use Phaser.Geom.Line to define the start and end points for each line and then draw them with strokeLineShape.

How to Initialize and Reset the Game

The initGame function sets up a new game, and hardReset is called when the restart button is clicked.

  function initGame() {
    board = Array.from({ length: GRID }, () => Array(GRID).fill(""));
    currentPlayer = "X";
    gameOver = false;
    overlayGfx.clear();
    for (const t of marks) t.destroy();
    marks = [];
    setStatus("Player X's turn");
  }

  function hardReset() {
    initGame();
  }

  function setStatus(msg) {
    statusText && statusText.setText(msg);
  }

The board is represented by a 2D array filled with empty strings. The current player starts as X, and the marks array keeps track of text objects so we can clear them on reset.

How to Handle Player Input

When the player clicks a cell, we determine its row and column and check if the move is valid.

  function onPointerDown(pointer) {
    if (gameOver) return;
    if (pointer.y > BOARD) return;

    const col = Math.floor(pointer.x / CELL);
    const row = Math.floor(pointer.y / CELL);
    if (!inBounds(row, col)) return;
    if (board[row][col] !== "") return;

    placeMark(row, col, currentPlayer);

    const win = checkWin(board);
    if (win) {
      gameOver = true;
      drawWinLine(win);
      setStatus(`Player ${currentPlayer} wins!`);
      return;
    }

    if (isFull(board)) {
      gameOver = true;
      setStatus("Draw! No more moves.");
      return;
    }

    currentPlayer = currentPlayer === "X" ? "O" : "X";
    setStatus(`Player ${currentPlayer}'s turn`);
  }

This ensures that we only act if the game is not over, the click is inside the board, and the chosen cell is empty. After placing a mark, we check for a win or draw before switching turns.

How to Place Marks on the Board

We display an X or O at the center of the clicked cell.

  function inBounds(r, c) {
    return r >= 0 && r < GRID && c >= 0 && c < GRID;
  }

  function placeMark(row, col, player) {
    board[row][col] = player;
    const cx = col * CELL + CELL / 2;
    const cy = row * CELL + CELL / 2;
    const t = scene.add.text(cx, cy, player, {
      fontSize: Math.floor(CELL * 0.66) + "px",
      color: "#111111",
      fontFamily: "Arial, Helvetica, sans-serif"
    }).setOrigin(0.5);
    marks.push(t);
  }

The coordinates are calculated so the text is centered in the cell. We store the text object in the marks array so it can be removed when resetting.

How to Check for a Winner

We check rows, columns, and diagonals to see if the current player has three in a row.

  function checkWin(b) {
    for (let r = 0; r < GRID; r++) {
      if (b[r][0] && b[r][0] === b[r][1] && b[r][1] === b[r][2]) {
        return { kind: "row", index: r };
      }
    }
    for (let c = 0; c < GRID; c++) {
      if (b[0][c] && b[0][c] === b[1][c] && b[1][c] === b[2][c]) {
        return { kind: "col", index: c };
      }
    }
    if (b[0][0] && b[0][0] === b[1][1] && b[1][1] === b[2][2]) {
      return { kind: "diag" };
    }
    if (b[0][2] && b[0][2] === b[1][1] && b[1][1] === b[2][0]) {
      return { kind: "anti" };
    }
    return null;
  }

If a win is found, we return an object describing the winning line so it can be drawn.

How to Detect a Draw

If every cell is filled and there is no winner, the game ends in a draw.

  function isFull(b) {
    for (let r = 0; r < GRID; r++) {
      for (let c = 0; c < GRID; c++) {
        if (b[r][c] === "") return false;
      }
    }
    return true;
  }

This loops over every cell and returns false if any are empty.

How to Draw the Winning Line

A red line is drawn over the winning cells.

  function drawWinLine(res) {
    overlayGfx.clear();
    overlayGfx.lineStyle(6, 0xef4444, 1);
    const pad = 14;
    const half = CELL / 2;

    if (res.kind === "row") {
      const y = res.index * CELL + half;
      overlayGfx.strokeLineShape(new Phaser.Geom.Line(pad, y, BOARD - pad, y));
    } else if (res.kind === "col") {
      const x = res.index * CELL + half;
      overlayGfx.strokeLineShape(new Phaser.Geom.Line(x, pad, x, BOARD - pad));
    } else if (res.kind === "diag") {
      overlayGfx.strokeLineShape(new Phaser.Geom.Line(pad, pad, BOARD - pad, BOARD - pad));
    } else if (res.kind === "anti") {
      overlayGfx.strokeLineShape(new Phaser.Geom.Line(BOARD - pad, pad, pad, BOARD - pad));
    }
  }
})();

The coordinates are calculated based on the type of win to ensure the line passes through the correct cells.

Great. Now open index.html and you can start playing the game!

Final Thoughts

You have now built a complete Tic Tac Toe game in Phaser.js. This includes a 3x3 grid, alternating turns, win detection with a highlight line, draw detection, and a restart button. The code uses core game development concepts like input handling, game state management, and rendering, which you can use in larger projects.

If you enjoy online games, check out GameBoost, the ultimate marketplace for gamers. You can find Fortnite accounts with exclusive skins, along with options for other popular games like Grow a Garden, Clash of Clans, and more.

Whether you’re making a small puzzle game or a full 3D experience, JavaScript has the tools to help you bring your ideas to life.

But with so many libraries and frameworks out there, it’s easy to feel overwhelmed. So let’s break it down.

Here are five of the best JavaScript frameworks for game development, each with its own strengths and ideal use cases. All the frameworks are fully free and open source, so you can use them without worrying about the costs.

Phaser

Phaser is often the first name that comes up when people talk about JavaScript game engines, and for good reason.

It’s designed to build 2D games that run in the browser or on mobile devices.

Phaser is lightweight but powerful. It has all the features you need to make a complete game, including physics, animations, input handling, sound, and asset management.

Phaser provides a gentle introduction to game development if you're just starting out. You don’t need to worry about rendering pipelines or low-level graphics APIs. It handles the complex stuff behind the scenes so you can focus on making your game fun.

Phaser uses Pixi.js under the hood for rendering, which means it’s optimized for performance and compatible with older browsers too. You can also export your game to mobile platforms using wrappers like Cordova or Capacitor.

This makes Phaser a fantastic choice for indie developers and hobbyists who want to make and share games quickly.

Pixi.js

Pixi.js isn’t a full game engine like Phaser. Instead, it’s a high-speed 2D and 2.5D animation rendering engine that gives you fine-grained control over how things appear on screen.

If you’re working on a game that involves a lot of components, animations, or visual effects, Pixi.js gives you the tools to make it look amazing.

Because it focuses purely on rendering, Pixi.js is extremely fast. It uses WebGL when available and falls back to Canvas if needed. This makes it a great option for UI-heavy games or experiences where you need to squeeze out every bit of performance.

Since Pixi.js doesn’t include game logic, physics, or input systems like a full game engine, if you need those, you’ll have to add them yourself.

For example, you can use Matter.js for physics, which handles collision detection and rigid body physics in 2D. Or you can use Colyseus for multiplayer logic.

If you want more control or already have your own game logic written, Pixi.js might be the perfect fit.

Three.js

Now let’s talk about 3D. Three.js is the most popular JavaScript library for rendering 3D graphics in the browser using WebGL.

It gives you a powerful set of tools for working with scenes, lights, cameras, meshes, and materials. If you’ve ever seen a 3D demo or game in a browser, chances are it used Three.js.

Three.js is incredibly flexible. You can use it to build full games, data visualizations, interactive art, or virtual reality scenes.

But with that flexibility comes a steeper learning curve. You need to understand some basic 3D concepts like coordinate systems, shading, and rendering loops. The good news is that there are plenty of examples, and the community is active and helpful.

One of the coolest things about Three.js is how well it integrates with other tools. You can load models from Blender, add post-processing effects, and even connect it to VR headsets.

If your dream is to build an interactive 3D world you can explore in the browser, Three.js gives you everything you need to make that happen.

Babylon.js

While Three.js is all about flexibility, Babylon.js aims to be more of an all-in-one 3D game engine.

It includes a physics engine, collision detection, animation tools, and support for advanced features like real-time shadows, reflections, and virtual reality.

What makes Babylon.js stand out is its performance and developer experience. It’s optimized for modern browsers and devices, and the documentation is excellent.

There’s even a web-based playground where you can test and share code snippets live. That’s great for learning and debugging.

Let’s say you want to build a first-person shooter or a multiplayer 3D arena game. Babylon.js gives you all the structure you need including scene management, game loop handling, input systems, and more. You don’t have to piece together different libraries to make things work  –  it’s all built in.

Another plus is its strong WebXR support to create virtual reality or augmented reality experiences right in the browser. If that’s part of your plan, Babylon is definitely worth a look.

PlayCanvas

If you want to create 3D games but don’t want to dive deep into code right away, PlayCanvas offers a different approach. It’s a cloud-based 3D engine with a visual editor you can use directly in your browser.

You can drag and drop assets, write scripts, and preview changes in real time, all from a web interface.

This makes PlayCanvas great for teams or classroom settings where collaboration is key. You don’t need to set up a local development environment or deal with complex build tools. Just log in, open your project, and start building.

Under the hood, PlayCanvas is still a powerful engine, and you can get under the hood when you need to. It supports WebGL, physics, and even VR. It’s used by companies like Snapchat and Disney for lightweight 3D experiences.

Playcanvas also comes with a cloud solution with a generous free tier, so if you want to host your games in the cloud, check out their pricing page.

So, which game framework should you pick?

It depends on what kind of game you want to make.

If you’re just starting out and want to build a fun 2D game quickly, go with Phaser. It’s simple, forgiving, and has everything you need in one place.

If your game is more about visuals and speed, especially for 2D, Pixi.js might be a better fit. It gives you great rendering power without a lot of overhead.

For 3D projects, the choice comes down to complexity and flexibility. If you want full control and are comfortable managing your own systems, Three.js is perfect. If you want more built-in features and a smoother on-ramp, Babylon.js is a great choice.

And if you’re working with a team or prefer visual tools, PlayCanvas offers a modern, web-based way to build 3D games.

Summary

No matter which one you choose, the best way to learn is by building something small. Pick a simple idea like a top-down shooter, a 3D maze, or a basic puzzle, and try to finish it. You’ll learn a lot, and you’ll gain the confidence to tackle bigger projects later on.

JavaScript might not be the first language people think of for game development, but it’s more than capable. With the right framework, you can create beautiful, responsive games that run anywhere. So pick your tool, fire up your editor, and start building.

Hope you enjoyed this article. If you're into game development, check out the Eldorado marketplace – a platform for buying and selling in-game goods. You can also create dedicated e-commerce pages for your games, like Grow A Garden Shop, where players can purchase tools to enhance their gameplay experience.

We just published a course on the freeCodeCamp.org Spanish YouTube channel that will guide you step by step through the fundamentals of Godot. You’ll learn the core concepts that you need to get started.

If you have Spanish-speaking friends, you are welcome to share the Spanish version of this article with them.

Luis Canary created this course. He is the Principal Gameplay Programmer at Pendulo Studios, a Madrid-based video game development company. He has taught courses at universities, schools, and companies and loves to share his passion for game development on his YouTube channel.

Before we dive into the course content, let's see what Godot is, and why you should learn it.

What is Godot?

Godot is an open-source game engine that you can use to build 2D and 3D games.

It has become very popular in the last few years, with robust features that make it a great tool in the game development world, without the heavy resource demands of some other game engines. This makes it a practical choice for creators looking for efficiency and high performance.

Its open-source license is great for independent developers and small teams, as it doesn’t come with any licensing fees. You’ll retain full ownership and control over the games and projects that you create with Godot.

This flexibility makes game development more approachable for everyone.

Godot also has its own user-friendly scripting language and node-based system. Its scripting language, called GDScript, is similar to Python and is easy to learn for beginners. Its intuitive node-based system simplifies the process of creating both 2D and 3D games.

By learning Godot, you’ll be taking your first steps into a career in game development.

💡 Tip: This course is perfect for anyone who wants to start developing video games. It covers core concepts in GDScript.

Godot Course in Spanish

Great. Now that you know more about Godot, let's see what you’ll learn during the course:

• Introduction

• What is Godot?

• Download and install Godot

• Lighting

• Materials and physics

• UI

• Movement

• Player

• First script

• Update project

• Change inputs for a 3D project

• 3D platforms and respawn player

• Collect coins

• 3D camera rotation

• Character model and animations

• Music and sounds

• Export video game .exe

By the end of the course, you’ll be familiar with the fundamentals of Godot and you’ll be ready to start developing video games.

If you’re ready to start learning Godot, check out the course on the freeCodeCamp.org Spanish YouTube channel:

✍️ Course created by Luis Canary.

• YouTube: @LuisCanary

• Instagram: @luiscanary_

• Twitter: @luiscanary

• TikTok: @luiscanary

• Twitch: LuisCanary

• Discord: Invitación

• Facebook: LuisCanaryy

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.

Table of Contents

1. React Three Fiber vs Three.js

2. How to Set Up the Game

3. How to Render a Map

4. How to Animate the Cars

5. How to Move the Player

6. Hit Detection

7. 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.

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.

Table of Contents

1. How to Set Up the Game

2. How to Render a Map

3. How to Animate the Cars

4. How to Move the Player

5. Hit Detection

6. 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.

<!DOCTYPE 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 App</title>
  </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.

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.

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.

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).

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

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. 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;
}

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 * 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);

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, 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;
}

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.

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 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.

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.

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.

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 * 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

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 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.

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 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();
  }
}

. . .

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.

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.

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.

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);
}

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.

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 { 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;
}

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 * 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);
}

. . .

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.

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

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.

JavaScript is versatile and widely used for web-based games, making it a fantastic entry point for aspiring game developers. Also, libraries like Kaplay make the process even easier by simplifying game development tasks.

Whether you want to create simple 2D games or dive into more advanced game mechanics, learning JavaScript and Kaplay will give you a strong foundation.

We just published a JavaScript crash course on the freeCodeCamp.org YouTube channel that will teach you how to code in JavaScript and use the Kaplay library for streamlined game development. Created by JSLegendDev, this course covers essential programming concepts and practical game development techniques.

What You’ll Learn in This Course

The course is divided into two main parts: learning JavaScript fundamentals and applying those skills to build games using the Kaplay library.

JavaScript Fundamentals for Game Development

In the first part of the course, you'll get a solid grounding in JavaScript by covering core concepts necessary for building games.

You’ll start by understanding why JavaScript is a great choice for game development and learn how to set up your coding environment. The course covers key concepts such as variables, constants, conditional statements, boolean operations, complex data types (arrays and objects), loops, and functions. It also explores parameter passing, local and global scoping, comments, and how JavaScript's import/export system works.

You’ll also set up a modern development environment using Node.js, NPM, and Vite. With these tools in place, you'll be ready to build your first complete JavaScript game. The course then guides you through the process of exporting and deploying your game to a platform like itch.io, allowing you to share your creations with others.

Game Development with the Kaplay Library

In the second part of the course, you’ll learn how to use the Kaplay library to simplify game development.

Kaplay provides a user-friendly framework for creating and managing game components. You’ll learn how to install Kaplay, initialize projects, and load assets. The course introduces you to key concepts like scenes, game objects, and their parent-child relationships.

You’ll work with essential Kaplay components, including sprites, areas, bodies, and text elements. The course also covers collision handling, user input management, and advanced features such as animations using the tween() function. Additionally, you’ll get a brief introduction to creating game maps, building AI with state machines, and using custom events to enhance your games.

Why This Course Is Perfect for You

This crash course is beginner-friendly and doesn’t require prior coding experience. Each concept is explained clearly with practical examples and hands-on projects. It covers everything from JavaScript fundamentals to using the Kaplay library, giving you a comprehensive understanding of game development. By building real projects, you’ll gain practical experience and learn how to deploy your games online.

By the end of this course, you’ll have the skills to create your own JavaScript games and the confidence to explore more advanced game development techniques. With the Kaplay library, you’ll also have a powerful tool to speed up your development process and make your games more interactive.

If you're ready to get started with game development, check out the course on the freeCodeCamp.org YouTube channel (4-hour watch).

This inspired me to build a similar game for her. Since she's currently into anime, I decided to create the game using cute anime-style images.

In this article, I'll walk you through the process of building the game for yourself or your kids 🎮.

We'll begin by exploring the game features, then cover the tech stack and project structure—both of which are straightforward. Finally, we'll discuss optimizations and ensuring smooth gameplay on mobile devices 📱.

If you want to skip the reading, here 💁 is the GitHub repository 🙌. And here you can see the live demo.

Table of Contents

• Project Description

• Let’s Build the Game

• Testing the App

• API Fallback Mechanism

• Optimizations

• Future Improvements

• Conclusion

Project Description

In this tutorial, we’ll build a challenging memory card game with React that tests your recall abilities. Your goal is to click unique anime images without clicking the same one twice. Each unique click earns you points, but be careful—clicking an image twice resets your progress.

Game features:

• 🎯 Dynamic gameplay that challenges your memory

• 🔄 Cards shuffle after each click to increase difficulty

• 🏆 Score tracking with best score persistence

• 😺 Adorable anime images from The Nekosia API

• ✨ Smooth loading transitions and animations

• 📱 Responsive design for all devices

• 🎨 Clean, modern UI

The game will help you test your memory skills while enjoying cute anime pictures. Can you achieve the perfect score?

How to Play

1. Click on any card to start

2. Remember which cards you've clicked

3. Try to click all cards exactly once

4. Watch your score grow with each unique selection

5. Then keep playing to try to beat your best score

The Tech Stack

Here’s a list of the main technologies we’ll be using:

• NPM – A package manager for JavaScript that helps manage dependencies and scripts for the project.

• Vite – A build tool that provides a fast development environment, particularly optimized for modern web projects.

• React – A popular JavaScript library for building user interfaces, enabling efficient rendering and state management.

• CSS Modules – A styling solution that scopes CSS to individual components, preventing style conflicts and ensuring maintainability.

Let’s Build the Game

From this point onward, I will guide you through the process I followed when building this game.

Project Structure and Architecture

When building this memory card game, I carefully organized the codebase to ensure maintainability, scalability, and clear separation of concerns. Let's explore the structure and the reasoning behind each decision:

Component-Based Architecture

I chose a component-based architecture for several reasons:

• Modularity: Each component is self-contained with its own logic and styles

• Reusability: Components like Card and Loader can be reused across the application

• Maintainability: Easier to debug and modify individual components

• Testing: Components can be tested in isolation

Component Organization

1. Card Component

• Separated into its own directory because it's a core game element

• Contains both JSX and SCSS modules for encapsulation

• Handles individual card rendering, loading states, and click events

2. CardsGrid Component

• Manages the game board layout

• Handles card shuffling and distribution

• Controls the responsive grid layout for different screen sizes

3. Loader Component

• Reusable loading indicator

• Improves user experience during image loading

• Can be used by any component that needs loading states

4. Header/Footer/Subtitle Components

• Structural components for app layout

• Header displays game title and scores

• Footer shows copyright and version info

• Subtitle provides game instructions

CSS Modules Approach

I used CSS Modules (.module.scss files) for several benefits:

• Scoped Styling: Prevents style leaks between components

• Name Collisions: Automatically generates unique class names

• Maintainability: Styles are co-located with their components

• SCSS Features: Leverages SCSS features while keeping styles modular

Custom Hooks

The hooks directory contains custom hooks like useFetch:

• Separation of Concerns: Isolates data fetching logic

• Reusability: Can be used by any component needing image data

• State Management: Handles loading, error, and data states

• Performance: Implements optimizations like image size control

Root Level Files

App.jsx:

• Acts as the application's entry point

• Manages global state and routing (if needed)

• Coordinates component composition

• Handles top-level layouts

Performance Considerations

The structure supports performance optimizations:

• Code Splitting: Components can be lazy-loaded if needed

• Memoization: Components can be memoized effectively

• Style Loading: CSS Modules enable efficient style loading

• Asset Management: Images and resources are properly organized

Scalability

This structure allows for easy scaling:

• New features can be added as new components

• Additional hooks can be created for new functionality

• Styles remain maintainable as the app grows

• Testing can be implemented at any level

Development Experience

The structure enhances developer experience:

• Clear file organization

• Intuitive component locations

• Easy to find and modify specific features

• Supports efficient collaboration

This architecture proved particularly valuable when optimizing the game for tablet use, as it allowed me to:

1. Easily identify and optimize performance bottlenecks

2. Add tablet-specific styles without affecting other devices

3. Implement loading states for better mobile experience

4. Maintain clean separation between game logic and UI components

Alright, now let’s get coding.

Step-by-Step Build Guide

1. Project Setup

Set Up the Development Environment

In order to start with a clean React project, open your terminal app and run the following commands (you may name your project folder as you like – in my case the name is ‘memory-card’):

npm create vite@latest memory-card -- --template react
cd memory-card
npm install

Install the Required Dependencies

The only dependencies we will use in this project are the hook package from UI.dev (by the way, here you can find a well-explained article on how rendering in React works).

The other dependency is the famous CSS preprocessor, SASS, that we’ll need to be able to write our CSS modules in SASS instead of regular CSS.

npm install @uidotdev/usehooks sass

Configure Vite and Project Setting

When setting up our project, we need to make some specific configuration adjustments to handle SASS warnings and improve our development experience. Here's how you can configure Vitest:

// vitest.config.js
import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: ['./src/setupTests.js'],
    css: {
      modules: {
        classNameStrategy: 'non-scoped'
      }
    },
    preprocessors: {
      '**/*.scss': 'sass'
    },
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
      exclude: [
        'node_modules/',
        'src/setupTests.js',
        'src/main.jsx',
        'src/vite-env.d.ts',
      ],
    },
  },
  css: {
    preprocessorOptions: {
      scss: {
        quietDeps: true,  // Silences SASS dependency warnings
        charset: false    // Prevents charset warning in recent SASS versions
      }
    }
  }
});

Keep in mind that most of these configurations are auto-generated for you when you create the project with Vite. Here’s what’s going on:

1. SASS Configuration:

   • quietDeps: true: This silences the warnings about deprecated dependencies in SASS modules. Particularly useful when working with third-party SASS/SCSS files.

   • charset: false: Prevents the "@charset" warning that appears in newer versions of SASS when using special characters in your stylesheets.

2. Test Configuration:

   • globals: true: Makes test functions globally available in test files

   • environment: 'jsdom': Provides a DOM environment for testing

   • setupFiles: Points to our test setup file

These configurations help create a cleaner development experience by removing unnecessary warning messages in the console, setting up proper test environment configurations, and ensuring SASS/SCSS processing works smoothly.

You might see warnings in your console without these configurations when:

• Using SASS/SCSS features or importing SASS files

• Running tests that require DOM manipulation

• Using special characters in your stylesheets

2. Building the Components

Create the Card Component

First, let's create our basic card component that will display individual images:

// src/components/Card/Card.jsx
import React, { useState, useCallback } from "react";
import Loader from "../Loader";
import styles from "./Card.module.scss";

const Card = React.memo(function Card({ imgUrl, imageId, categoryName, processTurn }) {
  const [isLoading, setIsLoading] = useState(true);

  const handleImageLoad = useCallback(() => {
    setIsLoading(false);
  }, []);

  const handleClick = useCallback(() => {
    processTurn(imageId);
  }, [processTurn, imageId]);

  return (
    <div className={styles.container} onClick={handleClick}>
      {isLoading && (
        <div className={styles.loaderContainer}>
          <Loader message="Loading..." />
        </div>
      )}
      <img
        src={imgUrl}
        alt={categoryName}
        onLoad={handleImageLoad}
        className={`${styles.image} ${isLoading ? styles.hidden : ''}`}
      />
    </div>
  );
});

export default Card;

The Card component is a fundamental building block of our game. It's responsible for displaying individual images and handling player interactions. Let's break down its implementation:

Props breakdown:

1. image: (string)

   • The URL of the image to be displayed that’s received from our API service.

   • It’s used directly in the img tag's src attribute.

2. id: (string)

   • Unique identifier for each card that’s critical for tracking which cards have been clicked.

   • It’s passed to the processTurn callback when a card is clicked.

3. category: (string)

   • Describes the type of image (for example, "anime", "neko"), and it’s used in the alt attribute for better accessibility.

   • It helps with SEO and screen readers.

4. processTurn: (function)

   • Callback function passed from the parent component that handles the game logic when a card is clicked.

   • It also manages score updates and game state changes and determines if a card has been clicked before.

5. isLoading: (boolean)

   • Controls whether to show a loading state. When true, it displays a Loader component instead of the image.

   • It improves the user experience during image loading.

Component styling:

// src/components/Card/Card.module.scss
.container {
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  background-color: rgba(255, 255, 255, 0.8);
  border: 1px solid rgba(0, 0, 0, 0.8);
  padding: 20px;
  font-size: 30px;
  text-align: center;
  min-height: 200px;
  position: relative;
  cursor: pointer;
  transition: transform 0.2s ease;

  &:hover {
    transform: scale(1.02);
  }

  .image {
    width: 10rem;
    height: auto;
    opacity: 1;
    transition: opacity 0.3s ease;

    &.hidden {
      opacity: 0;
    }
  }

  .loaderContainer {
    position: absolute;
    top: 50%;
    left: 50%;
    transform: translate(-50%, -50%);
  }
}

Usage in the component:

<Card
    key={getKey()}
    imgUrl={item?.image?.original?.url || ""}
    imageId={item?.id}
    categoryName={item?.category}
    processTurn={(imageId) => processTurn(imageId)} 
/>

Key features:

1. Performance Optimization:

   • Uses React.memo to prevent unnecessary re-renders

   • Implements useCallback for event handlers

   • Manages loading state internally for better UX

2. Loading State Management:

   • Internal isLoading state tracks image loading

   • Shows a Loader component with a message while loading

   • Hides the image until it's fully loaded using CSS classes

3. Event Handling:

   • handleImageLoad: Manages the loading state transition

   • handleClick: Processes player moves via the processTurn callback

Build the CardsGrid Component

This is our main game component that manages the game state, scoring logic, and card interactions. Let's break down its implementation:

// src/components/CardsGrid/CardsGrid.jsx
import React, { useState, useEffect } from "react";
import { useLocalStorage } from "@uidotdev/usehooks";
import Card from "../Card";
import Loader from "../Loader";
import styles from "./CardsGrid.module.scss";
import useFetch from "../../hooks/useFetch";

function CardsGrid(data) {
  // State Management
  const [images, setImages] = useState(data?.data?.images || []);
  const [clickedImages, setClickedImages] = useLocalStorage("clickedImages", []);
  const [score, setScore] = useLocalStorage("score", 0);
  const [bestScore, setBestScore] = useLocalStorage("bestScore", 0);
  const [isLoading, setIsLoading] = useState(!data?.data?.images?.length);

  // Custom hook for fetching images
  const { data: fetchedData, fetchData, error } = useFetch();

  // Update images when new data is fetched
  useEffect(() => {
    if (fetchedData?.images) {
      setImages(fetchedData.images);
      setIsLoading(false);
      // Reset clicked images when new batch is loaded
      setClickedImages([]);
    }
  }, [fetchedData]);

  // Helper function to update best score
  function updateBestScore(currentScore) {
    if (currentScore > bestScore) {
      setBestScore(currentScore);
    }
  }

  // Core game logic
  function processTurn(imageId) {
    const newClickedImages = [...clickedImages, imageId];
    setClickedImages(newClickedImages);

    // If clicking the same image twice, reset everything
    if (clickedImages.includes(imageId)) {
      // Update the best score if necessary
      updateBestScore(score);

      setClickedImages([]);
      setScore(0);
    } else {
      // Handle successful card selection
      const newScore = score + 1;
      setScore(newScore);

      // Check for perfect score (all cards clicked once)
       if (newClickedImages.length === images.length) {
        updateBestScore(newScore);
        fetchData();
        setClickedImages([]);
      } else {
        // Shuffle the images
        const shuffled = [...images].sort(() => Math.random() - 0.5);
        setImages(shuffled);
      }
    }
  }

 if (error) {
    return <p>Failed to fetch data</p>;
  }

  if (isLoading) {
    return <Loader message="Loading new images..." />;
  }

  return (
    <div className={styles.container}>
      {images.map((item) => (
        <Card
          key={getKey()}
          imgUrl={item?.image?.original?.url || ""}
          imageId={item?.id}
          categoryName={item?.category}
          processTurn={(imageId) => processTurn(imageId)}
        />
      ))}
    </div>
  );
}

export default React.memo(CardsGrid);

Component styling:

.container {
  display: grid;
  gap: 1rem 1rem;
  grid-template-columns: auto; /* Default: one column for mobile-first */
  background-color: #2196f3;
  padding: 0.7rem;
  cursor: pointer;
}

@media (min-width: 481px) {
  .container {
    grid-template-columns: auto auto; /* Two columns for tablets and up */
  }
}

@media (min-width: 769px) {
  .container {
    grid-template-columns: auto auto auto; /* Three columns for desktops and larger */
  }
}

Key Features Breakdown:

1. State Management:

   • Uses useState for component-level state

   • Implements useLocalStorage for persistent game data:

     • clickedImages: Tracks which cards have been clicked

     • score: Current game score

     • bestScore: Highest score achieved

   • Manages loading state for image fetching

   • Shuffle the cards

2. Game Logic:

   • processTurn: Handles player moves

     • Tracks duplicate clicks

     • Updates scores

     • Manages perfect score scenarios

   • updateBestScore: Updates high score when necessary

   • Automatically fetches new images when a round is completed

3. Data Fetching:

   • Uses custom useFetch hook for image data

   • Handles loading and error states

   • Updates images when new data is fetched

4. Performance Optimization:

   • Component wrapped in React.memo

   • Efficient state updates

   • Responsive grid layout

5. Persistence:

   • Game state persists across page reloads

   • Best score tracking

   • Current game progress saving

Usage Example:

...
...

function App() {
  const { data, loading, error } = useFetch();

  if (loading) return <Loader />;
  if (error) return <p>Error: {error}</p>;

  return (
    <div className={styles.container}>
      <Header />
      <Subtitle />
      <CardsGrid data={data} />
      <Footer />
    </div>
  );
}
export default App;

The CardsGrid component serves as the heart of our memory card game, managing:

• Game state and logic

• Score tracking

• Card interactions

• Image loading and display

• Responsive layout

• Data persistence

This implementation provides a smooth gaming experience while maintaining code readability and maintainability through clear separation of concerns and proper state management.

3. Implementing the API Layer

Our game uses a robust API layer with multiple fallback options to ensure reliable image delivery. Let's implement each service and the fallback mechanism.

Set Up the Primary API Service:

// src/services/api/nekosiaApi.js
const NEKOSIA_API_URL = "https://api.nekosia.cat/api/v1/images/catgirl";

export async function fetchNekosiaImages() {
  const response = await fetch(
    `${NEKOSIA_API_URL}?count=21&additionalTags=white-hair,uniform&blacklistedTags=short-hair,sad,maid&width=300`
  );

  if (!response.ok) {
    throw new Error(`Nekosia API error: ${response.status}`);
  }

  const result = await response.json();

  if (!result.images || !Array.isArray(result.images)) {
    throw new Error('Invalid response format from Nekosia API');
  }

  const validImages = result.images.filter(item => item?.image?.original?.url);

  if (validImages.length === 0) {
    throw new Error('No valid images received from Nekosia API');
  }

  return { ...result, images: validImages };
}

Create the First Fallback API Service:

// src/services/api/nekosBestApi.js
const NEKOS_BEST_API_URL = "https://nekos.best/api/v2/neko?amount=21";

export async function fetchNekosBestImages() {
  const response = await fetch(NEKOS_BEST_API_URL, {
    method: "GET",
    mode: "no-cors"
  });

  if (!response.ok) {
    throw new Error(`Nekos Best API error: ${response.status}`);
  }

  const result = await response.json();

  // Transform the response to match our expected format
  const transformedImages = result.results.map(item => ({
    id: item.url.split('/').pop().split('.')[0], // Extract UUID from URL
    image: {
      original: {
        url: item.url
      }
    },
    artist: {
      name: item.artist_name,
      href: item.artist_href
    },
    source: item.source_url
  }));

  return { images: transformedImages };
}

Create the Second Fallback API Service:

// src/services/api/nekosApi.js
const NEKOS_API_URL = "https://api.nekosapi.com/v3/images/random?limit=21&rating=safe";

export async function fetchNekosImages() {
  const response = await fetch(NEKOS_API_URL, {
    method: "GET",
  });

  if (!response.ok) {
    throw new Error(`Nekos API error: ${response.status}`);
  }

  const result = await response.json();

  // Transform the response to match our expected format
  const transformedImages = result.items.map(item => ({
    id: item.id,
    image: {
      original: {
        url: item.image_url
      }
    }
  }));

  return { images: transformedImages };
}

Build the API Fallback Mechanism:

// src/services/api/imageService.js
import { fetchNekosiaImages } from "./nekosiaApi";
import { fetchNekosImages } from "./nekosApi";
import { fetchNekosBestImages } from "./nekosBestApi";

export async function fetchImages() {
  try {
    // Try primary API first
    return await fetchNekosiaImages();
  } catch (error) {
    console.warn("Primary API failed, trying fallback:", error);

    // Try first fallback API
    try {
      return await fetchNekosBestImages();
    } catch (fallbackError) {
      console.warn("First fallback API failed, trying second fallback:", fallbackError);

      // Try second fallback API
      try {
        return await fetchNekosImages();
      } catch (secondFallbackError) {
        console.error("All image APIs failed:", secondFallbackError);
        throw new Error("All image APIs failed");
      }
    }
  }
}

Use the Image Service:

// src/hooks/useFetch.js
import { useState, useEffect } from "react";
import { fetchImages } from "../services/api/imageService";

export default function useFetch() {
  const [data, setData] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  const fetchData = async () => {
    setLoading(true);
    setError(null);

    try {
      const result = await fetchImages();
      setData(result);
    } catch (err) {
      setError(err.message || 'An error occurred');
    } finally {
      setLoading(false);
    }
  };

  useEffect(() => {
    fetchData();
  }, []);

  return {
    data,
    loading,
    error,
    fetchData,
  };
}

Key Features of Our API Implementation:

1. Multiple API Sources:

   • Primary API (Nekosia): Provides high-quality anime images

   • First Fallback (Nekos Best): Includes artist information

   • Second Fallback (Nekos): Simple and reliable backup

2. Consistent Data Format:

   • All APIs transform their responses to match our expected format:

    {
      images: [
        {
          id: string,
          image: {
            original: {
              url: string
            }
          }
        }
      ]
    }

3. Robust Error Handling:

   • Validates API responses

   • Checks for valid image URLs

   • Provides detailed error messages

   • Graceful fallback mechanism

4. Safety Features:

   • Safe content filtering (rating=safe)

   • Image count limitation (21 images)

   • URL validation

   • Response format validation

5. Performance Considerations:

   • Optimized image sizes

   • Filtered content tags

   • Efficient data transformation

   • Minimal API calls

This implementation ensures our game has a reliable source of images while handling potential API failures gracefully. The consistent data format across all APIs makes it easy to switch between them without affecting the game's functionality.

Testing the App

Testing is a crucial part of any application development, and for our Memory Card Game, we implemented a comprehensive testing strategy using modern tools and practices. Let's dive into how we structured our tests and some key testing patterns we used.

Testing Stack

• Vitest: Our primary testing framework, chosen for its speed and seamless integration with Vite

• React Testing Library: For testing React components with a user-centric approach

• @testing-library/user-event: For simulating user interactions

• jsdom: For creating a DOM environment in our tests

Key Testing Patterns

Testing was a crucial part of ensuring the reliability and maintainability of this Memory Card Game. I implemented a comprehensive testing strategy using React Testing Library and Vitest, focusing on several key areas:

1. Component Testing

I wrote extensive tests for my React components to ensure they render correctly and behave as expected. For example, the CardsGrid component, which is the heart of the game, has thorough test coverage including:

• Initial rendering states

• Loading states

• Error handling

• Score tracking

• Card interaction behavior

2. Test Mocking

To ensure reliable and fast tests, I implemented several mocking strategies:

• Local storage operations using useLocalStorage hook

• API calls using the useFetch hook

• Event handlers and state updates

3. Testing Best Practices

Throughout my testing implementation, I followed several best practices:

• Using beforeEach and afterEach hooks to reset state between tests

• Testing user interactions using fireEvent from React Testing Library

• Writing tests that resemble how users interact with the app

• Testing both success and error scenarios

• Isolating tests using proper mocking

4. Testing Tools

The project leverages modern testing tools and libraries:

• Vitest: As the test runner

• React Testing Library: For testing React components

• @testing-library/jest-dom: For enhanced DOM testing assertions

• @testing-library/user-event: For simulating user interactions

This comprehensive testing approach helped me catch bugs early, ensured code quality, and made refactoring safer and more manageable.

Optimizations

To ensure smooth performance, especially on mobile devices, we implemented several optimization techniques:

1. Response Transformation

   • Standardized data format across all APIs

   • Efficient ID extraction from URLs

   • Structured image metadata for quick access

2. Network Optimization

   • Using no-cors mode where appropriate to handle CORS issues efficiently

   • Error handling with specific status codes for better debugging

   • Consistent response structure across all API implementations

3. Mobile-First Considerations

   • Optimized image loading strategy

   • Efficient error handling to prevent unnecessary retries

   • Streamlined data transformation to reduce processing overhead

Future Improvements

There are a few ways that we could further improve this project:

1. API Response Caching

   • Implement local storage caching for frequently used images

   • Add cache invalidation strategy for fresh content

   • Implement progressive image loading

2. Performance Optimizations

   • Add image lazy loading for better initial load time

   • Implement request queuing for better bandwidth management

   • Add response compression for faster data transfer

3. Reliability Enhancements

   • Add API health checking before attempts

   • Implement retry mechanisms with exponential backoff

   • Add circuit breaker pattern for failing APIs

4. Analytics and Monitoring

   • Track API success rates

   • Monitor response times

   • Implement automatic API switching based on performance metrics

This robust implementation ensures that our game remains functional and performant even under adverse network conditions or API unavailability, while still maintaining room for future improvements and optimizations.

Conclusion

Building this Memory Card Game has been more than just creating a fun, ad-free alternative for kids—it's been an exercise in implementing modern web development best practices while solving a real-world problem.

The project demonstrates how combining thoughtful architecture, robust testing, and reliable fallback mechanisms can result in a production-ready application that's both entertaining and educational.

🗝️ Key Takeaways

1. User-Centric Development

   • Started with a clear problem (ad-filled games affecting user experience)

   • Implemented features that enhance gameplay without interruptions

   • Maintained focus on performance and reliability across devices

2. Technical Excellence

   • Leveraged modern React patterns and hooks for clean, maintainable code

   • Implemented comprehensive testing strategy ensuring reliability

   • Created a robust API fallback system for uninterrupted gameplay

3. Performance First

   • Adopted mobile-first approach with responsive design

   • Optimized image loading and handling

   • Implemented efficient state management and caching strategies

📚 Learning Outcomes

This project showcases how seemingly simple games can be excellent vehicles for implementing complex technical solutions. From component architecture to API fallbacks, each feature was built with scalability and maintainability in mind, proving that even hobby projects can maintain professional-grade code quality.

🔮 Moving Forward

While the game successfully achieves its primary goal of providing an ad-free, enjoyable experience, the documented future improvements provide a clear roadmap for evolution. Whether it's implementing additional optimizations or adding new features, the foundation is solid and ready for expansion.

The Memory Card Game stands as a testament to how personal projects can both solve real-world problems and serve as platforms for implementing best practices in modern web development. Feel free to explore the code, contribute, or use it as inspiration for your own projects!

We just published a course on the freeCodeCamp.org YouTube channel that will teach you how to build an infinite runner game using JavaScript! In this course, JSLegendDev guides you through the process of creating a Sonic-inspired infinite runner game, complete with all the exciting elements you'd expect. You’ll be working with the Kaplay game development library, a powerful yet beginner-friendly tool that simplifies the process of building 2D games in JavaScript. By the end of this course, you'll know how to implement core game mechanics such as gameplay, enemy logic, parallax scrolling, scoring systems, and more.

The course covers everything from project setup and loading assets to more advanced features like creating interactive game objects and handling game states. You'll start by setting up your development environment, loading the assets for your game, and building a main menu scene. Next, you'll learn to create the Sonic game object, which will serve as the player's character, and learn how to manage its movement and interactions within the game world.

As the game takes shape, you'll implement key gameplay mechanics, such as enemy logic, where you'll learn how to create obstacles that challenge the player, and a scoring system that tracks rings collected during the run. The course also explores parallax scrolling, which adds depth to the game by making background elements move at different speeds, giving the illusion of a 3D environment.

Towards the end of the course, you'll build a game over scene, polish the game, and package it for distribution, ensuring it's ready for others to play and enjoy.

Watch the full course on the freeCodeCamp.org YouTube channel (2-hour watch).

We just published a course on the freeCodeCamp.org YouTube channel that will teach you all about using JavaScript and Kaboom.js to build a Metroidvania-style game from scratch. This comprehensive tutorial covers everything you need to know, from setting up your development environment to implementing complex game mechanics like enemy AI and boss battles. Plus, all the game assets you’ll need are provided, so you can focus on learning and creating. JSLegendDev created this course.

The course begins with an introductory section that gives you a high-level overview of what you’ll be building. You'll then move on to setting up your development environment, ensuring you have all the tools necessary to begin coding. The next steps involve initializing Kaboom.js, a JavaScript game programming library, and loading the various assets that will make up your game world.

Once your environment is set up and your assets are loaded, you'll dive into defining scenes, an essential part of structuring your game. Understanding game objects in Kaboom.js is crucial, as these are the building blocks of your game. You’ll learn how to implement logic to load and display the game map and place colliders that control the interaction between your player and the environment.

The course doesn’t just stop at the basics. You’ll also implement player logic, manage global state, and set up a dynamic camera system that follows the player. Enemy AI is a big part of what makes Metroidvania games challenging, so you'll learn how to implement a drone enemy and a formidable boss barrier. To make your game even more engaging, the tutorial covers the creation of a boss battle, complete with health cartridges and a health bar to track the player's status.

Moreover, you'll ensure your game handles player respawns correctly when they fall out of bounds and link multiple rooms to create a seamless game world. The finishing touches will polish your game, making it feel complete and professional. Finally, you’ll receive general guidance on deploying your project, so you can share your creation with the world.

Whether you are an experienced developer looking to expand your skills or a beginner eager to dive into game development, this course is designed to be accessible and comprehensive.

Watch the full course on the freeCodeCamp.org YouTube channel (5-hour watch).

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.

Table of Contents:

1. Background on the Game
2. Project Setup
3. Overview of the Game Logic
4. How to Draw the Scene
5. How to Turn the Coordinate System Upside Down
6. How to Draw the Game Elements
7. How to Fit the Size of the City to the Browser Window
8. How the Gorilla Can Throw the Bomb
9. How to Animate the Incoming Bomb
10. Next Steps

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:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Gorillas</title>
    <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 <canvas> 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 <canvas> 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.

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.

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

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("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();

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. 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.

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 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();
}

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 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.

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).

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.

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

    <div id="info-left">
      <h3>Player 1</h3>
      <p>Angle: <span class="angle">0</span>°</p>
      <p>Velocity: <span class="velocity">0</span></p>
    </div>

    <div id="info-right">
      <h3>Player 2</h3>
      <p>Angle: <span class="angle">0</span>°</p>
      <p>Velocity: <span class="velocity">0</span></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 1</h3>
      <p>Angle: <span class="angle">0</span>°</p>
      <p>Velocity: <span class="velocity">0</span></p>
    </div>

    <div id="info-right">
      <h3>Player 2</h3>
      <p>Angle: <span class="angle">0</span>°</p>
      <p>Velocity: <span class="velocity">0</span></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
    }
  }
}