Kehinde Owolabi

Posted on Jun 20

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

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

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
}

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

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

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

💡 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

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

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

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

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

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

DEV Community

🟢 Level 1 Tutorial — Limn Engine Beginner Guide

🟢 Level 1 Tutorial — Limn Engine Beginner Guide

Start Your Game Development Journey Here

What You'll Learn

Before You Start

What You Need

The Golden Rule

1. Creating a Display

What's Happening?

2. Adding & Moving Components

Component Properties

Component Types

3. Keyboard Input & DeltaTime

Common Key Codes

4. Boundaries with move.bound()

5. Rectangle Collision with crashWith()

6. Text with Tctxt

7. Images with setImage()

8. Mouse Input & clicked()

9. Sound with the Sound Class

10. Game States with display.scene

11. Coin Collector — Complete Tutorial

12. Quick Reference

What's Next?

Special Thanks

Useful Links

Top comments (0)