DEV Community

Cover image for 🟢 Level 1 Tutorial — Limn Engine Beginner Guide
Kehinde Owolabi
Kehinde Owolabi

Posted on

🟢 Level 1 Tutorial — Limn Engine Beginner Guide

#javascript #beginners #tutorial #programming

🟢 Level 1 Tutorial — Limn Engine Beginner Guide

Start Your Game Development Journey Here

Welcome to Limn Engine — the zero‑configuration, browser‑based 2D game engine that prioritises creativity over complexity.

This is Level 1: Beginner, where you'll learn everything you need to make your first game in under 60 seconds.

A special thank you to **GyaanSetu Javascript* for featuring our work and helping us share Limn Engine with the JavaScript community. Your support means the world to us. 🙏*

What You'll Learn

Topic What You'll Build
1. Creating a Display Your first canvas
2. Adding & moving Components Your first game object
3. Keyboard input & deltaTime Move with arrow keys
4. Boundaries with move.bound() Keep objects on screen
5. Rectangle collision Collect coins, hit walls
6. Text with Tctxt Score display
7. Images with setImage() Add sprites
8. Mouse input & clicked() Click interactions
9. Sound class Add audio
10. Game states with display.scene Menu → Game → Game Over
11. Coin collector tutorial Complete beginner game
12. Quick reference All the essentials

Before You Start

What You Need

  • A text editor (VS Code, Notepad++, or even Notepad)
  • A browser (Chrome, Firefox, Edge, etc.)
  • Limn Engine — Download epic.js from limn-engine.vercel.app

The Golden Rule

Your Display instance **must* be named display (lowercase). The engine relies on this variable name internally. Any other name will break it.*

1. Creating a Display

The Display class is the foundation of every Limn Engine game. It creates the canvas, runs the game loop, captures input, manages the camera, and controls which scene is active.

<!DOCTYPE html>
<html>
<head>
    <title>My First Limn Game</title>
</head>
<body>
    <script src="epic.js"></script>
    <script>
        // Create the engine
        const display = new Display();

        // Start the game
        display.start(800, 600);

        // Set a background colour (optional)
        display.backgroundColor("#0d0d2a");

        // Your game logic runs here every frame
        function update() {
            // Game code goes here
        }
    </script>
</body>
</html>
Enter fullscreen mode Exit fullscreen mode

What's Happening?

Line What It Does
new Display() Creates the engine instance
display.start(800, 600) Creates an 800x600 canvas and starts the game loop
display.backgroundColor("#0d0d2a") Sets a dark blue background
function update() Runs every frame — your game logic lives here

💡 Tip: Always name your Display instance display. The engine uses this name internally across many classes.

2. Adding & Moving Components

A Component is any visible object in your game — the player, an enemy, a coin, a wall. You create one and register it with display.add() so the engine draws and moves it every frame.

// Component(width, height, color, x, y, type)
const player = new Component(50, 50, "blue", 100, 200, "rect");
display.add(player); // Now the engine draws and moves it

// Move the player
player.speedX = 3;  // Moves 3px right per frame
player.speedY = 2;  // Moves 2px down per frame

// Teleport instantly
player.x = 400;
player.y = 300;

// Stop all movement
player.stopMove();
Enter fullscreen mode Exit fullscreen mode

Component Properties

Property Type Purpose
x / y Number Position (top-left corner)
width / height Number Size in pixels
speedX / speedY Number Velocity added every frame
color String Fill colour (or image path)
angle Number Rotation in radians
type String "rect", "image", or "text"

Component Types

Type How to Use
"rect" Default — draws a filled rectangle
"image" Draws an image — pass file path as color
"text" Draws text — use Tctxt for more control

3. Keyboard Input & DeltaTime

Limn Engine fills display.keys[] with true while a key is held. Check key codes inside update() and multiply by deltaTime (dt) for frame‑rate‑independent movement.

function update(dt) {
    // Reset every frame so player stops when no key is held
    player.speedX = 0;
    player.speedY = 0;

    // Arrow keys
    if (display.keys[37]) player.speedX = -250 * dt; // ←
    if (display.keys[39]) player.speedX =  250 * dt; // →
    if (display.keys[38]) player.speedY = -250 * dt; // ↑
    if (display.keys[40]) player.speedY =  250 * dt; // ↓

    // WASD — same thing, different codes
    if (display.keys[65]) player.speedX = -250 * dt; // A
    if (display.keys[68]) player.speedX =  250 * dt; // D
    if (display.keys[87]) player.speedY = -250 * dt; // W
    if (display.keys[83]) player.speedY =  250 * dt; // S
}
Enter fullscreen mode Exit fullscreen mode

Common Key Codes

Key Code Key Code
← Left Arrow 37 A 65
↑ Up Arrow 38 W 87
→ Right Arrow 39 D 68
↓ Down Arrow 40 S 83
Space 32 Enter 13
Escape 27 Shift 16

💡 Tip: Without dt, your game runs faster on fast monitors. With dt, 250 pixels per second is the same on every device.

4. Boundaries with move.bound()

move.bound() prevents a Component from walking off any edge of the canvas. One line replaces four manual if-checks.

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

    // Keep player on screen
    move.bound(player);

    // OR clamp to custom boundaries
    move.boundTo(player, 50, 750, 0, 580);
    // left=50, right=750, top=0, bottom=580

    // Leave top and bottom open (only clamp horizontally)
    move.boundTo(player, 0, 800, false, false);
}
Enter fullscreen mode Exit fullscreen mode
Method Parameters Purpose
move.bound(id) Component Clamp to all four canvas edges
move.boundTo(id, l, r, t, b) Component, left, right, top, bottom Clamp to custom boundaries

5. Rectangle Collision with crashWith()

crashWith(other) checks if two Components overlap and returns true if they do. This is the foundation for hit detection, pickups, and obstacle collision.

const player = new Component(40, 40, "blue", 100, 300, "rect");
const coin   = new Component(20, 20, "gold", 400, 200, "rect");
const wall   = new Component(200, 20, "gray", 300, 350, "rect");
display.add(player);
display.add(coin);
display.add(wall);

let score = 0;

function update(dt) {
    // Move player
    if (display.keys[39]) player.speedX =  4;
    if (display.keys[37]) player.speedX = -4;
    else if (!display.keys[39]) player.speedX = 0;

    // Collect coin on touch
    if (player.crashWith(coin)) {
        score++;
        coin.x = Math.random() * 760;
        coin.y = Math.random() * 560;
    }

    // Stop at wall
    if (player.crashWith(wall)) {
        player.speedX = 0;
    }
}
Enter fullscreen mode Exit fullscreen mode

💡 Tip: crashWith() is rotation-aware. Even if your Component is rotated, collisions still work correctly.

6. Text with Tctxt

Tctxt is Limn Engine's rich text Component. It extends the base Component class with font size, font family, text alignment, optional background, and padding.

// Tctxt(size, font, color, x, y, align, stroke, baseline, background, padX, padY)
const scoreText = new Tctxt(
    "22px",                   // font size
    "Arial",                  // font family
    "white",                  // text colour
    20, 36,                   // x, y position
    "left",                   // alignment: "left", "center", or "right"
    false,                    // stroke mode (false = fill, true = outline only)
    "alphabetic",             // text baseline
    "rgba(0,0,0,0.6)",        // background fill colour (null to disable)
    14, 6                     // paddingX, paddingY
);
scoreText.setText("Score: 0");
display.add(scoreText);

let score = 0;

function update() {
    score++;
    scoreText.setText("Score: " + Math.floor(score / 60));

    // Keep the score box locked to the screen when the camera moves
    scoreText.fixed();
}
Enter fullscreen mode Exit fullscreen mode

💡 Tip: fixed() must be called every frame. It keeps the text at the same screen position even when the camera moves.

Parameter Example Purpose
size "22px" Font size as CSS string
font "Arial" Font family name
align "left" "left", "center", or "right"
stroke false false = filled text, true = outlined
background "rgba(0,0,0,0.6)" Background fill (null to disable)
padX / padY 14, 6 Pixel padding inside background

7. Images with setImage()

Any Component can display an image instead of a coloured rectangle. Pass "image" as the type at construction, or call setImage(src) at any point.

// Method 1 — image at construction
const player = new Component(64, 64, "img/hero.png", 100, 100, "image");
display.add(player);

// Method 2 — switch to image at runtime
const enemy = new Component(40, 40, "red", 300, 200, "rect");
display.add(enemy);
enemy.setImage("img/enemy.png"); // switches to image mode

// Switch back to a colour rectangle
enemy.setColor("purple"); // image cleared, back to rect mode
Enter fullscreen mode Exit fullscreen mode
Method Parameters Behaviour
setImage(src) file path Load image — falls back to red rect on error
setColor(color) CSS color Switch back to filled rect

💡 Tip: If the image fails to load, Limn automatically falls back to a red rectangle so you can diagnose the problem.

8. Mouse Input & clicked()

Limn Engine stores the mouse position in display.x and display.y while pressed. clicked() checks if the press landed on a specific Component.

const btn = new Component(160, 50, "#7fffb2", 320, 270, "rect");
display.add(btn);

function update() {
    // Check if mouse is pressed anywhere
    if (display.x) {
        console.log("Mouse at", display.x, display.y);
    }

    // Check if mouse pressed specifically on the button
    if (display.x && btn.clicked()) {
        btn.setColor("lime");
        console.log("Button clicked!");
    } else {
        btn.setColor("#7fffb2");
    }
}
Enter fullscreen mode Exit fullscreen mode

💡 Tip: Works on touchscreen too — touchstart sets display.x and display.y to the finger position.

9. Sound with the Sound Class

The Sound class wraps the browser's Audio API for simple load-and-play audio with volume control, looping, pause, and automatic clone-on-overlap.

// Create sounds at the top — preloading starts immediately
const jumpSfx  = new Sound("audio/jump.wav");
const hitSfx   = new Sound("audio/hit.wav", { volume: 0.8 });
const bgMusic  = new Sound("audio/music.mp3", { loop: true, volume: 0.5 });

bgMusic.play(); // start background music

function update() {
    // Jump on Space — reset key so it fires only once per press
    if (display.keys[32]) {
        display.keys[32] = false;
        jumpSfx.play(); // clones if already playing — no cut-off
    }

    if (player.crashWith(enemy)) {
        hitSfx.play();
    }
}
Enter fullscreen mode Exit fullscreen mode
Method Purpose
play(volume?) Play sound — clones if already playing (overlap safe)
stop() Stop and rewind to beginning
pause() Pause at current position
setVolume(0–1) Change volume
setLoop(bool) Enable or disable looping
isPlaying() Returns true if currently playing

10. Game States with display.scene

display.scene is Limn Engine's scene management system. Every Component is registered to a scene number, and only Components whose scene matches display.scene are drawn and updated.

// Scene 0 — main menu
const playBtn = new Component(160, 50, "#7fffb2", 320, 270, "rect");
display.add(playBtn, 0);

// Scene 1 — gameplay
const player = new Component(40, 40, "cyan", 100, 100, "rect");
display.add(player, 1);

// Scene 2 — game over
const gameOverText = new Tctxt("36px","Arial","red",260,280,"center");
gameOverText.setText("GAME OVER");
display.add(gameOverText, 2);

display.scene = 0; // start on the menu

let playerDead = false;

function update() {
    if (display.scene === 0) {
        if (display.x && playBtn.clicked()) {
            display.scene = 1; // start game
        }
    }

    if (display.scene === 1) {
        // gameplay logic here
        if (playerDead) display.scene = 2;
    }
}
Enter fullscreen mode Exit fullscreen mode

💡 Tip: Components default to scene 0 if you call display.add(obj) without a second argument.

11. Coin Collector — Complete Tutorial

This builds a complete game using only Level 1 concepts — movement, collision, score, boundaries, and Tctxt.

<!DOCTYPE html>
<html>
<head>
    <title>Coin Collector</title>
    <script src="epic.js"></script>
</head>
<body>
    <script>
        let gameActive = true;
        const display = new Display();
        display.perform();
        display.start(800, 600);
        display.backgroundColor("green");

        const player = new Component(40, 40, "blue", 400, 300, "rect");
        display.add(player);

        const scoreText = new Tctxt("24px", "Arial", "white", 20, 50);
        scoreText.setText("Score: 0 / 10");
        display.add(scoreText);

        const winText = new Tctxt("48px", "Arial", "gold", 400, 300);
        winText.align = "center";
        winText.setText("YOU WIN!");
        winText.hide();
        display.add(winText);

        const restartText = new Tctxt("20px", "Arial", "white", 400, 380);
        restartText.align = "center";
        restartText.setText("Press R to play again");
        restartText.hide();
        display.add(restartText);

        let score = 0;
        const totalCoins = 10;
        let coins = [];

        for (let i = 0; i < totalCoins; i++) {
            let coin = new Component(30, 30, "gold",
                Math.random() * 700 + 50,
                Math.random() * 500 + 50, "rect");
            display.add(coin);
            coins.push(coin);
        }

        function restart() {
            location.reload();
        }

        function update(deltaTime) {
            if (display.keys[82]) { restart(); return; }
            if (!gameActive) return;

            // Player movement
            if (display.keys[37]) player.speedX = -400 * deltaTime;
            else if (display.keys[39]) player.speedX = 400 * deltaTime;
            else player.speedX = 0;

            if (display.keys[38]) player.speedY = -400 * deltaTime;
            else if (display.keys[40]) player.speedY = 400 * deltaTime;
            else player.speedY = 0;

            move.bound(player);

            // Coin collection
            for (let i = 0; i < coins.length; i++) {
                if (player.crashWith(coins[i])) {
                    display.camera.shake(3, 3);
                    coins[i].hide();
                    coins.splice(i, 1);
                    score++;
                    scoreText.setText("Score: " + score + " / " + totalCoins);
                    break;
                }
            }

            // Win condition
            if (score === totalCoins && gameActive) {
                gameActive = false;
                winText.show();
                restartText.show();
                scoreText.hide();
            }
        }
    </script>
</body>
</html>
Enter fullscreen mode Exit fullscreen mode

✅ What You Get:

  • Move with arrow keys
  • Collect gold coins
  • Screen shake on collection
  • Win screen when all coins collected
  • Press R to restart

12. Quick Reference

What you want Code
Start the engine const display = new Display(); display.start(800,600);
Add a coloured box const b = new Component(w,h,"red",x,y); display.add(b);
Move with keys if(display.keys[39]) player.speedX = 250*dt;
Stop moving player.stopMove(); or player.speedX = 0;
Keep inside canvas move.bound(player);
Detect collision if(a.crashWith(b)) { ... }
Show score text const t = new Tctxt("20px","Arial","white",10,30); t.setText("0");
Lock HUD to screen t.fixed(); // every frame
Display an image obj.setImage("img/hero.png");
Detect mouse click if(display.x && btn.clicked()) { ... }
Play a sound const s = new Sound("sfx.wav"); s.play();
Switch game screen display.add(obj, 1); display.scene = 1;

What's Next?

You've completed Level 1: Beginner! 🎉

Level Description
🟢 Level 1 — Beginner ✅ You are here
🟡 Level 2 — Intermediate Physics, tilemaps, camera follow
🟠 Level 3 — Advanced Particles, circle collision, dynamic tilemaps
🔴 Level 4 — 10x Dual‑renderer, performance optimization, engine extension

Special Thanks

"A heartfelt thank you to **GyaanSetu Javascript* for featuring Limn Engine and helping us share this tutorial with the JavaScript community. Your support means the world to us."*

If you're reading this because of GyaanSetu Javascript's post, welcome! We're thrilled to have you here.

Useful Links

Resource Link
Download Limn Engine limn-engine.vercel.app
Complete API Reference limn-engine.vercel.app/reference.html
Discord Community discord.gg/ZqnUtTQb8
GitHub github.com/limn-engine

Draw your game into existence. 🎨

Top comments (0)