DEV Community

Cover image for TCJSgame Tutorial #1: Setting Up Your First Game Engine
Kehinde Owolabi
Kehinde Owolabi

Posted on

TCJSgame Tutorial #1: Setting Up Your First Game Engine

#javascript #programming #webdev #tutorial

TCJSgame Tutorial #1: Setting Up Your First Game Engine

Welcome to the first tutorial in the TCJSgame series. If you have ever wanted to create your own browser games but found engines like Phaser or Unity overwhelming, you are in the right place.

TCJSgame is a lightweight, beginner-friendly JavaScript game engine that lets you create 2D games with just a few lines of code. No build tools. No complex setups. Just HTML, JavaScript, and your creativity.

Code editor with JavaScript

In this tutorial, you will learn:

  • What TCJSgame is and how its core classes work
  • How to get the engine file and set it up locally
  • How to create your first canvas and game loop
  • How to draw and move a simple object

By the end, you will have a working game window with a moving square. Let us dive in.

What is TCJSgame?

TCJSgame (Terra Codes JavaScript Game) is an open-source 2D game engine created by Owolabi Kehinde. It was built to make game development accessible, especially for beginners and educators who want to focus on game logic rather than complex setup.

JavaScript code on screen

Core Classes You Will Use

Based on the engine file, here are the main classes you will work with:

  • Display – Creates and manages the game canvas, handles the game loop, tracks keyboard, mouse, and touch input, and manages camera and scenes.
  • Component – The base class for all game objects (rectangles, images, text). Handles position, size, color, physics, movement, rotation, and collision.
  • Camera – Allows you to follow a target component and scroll the world.
  • Sound – Simple audio player for sound effects and music.
  • TileMap – For creating tile-based levels (platformers, RPGs).

The engine powers everything from simple platformers to complex tile-based games, and it is perfect for learning game development concepts.

Getting the Engine File

TCJSgame is hosted on Vercel, not on a traditional CDN. You need to download the file directly.

Option 1: Download from the Official Website

Open your browser and go to tcjsgame.vercel.app. Look for the Download section on the homepage. Click to download tcjsgame-v3.js and save the file in your project folder.

Download button on website

Option 2: Save the File from the Direct Link

If you have the direct link to the file, open it in your browser, right-click and select Save As, then save it as tcjsgame-v3.js in your project folder.

Option 3: Copy the Code Directly

You can also create a new file called tcjsgame-v3.js and paste the entire engine code into it using any text editor like Notepad or VS Code.

Text editor showing code

Creating Your First HTML File

Once you have the engine file locally, create a new file called index.html in the same folder.

Paste this code into the file:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My First TCJSgame</title>
    <style>
        body {
            margin: 0;
            min-height: 100vh;
            display: flex;
            justify-content: center;
            align-items: center;
            background: linear-gradient(135deg, #1a1a2e, #16213e);
            font-family: system-ui, 'Segoe UI', monospace;
        }
        canvas {
            box-shadow: 0 10px 25px rgba(0,0,0,0.3);
            border-radius: 8px;
        }
    </style>
</head>
<body>
    <script src="tcjsgame-v3.js"></script>

    <script>
        const display = new Display();
        display.start(800, 600, document.body);

        const player = new Component(50, 50, "limegreen", 375, 275, "rect");
        display.add(player);

        function update() {
            if (display.keys[39]) {
                player.x += 5;
            }
            if (display.keys[37]) {
                player.x -= 5;
            }
            if (display.keys[38]) {
                player.y -= 5;
            }
            if (display.keys[40]) {
                player.y += 5;
            }

            if (player.x < 0) player.x = 0;
            if (player.x > display.canvas.width - player.width) player.x = display.canvas.width - player.width;
            if (player.y < 0) player.y = 0;
            if (player.y > display.canvas.height - player.height) player.y = display.canvas.height - player.height;
        }

        const instruction = new Component("16px", "Arial", "white", 20, 30, "text");
        instruction.text = "Arrow keys to move the green square";
        display.add(instruction);

        console.log("Game is running. Use arrow keys to move.");
    </script>
</body>
</html>
Enter fullscreen mode Exit fullscreen mode

Save the file and open it in your browser. You should see a green square that moves when you press the arrow keys.

Green square on canvas

Understanding the Code

Let us break down what each part does based on the actual engine file.

Loading the engine

<script src="tcjsgame-v3.js"></script>
Enter fullscreen mode Exit fullscreen mode

This makes all the classes available globally.

Creating the Display

const display = new Display();
Enter fullscreen mode Exit fullscreen mode

This creates a new game display object. The Display constructor sets up the canvas element, input tracking arrays, and initializes the camera.

Starting the game

display.start(800, 600, document.body);
Enter fullscreen mode Exit fullscreen mode

The start method sets canvas width and height, inserts the canvas into the specified container, starts the interval timer that runs updat() every 20 milliseconds, and adds event listeners for keyboard, mouse, and touch input.

Creating a Component

const player = new Component(50, 50, "limegreen", 375, 275, "rect");
Enter fullscreen mode Exit fullscreen mode

The Component constructor stores width, height, color, x, y, type. It also sets default values for speedX, speedY, gravity, bounce, and physics flag. If type is "image", it loads the image from the color parameter.

Adding to the display

display.add(player);
Enter fullscreen mode Exit fullscreen mode

This pushes the component into the global comm array. The updat() method then automatically calls move() and update() for every component in comm.

The update function

function update() { ... }
Enter fullscreen mode Exit fullscreen mode

This is a special function that the engine calls every frame. It does not require any parameters. Inside it, you can check input and update component properties.

Keyboard input

if (display.keys[39]) { ... }
Enter fullscreen mode Exit fullscreen mode

The Display class tracks all key presses. When a key is pressed, it sets display.keys[keyCode] = true. When released, it sets it to false. Key code 39 is the right arrow.

Text component

const instruction = new Component("16px", "Arial", "white", 20, 30, "text");
instruction.text = "Arrow keys to move...";
Enter fullscreen mode Exit fullscreen mode

For text components, the width parameter becomes the font size, and height becomes the font family. The actual text is stored in the .text property.

Code explanation diagram

Adding Simple Physics

The engine has built-in physics support. To make your square fall with gravity, enable the physics property.

Replace your player creation code with this:

const player = new Component(50, 50, "limegreen", 375, 100, "rect");
player.physics = true;
player.gravity = 0.5;
player.bounce = 0.7;
Enter fullscreen mode Exit fullscreen mode

Then change your update function to this:

function update() {
    if (display.keys[39]) {
        player.speedX = 5;
    } else if (display.keys[37]) {
        player.speedX = -5;
    } else {
        player.speedX = 0;
    }

    player.hitBottom();
}
Enter fullscreen mode Exit fullscreen mode

The move() method, when physics is true, adds gravitySpeed to y each frame. The hitBottom() method checks if the component has reached the bottom of the canvas and applies bounce.

Physics simulation

Troubleshooting

Issue Solution
Canvas does not appear Make sure tcjsgame-v3.js is in the same folder as your HTML file. Check the file name spelling. Open browser console (F12) to see error messages.
Arrow keys do not move the square Click on the canvas first to give it focus. Add display.canvas.focus() at the end of your script. Check that display.keys[39] is being set by adding console.log(display.keys) inside update.
Player falls through the ground Make sure you are calling player.hitBottom() inside update(). The hitBottom method uses display.canvas.height to detect the bottom edge.
"display is not defined" error You likely forgot to create the Display instance with new Display(). Or you placed your script before loading the engine file.
"update is not defined" error This is not an error – the engine checks for update() and calls it if it exists. If you see this, it means update() is not defined, but it is optional.

Debugging tools

Folder Structure

Your project folder should look like this:

my-first-game/
├── index.html
└── tcjsgame-v3.js
Enter fullscreen mode Exit fullscreen mode

That is all you need. No build tools, no package managers, no complex setup.

What's Next

You have just created your first interactive canvas with TCJSgame. In future tutorials, we will build on this foundation:

  • Topic 2: Drawing images, sprites, and animations
  • Topic 3: Handling mouse and touch input
  • Topic 4: Using the built-in collision detection
  • Topic 5: Building a simple platformer with tilemaps

Next steps

Resources

Share Your Creation

I would love to see what you build. Share your first game in the comments or reach out on Discord with your creation.

Next tutorial: Drawing Images, Sprites, and Animations – Bringing Your Game to Life

Happy coding. 🎮

Top comments (0)