DEV Community: Kehinde Owolabi

Multiplayer Games with Limn Engine and WebSockets

Kehinde Owolabi — Mon, 13 Jul 2026 17:31:58 +0000

Multiplayer Games with Limn Engine and WebSockets

Building Real-Time Multiplayer Games from Scratch

📖 Introduction

Multiplayer gaming is one of the most sought-after features in game development. Players want to compete, cooperate, and connect with others. But building a multiplayer game is notoriously difficult — networking introduces latency, synchronization issues, and a whole new layer of complexity.

In this guide, we'll build a real-time multiplayer game using Limn Engine and WebSockets. We'll cover everything from setting up a WebSocket server to handling player movement, synchronization, and latency compensation.

Note: This is a basic implementation for learning purposes. For production games, you'll need to add authentication, matchmaking, and more robust error handling.

🎯 What We're Building

A simple top-down multiplayer game where:

Players connect to a server
Each player controls a colored square
Players see each other move in real-time
Players can see each other's names

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   ┌─────────────┐     WebSocket      ┌─────────────────────┐   │
│   │   Client 1  │ ◄────────────────► │                     │   │
│   └─────────────┘                     │                     │   │
│                                        │   Node.js Server   │   │
│   ┌─────────────┐     WebSocket      │   (ws library)     │   │
│   │   Client 2  │ ◄────────────────► │                     │   │
│   └─────────────┘                     └─────────────────────┘   │
│                                                                 │
│   ┌─────────────┐                                              │
│   │   Client 3  │ ◄────────────────►                         │
│   └─────────────┘                                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

How It Works

Clients connect to the server via WebSocket
Server tracks all connected players and their positions
Each client sends their movement updates to the server
Server broadcasts all player positions to all clients
Each client renders all players on their screen

🖥️ Step 1: The WebSocket Server (Node.js)

Install Dependencies

npm init -y
npm install ws

Server Code (`server.js`)

const WebSocket = require('ws');
const http = require('http');

// ── CONFIGURATION ──
const PORT = 8080;
const WORLD_WIDTH = 2000;
const WORLD_HEIGHT = 2000;

// ── CREATE HTTP SERVER ──
const server = http.createServer((req, res) => {
    res.writeHead(200, { 'Content-Type': 'text/html' });
    res.end('<h1>Multiplayer Server Running</h1>');
});

// ── CREATE WEBSOCKET SERVER ──
const wss = new WebSocket.Server({ server });

// ── GAME STATE ──
const players = {};
let nextId = 1;

// ── HELPER FUNCTIONS ──
function broadcast(data) {
    const message = JSON.stringify(data);
    wss.clients.forEach(client => {
        if (client.readyState === WebSocket.OPEN) {
            client.send(message);
        }
    });
}

function getPlayerState(id) {
    return {
        id: id,
        x: players[id].x,
        y: players[id].y,
        color: players[id].color,
        name: players[id].name
    };
}

function getAllPlayerStates() {
    const states = {};
    for (let id in players) {
        states[id] = getPlayerState(id);
    }
    return states;
}

// ── WEBHOOKS ──
wss.on('connection', (ws) => {
    console.log('New player connected');

    // Assign player ID
    const playerId = nextId++;

    // Assign random color
    const colors = ['#ff6b6b', '#5b8cff', '#7fffb2', '#ffbb6b', '#ff6bff', '#6bffb2'];
    const color = colors[Math.floor(Math.random() * colors.length)];

    // Create player
    players[playerId] = {
        id: playerId,
        x: Math.random() * 400 + 200,
        y: Math.random() * 400 + 200,
        color: color,
        name: `Player ${playerId}`
    };

    // Send current state to new player
    ws.send(JSON.stringify({
        type: 'init',
        playerId: playerId,
        players: getAllPlayerStates()
    }));

    // Broadcast new player to others
    broadcast({
        type: 'playerJoined',
        player: getPlayerState(playerId)
    });

    // ── HANDLE INCOMING MESSAGES ──
    ws.on('message', (message) => {
        try {
            const data = JSON.parse(message);

            if (data.type === 'move') {
                // Update player position
                players[playerId].x = data.x;
                players[playerId].y = data.y;

                // Broadcast update to all clients
                broadcast({
                    type: 'playerMoved',
                    id: playerId,
                    x: data.x,
                    y: data.y
                });
            }

            if (data.type === 'chat') {
                broadcast({
                    type: 'chat',
                    id: playerId,
                    name: players[playerId].name,
                    message: data.message
                });
            }

            if (data.type === 'nameChange') {
                players[playerId].name = data.name;
                broadcast({
                    type: 'playerNameChanged',
                    id: playerId,
                    name: data.name
                });
            }
        } catch (e) {
            console.error('Error processing message:', e);
        }
    });

    // ── HANDLE DISCONNECT ──
    ws.on('close', () => {
        console.log(`Player ${playerId} disconnected`);
        delete players[playerId];
        broadcast({
            type: 'playerLeft',
            id: playerId
        });
    });
});

// ── START SERVER ──
server.listen(PORT, () => {
    console.log(`🚀 Multiplayer server running on ws://localhost:${PORT}`);
    console.log(`📊 World size: ${WORLD_WIDTH}x${WORLD_HEIGHT}`);
});

🎮 Step 2: The Client (Limn Engine)

Client Code (`multiplayer.html`)

<!DOCTYPE html>
<html>
<head>
    <title>Multiplayer Game - Limn Engine</title>
    <script src="epic.js"></script>
    <style>
        body { margin: 0; background: #0a0a0a; overflow: hidden; }
        #status {
            position: fixed;
            top: 10px;
            left: 50%;
            transform: translateX(-50%);
            color: #7fffb2;
            font-family: 'Courier New', monospace;
            font-size: 14px;
            background: rgba(0,0,0,0.7);
            padding: 8px 16px;
            border-radius: 8px;
            z-index: 1000;
            pointer-events: none;
        }
        #chat {
            position: fixed;
            bottom: 20px;
            left: 50%;
            transform: translateX(-50%);
            width: 400px;
            z-index: 1000;
        }
        #chat-input {
            width: 100%;
            padding: 8px 12px;
            background: rgba(0,0,0,0.8);
            color: white;
            border: 1px solid #333;
            border-radius: 8px;
            font-size: 14px;
            outline: none;
            display: none;
        }
        #chat-input:focus {
            border-color: #7fffb2;
        }
        #chat-messages {
            max-height: 150px;
            overflow-y: auto;
            margin-bottom: 8px;
            color: #aaa;
            font-size: 12px;
            font-family: 'Courier New', monospace;
        }
        #chat-messages .system { color: #7fffb2; }
        #chat-messages .player { color: #5b8cff; }
    </style>
</head>
<body>

    <div id="status">🔌 Connecting...</div>

    <div id="chat">
        <div id="chat-messages"></div>
        <input id="chat-input" type="text" placeholder="Press Enter to chat..." />
    </div>

    <script>
        // ── DOM REFS ──
        const statusEl = document.getElementById('status');
        const chatInput = document.getElementById('chat-input');
        const chatMessages = document.getElementById('chat-messages');

        // ── LIMN ENGINE SETUP ──
        const display = new Display();
        display.perform();
        display.start(800, 600);
        display.backgroundColor("#0a0a10");

        // World size
        display.camera.worldWidth = 2000;
        display.camera.worldHeight = 2000;

        // ── GAME STATE ──
        let myId = null;
        let myName = 'Player';
        let remotePlayers = {};
        let localPlayer = null;
        let isConnected = false;

        // ── CREATE LOCAL PLAYER ──
        function createLocalPlayer() {
            localPlayer = new Component(36, 36, "cyan", 400, 300, "rect");
            display.add(localPlayer);
            display.camera.follow(localPlayer, true);
            return localPlayer;
        }

        // ── REMOTE PLAYER MANAGEMENT ──
        function addRemotePlayer(id, x, y, color, name) {
            const player = new Component(36, 36, color, x, y, "rect");
            display.add(player);

            // Store extra data
            player._id = id;
            player._name = name || `Player ${id}`;
            player._targetX = x;
            player._targetY = y;

            remotePlayers[id] = player;
            return player;
        }

        function removeRemotePlayer(id) {
            if (remotePlayers[id]) {
                remotePlayers[id].destroy();
                delete remotePlayers[id];
            }
        }

        function updateRemotePlayer(id, x, y) {
            if (remotePlayers[id]) {
                // Smooth interpolation (lerp) for movement
                remotePlayers[id]._targetX = x;
                remotePlayers[id]._targetY = y;
            }
        }

        // ── WEBHOOKS SETUP ──
        function connectWebSocket() {
            const ws = new WebSocket('ws://localhost:8080');

            ws.onopen = () => {
                isConnected = true;
                statusEl.textContent = '✅ Connected!';
                statusEl.style.color = '#7fffb2';

                // Create local player after receiving initial state
                createLocalPlayer();
            };

            ws.onmessage = (event) => {
                try {
                    const data = JSON.parse(event.data);
                    handleMessage(data);
                } catch (e) {
                    console.error('Error parsing message:', e);
                }
            };

            ws.onclose = () => {
                isConnected = false;
                statusEl.textContent = '❌ Disconnected!';
                statusEl.style.color = '#ff6b6b';
                setTimeout(() => {
                    connectWebSocket(); // Auto-reconnect
                }, 3000);
            };

            ws.onerror = (error) => {
                console.error('WebSocket error:', error);
                statusEl.textContent = '⚠️ Connection error';
                statusEl.style.color = '#ffbb6b';
            };

            // ── MESSAGE HANDLER ──
            function handleMessage(data) {
                switch (data.type) {
                    case 'init':
                        // Set player ID
                        myId = data.playerId;
                        statusEl.textContent = `✅ Connected as ${myName}`;

                        // Add remote players
                        for (let id in data.players) {
                            if (parseInt(id) !== myId) {
                                const p = data.players[id];
                                addRemotePlayer(id, p.x, p.y, p.color, p.name);
                            }
                        }
                        break;

                    case 'playerJoined':
                        if (data.player.id !== myId) {
                            const p = data.player;
                            addRemotePlayer(p.id, p.x, p.y, p.color, p.name);
                            addChatMessage(`👋 ${p.name} joined the game`, 'system');
                        }
                        break;

                    case 'playerLeft':
                        if (data.id !== myId) {
                            const name = remotePlayers[data.id]?._name || `Player ${data.id}`;
                            removeRemotePlayer(data.id);
                            addChatMessage(`👋 ${name} left the game`, 'system');
                        }
                        break;

                    case 'playerMoved':
                        if (data.id !== myId) {
                            updateRemotePlayer(data.id, data.x, data.y);
                        }
                        break;

                    case 'playerNameChanged':
                        if (data.id !== myId) {
                            if (remotePlayers[data.id]) {
                                remotePlayers[data.id]._name = data.name;
                            }
                        }
                        break;

                    case 'chat':
                        if (data.id !== myId) {
                            addChatMessage(`${data.name}: ${data.message}`, 'player');
                        }
                        break;
                }
            }

            // ── SEND FUNCTIONS ──
            window.sendMove = function(x, y) {
                if (isConnected && ws.readyState === WebSocket.OPEN) {
                    ws.send(JSON.stringify({
                        type: 'move',
                        x: x,
                        y: y
                    }));
                }
            };

            window.sendChat = function(message) {
                if (isConnected && ws.readyState === WebSocket.OPEN) {
                    ws.send(JSON.stringify({
                        type: 'chat',
                        message: message
                    }));
                }
            };

            window.sendNameChange = function(name) {
                if (isConnected && ws.readyState === WebSocket.OPEN) {
                    ws.send(JSON.stringify({
                        type: 'nameChange',
                        name: name
                    }));
                }
            };

            // ── CHAT UI ──
            function addChatMessage(text, type = 'system') {
                const div = document.createElement('div');
                div.className = type;
                div.textContent = text;
                chatMessages.appendChild(div);
                chatMessages.scrollTop = chatMessages.scrollHeight;

                // Limit messages
                while (chatMessages.children.length > 50) {
                    chatMessages.removeChild(chatMessages.firstChild);
                }
            }

            // ── CHAT INPUT HANDLING ──
            document.addEventListener('keydown', (e) => {
                if (e.key === 't' || e.key === 'T') {
                    chatInput.style.display = 'block';
                    chatInput.focus();
                }
                if (e.key === 'Enter' && chatInput.style.display === 'block') {
                    const msg = chatInput.value.trim();
                    if (msg) {
                        if (msg.startsWith('/name ')) {
                            const newName = msg.substring(6).trim();
                            if (newName) {
                                myName = newName;
                                sendNameChange(newName);
                                addChatMessage(`You changed your name to ${newName}`, 'system');
                            }
                        } else {
                            sendChat(msg);
                            addChatMessage(`${myName}: ${msg}`, 'player');
                        }
                    }
                    chatInput.value = '';
                    chatInput.style.display = 'none';
                }
                if (e.key === 'Escape' && chatInput.style.display === 'block') {
                    chatInput.value = '';
                    chatInput.style.display = 'none';
                }
            });

            // ── PLAYER NAME INPUT ──
            const nameInput = prompt('Enter your name:', `Player ${Math.floor(Math.random() * 1000)}`);
            if (nameInput) {
                myName = nameInput;
                // We'll send the name after connection is established
            }

            // Wait for connection to send name
            const nameCheckInterval = setInterval(() => {
                if (isConnected && ws.readyState === WebSocket.OPEN) {
                    sendNameChange(myName);
                    clearInterval(nameCheckInterval);
                }
            }, 100);

            // ── GAME LOOP ──
            const SPEED = 200;
            let lastSendTime = 0;
            const SEND_INTERVAL = 50; // ms

            function update(dt) {
                if (!isConnected || !localPlayer) return;

                // Player movement (WASD)
                let mx = 0, my = 0;
                if (display.keys[87]) my = -1;
                if (display.keys[83]) my = 1;
                if (display.keys[65]) mx = -1;
                if (display.keys[68]) mx = 1;

                if (mx !== 0 && my !== 0) {
                    mx *= 0.707;
                    my *= 0.707;
                }

                localPlayer.x += mx * SPEED * dt;
                localPlayer.y += my * SPEED * dt;

                // Clamp to world
                localPlayer.x = Math.max(0, Math.min(1950, localPlayer.x));
                localPlayer.y = Math.max(0, Math.min(1950, localPlayer.y));

                // Send position to server (throttled)
                const now = performance.now();
                if (now - lastSendTime > SEND_INTERVAL) {
                    sendMove(localPlayer.x, localPlayer.y);
                    lastSendTime = now;
                }

                // Update remote players (smooth interpolation)
                for (let id in remotePlayers) {
                    const p = remotePlayers[id];
                    // Smoothly interpolate toward target position
                    p.x += (p._targetX - p.x) * 0.15;
                    p.y += (p._targetY - p.y) * 0.15;
                }
            }

            // ── START THE GAME ──
            // The update function is now ready
        }

        // ── INITIALIZE CONNECTION ──
        connectWebSocket();

        // ── OVERRIDE UPDATE ──
        // This is a bit of a hack — we're replacing the global update function
        // that Limn Engine expects. In a real game, you'd structure this better.
        const originalUpdate = window.update || function() {};
        window.update = function(dt) {
            // The actual update logic is inside connectWebSocket
            // but we need to call it from here
            if (typeof updateGame === 'function') {
                updateGame(dt);
            }
        };

        // We'll store the update function from the closure
        // This is a simplified approach — in production, use a proper module system
        let updateGame = function(dt) {};

        // Override the connectWebSocket to expose the update function
        const originalConnect = connectWebSocket;
        connectWebSocket = function() {
            // Call the original but capture the update function
            // This is a hack — in a real game, use proper architecture
            originalConnect();

            // Wait for connection to be established
            const checkInterval = setInterval(() => {
                if (isConnected) {
                    // Expose the update function
                    updateGame = function(dt) {
                        if (!isConnected || !localPlayer) return;

                        // Player movement (WASD)
                        let mx = 0, my = 0;
                        if (display.keys[87]) my = -1;
                        if (display.keys[83]) my = 1;
                        if (display.keys[65]) mx = -1;
                        if (display.keys[68]) mx = 1;

                        if (mx !== 0 && my !== 0) {
                            mx *= 0.707;
                            my *= 0.707;
                        }

                        localPlayer.x += mx * SPEED * dt;
                        localPlayer.y += my * SPEED * dt;

                        // Clamp to world
                        localPlayer.x = Math.max(0, Math.min(1950, localPlayer.x));
                        localPlayer.y = Math.max(0, Math.min(1950, localPlayer.y));

                        // Send position to server (throttled)
                        const now = performance.now();
                        if (now - lastSendTime > SEND_INTERVAL) {
                            sendMove(localPlayer.x, localPlayer.y);
                            lastSendTime = now;
                        }

                        // Update remote players (smooth interpolation)
                        for (let id in remotePlayers) {
                            const p = remotePlayers[id];
                            p.x += (p._targetX - p.x) * 0.15;
                            p.y += (p._targetY - p.y) * 0.15;
                        }
                    };
                    clearInterval(checkInterval);
                }
            }, 100);
        };

        // Actually start the connection
        connectWebSocket();

        console.log('🎮 Multiplayer client ready');
        console.log('📝 Type /name YourName to change name');
        console.log('💬 Press T to chat');
        console.log('🕹️  WASD to move');
    </script>
</body>
</html>

🎯 Step 3: Running the Game

Start the Server

node server.js

You should see:

🚀 Multiplayer server running on ws://localhost:8080
📊 World size: 2000x2000

Open the Client

Open multiplayer.html in your browser
Enter your name when prompted
Open the same file in another browser tab (or on another device)
Watch both players move in real-time!

📊 Key Concepts Explained

1. WebSocket Communication

Message Type	Sent By	Received By	Purpose
`move`	Client	Server	Send player position
`playerMoved`	Server	All Clients	Broadcast position update
`playerJoined`	Server	All Clients	New player joined
`playerLeft`	Server	All Clients	Player disconnected

2. Interpolation (Smooth Movement)

// Smoothly interpolate toward target position
p.x += (p._targetX - p.x) * 0.15;
p.y += (p._targetY - p.y) * 0.15;

This makes remote players move smoothly instead of jumping.

3. Throttled Sending

const SEND_INTERVAL = 50; // ms
if (now - lastSendTime > SEND_INTERVAL) {
    sendMove(localPlayer.x, localPlayer.y);
    lastSendTime = now;
}

Sending every frame (60 times/sec) would overload the server. Sending 20 times/sec (every 50ms) is enough.

🚀 Extending the Game

Add Player Names Above Heads

// In the render loop
for (let id in remotePlayers) {
    const p = remotePlayers[id];
    // Draw name above player
    display.context.fillStyle = "white";
    display.context.font = "12px Arial";
    display.context.textAlign = "center";
    display.context.fillText(p._name, p.x + 18, p.y - 10);
}

Add Shooting

// Client sends shoot message
function shoot() {
    ws.send(JSON.stringify({
        type: 'shoot',
        x: localPlayer.x + 18,
        y: localPlayer.y + 18,
        angle: localPlayer.angle || 0
    }));
}

// Server broadcasts bullet
broadcast({
    type: 'bulletFired',
    id: playerId,
    x: data.x,
    y: data.y,
    angle: data.angle
});

Add Score Tracking

// Server tracks scores
players[playerId].score = 0;

// On hit
players[shooterId].score += 10;
broadcast({
    type: 'scoreUpdate',
    id: shooterId,
    score: players[shooterId].score
});

⚠️ Limitations (Not Yet Tested)

Limitation	Description
No authentication	Anyone can join with any name
No matchmaking	All players join the same world
No room support	Can't create separate game rooms
No latency compensation	Players with high ping will lag
No reconnection handling	If connection drops, progress is lost

🎯 The One-Line Summary

"WebSockets + Limn Engine = real-time multiplayer games with minimal setup."

🔗 Resources

Resource	Link
WebSocket Documentation	developer.mozilla.org/en-US/docs/Web/API/WebSocket
ws Library	github.com/websockets/ws
Limn Engine	limn-engine-doc.vercel.app

Draw your game into existence — and let others play it too. 🚀

Memory Management in JavaScript Games — `destroy()`, `hide()`, and Object Pooling

Kehinde Owolabi — Mon, 13 Jul 2026 16:45:29 +0000

Memory Management in JavaScript Games — destroy(), hide(), and Object Pooling

How to Prevent Memory Leaks and Optimize Performance in Limn Engine

📖 Introduction

Memory management is one of the most overlooked aspects of game development. It's easy to focus on features, graphics, and gameplay — but if your game leaks memory, it will eventually slow down, stutter, and crash.

In JavaScript, memory management is "automatic" thanks to garbage collection. But that doesn't mean you can ignore it. In fact, automatic garbage collection can be a trap — if you don't manage your objects properly, you'll create work for the garbage collector, causing frame drops and stuttering.

Limn Engine provides three tools for memory management:

Tool	Purpose	Use Case
`destroy()`	Permanent removal	Bullets, defeated enemies, collected items
`hide()` / `show()`	Temporary invisibility	Respawnable enemies, UI panels
Object Pooling	Reuse objects	Particles, bullets, frequent spawns

In this guide, we'll cover all three — what they are, when to use them, and why they matter.

🎯 The Problem: What Happens When You Don't Manage Memory?

Scenario 1: The Infinite Bullet

// ❌ WRONG: Bullets never get removed
function shoot() {
    const bullet = new Component(5, 10, "yellow", player.x, player.y, "rect");
    bullet.speedY = -500;
    display.add(bullet);
    bullets.push(bullet);
}

function update(dt) {
    for (let i = 0; i < bullets.length; i++) {
        bullets[i].y += bullets[i].speedY * dt;
        // Bullets keep going forever — even off-screen!
    }
}

The Problem: Every bullet you shoot stays in memory forever. After 10,000 bullets, your game will slow to a crawl.

The Fix: Remove bullets when they leave the screen.

// ✅ CORRECT: Remove off-screen bullets
function update(dt) {
    for (let i = bullets.length - 1; i >= 0; i--) {
        bullets[i].y += bullets[i].speedY * dt;
        if (bullets[i].y < -50) {
            bullets[i].destroy();  // Remove from memory
            bullets.splice(i, 1);   // Remove from array
        }
    }
}

Scenario 2: The Enemy That Won't Die

// ❌ WRONG: Enemies just hide — never destroy
function killEnemy(enemy) {
    enemy.hide();  // Disappears, but still in memory!
}

function update() {
    // 100 enemies hidden, still being processed every frame
    for (let i = 0; i < enemies.length; i++) {
        if (enemies[i].health <= 0) {
            enemies[i].hide();  // Still in comm[] !
        }
    }
}

The Problem: Hidden enemies are still in comm[] and still being processed every frame. They just aren't drawn.

The Fix: Use destroy() for permanent removal, hide() only for temporary invisibility.

// ✅ CORRECT: Destroy dead enemies
function killEnemy(enemy) {
    enemy.destroy();  // Remove from comm[] completely
}

// Use hide() only for temporary invisibility
function respawnEnemy(enemy) {
    enemy.hide();           // Temporary
    setTimeout(() => {
        enemy.show();       // Reappear
    }, 3000);
}

🔧 Tool 1: `destroy()` — Permanent Removal

What It Does: Completely removes a component from the engine's rendering pipeline.

How It Works:

// Inside Component.destroy()
destroy() {
    // Find and remove from comm[] (main display)
    let index = comm.findIndex(c => c.x === this);
    if (index > -1) comm.splice(index, 1);

    // Find and remove from commp[] (fake canvas)
    index = commp.findIndex(c => c.x === this);
    if (index > -1) commp.splice(index, 1);

    // Nullify the update method to prevent accidental calls
    this.update = null;
}

When to Use:

Bullets that leave the screen
Defeated enemies
Collected items
Any object that will never be needed again

Example:

// Remove off-screen bullets
if (bullet.y < -50 || bullet.y > 650 || bullet.x < -50 || bullet.x > 850) {
    bullet.destroy();
}

// Remove defeated enemies
if (enemy.health <= 0) {
    enemy.destroy();
}

// Remove collected coins
if (player.crashWith(coin)) {
    coin.destroy();
}

Why It Matters:

Prevents comm[] from growing indefinitely
Reduces the number of objects processed each frame
Prevents memory leaks

🔧 Tool 2: `hide()` / `show()` — Temporary Invisibility

What They Do: hide() stops a component from being drawn. show() makes it visible again.

How They Work:

// Inside Component.hide()
hide() {
    this.update = null;  // Stop drawing
}

// Inside Component.show()
show() {
    this.update = this.bUpdate;  // Resume drawing
}

When to Use hide():

Enemies that respawn
UI panels that toggle
Objects that temporarily disappear
Anything that will be needed again

Example:

// Enemy respawn system
function respawnEnemy(enemy) {
    // 1. Hide the enemy
    enemy.hide();

    // 2. Wait 3 seconds
    setTimeout(() => {
        // 3. Move to a new position
        enemy.x = Math.random() * 700 + 50;
        enemy.y = Math.random() * 500 + 50;

        // 4. Show the enemy
        enemy.show();
    }, 3000);
}

// UI panel toggle
function toggleMenu() {
    if (menu.visible) {
        menu.hide();
        menu.visible = false;
    } else {
        menu.show();
        menu.visible = true;
    }
}

Why Not Use destroy()?

destroy() removes the object from comm[]
If you destroy an enemy, you have to recreate it from scratch
hide() keeps the object in memory — faster to show again

🔧 Tool 3: Object Pooling — Reuse Objects

What It Is: A design pattern where you pre-create a pool of objects and reuse them instead of creating and destroying them constantly.

Why It Matters:

Approach	Performance	Memory
Create/Destroy	❌ Slow (GC spikes)	❌ Fragmented
Object Pool	✅ Fast (no GC)	✅ Efficient

How It Works:

Create a pool of objects at startup
When you need an object, take one from the pool
When you're done, return it to the pool
Never create or destroy objects during gameplay

Example: Bullet Pool

class BulletPool {
    constructor(size = 50) {
        this.pool = [];
        this.active = [];

        // Pre-create bullets
        for (let i = 0; i < size; i++) {
            const bullet = new Component(5, 10, "yellow", 0, 0, "rect");
            bullet.hide();  // Start invisible
            this.pool.push(bullet);
        }
    }

    // Get a bullet from the pool
    get(x, y, speedX, speedY) {
        let bullet = this.pool.pop();

        // If pool is empty, create a new one (expands the pool)
        if (!bullet) {
            bullet = new Component(5, 10, "yellow", 0, 0, "rect");
        }

        // Configure the bullet
        bullet.x = x;
        bullet.y = y;
        bullet.speedX = speedX;
        bullet.speedY = speedY;
        bullet.show();
        display.add(bullet);

        this.active.push(bullet);
        return bullet;
    }

    // Return a bullet to the pool
    return(bullet) {
        bullet.hide();
        bullet.x = -1000;  // Move off-screen
        bullet.y = -1000;
        this.pool.push(bullet);

        // Remove from active array
        const index = this.active.indexOf(bullet);
        if (index > -1) this.active.splice(index, 1);
    }

    // Update all active bullets
    update(dt) {
        for (let i = this.active.length - 1; i >= 0; i--) {
            const bullet = this.active[i];
            bullet.y += bullet.speedY * dt;
            bullet.x += bullet.speedX * dt;

            // Return to pool when off-screen
            if (bullet.y < -50 || bullet.y > 650 || 
                bullet.x < -50 || bullet.x > 850) {
                this.return(bullet);
            }
        }
    }
}

// Usage
const bulletPool = new BulletPool(30);

function shoot() {
    bulletPool.get(player.x + 20, player.y, 0, -500);
}

function update(dt) {
    bulletPool.update(dt);
}

📊 Comparison: Which Approach to Use?

Scenario	Best Approach	Why
Bullets	Object Pool	High frequency, needs to be fast
Enemies	`destroy()` + recreate	Lower frequency, `destroy()` is fine
Respawnable enemies	`hide()` / `show()`	Reuse the same object
Particles	Object Pool	High frequency, custom system
UI panels	`hide()` / `show()`	Toggle visibility
Collected items	`destroy()`	Never needed again
Tiles	`destroy()`	Permanent changes

💡 Pro Tips for Memory Management

1. Always Iterate Backwards When Splicing

// ✅ CORRECT: Reverse iteration
for (let i = enemies.length - 1; i >= 0; i--) {
    if (enemies[i].health <= 0) {
        enemies[i].destroy();
        enemies.splice(i, 1);
    }
}

// ❌ WRONG: Forward iteration skips elements
for (let i = 0; i < enemies.length; i++) {
    if (enemies[i].health <= 0) {
        enemies.splice(i, 1); // Skips the next enemy!
    }
}

2. Use `destroy()` After Removing from Your Arrays

// 1. Remove from your array
enemies.splice(i, 1);

// 2. Then destroy
enemy.destroy();

3. Pre-Allocate Pools for High-Frequency Objects

// Pre-allocate bullets, particles, and other high-frequency objects
const bulletPool = new BulletPool(100);  // Pre-create 100 bullets
const particlePool = new ParticlePool(500);  // Pre-create 500 particles

4. Profile Your Game

Use the browser's built-in tools:

Chrome DevTools → Performance → Record
Look for garbage collection spikes
If you see regular GC spikes, you need better memory management

🎯 The One-Line Summary

"destroy() for permanent removal, hide() for temporary invisibility, and object pooling for high-frequency objects — use the right tool for the right job."

🔗 Resources

Resource	Link
10x Developer Guide	limn-engine-doc.vercel.app/10x.html
API Reference	limn-engine-doc.vercel.app/reference.html

Draw your game into existence — and clean up after yourself. 🚀

🏃 The Ultimate Guide to Limn Engine's `move` Utility

Kehinde Owolabi — Sat, 11 Jul 2026 17:20:28 +0000

🏃 The Ultimate Guide to Limn Engine's `move` Utility

Everything You Need to Know About Movement, Physics, and Control

📖 Introduction

Movement is the foundation of every game. Whether you're building a platformer, a top-down shooter, or an open-world RPG, how objects move determines how your game feels. Get it right, and your game feels polished and professional. Get it wrong, and your game feels clunky and frustrating.

The Limn Engine's move utility is a collection of 34 functions that handle movement, physics, and control. It's designed to save you from writing the same boilerplate code over and over, and to give you powerful, flexible control over how objects move in your game.

The philosophy: Common outcomes should be functions. Every function in move exists because I was tired of writing the same code repeatedly — tired of edge detection, tired of trigonometry, tired of lerp functions, tired of configuring particles.

In this guide, we'll cover every function in the move utility — what it does, when to use it, and why it's powerful.

📊 Complete Function List

Category	Functions
Movement & Positioning	`teleport()`, `setX()`, `setY()`, `position()`, `stamp()`, `clearStamp()`
Angular & Directional	`forward()`, `backward()`, `turnLeft()`, `turnRight()`, `circle()`, `pointTo()`
Boundaries	`bound()`, `boundTo()`
Smooth Movement	`glideX()`, `glideY()`, `glideTo()`
Physics	`accelerate()`, `decelerate()`, `project()`, `hitObject()`
Particles	`explosion()`, `smoke()`, `sparkle()`, `rain()`, `blood()`, `magic()`
Sound	`play()`, `playMusic()`, `stopMusic()`, `setMasterVolume()`, `mute()`, `unmute()`
Debugging	`dot()`

Total: 34 functions

🎯 Movement & Positioning Functions

These functions handle basic movement and positioning of components.

`move.teleport()`

move.teleport(player, 400, 300);

What It Does: Instantly moves a component to a new position.

Why It's Useful: It's the foundation of respawns, checkpoints, and teleportation mechanics. Simple but essential.

When to Use:

Respawn players at checkpoints
Teleport enemies to random positions
Move objects instantly without animation

Example:

// Respawn player at checkpoint
if (player.health <= 0) {
    move.teleport(player, checkpoint.x, checkpoint.y);
}

// Teleport enemy to random position
move.teleport(enemy, Math.random() * 700 + 50, Math.random() * 500 + 50);

`move.setX()` / `move.setY()`

move.setX(player, 100);
move.setY(player, 200);

What It Does: Sets the X or Y position of a component individually.

Why It's Useful: Sometimes you only need to change one axis.

When to Use:

Adjusting position on one axis only
Keeping one axis fixed while changing the other

The Hard Truth: This is just obj.x = value or obj.y = value. It's a convenience wrapper.

`move.position()`

move.position(healthBar, "top", 20);

What It Does: Snaps UI to screen edges or center with one line.

Why It's Useful: It saves you from doing manual centering calculations. Makes UI layout trivial.

When to Use:

Positioning UI elements (health bars, score displays)
Centering logos or titles
Placing buttons at screen edges

Supported Directions:

"top" — top edge with offset
"bottom" — bottom edge with offset
"left" — left edge with offset
"right" — right edge with offset
"center" — center of screen

Example:

move.position(healthBar, "top", 20);
move.position(scoreText, "top", 50);
move.position(logo, "center");
move.position(menuButton, "bottom", 30);

`move.stamp()` / `move.clearStamp()`

const clone = move.stamp(enemy);
move.clearStamp(clone);

What It Does: stamp() creates a clone of a component at its current position. clearStamp() removes it.

Why It's Useful: Useful for creating duplicates of objects or creating effects.

When to Use:

Particle-like duplication
Creating multiple objects from a template
Spawning effects

🧭 Angular & Directional Functions

These functions handle movement and rotation based on a component's angle.

`move.forward()` / `move.backward()`

move.forward(player, 5);   // Move in facing direction
move.backward(player, 5);  // Move opposite facing direction

What It Does: Moves a component along its current angle direction. Uses Math.cos(angle) and Math.sin(angle) internally.

Why It's Useful: It simplifies movement in a specific direction. Perfect for driving games, top-down shooters, and any game with directional movement.

When to Use:

Driving games
Top-down shooters
Any time you need to move in the direction the component is facing

How It Works Internally:

// Simplified version
function forward(id, steps) {
    id.speedX = steps * Math.cos(id.angle);
    id.speedY = steps * Math.sin(id.angle);
}

Example:

const car = new Component(40, 20, "red", 400, 300, "rect");
car.changeAngle = true;
display.add(car);

function update(dt) {
    if (display.keys[38]) move.forward(car, 3);
    if (display.keys[40]) move.backward(car, 2);
    if (display.keys[37]) move.turnLeft(car, 0.05);
    if (display.keys[39]) move.turnRight(car, 0.05);
}

`move.turnLeft()` / `move.turnRight()`

move.turnLeft(car, 0.05);   // Rotate left
move.turnRight(car, 0.05);  // Rotate right

What It Does: Rotates a component by a given angle. Works with changeAngle = true (the default).

Why It's Useful: It simplifies rotation. Instead of obj.angle += 0.05, you get a readable function.

When to Use:

Driving games
Top-down shooters
Any time you need to rotate a component

`move.circle()`

move.circle(orbiter, 2);  // 2 degrees per frame

What It Does: Creates orbiting motion without trigonometry. It adds to the component's angle each frame, and the component's moveAngle() method converts that angle into movement.

Why It's Useful: It's a unique feature. Most engines require manual trigonometry for orbiting. Limn handles it with one line.

When to Use:

Orbiting enemies
Planetary systems
Circular patterns

How It Works Internally:

// Simplified version
function circle(id, speed) {
    id.physics = true;
    id.changeAngle = true;
    id.angle += speed * Math.PI / 180;
}

// And in the component's moveAngle():
this.x += this.speedX * Math.cos(this.angle);
this.y += this.speedY * Math.sin(this.angle) + this.gravitySpeed;

Example:

const orbiter = new Component(16, 16, "cyan", 400, 300, "rect");
orbiter.angularMovement = true;
orbiter.speedX = 80;
orbiter.speedY = 80;
display.add(orbiter);

function update(dt) {
    move.circle(orbiter, 2);  // Orbits automatically!
}

Note: Requires angularMovement = true and speedX / speedY to be set.

`move.pointTo()`

move.pointTo(turret, mouse.x, mouse.y);

What It Does: Rotates any component to face a target coordinate. Uses Math.atan2() internally and sets the component's angle property.

Why It's Useful: It removes a common barrier — trigonometry. Beginners can now build aiming mechanics without math anxiety.

When to Use:

Turrets
Enemies that track the player
Aiming mechanics
Any time you need an object to face a specific point

How It Works Internally:

// Simplified version
function pointTo(id, targetX, targetY) {
    const deltaX = targetX - id.x;
    const deltaY = targetY - id.y;
    id.angle = Math.atan2(deltaY, deltaX);
}

Example:

function update() {
    // Turret faces the mouse
    move.pointTo(turret, display.x, display.y);

    // Enemy faces the player
    move.pointTo(enemy, player.x, player.y);
}

📐 Boundaries

These functions keep components within defined boundaries.

`move.bound()`

move.bound(player);

What It Does: Keeps any component on screen with one line. It clamps the component's position so it can never go past any of the four canvas edges.

Why It's Useful: It's the most used function in almost every game. Every game needs boundaries. This replaces four if statements in every object, forever.

When to Use: Every game. Every component that moves. Every frame.

Example:

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

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

`move.boundTo()`

move.boundTo(player, 50, 750, 100, 500);

What It Does: Custom boundaries for any component. It clamps the component to specific pixel values on each side — or leaves a side open by passing false.

Why It's Useful: It enables arena games, room-based levels, and custom playfields. Sometimes you need boundaries that aren't the canvas edges.

When to Use:

Arena games
Room-based levels
Custom playfields
Any situation where you need different boundaries for different objects

Example:

// Keep player inside an arena
move.boundTo(player, 50, 750, 50, 550);

// Keep enemy in a specific room
move.boundTo(enemy, 200, 600, 200, 400);

// Leave top and bottom open (only clamp horizontally)
move.boundTo(player, 0, 800, false, false);

🌊 Smooth Movement (Glide)

These functions create smooth, easing-based movement.

`move.glideX()` / `move.glideY()` / `move.glideTo()`

move.glideX(coin, 1000, 500);        // Move X only
move.glideY(coin, 1000, 300);        // Move Y only
move.glideTo(coin, 1000, 500, 300);  // Move both

What It Does: Smooth, easing-based movement to a target point. Uses cubic ease-out for natural deceleration — fast at the start, slow at the end.

Why It's Useful: It saves you from writing lerp functions, animation loops, and timing management every time. It makes movement feel polished.

When to Use:

UI animations
Cutscenes
Enemy patrols
Smooth transitions
Any time you need polished movement

How It Works Internally:

// Simplified version of glideX()
function glideX(id, duration, x) {
    const startX = id.x;
    const startTime = performance.now();

    function step(currentTime) {
        const elapsed = currentTime - startTime;
        const progress = Math.min(1, elapsed / duration);
        const eased = 1 - Math.pow(1 - progress, 3); // Cubic ease-out

        id.x = startX + (x - startX) * eased;

        if (progress < 1) {
            requestAnimationFrame(step);
        }
    }
    requestAnimationFrame(step);
}

Example:

// Move a coin to a random position over 1 second
move.glideTo(coin, 1000, Math.random() * 700, Math.random() * 500);

// Move the player to a cutscene position
move.glideTo(player, 2000, 400, 300);

// Move UI element smoothly
move.glideTo(menu, 500, 400, 300);

⚡ Physics

These functions handle physics-based movement.

`move.accelerate()` / `move.decelerate()`

move.accelerate(player, 0.6, 0, 8, 0);
move.decelerate(player, 0.4, 0);

What It Does: Creates smooth, weighty movement with acceleration curves. accelerate() adds to speed and clamps to a maximum. decelerate() reduces speed toward zero without overshooting.

Why It's Useful: It enables realistic physics and vehicle-like motion. Games with weighty movement feel more polished and professional.

When to Use:

Vehicles
Platformer movement
Realistic motion
Any time you want smooth acceleration

How It Works Internally:

// Simplified version
function accelerate(id, accelX, accelY, maxX, maxY) {
    id.speedX += accelX;
    id.speedY += accelY;

    if (Math.abs(id.speedX) > maxX) {
        id.speedX = id.speedX > 0 ? maxX : -maxX;
    }
    if (Math.abs(id.speedY) > maxY) {
        id.speedY = id.speedY > 0 ? maxY : -maxY;
    }
}

function decelerate(id, decelX, decelY) {
    if (id.speedX > 0) {
        id.speedX -= decelX;
        if (id.speedX < 0) id.speedX = 0;
    } else if (id.speedX < 0) {
        id.speedX += decelX;
        if (id.speedX > 0) id.speedX = 0;
    }
    // Same for Y
}

Example:

function update(dt) {
    if (display.keys[68]) {
        move.accelerate(player, 0.6, 0, 8, 0);  // Accelerate right
    } else if (display.keys[65]) {
        move.accelerate(player, -0.6, 0, 8, 0); // Accelerate left
    } else {
        move.decelerate(player, 0.4, 0);        // Slow down
    }
    move.bound(player);
}

`move.project()`

move.project(bullet, 300, 45, 0.5);
move.project(arrow, 220, 28, 0.4, 420);

What It Does: Launches a component as a projectile with gravity and bounce. Converts angle to velocity components and handles the arc.

Parameters:

id — The component to launch
initialVelocity — Speed in pixels per second
angle — Launch angle in degrees (0° = right, 90° = up)
gravity — Added to vertical speed each frame
ground (optional) — Custom floor Y position

Why It's Useful: It handles all the physics of projectile motion — angle conversion, gravity, arc, and bouncing.

When to Use:

Arrows
Fireballs
Angry-birds style games
Any projectile with gravity

Example:

// Launch a fireball
move.project(fireball, 400, 35, 0.3);

// Launch an arrow with custom ground
move.project(arrow, 250, 30, 0.4, 400);

`move.hitObject()`

move.hitObject(player, floor);

What It Does: Handles platform-style collision with another component. Treats the top edge of otherid as a floor and applies bounce.

Why It's Useful: It's essential for platformers. It makes the component land on top of another component.

When to Use:

Platformer games
Landing on platforms
Ground collision

Example:

const player = new Component(36, 48, "cyan", 100, 0, "rect");
const platform = new Component(200, 20, "#555", 200, 300, "rect");
display.add(player);
display.add(platform);

player.physics = true;
player.gravity = 0.5;
player.bounce = 0.05;

function update() {
    move.hitObject(player, platform);  // Land on platform
    player.hitBottom();                // Also stop at canvas floor
}

✨ Particles

These functions create visual effects with particles.

`move.particles.*`

move.particles.explosion(ps, x, y, 30);
move.particles.sparkle(ps, x, y);
move.particles.blood(ps, x, y, 15);

What It Does: Six built-in particle presets with zero configuration. Each preset is a carefully tuned burst or emission of particles.

Why It's Useful: It saves you hours of particle system configuration. In other engines, setting up an explosion requires tweaking gravity, friction, alpha fade, scale, color, and speed parameters. Limn does it all for you.

The Presets:

Preset	What It Does	When to Use
`explosion(ps, x, y, intensity)`	Orange-red radial burst	Explosions, bombs, death
`smoke(ps, x, y)`	Single upward grey circle	Fire, exhaust, atmosphere
`sparkle(ps, x, y)`	Yellow radial burst	Coins, power-ups, magic
`rain(ps, x, y, intensity)`	Thin blue vertical rects	Weather effects
`blood(ps, x, y, amount)`	Red radial burst with gravity	Combat, hits
`magic(ps, x, y)`	Multicolour rotating rects	Spells, power-ups

Example:

// One line = instant explosion effect
move.particles.explosion(ps, enemy.x, enemy.y, 30);

// One line = coin collection sparkle
move.particles.sparkle(ps, coin.x, coin.y);

// One line = blood splatter
move.particles.blood(ps, player.x, player.y, 10);

🔊 Sound

These functions handle audio playback.

`move.sound.*`

move.sound.play("jump");
move.sound.playMusic("theme");
move.sound.stopMusic();
move.sound.setMasterVolume(0.8);
move.sound.mute();
move.sound.unmute();

What It Does: A thin wrapper around SoundManager that provides one-line audio control.

Why It's Useful: It simplifies audio management. No need to check if SoundManager exists — just call the function.

When to Use:

Playing sound effects
Background music
Volume control
Mute/unmute

Example:

function update() {
    if (display.keys[32]) {
        display.keys[32] = false;
        move.sound.play("shoot");
    }
    if (playerDied) {
        move.sound.stopMusic();
        move.sound.play("explode");
    }
}

🐛 Debugging

`move.dot()`

move.dot(id);

What It Does: Draws a dot at a component's position. Useful for debugging.

Why It's Useful: It helps visualize positions during development.

📊 Quick Reference

What You Want	Code
Keep on screen	`move.bound(player)`
Custom boundaries	`move.boundTo(player, 50, 750, 50, 550)`
Instant move	`move.teleport(player, 400, 300)`
Snap to edge	`move.position(healthBar, "top", 20)`
Smooth movement	`move.glideTo(coin, 1000, 500, 300)`
Realistic physics	`move.accelerate(player, 0.6, 0, 8, 0)`
Face target	`move.pointTo(turret, mouse.x, mouse.y)`
Orbit	`move.circle(orbiter, 2)`
Move forward	`move.forward(car, 3)`
Turn	`move.turnLeft(car, 0.05)`
Explosion	`move.particles.explosion(ps, x, y, 30)`
Sparkle	`move.particles.sparkle(ps, x, y)`
Play sound	`move.sound.play("jump")`
Play music	`move.sound.playMusic("theme")`
Mute	`move.sound.mute()`

💡 The Philosophy Behind `move`

Every function in move exists because I was tired of writing the same code over and over:

move.bound() — tired of edge detection
move.glideTo() — tired of lerp functions
move.pointTo() — tired of trigonometry
move.particles.* — tired of configuring particles

"Common outcomes should be functions." That's the philosophy that created the move utility.

🎯 The One-Line Summary

"The move utility turns complex movement mechanics into one-line commands — saving you hundreds of lines of boilerplate and making your game feel polished."

🔗 Resources

Resource	Link
10x Developer Guide	limn-engine-doc.vercel.app/10x.html
API Reference	limn-engine-doc.vercel.app/reference.html
GitHub Repository	github.com/terracodes004/limn-engine-doc

Draw your game into existence — one powerful function at a time. 🚀

[Boost]

Kehinde Owolabi — Sat, 11 Jul 2026 17:11:37 +0000

Kehinde Owolabi

Jun 17

Limn Engine — Complete API Reference

#webdev #programming #tutorial #javascript

9 min read

🔥 Top 20 Most Powerful Functions in Limn Engine

Kehinde Owolabi — Sat, 11 Jul 2026 03:43:36 +0000

🔥 Top 20 Most Powerful Functions in Limn Engine

The Functions That Actually Transform Your Game — Ranked by Performance, Control, and Capability

📖 Introduction

Every game engine has its superstars — the functions that you reach for again and again, the ones that save you hours of frustration, the ones that make complex mechanics feel simple. But not all functions are created equal. Some are just convenient. Some are genuinely powerful. And some are the difference between 4 FPS and 60 FPS.

I've been building Limn Engine from scratch for years. I've used it to create dungeon crawlers, space shooters, platformers, and open-world demos. Along the way, I've discovered which functions are actually worth your time — and which ones are just there to look pretty.

This isn't a list of "nice-to-haves." This is a list of functions that change how you build games.

🎯 The Criteria

Before we dive in, let's be real about what "powerful" actually means:

Criteria	Weight	Why It Matters
Performance Impact	40%	Does this function make your game faster?
Architectural Control	30%	Does it change how you structure your game?
Capability Unlocked	20%	Does it enable new genres or mechanics?
Time Saved	10%	Does it save you significant development time?

What This List Is NOT About:

Saving 2 lines of code
Being "convenient"
Looking cool

What This List IS About:

4 FPS → 60 FPS
Thousands of objects → One draw call
Single-screen games → Open worlds
Memory leaks → Clean memory management

📊 How to Read This List

Element	What It Means
Rating	A score out of 100 based on the criteria above
What It Does	A plain-English explanation of the function
Why It's Ranked Here	The honest reason it's at this position
When to Use	The best use case for this function
The Hard Truth	The brutal reality about this function

The List

#20 — `display.lgradient()` / `display.rgradient()`

Rating: 35/100

display.lgradient("top", "royalblue", "darkblue");
display.rgradient("#ffaa00", "#442200");

What It Does: Creates beautiful gradient backgrounds with one line.

Why It's #20: This is purely cosmetic. It doesn't improve performance. It doesn't enable new mechanics. It saves you from writing 5-6 lines of gradient setup code, but that's it. It's a nice-to-have, not a must-have.

When to Use: When you want a polished background without CSS. It's great for title screens, menu backgrounds, and atmospheric effects.

The Hard Truth: If this is the most powerful function you're using, you're not building complex games. This is the bottom of the list for a reason — it's visual polish, not game-changing power.

#19 — `display.backgroundColor()`

Rating: 40/100

display.backgroundColor("#0a0a10");

What It Does: Sets the canvas background with one line.

Why It's #19: It's used in every game. Every game needs a background. It replaces ctx.fillStyle = "color"; ctx.fillRect(0, 0, w, h); — that's two lines of code saved in every project. But that's all it does.

When to Use: Every game. Every frame. It's the easiest way to set a solid background color.

The Hard Truth: It's convenient, but it's trivial. Two lines of code saved is not "powerful" — it's just "nice." It's above gradients because it's used more often, but it's still near the bottom.

#18 — `move.teleport()`

Rating: 50/100

move.teleport(player, 400, 300);

What It Does: Instantly moves a component to any position.

Why It's #18: It's literally obj.x = x; obj.y = y; wrapped in a function. That's two lines of code saved. It's useful for respawns and checkpoints, but it's not a game-changer.

When to Use: Respawns, checkpoints, teleportation mechanics, and any time you need to instantly move an object.

The Hard Truth: If you need a function for two lines of code, your codebase has bigger problems. This is convenience, not power.

#17 — `move.position()`

Rating: 55/100

move.position(healthBar, "top", 20);

What It Does: Snaps UI to screen edges or center with one line.

Why It's #17: It saves you from doing manual centering calculations. That's it. It's a helper function for UI layout.

When to Use: UI layout — health bars, score displays, menus, and any on-screen text.

The Hard Truth: It's a helper function. Helpful, but not powerful. It saves you a few lines of code, but it doesn't unlock new mechanics.

#16 — `display.scale()`

Rating: 78/100

display.scale(1024, 768);

What It Does: Resizes the canvas at runtime.

Why It's #16: It enables responsive design. Your game can adapt to different screen sizes without restarting. This is essential for modern web games.

When to Use: Window resizing, full-screen transitions, responsive design, and any time you need to change the canvas size dynamically.

The Hard Truth: It only resizes the canvas. It doesn't scale your game objects. You still have to handle that yourself. It's a half-solution, but it's a necessary one.

#15 — `move.boundTo()`

Rating: 75/100

move.boundTo(player, 50, 750, 100, 500);

What It Does: Custom boundaries for any component.

Why It's #15: It's move.bound() with extra parameters. It enables arena games and room-based levels by giving you precise control over where objects can go.

When to Use: Arena games, room-based levels, custom playfields, and any situation where you need different boundaries for different objects.

The Hard Truth: This should be an overload of move.bound(), not a separate function. It's useful but not game-changing.

#14 — `component.hide()` / `component.show()`

Rating: 70/100

enemy.hide();   // Disappear
enemy.show();   // Reappear

What It Does: Temporary visibility control without destroying objects.

Why It's #14: It enables respawning enemies, collectibles, and UI transitions without recreating objects. This saves you from the overhead of destroying and recreating objects.

When to Use: Respawn systems, UI panels, menu transitions, and any time you need an object to temporarily disappear.

The Hard Truth: Hidden objects are still processed every frame. If you hide 100 enemies, they're still being updated. This is a band-aid, not a solution. Use it wisely.

#13 — `display.camera.shakeRotation()`

Rating: 78/100

display.camera.shakeRotation(0.08);

What It Does: Creates a dramatic screen-twist effect with one line.

Why It's #13: This is a unique feature that most engines don't have. It adds a level of polish that players notice. Combined with shake(), it creates impact that feels powerful.

When to Use: Boss hits, explosions, heavy impacts, and any time you want a dramatic visual effect.

The Hard Truth: It's a cool effect, but it's not essential. It adds polish, not functionality. It's above hide()/show() because it's unique to Limn, but it's still not a core function.

#12 — `move.pointTo()`

Rating: 78/100

move.pointTo(turret, mouse.x, mouse.y);

What It Does: Rotates any component to face a target coordinate without trigonometry.

Why It's #12: It removes a common barrier — trigonometry. Beginners can now build aiming mechanics without math anxiety. It's a great equalizer.

When to Use: Turrets, enemies that track the player, aiming mechanics, and any time you need an object to face a specific point.

The Hard Truth: It saves you one line — Math.atan2(). That's not a revolution. But for beginners, removing that barrier is significant.

#11 — `move.circle()`

Rating: 80/100

move.circle(orbiter, 2);

What It Does: Creates orbiting motion without trigonometry.

Why It's #11: It's a unique feature. Most engines require manual trigonometry for orbiting. Limn handles it with one line. It's a real time-saver.

When to Use: Orbiting enemies, planetary systems, circular patterns, and any time you need an object to orbit another.

The Hard Truth: It requires angularMovement = true. That's an extra step. And how often do you need orbiting? Not every game. It's cool but niche.

#10 — `move.glideTo()`

Rating: 84/100

move.glideTo(coin, 1000, 500, 300);

What It Does: Smooth, easing-based movement to any target point.

Why It's #10: It saves you from writing lerp functions, animation loops, and timing management every time. This is a significant time-saver.

When to Use: UI animations, cutscenes, enemy patrols, smooth transitions, and any time you need polished movement.

The Hard Truth: It's a one-off animation. It doesn't loop. You have to call it again. It's a time-saver, not a game-changer.

#9 — `move.accelerate()` / `move.decelerate()`

Rating: 82/100

move.accelerate(player, 0.6, 0, 8, 0);
move.decelerate(player, 0.4, 0);

What It Does: Creates smooth, weighty movement with acceleration curves.

Why It's #9: It enables realistic physics and vehicle-like motion. Games with weighty movement feel more polished and professional.

When to Use: Vehicles, platformer movement, realistic motion, and any time you want smooth acceleration.

The Hard Truth: Basic physics. Every engine has this. But it's still essential for polished games.

#8 — `move.bound()`

Rating: 88/100

move.bound(player);

What It Does: Keeps any component on screen with one line.

Why It's #8: It's the most used function in almost every game. Every game needs boundaries. This replaces four if statements in every object, forever.

When to Use: Every game. Every component that moves. Every frame.

The Hard Truth: It's four if statements. That's all it is. It's powerful because of frequency, not complexity. But frequency is power.

#7 — `move.particles.*`

Rating: 86/100

move.particles.explosion(ps, x, y, 30);

What It Does: Six built-in particle presets with zero configuration.

Why It's #7: It saves you hours of particle system configuration. In other engines, setting up an explosion requires tweaking gravity, friction, alpha fade, scale, color, and speed parameters. Limn does it all for you.

When to Use: Explosions, sparkles, blood, magic, smoke, rain — any visual effect you need.

The Hard Truth: Presets are opinionated. Advanced developers will write their own particles anyway. But for 90% of use cases, these are perfect.

#6 — `display.camera.follow()`

Rating: 94/100

display.camera.follow(player, true);

What It Does: Smooth or instant camera tracking.

Why It's #6: It unlocks a whole genre of games — platformers and exploration games. Without camera follow, you're stuck with single-screen games. This is essential.

When to Use: Platformers, open-world games, exploration games, and any game with a world larger than the screen.

The Hard Truth: It's a basic follow. No dead zones, no prediction, no look-ahead. Advanced games need more. But for most games, it's perfect.

#5 — `component.fixed()`

Rating: 92/100

healthBar.fixed();

What It Does: Locks UI to screen position regardless of camera movement.

Why It's #5: Without this function, UI elements would scroll with the world. This is essential for any game with a moving camera. It's the foundation of every HUD.

When to Use: Health bars, score displays, HUDs, menus — any UI element that should stay on screen.

The Hard Truth: You have to call it every frame. That's manual work. But it's a small price for a functioning HUD.

#4 — `display.camera.shake()`

Rating: 90/100

display.camera.shake(8, 8);

What It Does: Instant screen shake with automatic reset.

Why It's #4: It adds game feel — impacts, explosions, and hits feel powerful. Players notice this immediately. It's one of the most effective ways to improve game feel.

When to Use: Explosions, player hits, boss attacks, coin collection — any impactful event.

The Hard Truth: Basic shake. No pattern control, no decay control. But for 90% of use cases, it's perfect.

#3 — `component.destroy()`

Rating: 95/100

bullet.destroy();

What It Does: Explicit memory management. Removes objects from comm[] immediately.

Why It's #3: Without destroy(), your game slows down over time. With it, you can have hundreds of objects at 60fps. This is the difference between a game that works and a game that crashes.

When to Use: Bullets, defeated enemies, collected items, off-screen objects — anything that should be permanently removed.

The Hard Truth: You have to remember to call it. Forget, and your game slows down. It requires discipline.

#2 — `fake.add()`

Rating: 98/100

fake.add(tree);
fake.add(decoration);

What It Does: Caches static content on an offscreen canvas — thousands of objects become one draw call.

Why It's #2: This is the performance powerhouse of Limn Engine. Without it, large worlds are impossible. With it, you can have thousands of objects at 60fps. This is what makes Limn special.

When to Use: Tilemaps, backgrounds, static decorations, anything that doesn't move.

The Hard Truth: Only works with display.perform(). If you forget perform(), it doesn't work. But when it works, it's magic.

#1 — `display.perform()`

Rating: 100/100

display.perform();

What It Does: Activates the dual-renderer system — 4 FPS → 60 FPS.

Why It's #1: This is the most important function in Limn Engine. Without it, the engine is slow. With it, the engine is professional-grade. This single function is the difference between a toy and a tool.

When to Use: Every game. Before start(). Always.

The Hard Truth: You have to remember to call it before start(). Forget, and performance is terrible. One line of code determines whether your game runs at 4 FPS or 60 FPS. That's power.

📊 The Full Top 20 — Ranked

Rank	Function	Rating	Category
1	`display.perform()`	100	Display
2	`fake.add()`	98	Fake Canvas
3	`component.destroy()`	95	Component
4	`display.camera.follow()`	94	Camera
5	`component.fixed()`	92	Component
6	`display.camera.shake()`	90	Camera
7	`move.bound()`	88	move
8	`move.particles.*`	86	move
9	`move.glideTo()`	84	move
10	`move.accelerate()` / `decelerate()`	82	move
11	`move.circle()`	80	move
12	`move.pointTo()`	78	move
13	`display.camera.shakeRotation()`	78	Camera
14	`display.scale()`	78	Display
15	`move.boundTo()`	75	move
16	`component.hide()` / `show()`	70	Component
17	`move.teleport()`	50	move
18	`move.position()`	55	move
19	`display.backgroundColor()`	40	Display
20	`display.lgradient()` / `rgradient()`	35	Display

💡 The Philosophy Behind the Rankings

Rank Range	What It Means
90-100	Essential. Game-changing. Unlocks core functionality.
80-89	Extremely powerful. Saves significant time or enables key mechanics.
70-79	Very useful. Makes development easier.
60-69	Good utility. Nice to have.
50-59	Convenient but not essential.
Below 50	Niche or rarely used. Mostly syntactic sugar.

🎯 The One-Line Summary

"The most powerful functions are those that control architecture (perform(), add()), manage memory (destroy()), or enable core mechanics (follow(), crashWith()). The rest are just convenience."

🔗 Resources

Resource	Link
10x Developer Guide	limn-engine-doc.vercel.app/10x.html
API Reference	limn-engine-doc.vercel.app/reference.html
GitHub Repository	github.com/terracodes004/limn-engine-doc

Draw your game into existence — but know which tools are truly powerful. 🚀

Limn Engine — Level 4: 10x Developer Guide (Topics 37–48)

Kehinde Owolabi — Wed, 08 Jul 2026 16:46:58 +0000

__Limn Engine — Level 4: 10x Developer Guide (Topics 37–48)

A complete guide to mastering the Limn Engine's most advanced features

📖 Introduction

You've made it. You're ready to become a 10x Limn Developer.

This guide covers the engine's most powerful internals: the dual-canvas rendering pipeline, performance optimizations, angular movement, and professional workflows. By the end, you'll understand the engine at a level that most developers never reach.

Whether you're building an open-world RPG, a multiplayer game, or optimizing for mobile, this guide will give you the tools you need.

📚 Table of Contents

display.perform() — The 60fps Loop
The fake Canvas — Limn Engine's Secret Weapon
angularMovement & moveAngle — Angular Motion
deltaTime Movement — Frame-Rate Independence
clearMargin Optimisation
Viewport Culling with TCJSgameGameArea
Custom Particle Systems from Scratch
Extending the Engine with Prototypes
SoundManager Deep-Dive
AnimatedSprite Advanced Techniques
Performance Checklist for Shipping
Open-World Demo — Complete Walkthrough

display.perform() — The 60fps Loop

⏱️ 20 min | Level: 10x

display.perform() is the single most impactful call you can make in Limn Engine. It replaces the default setInterval loop with requestAnimationFrame, giving you accurate deltaTime and enabling the dual-canvas pipeline.

What Actually Happens

When you call display.perform(), the engine:

Patches Display.prototype.start — It overwrites the start method so that when you call display.start() immediately after, it launches the ani() function driven by requestAnimationFrame instead of the old setInterval loop.
Activates the dual-canvas pipeline — It creates a hidden fake Display instance and sets it up as an offscreen buffer.
Enables accurate deltaTime — The ani() function receives a high-precision DOMHighResTimeStamp from the browser and uses it to calculate display.fps and display.deltaTime from live frame timestamps.

Understanding the Code

const display = new Display();  // 1. Create the main game object

// 2. ⚡ CRITICAL: perform() MUST come before start()
display.perform();

// 3. start() now launches ani() → requestAnimationFrame instead of setInterval
display.start(800, 600);

// 4. Static content → fake canvas (only drawn once, then cached)
fake.add(new Component(800, 600, "#0d0d1a", 0, 0, "rect"));

// 5. Dynamic content → main display (redrawn every frame)
const player = new Component(40, 40, "cyan", 400, 300, "rect");
display.add(player);

// 6. update() now receives accurate deltaTime from live frame timestamps
function update(dt) {
    // dt is the time elapsed since the last frame in seconds
    // At 60fps, dt ≈ 0.0167; at 30fps, dt ≈ 0.033

    if (display.keys[68]) {
        // Move right at 250 pixels per second (frame-rate independent)
        player.speedX = 250 * dt;
    }
    if (display.keys[65]) {
        // Move left at 250 pixels per second
        player.speedX = -250 * dt;
    }
    else if (!display.keys[68]) {
        player.speedX = 0;
    }
}

Why requestAnimationFrame Matters

Aspect Without perform() With perform()
Loop setInterval at 20ms — ~50fps max requestAnimationFrame — 60–144fps
Sync Out of sync with screen paint Synced to monitor refresh rate
deltaTime From a separate interval — stale From live frame timestamp — accurate
Rendering Single canvas — all objects redrawn Dual canvas — static cached, dynamic on top
Fake canvas Not available Auto-initialised by perform()

💡 Pro Tip: Why requestAnimationFrame Matters

The browser's refresh rate syncs with the monitor's vertical blanking interval. requestAnimationFrame schedules your game loop to run exactly when the browser is about to paint the next frame, eliminating screen tearing and jitter. This is why perform() makes your game feel smoother even at the same framerate.

⚠️ Critical: TileMap Requires perform()

This is one of the most important things to understand about Limn Engine:

The TileMap system will NOT work unless display.perform() is called first!

The TileMap relies on the fake canvas to cache tiles. Without perform(), the fake canvas doesn't exist, and your tiles will never be drawn — even if you set up your level correctly.

// ❌ WRONG: TileMap won't work!
const display = new Display();
display.start(800, 600);  // No perform() — fake canvas doesn't exist
display.tileMap();        // TileMap has nowhere to render
display.tileFace.show();  // Nothing appears!

// ✅ CORRECT: TileMap works!
const display = new Display();
display.perform();        // Creates the fake canvas
display.start(800, 600);  // Now the fake canvas exists
display.tileMap();        // TileMap renders to fake canvas
display.tileFace.show();  // Tiles appear!

Always remember: display.perform() is the gateway to the TileMap system. Without it, your levels are invisible.

The Fake Canvas — Limn Engine's Secret Weapon

⏱️ 25 min | Level: 10x

The fake canvas is one of Limn Engine's most powerful and unique features. It's a hidden, offscreen canvas that acts as a cache for static content, created automatically when you call display.perform().

What Is the Fake Canvas?

Think of the fake canvas like a "screenshot" of your static world:

Without Fake Canvas With Fake Canvas
Every frame: draw 1,000 tiles individually Every frame: draw 1 cached image
1,000 draw calls per frame 1 draw call per frame
Slow Fast

That's a 99.9% reduction in draw calls!

How It Works — Step by Step

Step 1: Creation (Internal)

// This happens inside display.perform()
let fake = new Display();           // Create a second Display instance
fake.canvas.style.display = "none"; // Hide it — it's just an offscreen buffer

Step 2: Rendering to the Fake Canvas

When you add static content, it's drawn once into the offscreen buffer:

// 1. Set a background — this will be drawn behind everything
fake.bgComm = new Component(2000, 2000, "#0a0a10", 0, 0);
// .bgComm is a special property — it renders at the very bottom

// 2. Add a tilemap — this renders on top of the background
display.tileMap();
display.tileFace.show();  // Draws all tiles to the fake canvas

// 3. Add static decorations — these render on top of tiles
const tree = new Component(64, 64, null, 400, 300, "image");
tree.setImage("tree.png");
fake.add(tree);  // fake.add() sends objects to the offscreen buffer

Step 3: Displaying the Fake Canvas

Every frame, the main canvas draws the fake canvas as a single image:

// Inside ani() — the main game loop
// This ONE call draws EVERYTHING that was cached on the fake canvas
display.context.drawImage(fake.canvas, 0, 0);

Step 4: Dynamic Content on Top

The main canvas then draws dynamic content on top of the cached image:

// Dynamic objects — these move every frame, so they stay on the main canvas
display.add(player);   // Moves every frame — redrawn every frame
display.add(enemy);    // Moves every frame — redrawn every frame
display.add(bullet);   // Moves every frame — redrawn every frame

The display.once Flag — How Caching Works

The display.once flag controls when the fake canvas is redrawn:

// Inside ani() — the main game loop (simplified)
if (display.once) {
    // This block runs ONLY on the first 2 frames and after fake.refresh()

    // 1. Clear everything from the fake canvas
    fake.context.clearRect(0, 0, fake.canvas.width, fake.canvas.height);

    // 2. Redraw the background
    fake.context.drawImage(bgImage, 0, 0);

    // 3. Redraw all tiles
    // ... iterate through tileComm and draw each one

    // 4. Redraw all fake.add() objects
    // ... iterate through commp and draw each one

    // 5. Stop redrawing — the cache is now built
    display.once = false;
}

// After the cache is built, this ONE call draws everything
display.context.drawImage(fake.canvas, 0, 0);  // FAST!

When Does display.once Get Set?

Event What Happens
First 2 frames display.once = true — builds the cache
After frame 2 display.once = false — cache is built
fake.refresh() called display.once = true — rebuild cache
TileMap change fake.refresh() called automatically

💡 Pro Tip: Forcing a Refresh

// After changing static content
fake.bgComm.setImage("new_sky.png");
fake.refresh();  // Forces the fake canvas to redraw

// Or manually
display.once = true;  // Same effect — rebuild cache on next frame

The Correct Pattern: Resize, Don't Sync

This is the key insight for 10x developers:

Instead of syncing the fake canvas camera with the main camera every frame (which forces the fake canvas to move and defeats caching), resize the fake canvas to match your world size:

// ✅ CORRECT: Resize fake canvas to world size
// The fake canvas contains the ENTIRE world
fake.canvas.width = display.camera.worldWidth;   // 2000
fake.canvas.height = display.camera.worldHeight; // 2000

// Render static content once — it covers the whole world
display.tileMap();
display.tileFace.show(0);

// Now the fake canvas NEVER moves — it's a complete image of the world
function update(dt) {
    // The main camera moves, showing a window into the cached world
    display.camera.follow(player, true);
    // No fake.camera sync needed!
}

// ❌ WRONG: Syncing cameras defeats caching
// This forces the fake canvas to move every frame
fake.camera.x = display.camera.x;  // Every frame — defeats caching
fake.camera.y = display.camera.y;

Approach What Happens Performance
Syncing cameras Fake canvas moves every frame ❌ Poor — defeats caching
Resize fake canvas Fake canvas is world-sized, never moves ✅ Excellent — true caching

The fake.bgComm Special Property

fake.bgComm is a special property for background images:

// Set a background that renders behind EVERYTHING ELSE
fake.bgComm = new Component(2000, 2000, null, 0, 0, "image");
fake.bgComm.setImage("sky.png");

// The background is drawn first, then tiles, then decorations
// This creates a proper layer stack

Render Order — From Bottom to Top

1. fake.bgComm          ← Lowest layer (sky, distant scenery)
2. tileComm (layers)    ← Tilemaps (ground, walls)
3. commp (fake.add())   ← Static decorations (trees, rocks)
4. comm (display.add()) ← Dynamic content (player, enemies)
5. UI with .fixed()     ← Top layer (HUD, score)

🎯 Important: TileMap Layers Are Switchable, Not Stackable

This is a critical architectural decision in Limn Engine:

TileMap layers are SWITCHABLE, not STACKABLE. Only one layer is visible at a time.

// Layer 0: Ground
display.tileFace.show(0); // Only this layer is visible

// Layer 1: Decorations
display.tileFace.addMap(decorationMap);
display.tileFace.show(1); // This REPLACES layer 0, not adds to it

What this means:

Aspect Explanation
Stackable layers Layer 0 is bottom, Layer 1 is on top, both visible (❌ Not how Limn works)
Switchable layers Only one layer visible at a time (✅ How Limn works)
Use case Level switching, room transitions
Alternative for stacking Use fake.add() for decorations on top of tiles

Why this design?

· Performance: Only one layer is rendered, keeping draw calls minimal
· Simplicity: Level switching is just one function call
· Memory: Only one layer's data is stored in tileComm[] at a time

Common Mistakes — And How to Fix Them

Mistake Why It's Wrong Fix
Adding moving objects to fake They never update — they're cached Use display.add() for dynamic objects
Forgetting to refresh Changes don't appear on screen Call fake.refresh() after changes
Syncing cameras Defeats the caching benefit Resize fake canvas to world size instead
Not using perform() The fake canvas doesn't exist Always call display.perform() first
Treating layers as stackable Layers replace each other Use fake.add() for stacking decorations

💡 Pro Tip: Multi-Layer Worlds

The fake canvas supports multiple layers for complex worlds, but they are switchable:

// Layer 0: Grassland
display.tileFace.show(0);

// Layer 1: Dungeon
display.tileFace.addMap(dungeonMap);
display.tileFace.show(1);  // Switches to dungeon

// Layer 2: Snow
display.tileFace.addMap(snowMap);
display.tileFace.show(2);  // Switches to snow

All layers are composited onto the fake canvas as a single cached image. This means a 3-layer world with 500 tiles costs the same as a 1-layer world with 1 tile — one draw call per frame.

angularMovement & moveAngle — Angular Motion

⏱️ 20 min | Level: 10x

angularMovement is a powerful but often overlooked property. When set to true, the engine uses moveAngle() instead of move() — meaning the component moves in the direction of its current angle.

Understanding the Difference

Property Effect
move() Moves using speedX and speedY independently of angle
moveAngle() Moves using speedX and speedY relative to angle

How moveAngle() Works Internally

// What moveAngle() does internally (simplified)
// This is the actual code inside the Component class:

moveAngle() {
    // Gravity still applies
    this.gravitySpeed += this.gravity;

    // The key difference: speed is multiplied by cos(angle) and sin(angle)
    // This means movement is RELATIVE to the component's facing direction
    this.x += this.speedX * Math.cos(this.angle);
    this.y += this.speedY * Math.sin(this.angle) + this.gravitySpeed;
}

// Compare with move():
move() {
    if (this.physics) {
        this.gravitySpeed += this.gravity;
        this.x += this.speedX;
        this.y += this.speedY + this.gravitySpeed;
    } else {
        this.x += this.speedX;
        this.y += this.speedY;
    }
}

Enabling Angular Movement

// 1. Create the component
const orbiter = new Component(20, 20, "cyan", 400, 300, "rect");

// 2. Enable angular movement — this tells the engine to use moveAngle()
orbiter.angularMovement = true;

// 3. Add it to the display
display.add(orbiter);

// 4. In the update loop:
function update(dt) {
    // Rotate the orbiter (2 degrees per frame)
    orbiter.angle += 0.02;

    // Set speed — this will be applied RELATIVE to the angle
    // The orbiter will move in the direction it's facing
    orbiter.speedX = 2;
    orbiter.speedY = 2;
}

Why This Matters — Practical Use Cases

Use Case How angularMovement Helps
Orbiting objects Planets circle their star automatically
Bullets fired at angles Shoot in any direction without trig
Smooth turns Vehicles turn gradually
Circular motion Particles orbit without manual math

Example: Orbiting Enemy

const enemy = new Component(40, 40, "red", 200, 200, "rect");
enemy.angularMovement = true;
display.add(enemy);

function update(dt) {
    // 1. Rotate the enemy's facing direction
    enemy.angle += dt * 1.5;  // 1.5 radians per second

    // 2. Set speed — the enemy moves in the direction it's facing
    // The enemy will trace a circle because the angle is constantly changing
    enemy.speedX = 80;        // Orbital speed
    enemy.speedY = 80;
}

Example: 360-Degree Shooting

function shoot() {
    // 1. Create the bullet
    const bullet = new Component(8, 8, "yellow", player.x, player.y, "rect");

    // 2. Enable angular movement
    bullet.angularMovement = true;

    // 3. Set the bullet's facing direction to match the player
    bullet.angle = player.angle;

    // 4. Set speed — the bullet will move in the direction it's facing
    bullet.speedX = 300;
    bullet.speedY = 300;

    // 5. Add to display
    display.add(bullet);
}

function update(dt) {
    // Point the player toward the mouse
    move.pointTo(player, mouse.x, mouse.y);

    // Shoot on spacebar
    if (display.keys[32]) {
        shoot();
        display.keys[32] = false;  // Prevent holding
    }
}

💡 Pro Tip: Combining with move.pointTo()

move.pointTo() sets the angle to face a target. Combine it with angularMovement to create enemies that turn toward the player and move in that direction:

// This enemy turns toward the player and moves forward
move.pointTo(enemy, player.x, player.y);
enemy.speedX = 80;  // Moves toward player
enemy.speedY = 80;

Comparison: move() vs moveAngle()

// move() — movement independent of angle
// The component moves exactly where speedX and speedY point
component.move();    // x += speedX, y += speedY

// moveAngle() — movement DEPENDENT on angle
// The component moves in the direction of angle
component.moveAngle();  // x += speedX * cos(angle), y += speedY * sin(angle)

Common Pitfalls — And How to Fix Them

Issue Why It Happens Solution
Component doesn't rotate changeAngle is false Set changeAngle = true (it's true by default)
Movement seems wrong angularMovement is false Set angularMovement = true
Speed is too fast speedX and speedY values are too high Reduce them — try values between 1 and 5
Gravity doesn't work gravity is not set Set component.gravity = 0.5

deltaTime Movement — Frame-Rate Independence

⏱️ 20 min | Level: 10x

Using dt (deltaTime) as a multiplier on all speed values makes your game frame-rate independent — objects move N pixels per second, not N pixels per frame.

What Is Delta Time?

Delta time is the time elapsed since the last frame, measured in seconds. At 60fps, dt ≈ 0.0167; at 30fps, dt ≈ 0.033.

const PLAYER_SPEED = 280; // Pixels per second
const BULLET_SPEED = 600; // Pixels per second

function update(dt) {
    // Without dt: speed would be in pixels per frame
    // player.speedX = 4;  // 240px/s at 60fps, 120px/s at 30fps ❌

    // With dt: speed is in pixels per second
    // player.speedX = PLAYER_SPEED * dt;  // Always 280px/s ✅

    player.speedX = 0;
    player.speedY = 0;

    if (display.keys[87]) player.speedY = -PLAYER_SPEED * dt;  // Up
    if (display.keys[83]) player.speedY =  PLAYER_SPEED * dt;  // Down
    if (display.keys[65]) player.speedX = -PLAYER_SPEED * dt;  // Left
    if (display.keys[68]) player.speedX =  PLAYER_SPEED * dt;  // Right
}

Why This Matters — A Real Example

dt at 60fps dt at 30fps 280 * dt at 60fps 280 * dt at 30fps
~0.0167 ~0.033 ~4.67 px/frame ~9.24 px/frame

Both cases travel exactly 280 pixels per second! The game runs at the same speed regardless of frame rate.

💡 Pro Tip: dt Comes from Live FPS

In perform() mode, display.deltaTime is calculated as 1 / display.fps where display.fps is measured from live browser timestamps. This means dt is accurate even when the browser drops frames.

Using Delta Time for Timers

let spawnTimer = 0;

function update(dt) {
    // 1. Accumulate time
    spawnTimer += dt;

    // 2. Check if 2 seconds have passed
    if (spawnTimer >= 2.0) {
        // 3. Spawn an enemy
        spawnEnemy();

        // 4. Reset the timer
        spawnTimer = 0;
    }
}

💡 Pro Tip: Never Use Frame Counters

Never use frame counters (e.g., if (frame++ > 60)) for timing — they break on high-refresh monitors. Always use dt:

// ❌ WRONG: Frame counter — breaks on high-refresh monitors
// At 60fps: spawns every 1 second
// At 144fps: spawns every 0.42 seconds ❌
if (frame++ > 60) {
    spawnEnemy();
    frame = 0;
}

// ✅ CORRECT: Delta time — works at any framerate
// At 60fps: spawns every 1 second
// At 144fps: spawns every 1 second ✅
spawnTimer += dt;
if (spawnTimer >= 1.0) {
    spawnEnemy();
    spawnTimer = 0;
}

clearMargin Optimisation

⏱️ 15 min | Level: 10x

display.clearMargin tells the engine how large an area to clear with clearRect at the start of each frame.

What It Does — The Internals

// Inside display.clear()
clear() {
    // clearRect clears a rectangle area of the canvas
    // The area is defined by [x, y, width, height]
    // display.clearMargin defines the width and height to clear
    this.context.clearRect(0, 0, this.clearMargin[0], this.clearMargin[1]);
}

Understanding the Default

const display = new Display();
display.perform();
display.start(800, 600);

// Default after start() — conservatively large for rotation safety
// display.clearMargin = [800*800, 600*600] = [640000, 360000]
// This clears a 640,000 x 360,000 pixel area! 😱

// ✅ Optimised for a fixed-camera game (no rotation)
display.clearMargin = [800, 600];  // Clears exactly the visible area

// ✅ Optimised for a scrolling world
display.clearMargin = [2000, 2000]; // Match your world dimensions

💡 Pro Tip: When to Keep the Default

Keep the large default only if you use shakeRotation() heavily. Otherwise, reducing clearMargin to match your canvas or world size is a simple one-line optimisation.

Viewport Culling with TCJSgameGameArea

⏱️ 15 min | Level: 10x

In perform() mode, Limn Engine automatically skips drawing any Component that is outside the visible viewport using a collision check against TCJSgameGameArea.

How It Works — The Internals

// Inside ani() — the main game loop
// TCJSgameGameArea is a giant invisible Component that covers the canvas
// It's positioned at the camera's current origin

comm.forEach(component => {
    if (component.scene == display.scene) {
        component.x.move();

        // ONLY draw the component if it overlaps with TCJSgameGameArea
        // This means: only draw if the component is ON SCREEN
        if (TCJSgameGameArea.crashWith(component.x)) {
            try {
                component.x.update(display.context);
            } catch (e) {
                // pass
            }
        }
    }
});

What This Means for You

// Culling is automatic in perform() mode — nothing to configure!
// You can have hundreds of enemies spread across a large world:

const enemies = [];
for (let i = 0; i < 200; i++) {
    const e = new Component(32, 32, "red",
        Math.random() * 3000,    // Random X across the world
        Math.random() * 2000,    // Random Y across the world
        "rect");
    display.add(e);
    enemies.push(e);
}

// Only enemies on-screen are drawn — off-screen enemies cost zero draw calls
// This is why the fake canvas + culling = high performance!

💡 Pro Tip: Large Backgrounds on Fake Canvas

Very large Components (like a 2000px background rectangle) should go on the fake canvas via fake.add() rather than the main canvas, so they are cached rather than culled.

Custom Particle Systems from Scratch

⏱️ 25 min | Level: 10x

When the built-in ParticleSystem is not specialised enough, draw particles directly onto display.context for maximum performance and pixel-level control.

Why Custom Particles?

Adding hundreds of Particles to comm[] means the engine iterates that array each frame — a pool-based custom system that draws directly to the context skips the array overhead entirely.

Building a Custom Particle System — Step by Step

Step 1: Define the Particle Class

class TrailSystem {
    constructor() {
        // The pool stores all active particles
        // Each particle is a plain object (not a Component)
        this.pool = [];
    }

Step 2: Create the emit() Method

    emit(x, y, color = "#7fffb2") {
        // Add a new particle to the pool
        // Each particle has:
        // - position (x, y)
        // - visual properties (color, alpha, size)
        // - physics properties (vx, vy for velocity)
        this.pool.push({ 
            x: x,
            y: y,
            color: color,
            alpha: 1,                     // Start fully opaque
            size: 5,                      // Start at size 5
            vx: (Math.random() - 0.5) * 2, // Random horizontal velocity
            vy: -1                         // Slight upward velocity
        });
    }

Step 3: Create the update() Method

    update(ctx) {
        // 1. Iterate backwards through the pool
        // Why backwards? We're removing items — forward iteration skips elements
        for (let i = this.pool.length - 1; i >= 0; i--) {
            const p = this.pool[i];

            // 2. Update particle properties
            p.alpha -= 0.035;  // Fade out
            p.size -= 0.1;     // Shrink
            p.x += p.vx;       // Move horizontally
            p.y += p.vy;       // Move vertically

            // 3. Check if particle is dead
            if (p.alpha <= 0 || p.size <= 0) {
                this.pool.splice(i, 1);  // Remove from pool
                continue;                 // Skip drawing this particle
            }

            // 4. Draw the particle
            ctx.save();                   // Save context state
            ctx.globalAlpha = p.alpha;    // Apply transparency
            ctx.fillStyle = p.color;      // Set color
            ctx.beginPath();              // Start drawing a circle
            ctx.arc(p.x, p.y, p.size, 0, Math.PI * 2);  // Draw circle
            ctx.fill();                   // Fill the circle
            ctx.restore();                // Restore context state
        }
    }
}

Using the Custom Particle System

// 1. Create the particle system
const trail = new TrailSystem();

// 2. In the update loop:
function update(dt) {
    // 3. Emit a particle at the player's position
    trail.emit(player.x + 20, player.y + 20);

    // 4. Update all particles (draw them to the canvas)
    trail.update(display.context); // Draws into the same context Limn uses
}

💡 Pro Tip: Reverse Iteration for Splicing

Always iterate arrays in reverse when removing elements mid-loop — forward iteration + splice skips elements:

// ✅ CORRECT: Reverse iteration
// This correctly removes dead particles without skipping any
for (let i = particles.length - 1; i >= 0; i--) {
    if (particles[i].alpha <= 0) {
        particles.splice(i, 1);  // Removes the current element safely
    }
}

// ❌ WRONG: Forward iteration + splice skips elements
// After splice, the array shifts left, skipping the next element
for (let i = 0; i < particles.length; i++) {
    if (particles[i].alpha <= 0) {
        particles.splice(i, 1); // Skips the next element! ❌
    }
}

Extending the Engine with Prototypes

⏱️ 20 min | Level: 10x

Limn Engine is plain unminified JavaScript, which means you can add methods to any class via prototype extension.

What Is Prototype Extension?

// Every Component instance shares methods from Component.prototype
// You can add new methods that become available to ALL components

Component.prototype.myNewMethod = function() {
    // This method is now available on every Component
    console.log("This works on any component: " + this.x);
};

// Usage:
player.myNewMethod();  // Works!
enemy.myNewMethod();   // Works!

Why Prototype Extension?

Advantage Explanation
Clean Reads like a built-in engine method
Safe Survives engine version updates — you never touch epic.js
Separate Keeps your game logic in a separate file

Adding a Full Health System — Step by Step

Step 1: Set Up Health

// Add setHealth() to every Component
Component.prototype.setHealth = function(max) {
    this.hp = max;      // Current health
    this.maxHp = max;   // Maximum health
    this.invincible = 0; // Invincibility frames counter
};

Step 2: Add Damage Handling

// Add damage() to every Component
Component.prototype.damage = function(amount) {
    // 1. Check if invincible
    if (this.invincible > 0) return false;  // Immune!

    // 2. Apply damage
    this.hp = Math.max(0, this.hp - amount);

    // 3. Activate invincibility frames
    this.invincible = 30;  // 30 frames of invincibility

    // 4. Return true if dead
    return this.hp === 0;
};

Step 3: Update Invincibility

// Add tickInvincible() to every Component
Component.prototype.tickInvincible = function() {
    if (this.invincible > 0) {
        this.invincible--;  // Count down one frame
    }
};

Step 4: Draw Health Bar

// Add drawHealthBar() to every Component
Component.prototype.drawHealthBar = function(ctx) {
    // 1. Calculate health percentage (0 to 1)
    const pct = this.hp / this.maxHp;

    // 2. Draw background (dark grey)
    ctx.fillStyle = "#333";
    ctx.fillRect(this.x, this.y - 10, this.width, 5);

    // 3. Choose color based on health
    let color;
    if (pct > 0.5) color = "#00cc44";      // Green — healthy
    else if (pct > 0.25) color = "#ffaa00"; // Yellow — wounded
    else color = "#cc0000";                  // Red — critical

    // 4. Draw health fill
    ctx.fillStyle = color;
    ctx.fillRect(this.x, this.y - 10, this.width * pct, 5);
};

Using the Health System

// 1. Set up health for game objects
player.setHealth(100);
enemy.setHealth(40);

// 2. In the update loop:
function update() {
    // 3. Count down invincibility
    player.tickInvincible();
    enemy.tickInvincible();

    // 4. Check collision
    if (player.crashWith(enemy)) {
        // 5. Apply damage
        const died = enemy.damage(25);

        // 6. If enemy died, remove it
        if (died) {
            enemy.destroy();  // Remove from engine
        }
    }

    // 7. Draw health bars
    player.drawHealthBar(display.context);
    enemy.drawHealthBar(display.context);
}

💡 Pro Tip: Method Chaining via Prototype

You can also patch existing engine methods by saving the original and calling it inside a wrapper:

// 1. Save the original update method
const originalUpdate = Component.prototype.update;

// 2. Wrap it with custom logic
Component.prototype.update = function(ctx) {
    // Custom logic before
    if (this.hp <= 0) return;  // Don't draw dead objects

    // Call the original
    originalUpdate.call(this, ctx);

    // Custom logic after
    this.drawHealthBar(ctx);
};

SoundManager Deep-Dive

⏱️ 20 min | Level: 10x

SoundManager is Limn's full audio pipeline — named sounds, separate volume levels, and mute/unmute toggling.

Setup — Step by Step

// 1. Create the SoundManager instance
window.soundManager = new SoundManager();

// 2. Load sounds with names
soundManager.load("jump",     "audio/jump.wav");
soundManager.load("shoot",    "audio/shoot.wav", { volume: 0.7 });
soundManager.load("explode",  "audio/explode.wav");
soundManager.load("music_bg", "audio/background.mp3", { loop: true });

// 3. Set volume levels
soundManager.masterVolume = 0.8;  // Global volume (0–1)
soundManager.sfxVolume    = 1.0;  // Sound effects volume (0–1)
soundManager.musicVolume  = 0.5;  // Music volume (0–1)

// 4. Play background music
soundManager.playMusic("music_bg");

The move.sound Shorthand

// The move.sound object is a thin wrapper that checks if SoundManager exists
// This lets you use sound in gameplay without null reference errors

function update() {
    if (display.keys[32]) {
        display.keys[32] = false;
        move.sound.play("shoot");  // Plays "shoot" sound
    }
}

💡 Pro Tip: Preload Before display.start()

Create and load all sounds before calling display.start() so they preload during any loading screen or intro. This prevents mid-game stutter on the first play of an unloaded sound.

Volume Control

Property Purpose
masterVolume Global multiplier (0–1) applied to all sounds
sfxVolume Volume for sound effects (0–1)
musicVolume Volume for background music (0–1)

AnimatedSprite Advanced Techniques

⏱️ 20 min | Level: 10x

AnimatedSprite extends Sprite with a named animation clip system — each clip stores its own start frame, end frame, speed, and loop flag.

Setting Up an AnimatedSprite — Step by Step

// 1. Create the AnimatedSprite
// Parameters: (image path, frameWidth, frameHeight, x, y)
const hero = new AnimatedSprite("hero_sheet.png", 64, 64, 200, 300);

// 2. Add animation clips
// addAnimation(name, startFrame, endFrame, speed, loop)
hero.addAnimation("idle",   0,  3, 10, true);  // Loops forever
hero.addAnimation("run",    4, 11,  5, true);  // Loops forever
hero.addAnimation("jump",  12, 15,  4, false); // Plays once, stops
hero.addAnimation("attack",16, 19,  3, false); // Plays once, stops

// 3. Add to display
display.add(hero);

The playAnimation Guard — Why It's Important

// Inside AnimatedSprite.playAnimation():
playAnimation(name) {
    // ⚡ CRITICAL GUARD: This prevents resetting the animation if it's already playing
    if (this.currentAnim === name) return;

    // Only reset if the animation name changed
    this.currentAnim = name;
    const anim = this.animations[name];
    this.currentFrame = anim.start;
    this.frameSpeed = anim.speed;
    this.loop = anim.loop;
}

// This guard means you can call playAnimation() every frame safely:
function update() {
    // This is called 60 times per second
    // Without the guard, it would reset to frame 0 every frame!
    hero.playAnimation("run");   // OK — guard prevents reset
}

Using AnimatedSprite in a Game

let state = "idle";

function update() {
    // 1. Determine the current state
    const moving = display.keys[68] || display.keys[65];

    if (moving) {
        state = "run";
    } else {
        state = "idle";
    }

    if (display.keys[87]) {
        state = "jump";
    }

    if (display.keys[90]) {  // Z key for attack
        state = "attack";
    }

    // 2. Play the appropriate animation
    hero.playAnimation(state);

    // 3. Advance the frame counter (required every frame)
    hero.updateAnimation();
}

💡 Pro Tip: The paused Flag

When a non-looping animation finishes, it sets this.paused = true. Check hero.paused to detect completion and transition to the next state:

if (hero.paused && state === "attack") {
    hero.paused = false;   // Reset the flag
    state = "idle";        // Return to idle
}

Flip Direction Helpers

// Flip the sprite horizontally without changing the frames
hero.faceLeft();   // flips X — faces left
hero.faceRight();  // resets flip — faces right

Performance Checklist for Shipping

⏱️ 15 min | Level: 10x

Everything a 10x Limn developer verifies before shipping:

Check Why It Matters
✅ display.perform() before start() requestAnimationFrame loop, accurate deltaTime, fake canvas activated
✅ Static objects on fake, dynamic on display Static world cached in one bitmap — zero per-frame re-draw cost
✅ All speeds multiplied by dt Identical game speed at 30fps, 60fps, and 144fps
✅ display.clearMargin set to canvas or world size Avoid clearing a 640,000px area when 800px is enough
✅ ps.update() called every frame Dead particles removed — prevents unbounded memory growth
✅ destroy() on off-screen bullets and killed enemies Removes from comm[] — reduces loop iteration count
✅ hide() for temporarily invisible objects Skips draw call without destroying — use for respawning objects
✅ Scenes used for menus and game-over No create/destroy cost on state change — just flip display.scene
✅ All sounds preloaded before display.start() No mid-game stutter on first play of an unloaded sound
✅ Reverse iteration when splicing arrays mid-loop Forward iteration + splice skips elements — reverse is safe

💡 Pro Tip: The destroy() Method

destroy() permanently removes a Component from the engine's rendering pipeline by splicing it out of both comm[] and commp[] arrays and setting its update method to null. Use it for objects that will never be needed again — bullets that exit the screen, enemies that are killed, collected items.

Open-World Demo — Complete Walkthrough

⏱️ 30 min | Level: 10x

This is a complete open-world demo (test15.html) combining everything we've covered: perform(), layered tilemap on fake canvas, deltaTime movement, particle trail, and fixed HUD.

Full Code with Line-by-Line Explanation

// ── SECTION 1: SETUP ──

// 1. Create the display
const display = new Display();

// 2. ⚡ CRITICAL: Activate dual-canvas mode
// This MUST come before start() — it creates the fake canvas
display.perform();

// 3. Create the canvas and start the game loop
display.start(800, 600);

// 4. Set a dark background
display.backgroundColor("#0a0a0a");

// 5. Define the world size — 2000x2000 pixel world
display.camera.worldWidth = 2000;
display.camera.worldHeight = 2000;

// 6. Optimise clear area to match world size
display.clearMargin = [2000, 2000];

// 7. Set culling area to match world size
TCJSgameGameArea.width = 2000;
TCJSgameGameArea.height = 2000;

// ── SECTION 2: FAKE CANVAS — STATIC WORLD ──

// 8. Resize the fake canvas to match the world size
// This is the CORRECT approach — the fake canvas never moves
fake.mapWidth = 2000;
fake.mapHeight = 2000;
fake.canvas.width = 2000;
fake.canvas.height = 2000;

// 9. Define tile types
// Each tile is a Component with a size and colour
fake.tile = [
    // Tile 0: Empty (placeholder)
    new Component(64, 64, "#1a3a1a", 0, 0), // 1 = grass (green)
    new Component(64, 64, "#2244aa", 0, 0), // 2 = water (blue)
    new Component(64, 64, "#555",    0, 0), // 3 = stone (gray)
];

// 10. Define the level as a 2D array (4 rows × 30 columns)
// Each number refers to a tile type defined above
// 0 = empty, 1 = grass, 2 = water, 3 = stone
fake.map = [
    [1,1,1,2,2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],
    [1,1,1,2,2,1,1,1,1,3,3,3,1,1,1,1,1,1,1,3,3,3,1,1,1,1,1,1,1,1],
    [1,1,1,2,2,2,2,2,1,3,3,3,1,1,1,1,1,1,1,3,3,3,1,1,1,1,1,1,1,1],
    [1,1,1,1,1,2,2,2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],
];

// 11. Initialise and render the tilemap to the fake canvas
fake.tileMap();        // Create the TileMap object
fake.tileFace.show();  // Render all tiles to the fake canvas (cached!)

// ── SECTION 3: DISPLAY CANVAS — DYNAMIC OBJECTS ──

// 12. Create the player — a 36x36 blue square
const player = new Component(36, 36, "blue", 400, 200, "rect");
display.add(player);  // Add to main canvas (dynamic — redrawn every frame)

// 13. Create a HUD for displaying coordinates
const hud = new Tctxt("16px","Arial","white",12,20,
    "left",false,"alphabetic","rgba(0,0,0,0.6)",8,4);
hud.setText("WASD to move");
display.add(hud);

// 14. Create the particle system for the sparkle trail
const ps = new ParticleSystem(display);

// 15. Player speed in pixels per second (frame-rate independent)
const SPEED = 220;

// ── SECTION 4: GAME LOOP ──

function update(dt) {
    // 16. Update particles (required every frame)
    // This advances all particles, fades them, and removes dead ones
    ps.update();

    // 17. Player movement using deltaTime (frame-rate independent)
    // Reset speed first
    player.speedX = 0; player.speedY = 0;

    // WASD controls — each key applies speed in pixels per second
    if (display.keys[87]) player.speedY = -SPEED * dt;  // W = Up
    if (display.keys[83]) player.speedY =  SPEED * dt;  // S = Down
    if (display.keys[65]) player.speedX = -SPEED * dt;  // A = Left
    if (display.keys[68]) player.speedX =  SPEED * dt;  // D = Right

    // 18. Particle trail — sparkles follow the player
    // Emits a sparkle at the player's centre (x+18, y+18)
    move.particles.sparkle(ps, player.x+18, player.y+18);

    // 19. Camera follows the player smoothly
    // true = smooth interpolation (lerp), false = instant snap
    display.camera.follow(player, true);

    // ❌ No fake.camera sync needed!
    // The fake canvas is already the full world size (2000×2000),
    // so the main camera just shows the right portion.
    // This is the CORRECT approach — the fake canvas never moves.

    // 20. Update HUD with player coordinates
    hud.setText("X:" + Math.floor(player.x) + " Y:" + Math.floor(player.y));

    // 21. Lock HUD to screen (doesn't scroll with camera)
    // This is essential for UI elements
    hud.fixed();
}

Key Takeaways from This Demo

Concept How It's Implemented Why It Matters
perform() required Called before start() Without it, the tilemap would be invisible
Fake canvas resizing Set to world size (2000×2000) No camera sync needed — true caching
Tilemap 4×30 grid with 3 tile types Rendered once and cached — one draw call per frame
DeltaTime SPEED * dt Consistent movement at any framerate
Particle trail move.particles.sparkle() Simple visual feedback for player movement
Camera follow Smooth follow with true Professional, polished feel
Fixed HUD hud.fixed() UI stays visible when camera moves

💡 Pro Tip: Why perform() Is Critical

The TileMap system does not exist without display.perform(). The fake canvas is created by perform(), and the TileMap relies on the fake canvas to cache tiles. If you forget perform(), your tiles will never be drawn — even if your level data is correct. This is the #1 mistake new Limn developers make.

🔗 Resources

Resource	Link
Live Demo (test15)	limn-engine-doc.vercel.app/test15.html
GitHub Repository	://github.com
Direct Download (epic.js)	://github.com/blob/main/asset/epic.js
Complete API Reference	limn-engine-doc.vercel.app/reference.html
Discord Community	discord.gg/ZqnUtTQb8

✅ Conclusion

You've reached the top of the Limn Engine — the 10x Developer Level.

You now understand:

· ✅ The dual-canvas rendering pipeline and display.perform()
· ✅ How to correctly use the fake canvas (resize, don't sync)
· ✅ That TileMap requires perform() to work
· ✅ That TileMap layers are switchable, not stackable
· ✅ Angular movement with angularMovement and moveAngle
· ✅ Frame-rate independent movement with deltaTime
· ✅ Performance optimisations with clearMargin and culling
· ✅ Custom particle systems and engine extension
· ✅ Advanced audio with SoundManager
· ✅ Professional animation with AnimatedSprite

You are now a 10x Limn Developer. 🎉

If anything is still unclear, just ask — I'm happy to explain any part of the code in more detail! 🚀

🎮 Building a Top‑Down Action Game with the Limn Engine

Kehinde Owolabi — Mon, 06 Jul 2026 14:26:41 +0000

🎮 Building a Top‑Down Action Game with the Limn Engine

A complete, line‑by‑line tutorial

Live demo: limn-engine-doc.vercel.app/test11.html

📖 Introduction

Every great game developer remembers their first "real" project – the moment when code transformed from abstract syntax into something interactive, something alive on the screen. Yet for many beginners, that milestone remains frustratingly out of reach, buried under complex frameworks, opaque build tools, and thousands of lines of boilerplate.

The Limn Engine changes that. Designed from the ground up for accessibility and clarity, it strips away unnecessary complexity and lets you focus on what matters: building your game. With just a single JavaScript file and a few lines of code, you can create a fully functional 2D game that runs in any browser.

This tutorial will guide you through every line of test11.html – a complete top‑down action game built with the Limn Engine. You'll learn not just what the code does, but why it works that way. By the end, you'll have a solid understanding of:

Setting up the engine and game world
Designing tile‑based levels
Implementing player movement, collisions, and AI
Adding visual effects, UI, and game state management
Using the engine's powerful features like the camera system, particles, and off‑screen rendering

Whether you're a complete beginner taking your first steps or an experienced developer looking for a refreshingly simple tool, this guide will give you the confidence to build your own games with the Limn Engine.

Let's begin.

📁 1. Project Setup & HTML Structure

<!doctype html>
<html>
  <head>
    <!-- Include the Limn Engine -->
    <script src="epic.js"></script>
  </head>
  <body>
  <script>
    // All game code goes here

What this does:

<!doctype html> – Declares this as an HTML5 document.
<html> – The root element of the page.
<head> – Contains meta‑information about the page.
<script src="epic.js"> – Loads the entire Limn Engine into your page. This gives you access to all the classes like Display, Component, Tctxt, ParticleSystem, etc.
<body> – The visible part of the webpage.
<script> – This is where we write our game code.

🚀 2. Engine Initialization

// Create the main game display and start it
const display = new Display();
display.perform();
display.start(800, 600);

What this does:

new Display() – Creates the main game window object – your game's "screen".
display.perform() – A special setup function that prepares the engine to use a more advanced rendering loop.
display.start(800, 600) – Actually creates the <canvas> element on your webpage and sets its size to 800×600 pixels. The game loop starts running immediately.

// Set up background image for the fake canvas
fake.bgComm = new Component(2000,2000, "#1a1a2e", 0 ,0);
fake.bgComm.setImage("limn-doc/img/alien.png");

What this does:

fake.bgComm – The fake object is an off‑screen canvas (a hidden canvas used for rendering static things). .bgComm is a special property for a background component.
new Component(2000,2000, "#1a1a2e", 0, 0) – Creates a 2000×2000 pixel component at position (0,0). The color "#1a1a2e" is a dark blue‑gray.
setImage("limn‑doc/img/alien.png") – Changes the component from a coloured rectangle to an image. This loads and displays the alien image as the background.

// Set the game area size (for culling/performance)
TCJSgameGameArea.width = 1600;
TCJSgameGameArea.height = 1200;

// Set the camera's world boundaries
display.camera.worldWidth = 1600;
display.camera.worldHeight = 1200;

What this does:

TCJSgameGameArea.width/height – Sets the size of the "game world". The engine uses this to decide what to draw (culling). If something is outside this area, it might not be rendered, which saves performance.
display.camera.worldWidth/Height – Tells the camera how big the entire game world is. The camera will never scroll beyond these bounds, keeping the player within the world.

// Create the particle system
const particles = new ParticleSystem(display);

What this does:

new ParticleSystem(display) – Creates a new particle manager linked to our main display. We'll use this to create cool effects like explosions and sparkles.

🗺️ 3. Creating the Level (TileMap)

// Define the level layout as a 2D array (10 rows x 10 columns)
fake.map = [
    [1,1,1,1,1,1,1,1,1,1], // Row 0
    [1,0,0,0,0,0,0,0,0,1], // Row 1
    [1,0,2,0,0,0,0,2,0,1], // Row 2
    [1,0,0,1,1,0,0,0,0,1], // Row 3
    [1,0,0,0,0,0,0,0,0,1], // Row 4
    [1,0,0,0,0,1,1,0,0,1], // Row 5
    [1,0,2,0,0,0,0,2,0,1], // Row 6
    [1,0,0,0,0,0,0,0,0,1], // Row 7
    [1,0,0,0,0,0,0,0,0,1], // Row 8
    [1,1,1,1,1,1,1,1,1,1]  // Row 9
];

What this does:

This is a 10×10 grid. Each number represents a tile type:
- 0 – empty space (floor)
- 1 – wall
- 2 – coin
This array is the blueprint for your level. The walls form a border and some interior structures, and there are coins placed in the corridors.

// Define tile size and create tile components
const tileW = 40;
const tileH = 40;

fake.tile = [
    new Component(tileW, tileH, "#654321", 0, 0, "rect"), // Index 0: Wall tile
    new Component(25, 25, "gold", 0, 0, "rect")          // Index 1: Coin tile
];

What this does:

tileW and tileH – Set the size of each tile to 40×40 pixels. Since our world is 1600×1200, we have exactly 40 tiles across and 30 tiles down.
fake.tile – This array holds the visual representation of each tile type.
- fake.tile[0] (index 0) is a brown rectangle (#654321) – our wall.
- fake.tile[1] (index 1) is a small gold rectangle – our coin.
Important: The engine automatically adds an empty placeholder at index 0, so our actual tiles start at index 1. This is why we map:
- Tile ID 1 → fake.tile[1] (wall)
- Tile ID 2 → fake.tile[2] (coin)

// Configure and render the tilemap
fake.mapWidth = 1600;
fake.mapHeight = 1200;
fake.canvas.width = 1600;
fake.canvas.height = 1200;
fake.tileMap();
const tilemap = fake.tileFace;
fake.tileFace.show();

What this does:

fake.mapWidth/Height – Set the size of the tilemap world.
fake.canvas.width/Height – Resize the off‑screen canvas to match the world size.
fake.tileMap() – This function reads fake.map and fake.tile and creates the internal tilemap object.
const tilemap = fake.tileFace – We store a reference to the tilemap so we can use it later for collision detection and coin collection.
fake.tileFace.show() – This renders all the tiles onto the off‑screen fake canvas. It calculates the position of each tile based on its row/column and draws it. This happens only once, which is very efficient!

🎮 4. Creating Game Objects

Creating the Player

const player = new Component(40, 40, "#5b8cff", 700, 500, "rect");
display.add(player);

What this does:

new Component(40, 40, "#5b8cff", 700, 500, "rect") – Creates a new component (game object).
- 40, 40 – width and height in pixels.
- "#5b8cff" – the colour (bright blue).
- 700, 500 – starting X and Y position.
- "rect" – the type is a rectangle.
display.add(player) – Adds the player to the main display, so it will be drawn and updated every frame.

Creating Enemies

let enemies = [];
for (let i = 0; i < 4; i++) {
    const enemy = new Component(35, 35, "#ff6b6b", 
        Math.random() * 1400 + 100, 
        Math.random() * 1000 + 100, "rect");
    enemy.speed = 60;
    display.add(enemy);
    enemies.push(enemy);
}

What this does:

let enemies = [] – Creates an empty array to store all our enemy objects.
for (let i = 0; i < 4; i++) – Loops 4 times to create 4 enemies.
new Component(35, 35, "#ff6b6b", ..., ..., "rect") – Creates a 35×35 pixel red enemy.
- Math.random() * 1400 + 100 – random X position between 100 and 1500.
- Math.random() * 1000 + 100 – random Y position between 100 and 1100.
enemy.speed = 60 – Adds a custom speed property to the enemy. The engine doesn't use this automatically; we'll use it in our update function.
display.add(enemy) – Adds the enemy to the display.
enemies.push(enemy) – Stores the enemy in our array so we can update all of them easily.

Creating the UI (Health Bar & Score)

// Health bar background
const healthBarBg = new Component(220, 25, "#440000", 20, 50, "rect");
const healthBarFill = new Component(200, 20, "#00ff44", 30, 52, "rect");
display.add(healthBarBg);
display.add(healthBarFill);

// Score text with styling
const scoreText = new Tctxt("24px", "Arial", "#ffffff", 20, 100, 
    "left", false, "hanging", "rgba(0,0,0,0.5)", 10, 5);
scoreText.setText("Score: 0");
display.add(scoreText);

What this does:

Health Bar Background (healthBarBg):
- 220, 25 – 220px wide, 25px tall.
- "#440000" – dark red.
- 20, 50 – position at (20, 50) from the top‑left corner of the screen.
- This creates the "container" for the health bar.
Health Bar Fill (healthBarFill):
- 200, 20 – slightly smaller to fit inside the background.
- "#00ff44" – bright green.
- 30, 52 – positioned slightly inside the background bar.
- This bar will change width to represent health.
Score Text (scoreText):
- new Tctxt(...) – Tctxt is a special text component with more features.
- "24px", "Arial", "#ffffff" – font size, family, colour.
- 20, 100 – position.
- "left" – alignment.
- false – no stroke/outline.
- "hanging" – text baseline.
- "rgba(0,0,0,0.5)" – semi‑transparent black background.
- 10, 5 – padding around the text.
- scoreText.setText("Score: 0") – sets the initial text.
- display.add(scoreText) – adds it to the display.

🎯 5. Game State & Helper Functions

let score = 0;
let health = 100;
let invincibleTimer = 0;
let gameActive = true;

What this does:

score – tracks the player's points.
health – starts at 100. When it reaches 0, the game is over.
invincibleTimer – counts down to make the player briefly invincible after being hit.
gameActive – a boolean that stops the game logic when false.

function applyKnockback(target, fromX, fromY, strength = 150) {
    const angle = Math.atan2(target.y - fromY, target.x - fromX);
    target.speedX = Math.cos(angle) * strength;
    target.speedY = Math.sin(angle) * strength;
    target.physics = true;
    setTimeout(() => {
        target.speedX = 0;
        target.speedY = 0;
        target.physics = false;
    }, 200);
}

What this does:

This function is called when the player is hit.
Math.atan2(target.y - fromY, target.x - fromX) – calculates the angle from the enemy to the player.
target.speedX/Y = Math.cos/Sin(angle) * strength – sets the player's speed in the direction away from the enemy (knockback).
target.physics = true – enables physics for the player so the speed will actually move them.
setTimeout(...) – after 200 milliseconds, stops the player's movement by setting speed back to 0 and disabling physics.

🔄 6. The Main Game Loop (`update` function)

This function runs every frame (≈60 times per second). It's the heart of your game.

📌 Section 1 – Initial Checks

function update(dt) {
    if (!gameActive) return;

What this does:

function update(dt) – the engine calls this every frame and passes dt (delta time in seconds). Using dt makes movement consistent regardless of framerate.
if (!gameActive) return – if the game is over, it exits immediately, freezing all game logic.

    // Make camera follow the player
    display.camera.follow(player, true);

What this does:

Centers the camera on the player with smooth (interpolated) movement.

    // Keep UI elements fixed on screen
    healthBarBg.fixed();
    healthBarFill.fixed();
    scoreText.fixed();

What this does:

.fixed() – a special method for UI components. Normally components move with the camera; .fixed() pins them to the screen so they stay in the corner even when the camera moves.

    // Update particle effects
    particles.update();

What this does:

Updates all particles (moves them, fades them, removes dead ones). Must be called every frame.

📌 Section 2 – Player Invincibility

    if (invincibleTimer > 0) {
        invincibleTimer -= dt;
        player.alpha = 0.5;  // Make player semi-transparent (blink)
    } else {
        player.alpha = 1;    // Fully opaque
    }

What this does:

Counts down invincibleTimer using dt.
player.alpha = 0.5 – makes the player 50% transparent (blink effect). When timer reaches 0, the player becomes fully opaque.

📌 Section 3 – Player Movement

    // Read keyboard input
    let mx = 0, my = 0;
    if (display.keys[37]) mx = -1; // Left arrow
    if (display.keys[39]) mx = 1;  // Right arrow
    if (display.keys[38]) my = -1; // Up arrow
    if (display.keys[40]) my = 1;  // Down arrow

What this does:

display.keys – an array where the engine stores which keys are currently pressed (keycodes 37‑40 for arrow keys).
If a key is pressed, we set mx or my to 1 or -1 (direction).

    // Normalize diagonal movement
    if (mx !== 0 && my !== 0) {
        mx *= 0.707;
        my *= 0.707;
    }

What this does:

Prevents faster diagonal movement by multiplying both components by 0.707 (≈1/√2). This keeps the movement vector length at 1, so the player moves at the same speed in all directions.

    // Apply movement
    player.x += mx * 200 * dt;
    player.y += my * 200 * dt;

What this does:

Moves the player by mx (or my) times speed (200 px/s) times dt. This makes movement framerate‑independent.

📌 Section 4 – Wall Collision

    if (tilemap.crashWith(player, 1)) {
        if (mx > 0) player.x -= 10;
        if (mx < 0) player.x += 10;
        if (my > 0) player.y -= 10;
        if (my < 0) player.y += 10;
    }

What this does:

tilemap.crashWith(player, 1) – checks if the player collides with any tile that has ID 1 (walls).
If collision occurs, we "push" the player back by 10 pixels in the opposite direction of movement – a simple way to prevent walking through walls.

📌 Section 5 – Coin Collection

    const coins = tilemap.tiles(2);
    for (let coin of coins) {
        if (player.crashWith(coin)) {
            tilemap.remove(coin.tx, coin.ty);
            score += 10;
            scoreText.setText("Score: " + score);
            move.particles.sparkle(particles, coin.x + coin.width/2, coin.y + coin.height/2);
            display.camera.shake(2, 2);
        }
    }

What this does:

tilemap.tiles(2) – gets all tile objects with ID 2 (coins).
Loops through all coins, checks overlap with player.
tilemap.remove(coin.tx, coin.ty) – removes the coin.
score += 10 – adds 10 points.
scoreText.setText(...) – updates the display.
move.particles.sparkle(...) – creates a sparkle effect at the coin's center.
display.camera.shake(2, 2) – shakes the camera slightly.

📌 Section 6 – Enemy AI & Collisions

    for (let i = 0; i < enemies.length; i++) {
        const enemy = enemies[i];

What this does:

Uses a standard for loop (not for...of) because we may need to remove enemies from the array while iterating.

        // Enemy chases player using normalized direction
        let dx = player.x - enemy.x;
        let dy = player.y - enemy.y;
        const distance = Math.sqrt(dx * dx + dy * dy);

        if (distance > 5) {
            enemy.x += (dx / distance) * enemy.speed * dt;
            enemy.y += (dy / distance) * enemy.speed * dt;
        }

What this does:

dx and dy – distance vector from enemy to player.
distance – straight‑line distance (Pythagoras).
The if (distance > 5) check prevents jitter when the enemy is already on top of the player.
(dx / distance) and (dy / distance) – normalised direction vector (length = 1). Multiplying by enemy.speed * dt gives consistent speed in any direction – this solves the "diagonal speed boost" problem.

        // Enemy hits player (and player is not invincible)
        if (player.crashWith(enemy) && invincibleTimer <= 0) {
            health -= 15;
            const healthPercent = Math.max(0, health / 100);
            healthBarFill.width = 200 * healthPercent;

            applyKnockback(player, enemy.x, enemy.y, 200);
            display.camera.shake(6, 6);
            move.particles.blood(particles, player.x, player.y, 10);
            invincibleTimer = 1.0;

            if (health <= 0) {
                gameActive = false;
                const gameOverText = new Tctxt("48px", "Arial", "#ff0000", 
                    400 + display.camera.x, 300 + display.camera.y, "center");
                gameOverText.setText("GAME OVER - Score: " + score);
                display.add(gameOverText);
            }
        }

What this does:

If player touches an enemy and is not invincible:
- health -= 15 – reduces health.
- healthPercent – health as a decimal (0.0‑1.0).
- healthBarFill.width = 200 * healthPercent – shrinks the green fill.
- applyKnockback(...) – pushes player away.
- display.camera.shake(6, 6) – bigger shake.
- move.particles.blood(...) – blood particle effect.
- invincibleTimer = 1.0 – 1 second of invincibility.
- If health ≤ 0:
- gameActive = false – stops the loop.
- Creates a new Tctxt for the game‑over message, centered on screen, and adds it.

        // Click to defeat enemy
        if (mouse.down && enemy.clicked()) {
            move.particles.explosion(particles, enemy.x, enemy.y, 20);
            score += 50;
            scoreText.setText("Score: " + score);
            display.camera.shake(4, 4);
            enemy.hide();
            enemies.splice(i, 1);
            i--;
        }

What this does:

mouse.down – is the mouse button pressed?
enemy.clicked() – checks if the click occurred inside the enemy's rectangle.
move.particles.explosion(...) – creates an explosion effect.
score += 50 – bonus points.
scoreText.setText(...) – updates score.
display.camera.shake(4, 4) – moderate shake.
enemy.hide() – makes the enemy disappear (sets update to null).
enemies.splice(i, 1) – removes the enemy from the array.
i-- – adjusts the loop counter so the next enemy is processed correctly.

📌 Section 7 – Player Boundaries

    // Keep player inside world boundaries
    player.x = Math.max(0, Math.min(1560, player.x));
    player.y = Math.max(0, Math.min(1160, player.y));
}

What this does:

Clamps the player's X position between 0 and 1560 (world width minus player width).
Clamps Y between 0 and 1160 (world height minus player height).
This ensures the player never leaves the visible world.

✅ Conclusion

You've now built a complete game using the Limn Engine! You've learned how to:

Set up the engine and a game world
Create tile‑based levels
Add player movement with keyboard controls
Implement wall collisions
Add coin collection with particle effects
Create enemies with AI that chase the player
Manage player health and invincibility
Build a UI with health bars and score text
Handle game‑over conditions
Use camera shake for game feel

The Limn Engine makes all of this possible with clean, readable code. Happy game development! 🎮
📦 Full Code: test11.html

Here's the complete, ready-to-run code for the game we just built. You can copy this directly into an HTML file and run it in your browser.

<!doctype html>
<html>
  <head>
    <script src="epic.js"></script>
  </head>
  <body>
  <script>
    const display = new Display();
display.perform();
display.start(800, 600);
//display.backgroundColor("lightblue")
fake.bgComm = new Component(2000,2000, "#1a1a2e", 0 ,0)
fake.bgComm.setImage("limn-doc/img/alien.png")
TCJSgameGameArea.width = 1600
TCJSgameGameArea.height = 1200
display.camera.worldWidth = 1600;
display.camera.worldHeight = 1200;
// display.camera.setZoom(0.75,0.75)
// display.camera.x-=100
const particles = new ParticleSystem(display);

// ===== EVENT BUS =====
const EventBus = {
    listeners: {},
    on(event, callback) {
        if (!this.listeners[event]) this.listeners[event] = [];
        this.listeners[event].push(callback);
    },
    emit(event, data) {
        if (this.listeners[event]) {
            this.listeners[event].forEach(cb => cb(data));
        }
    }
};

// ===== PLAYER =====
const player = new Component(40, 40, "#5b8cff", 700, 500, "rect");
display.add(player);

// ===== SIMPLE LEVEL (10x10 grid, no procedural generation to avoid bugs) =====
fake.map = [
    [1,1,1,1,1,1,1,1,1,1],
    [1,0,0,0,0,0,0,0,0,1],
    [1,0,2,0,0,0,0,2,0,1],
    [1,0,0,1,1,0,0,0,0,1],
    [1,0,0,0,0,0,0,0,0,1],
    [1,0,0,0,0,1,1,0,0,1],
    [1,0,2,0,0,0,0,2,0,1],
    [1,0,0,0,0,0,0,0,0,1],
    [1,0,0,0,0,0,0,0,0,1],
    [1,1,1,1,1,1,1,1,1,1]
];

const tileSize = 80; // 800/10 = 80, 600/10 = 60 but we need square
// Actually for 1600x1200 world, tiles should be 40x40
 tileW = 40;
tileH = 40;

fake.tile = [new Component(tileW, tileH, "#654321", 0, 0, "rect"),new Component(25, 25, "gold", 0, 0, "rect")
]
fake.mapWidth =1600
fake.mapHeight = 1200
fake.canvas.width = 1600
fake.canvas.height = 1200
fake.tileMap()
const tilemap = fake.tileFace
fake.tileFace.show();

// ===== ENEMIES =====
let enemies = [];
for (let i = 0; i < 4; i++) {
    const enemy = new Component(35, 35, "#ff6b6b", 
        Math.random() * 1400 + 100, 
        Math.random() * 1000 + 100, "rect");
    enemy.speed = 60;
    display.add(enemy);
    enemies.push(enemy);
}

// ===== UI =====
const healthBarBg = new Component(220, 25, "#440000", 20, 50, "rect");
const healthBarFill = new Component(200, 20, "#00ff44", 30, 52, "rect");
display.add(healthBarBg);
display.add(healthBarFill);

const scoreText = new Tctxt("24px", "Arial", "#ffffff", 20, 100, "left", false, "hanging", "rgba(0,0,0,0.5)", 10, 5);
scoreText.setText("Score: 0");
display.add(scoreText);
let hhh = [healthBarBg,healthBarFill, scoreText]
// ===== GAME STATE =====
let score = 0;
let health = 100;
let invincibleTimer = 0;
let gameActive = true;

// ===== CUSTOM KNOCKBACK =====
function applyKnockback(target, fromX, fromY, strength = 150) {
    const angle = Math.atan2(target.y - fromY, target.x - fromX);
    target.speedX = Math.cos(angle) * strength;
    target.speedY = Math.sin(angle) * strength;
    target.physics = true;
    setTimeout(() => {
        target.speedX = 0;
        target.speedY = 0;
        target.physics = false;
    }, 200);
}
// ===== UPDATE FUNCTION =====
function update(dt) {
    if (!gameActive) return;
    display.camera.follow(player,true);
    healthBarBg.fixed()
    healthBarFill.fixed()
    scoreText.fixed()
    particles.update();

    // Invincibility frames
    if (invincibleTimer > 0) {
        invincibleTimer -= dt;
        player.alpha = 0.5;
    } else {
        player.alpha = 1;
    }

    // Player movement
    let mx = 0, my = 0;
    if (display.keys[37]) mx = -1;
    if (display.keys[39]) mx = 1;
    if (display.keys[38]) my = -1;
    if (display.keys[40]) my = 1;

    if (mx !== 0 && my !== 0) {
        mx *= 0.707;
        my *= 0.707;
    }

    player.x += mx * 200 * dt;
    player.y += my * 200 * dt;

    // Wall collision
    if (tilemap.crashWith(player, 1)) {
        if (mx > 0) player.x -= 10;
        if (mx < 0) player.x += 10;
        if (my > 0) player.y -= 10;
        if (my < 0) player.y += 10;
    }

    // Coin collection
    const coins = tilemap.tiles(2);
    for (let coin of coins) {
        if (player.crashWith(coin)) {
            tilemap.remove(coin.tx, coin.ty);
            //tilemap.show()
            //fake.refresh()
            score += 10;
            scoreText.setText("Score: " + score);
            move.particles.sparkle(particles, coin.x + coin.width/2, coin.y + coin.height/2);
            display.camera.shake(2, 2);
        }
    }

    // Enemy AI
    for (let i = 0; i < enemies.length; i++) {
        const enemy = enemies[i];

        // Chase player
        if (enemy.x < player.x) enemy.x += enemy.speed * dt;
        if (enemy.x > player.x) enemy.x -= enemy.speed * dt;
        if (enemy.y < player.y) enemy.y += enemy.speed * dt;
        if (enemy.y > player.y) enemy.y -= enemy.speed * dt;

        // Enemy collision with player
        if (player.crashWith(enemy) && invincibleTimer <= 0) {
            health -= 15;
            const healthPercent = Math.max(0, health / 100);
            healthBarFill.width = 200 * healthPercent;

            applyKnockback(player, enemy.x, enemy.y, 200);
            display.camera.shake(6, 6);
            move.particles.blood(particles, player.x, player.y, 10);
            invincibleTimer = 1.0;

            if (health <= 0) {
                gameActive = false;
                const gameOverText = new Tctxt("48px", "Arial", "#ff0000", 400+display.camera.x, 300+display.camera.y, "center");
                gameOverText.setText("GAME OVER - Score: " + score);
                display.add(gameOverText);
            }
        }

        // Click to defeat enemy
        if (mouse.down && enemy.clicked()) {
          console.log("uygiik")
            move.particles.explosion(particles, enemy.x, enemy.y, 20);
            score += 50;
            scoreText.setText("Score: " + score);
            display.camera.shake(4, 4);
            enemy.hide();
            enemies.splice(i, 1);
            i--;
        }
    }

    // Boundaries

    player.x = Math.max(0, Math.min(1560, player.x));
    player.y = Math.max(0, Math.min(1160, player.y));
}
  </script>
    </body>
</html>

📝 How to Use This Code

Save the code as test11.html
Make sure epic.js (the Limn Engine) is in the same folder
Open test11.html in your browser
Play the game! Use arrow keys to move, click on enemies to defeat them

Useful Links

Resource	Link
GitHub Repository	github.com/terracodes004/limn-engine-doc
Direct Download (epic.js)	github.com/terracodes004/limn-engine-doc/blob/main/asset/epic.js
Complete API Reference	limn-engine-doc.vercel.app/reference.html
Discord Community	discord.gg/ZqnUtTQb8

If anything is still unclear, just ask – I'm happy to explain any part of the code in more detail!

🟠 Level 3 Tutorial — Limn Engine Advanced Guide

Kehinde Owolabi — Tue, 30 Jun 2026 01:50:17 +0000

🟠 Level 3 Tutorial — Limn Engine Advanced Guide

Particles, Circle Collision, Screen Shake & Dynamic Tilemaps

Welcome to Level 3: Advanced of Limn Engine! You've mastered physics, tilemaps, and camera work. Now it's time to add particle effects, circle collision, screen shake, dynamic tilemap editing, and professional polish that makes your games feel alive.

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. Scene Management	Menu → Gameplay → Game Over
2. Particle System Basics	Sparks, fire, magic effects
3. Built-in Particle Presets	Explosion, smoke, sparkle, blood, magic
4. Continuous Emitters	Engine exhaust, rain, fire
5. Circle Collision	Perfect collision for round objects
6. Camera Shake	Impact feedback
7. Camera Rotation Shake	Dramatic screen twist
8. Dynamic TileMap Editing	Destructible terrain
9. move.pointTo & move.circle	Turret aiming, orbiting
10. fixed() — HUD Anchoring	UI that stays on screen
11. destroy()	Memory management
12. Top-down Shooter Tutorial	Complete advanced game

Prerequisites

Before starting Level 3, you should be comfortable with:

✅ Physics and gravity (physics, gravity, bounce)
✅ Tilemaps (display.map, display.tile, display.tileFace)
✅ Camera follow and zoom
✅ Sprite animation
✅ Tctxt for UI

If you're not confident with these, complete Level 2: Intermediate first.

1. Scene Management

Scenes let you build every screen of your game — menu, gameplay, pause, game over — as separate Component collections that all exist in memory simultaneously. Switching between them happens instantly by changing a single integer.

How It Works

When you register a Component with display.add(obj, 2), the engine stores the number 2 alongside that Component in the comm[] array. Every frame, the render loop checks if (component.scene == display.scene) before drawing anything. Components in scenes 1 and 2 are completely invisible and receive no move() or update() calls when display.scene is 0.

Implementation

// Build all scenes at startup
const playBtn = new Component(160, 50, "#7fffb2", 320, 275, "rect");
display.add(playBtn, 0); // scene 0 = menu

const player = new Component(40, 40, "cyan", 100, 100, "rect");
const gameUI = new Tctxt("18px","Arial","white",14,28,"left",false,"alphabetic","rgba(0,0,0,0.5)",8,4);
gameUI.setText("Score: 0");
display.add(player, 1);  // scene 1 = gameplay
display.add(gameUI, 1);

const gameOverMsg = new Tctxt("40px","Arial","red",220,260,"center");
gameOverMsg.setText("GAME OVER");
display.add(gameOverMsg, 2); // scene 2 = game over

display.scene = 0; // start on menu

function update() {
    if (display.scene === 0 && display.x && playBtn.clicked()) {
        display.scene = 1;
    }
    if (display.scene === 1) {
        // all gameplay logic here
        gameUI.fixed();
    }
    if (display.scene === 2) {
        // game over logic
        if (display.keys[32]) display.scene = 0; // restart
    }
}

Visual Explanation

┌─────────────────────────────────────────────────────────────────┐
│                         ALL SCENES EXIST                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │   Scene 0   │  │   Scene 1   │  │       Scene 2           │ │
│  │   Menu      │  │  Gameplay   │  │     Game Over           │ │
│  │  (visible)  │  │  (hidden)   │  │      (hidden)           │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                    │
                    ▼
          display.scene = 1
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────┐
│  ┌─────────────┐  ┌─────────────────────────┐  ┌─────────────┐│
│  │   Scene 0   │  │       Scene 1           │  │   Scene 2   ││
│  │   Menu      │  │      Gameplay           │  │ Game Over   ││
│  │  (hidden)   │  │     (visible)           │  │  (hidden)   ││
│  └─────────────┘  └─────────────────────────┘  └─────────────┘│
└─────────────────────────────────────────────────────────────────┘

Best Practices

Do	Don't
Build all scenes at startup	Create/destroy objects on state change
Use `display.add(obj, scene)`	Forget to specify scene number
Use `display.scene = n` to switch	Use complex state machines
Use `hide()`/`show()` for temporary elements	Destroy UI elements that will be needed again

💡 Tip: Scenes are just integers — you can have as many as you need. Use constants like const SCENE_MENU = 0, SCENE_GAME = 1, SCENE_GAMEOVER = 2 for readability.

2. Particle System Basics

ParticleSystem manages a pool of short-lived Particle Components — spawning them with emit(), updating their physics and fade every frame via ps.update(), and automatically removing them from comm[] when their life or alpha reaches zero.

How It Works

Each Particle is a real Component that gets added to comm[] via display.add() when spawned, so the engine draws it automatically alongside all other Components — no manual draw calls needed. The Particle's update() method applies gravity, friction, rotation, alpha fade, and scale fade on every frame.

const ps = new ParticleSystem(display);

function update() {
    ps.update(); // REQUIRED every frame — advances physics, removes dead particles

    if (display.x) {
        ps.emit(display.x, display.y, {
            width: 6, height: 6,
            color: "#ffaa00",
            life: 45,
            speedX: (Math.random() - 0.5) * 4,
            speedY: -2,
            gravity: 0.1,
            friction: 0.97,
            alphaFade: 0.022,
            type: "circle"
        });
    }
}

Particle Options

Option	Default	Purpose
`life`	60	Frames until the particle is removed
`alphaFade`	0.02	Alpha subtracted per frame — 0.02 = 50-frame fade
`friction`	0.98	Speed multiplied per frame — values below 1 create drag
`gravity`	0	Added to speedY per frame
`type`	"rect"	"rect", "circle", or "image"
`randomColor`	false	If true, picks randomly from a colors[] array

⚠️ Warning: If you ever stop calling ps.update(), dead particles accumulate in comm[] indefinitely and the engine will slow down as it tries to draw thousands of invisible zero-alpha rectangles every frame.

3. Built-in Particle Presets

Limn Engine ships six ready-made particle effects accessible via move.particles.* — each one is a single function call that bursts or emits a carefully configured set of particles to produce a specific visual: explosion, smoke, sparkle, rain, blood, or magic.

const ps = new ParticleSystem(display);

function update() {
    ps.update();

    if (enemyDied) {
        move.particles.explosion(ps, enemy.x, enemy.y, 40); // 40 particles
        move.particles.blood(ps, enemy.x, enemy.y, 20);     // 20 particles
    }
    if (playerPowerUp) {
        move.particles.magic(ps, player.x, player.y);
        move.particles.sparkle(ps, player.x, player.y);
    }
    // Continuous weather — call every frame
    move.particles.rain(ps, 0, 0, 3);   // 3 raindrops per frame
    move.particles.smoke(ps, 200, 300); // one smoke puff per frame
}

Preset Reference

Preset	Type	Extra param	Effect
`explosion(ps,x,y,n)`	burst	intensity=30	Orange-red radial circles with gravity
`smoke(ps,x,y)`	emit	—	Single upward grey circle — call per frame
`sparkle(ps,x,y)`	burst	—	5 yellow circles with random radial spread
`rain(ps,x,y,n)`	emit×n	intensity=1	Thin blue vertical rects falling fast
`blood(ps,x,y,n)`	burst	amount=15	Red circles with downward gravity
`magic(ps,x,y)`	burst	—	20 multicolour rotating rects drifting up

4. Continuous Emitters

ps.createEmitter() returns an emitter object that fires particles automatically at a set rate every frame without you calling emit() manually — you can start it, stop it, and move it at any time, and ps.update() drives it automatically.

const ps = new ParticleSystem(display);

const fire = ps.createEmitter(400, 300, {
    rate: 30,              // 30 particles per second (0.5 per frame at 60fps)
    randomSpread: true,    // random direction each particle
    speed: 2,              // speed magnitude for random spread
    color: "#ff4400",
    life: 35,
    alphaFade: 0.03,
    gravity: -0.06,        // negative = particles float upward
    type: "circle",
    width: 5, height: 5
});

function update() {
    ps.update(); // drives emitter.update() internally

    // Move the emitter to follow the player
    fire.setPosition(player.x + 20, player.y + 30);

    // Toggle on a key
    if (display.keys[70]) fire.stop();  // F key
    else fire.start();
}

Emitter Methods

Method	Purpose
`emitter.start()`	Begin emitting — active by default on creation
`emitter.stop()`	Pause emission — already-live particles continue
`emitter.setPosition(x,y)`	Move the emitter origin

5. Circle Collision

enableCircleCollision() switches a Component from rectangle-based to radius-based collision detection — instead of comparing edges, crashWithCircle() measures the distance between the two centres and returns true if that distance is less than the sum of their radii.

const ball   = new Component(40, 40, "blue", 200, 200, "rect");
const target = new Component(40, 40, "red",  350, 200, "rect");
display.add(ball);
display.add(target);

// Enable circle collision — auto radius = max(width,height)/2 = 20
ball.enableCircleCollision();
target.enableCircleCollision(22); // explicit radius

function update(dt) {
    if (display.keys[39]) ball.speedX =  3;
    if (display.keys[37]) ball.speedX = -3;

    if (ball.crashWithCircle(target)) {
        target.setColor("yellow");
    } else {
        target.setColor("red");
    }
}

How It Works

Calling enableCircleCollision() sets this.isCircle = true and stores a radius — if you pass a number it uses that value directly, and if you leave it empty it defaults to half the largest dimension of the Component (Math.max(width, height) / 2).

When you call a.crashWithCircle(b), the engine first checks if b.isCircle is true — if it is, it calculates the Euclidean distance between the two centre points using Math.sqrt(dx*dx + dy*dy) and compares it to this.radius + other.radius. If the other Component does not have circle collision enabled, the method falls back to the standard AABB crashWith() check automatically.

💡 Tip: Circle collision is noticeably more accurate than AABB for any Component that looks round — bullets, balls, coins, and enemies with circular sprites will register hits that look correct to the player.

6. Camera Shake

display.camera.shake(x, y) applies an immediate positional offset to the camera and automatically reverses it after approximately 42 milliseconds — one call produces the classic screen-jolt effect used for explosions, hits, and impactful events.

function update() {
    if (bigExplosion) {
        display.camera.shake(12, 9);   // main canvas shake
        fake.camera.shake(-12, -9);    // fake canvas shake — opposite for realism

        // Add rotation shake for extra drama
        display.camera.shakeRotation(0.08);
    }

    // Small rumble on bullet fire
    if (playerShot) {
        display.camera.shake(3, 2);
        fake.camera.shake(-3, -2);
    }
}

Intensity Guide

Event	Shake Intensity
Coin collection	2-3 px
Player hit	5-8 px
Explosion	10-15 px
Boss death	15-20 px

⚠️ Warning: In perform() mode always shake both display.camera and fake.camera — they are independent cameras on separate canvases.

7. Camera Rotation Shake

display.camera.shakeRotation(angle) rotates the entire canvas around its centre point by the given radian value and resets automatically after 42 milliseconds — producing a dramatic screen-twist effect that conveys disorientation, powerful impacts, and boss hits far more forcefully than positional shake alone.

window.addEventListener("dblclick", () => {
    // Rotation shake alone — like a camera twist
    display.camera.shakeRotation(0.08); // ~4.6 degrees

    // Combined position + rotation for maximum impact
    display.camera.shake(14, 10);
    display.camera.shakeRotation(0.12);
    fake.camera.shake(-14, -10); // shake fake canvas too in perform() mode
});

Rotation Guide

Radians	Degrees	Feel
0.03	~1.7°	Subtle rumble
0.08	~4.6°	Strong hit
0.12	~6.9°	Explosion
0.20+	11°+	Boss / world event

8. Dynamic TileMap Editing

The TileMap's add() and remove() methods let you place and delete individual tiles at runtime on any layer — enabling destructible terrain, growing maps, and puzzle mechanics.

// Runtime tile editing
display.tileFace.add(1, 5, 3);        // place grass at grid(5,3) on layer 0
display.tileFace.add(3, 2, 1, 1);     // place tree at grid(2,1) on layer 1
display.tileFace.remove(5, 3);        // remove tile at grid(5,3) on layer 0
display.tileFace.remove(2, 0, 2);     // remove tile at grid(2,0) on layer 2

// fake.refresh() is called automatically inside add() and remove()

// Get world coordinates of a specific tile
const t = display.tileFace.rTile(5, 3);
if (t) console.log("Tile world position:", t.x, t.y);

// Get all tiles of a specific type
const allGrass = display.tileFace.tiles(1); // all tile-type-1 objects
allGrass.forEach(tile => {
    if (player.crashWith(tile)) {
        // player is standing on grass
    }
});

How It Works

tileFace.add(tileId, tx, ty, layer) writes the tile ID number into this.map[layer][ty][tx] and then calls this.show() followed by fake.refresh() — show() rebuilds the tileList array with the new tile included, and fake.refresh() sets display.once = true so the ani() loop redraws the fake canvas on the next frame.

💡 Tip: tileFace.rTile(tx, ty) returns the actual Tile Component object at a grid position, giving you direct access to its world coordinates, colour, and other Component properties.

9. move.pointTo & move.circle

move.pointTo() rotates a Component to face any world coordinate by calculating the angle with Math.atan2 and assigning it to the Component's angle property — and move.circle() increments that angle each frame so the Component orbits using moveAngle().

const turret  = new Component(40, 20, "gray", 400, 300, "rect");
const orbiter = new Component(16, 16, "cyan", 500, 300, "rect");
display.add(turret);
display.add(orbiter);

orbiter.angularMovement = true; // enables moveAngle() instead of move()
orbiter.speedX = 2;
orbiter.speedY = 2;

function update() {
    // Turret always faces the mouse
    if (display.x) {
        move.pointTo(turret, display.x, display.y);
    }

    // Orbiter spins in a circle around its own angle
    move.circle(orbiter, 2);  // 2 degrees per frame
    // orbiter.moveAngle() is called automatically because angularMovement = true
}

How It Works

move.pointTo(id, targetX, targetY) computes Math.atan2(targetY - id.y, targetX - id.x) to get the angle from the Component's position to the target and assigns it to id.angle — because Limn renders all Components with their angle applied via a context.rotate(), this makes the Component's right side face the target position on every frame it is called.

move.circle(id, speed) sets angularMovement = true on the Component and then adds speed * Math.PI / 180 to its angle each frame — the moveAngle() method uses Math.cos(angle) and Math.sin(angle) to convert that angle into X and Y velocity.

10. fixed() — HUD Anchoring

component.fixed() keeps a Component locked to a fixed screen position even when the camera is scrolling — it works by reading the Component's original anchor coordinates stored in aX and aY at construction time and adding the current camera offset to them every frame.

// Create at desired screen position — aX=16, aY=16 stored automatically
const healthBar = new Component(160, 14, "red", 16, 16, "rect");
const hpLabel   = new Tctxt("16px","Arial","white",16,36,"left",false,"alphabetic","rgba(0,0,0,0.5)",8,3);
hpLabel.setText("HP: 100");
display.add(healthBar);
display.add(hpLabel);

function update() {
    display.camera.follow(player, true);

    // Call every frame — recalculates position from aX/aY + camera offset
    healthBar.fixed();
    hpLabel.fixed();
}

⚠️ Warning: fixed() must be called every frame. If you call it only once at startup the element will be fixed at frame 0's camera position and drift away as the camera moves.

11. destroy()

component.destroy() permanently removes a Component from the engine's rendering pipeline by splicing it out of both the comm[] and commp[] arrays and setting its update method to null — after this call the Component will never be drawn or moved again.

function update() {
    // Remove bullets that leave the screen — prevents comm[] from growing
    for (let i = bullets.length - 1; i >= 0; i--) {
        if (bullets[i].y < -50) {
            bullets[i].destroy(); // removed from comm[] immediately
            bullets.splice(i, 1); // also remove from your own tracking array
        }
    }

    // Remove enemies on collision
    for (let i = enemies.length - 1; i >= 0; i--) {
        if (player.crashWith(enemies[i])) {
            move.particles.explosion(ps, enemies[i].x, enemies[i].y, 20);
            enemies[i].destroy();
            enemies.splice(i, 1);
        }
    }
}

💡 Tip: Always iterate arrays in reverse (for (let i = arr.length-1; i >= 0; i--)) when removing elements mid-loop — otherwise splicing shifts the indices and you skip elements.

12. Top-down Shooter Tutorial

This tutorial builds a complete top-down shooter combining scenes, particles, camera shake, circle collision, pointTo, destroy(), and HUD anchoring into a game where enemies chase the player and explode on contact.

<!DOCTYPE html>
<html>
<head>
    <title>Top-down Shooter</title>
    <script src="asset/epic.js"></script>
</head>
<body>
<script>
const display = new Display();
display.start(800, 600);
display.backgroundColor("#0d0d1a");
const ps = new ParticleSystem(display);

const player = new Component(36, 36, "cyan", 400, 300, "rect");
player.enableCircleCollision(18);
display.add(player, 1);

let enemies = [];
function spawnEnemy() {
    const e = new Component(32, 32, "red",
        Math.random() * 760, Math.random() * 560, "rect");
    e.enableCircleCollision(16);
    display.add(e, 1);
    enemies.push(e);
}
for (let i = 0; i < 5; i++) spawnEnemy();

const scoreUI = new Tctxt("18px","Arial","white",14,28,
    "left",false,"alphabetic","rgba(0,0,0,0.5)",8,4);
scoreUI.setText("Score: 0");
display.add(scoreUI, 1);

let score = 0;
display.scene = 1;

function update() {
    ps.update();

    // WASD movement
    player.speedX = 0; player.speedY = 0;
    if (display.keys[87]) player.speedY = -4;
    if (display.keys[83]) player.speedY =  4;
    if (display.keys[65]) player.speedX = -4;
    if (display.keys[68]) player.speedX =  4;
    move.pointTo(player, display.x || 400, display.y || 300);
    move.bound(player);

    // Enemies chase player
    for (let i = enemies.length - 1; i >= 0; i--) {
        const e = enemies[i];
        const dx = player.x - e.x, dy = player.y - e.y;
        const d  = Math.sqrt(dx*dx+dy*dy);
        e.speedX = (dx/d) * 1.8;
        e.speedY = (dy/d) * 1.8;

        if (player.crashWithCircle(e)) {
            move.particles.explosion(ps, e.x, e.y, 25);
            move.particles.blood(ps, e.x, e.y, 12);
            display.camera.shake(10, 8);
            display.camera.shakeRotation(0.07);
            e.destroy();
            enemies.splice(i, 1);
            score += 10;
            spawnEnemy(); // respawn
        }
    }

    display.camera.follow(player, true);
    scoreUI.setText("Score: " + score);
    scoreUI.fixed();
}
</script>
</body>
</html>

✅ What You Get:

WASD to move
Player faces mouse
Enemies chase the player
On hit: explosion, blood, camera shake, +10 score
New enemy spawns automatically

Quick Reference

Feature	Code
Scenes	`display.add(obj,n); display.scene=n;`
Particles	`const ps=new ParticleSystem(display); ps.emit(x,y,opts); ps.update();`
Preset	`move.particles.explosion(ps,x,y,40)`
Emitter	`const e=ps.createEmitter(x,y,opts); e.start(); e.setPosition(x,y);`
Circle collision	`obj.enableCircleCollision(); obj.crashWithCircle(other)`
Shake	`display.camera.shake(10,8); fake.camera.shake(-10,-8);`
Rotation shake	`display.camera.shakeRotation(0.08)`
Edit tile	`tileFace.add(id,tx,ty,layer); tileFace.remove(tx,ty,layer);`
pointTo	`move.pointTo(obj,targetX,targetY)`
Fixed HUD	`obj.fixed(); // every frame`
destroy	`obj.destroy() // removes from comm[] and commp[]`

What's Next?

You've completed Level 3: Advanced! 🎉

Level	Description
🟢 Level 1 — Beginner	✅ Basics complete
🟡 Level 2 — Intermediate	✅ Physics, tilemaps, camera
🟠 Level 3 — Advanced	✅ You are here
🔴 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."*

Useful Links

Resource	Link
GitHub Repository	github.com/terracodes004/limn-engine-doc
Direct Download (epic.js)	github.com/terracodes004/limn-engine-doc/blob/main/asset/epic.js
Complete API Reference	limn-engine-doc.vercel.app/reference.html
Discord Community	discord.gg/ZqnUtTQb8

Draw your game into existence — one particle at a time. 🎨

🏓 Build a Ball Game with Limn Engine

Kehinde Owolabi — Tue, 30 Jun 2026 01:45:16 +0000

🏓 Build a Ball Game with Limn Engine

A Complete Step-by-Step Tutorial for JavaScript Beginners

Welcome! In this tutorial, you'll build a complete ball-and-paddle game (like Breakout) using Limn Engine — a zero‑configuration 2D game engine that runs in your browser.

What you'll build: A paddle that moves left and right, a bouncing ball that speeds up over time, score tracking, high scores saved in your browser, and a game-over screen. All in about 100 lines of code.

By the end, you'll understand:

How to create game objects (paddle, ball, floor)
How to handle keyboard and touch input
How to detect and respond to collisions
How to track and save high scores
How to manage game states (playing, game over)

🎮 Want to play the finished game? Click here to play Ball Game Live!

Before We Start

What You Need

A text editor (VS Code, Notepad, or any code editor)
A web browser (Chrome, Firefox, Edge)
Limn Engine — download epic.js from limn-engine-doc.vercel.app

What You Should Know

Basic JavaScript (variables, functions, if-statements)
How to open an HTML file in a browser

No game development experience required!

Step 1: The HTML Structure

Every Limn Engine game starts with a simple HTML file.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Ball game</title>
  <script src="asset/epic.js"></script>
  <style>
    canvas{
      border: solid red 5px;
    }
  </style>
</head>
<body bgcolor="darkblue">
  <dialog open style="background:linear-gradient(darkblue,royalblue);"></dialog>
  <script>
    // All your game code goes here
  </script>
</body>
</html>

What's happening:

<script src="asset/epic.js"> — loads the Limn Engine library
<style> — adds a red border around the canvas
<dialog> — acts as a container for the canvas with a gradient background
Everything inside the second <script> tag is your game code

Save this as ballgame.html and open it in your browser.

Step 2: Setting Up the Game

The first thing we need is a Display — this is the engine that creates the canvas, runs the game loop, and handles input.

const display = new Display();
display.perform();        // Activates performance mode (dual-canvas rendering)
display.start(800, 600, document.querySelector("dialog"));  // Creates an 800×600 canvas inside the dialog
display.rgradient("royalblue", "darkblue");  // Radial gradient background

What's happening:

new Display() — creates the engine
display.perform() — turns on high-performance mode
display.start(800, 600, document.querySelector("dialog")) — creates a canvas 800 pixels wide and 600 pixels tall inside the <dialog> element
display.rgradient() — creates a radial gradient background from royal blue to dark blue

Add this code now. If you refresh your browser, you'll see a canvas with a gradient background.

Step 3: Creating the Paddle and Ball

Every visible object in Limn Engine is a Component — that includes the paddle, ball, floor, and even text.

const player = new Component(100, 30, "magenta", 0, 0);  // Paddle
const ball = new Component(12, 12, "aqua", 10, 10);     // Ball
const floor = new Component(800, 10, "black", 0, 590);  // Floor (game over trigger)

move.position(player, "bottom", 10);  // Position paddle at bottom center

Breakdown:
| Object | Width | Height | Color | Position | Purpose |
|--------|-------|--------|-------|----------|---------|
| player | 100 | 30 | magenta | Bottom center | Paddle controlled by player |
| ball | 12 | 12 | aqua | (10, 10) | Bouncing ball |
| floor | 800 | 10 | black | (0, 590) | Triggers game over on contact |

Add this code. You'll see a magenta paddle at the bottom and a small aqua ball at the top-left.

Step 4: Adding the Game Objects to the Display

To make objects appear on screen, you must add them to the display:

display.add(floor);
display.add(player);
display.add(ball);

What's happening:

display.add() — registers each component with the engine
Objects are drawn in the order they're added (floor first, ball on top)

Add this code. Now all three objects are visible.

Step 5: Ball Movement

We need the ball to move and bounce off walls. First, set its initial speed:

let ballSpeedX = 300;  // Horizontal speed (pixels per second)
let ballSpeedY = 500;  // Vertical speed (pixels per second)
ball.speedX = 300;
ball.speedY = 500;

Now add this to the update function:

function update(dt) {
    // Ball movement
    ball.x += ball.speedX * dt;
    ball.y += ball.speedY * dt;
}

What's happening:

dt (delta time) ensures the ball moves at the same speed on all devices
The ball moves 300 pixels right and 500 pixels down per second

Test your game: The ball will start moving diagonally.

Step 6: Ball vs Walls

The ball needs to bounce off the walls:

function update(dt) {
    // ... ball movement code ...

    // Ball vs walls
    if(ball.x <= 0) {
        ball.x = 0;
        ball.speedX = Math.abs(ball.speedX);  // Bounce right
    }
    if(ball.x + ball.width >= 800) {
        ball.x = 800 - ball.width;
        ball.speedX = -Math.abs(ball.speedX);  // Bounce left
    }
    if(ball.y <= 0) {
        ball.y = 0;
        ball.speedY = Math.abs(ball.speedY);  // Bounce down
    }
}

What's happening:

Math.abs() — makes the speed positive or negative to reverse direction
ball.width — accounts for the ball's size when hitting the right wall

Test your game: The ball now bounces off the left, right, and top walls.

Step 7: Game Over — Ball vs Floor

If the ball hits the floor, it's game over:

function update(dt) {
    // ... existing code ...

    // Ball vs floor (GAME OVER)
    if(ball.y + ball.height >= 590) {
        gameOver = true;
        display.scene = 1;  // Switch to scene 1 (game over)
        loseTxt.setText("GAME OVER!\nScore: " + score + "\nHigh Score: " + highScore + "\nPress SPACE to restart");
        return;
    }
}

What's happening:

ball.y + ball.height — checks if the ball's bottom edge reaches the floor
gameOver = true — stops the game logic
display.scene = 1 — switches to scene 1 (game over screen)
The return prevents further code from running this frame

Step 8: Ball vs Paddle (Scoring)

When the ball hits the paddle, it bounces back and you score a point:

function update(dt) {
    // ... existing code ...

    // Ball vs paddle
    if(ball.crashWith(player) && ball.speedY > 0) {
        ball.y = player.y - ball.height;
        ball.speedY = -Math.abs(ball.speedY);  // Bounce upward
        score++;
        scoreTxt.setText("Score: " + score);
        display.camera.shake(3, 3);  // Small screen shake for feedback

        // Increase ball speed gradually (gets harder!)
        ballSpeedX += 10;
        ballSpeedY += 10;
        ball.speedX = (ball.speedX > 0 ? 1 : -1) * ballSpeedX;
        ball.speedY = (ball.speedY > 0 ? 1 : -1) * ballSpeedY;

        // Update high score
        if(score > highScore) {
            highScore = score;
            localStorage.hs = highScore;
        }
    }
}

What's happening:

crashWith() — detects collision between the ball and paddle
ball.speedY > 0 — ensures the ball is moving downward (prevents paddle from "sucking" the ball)
ball.y = player.y - ball.height — places the ball on top of the paddle
display.camera.shake(3, 3) — adds a small screen shake for feedback
The ball speeds up gradually with each hit

Step 9: Player Movement (Keyboard)

The player controls the paddle with the arrow keys or WASD:

function update(dt) {
    // ... existing code ...

    // Player movement (keyboard)
    if(display.keys[37] || display.keys[65]) {  // Left arrow or A
        player.x -= 700 * dt;
    } else if(display.keys[39] || display.keys[68]) {  // Right arrow or D
        player.x += 700 * dt;
    }
    move.bound(player);  // Keep paddle on screen
}

Key codes:

37 — Left arrow
39 — Right arrow
65 — A key
68 — D key

What's happening:

The paddle moves at 700 pixels per second
move.bound(player) — keeps the paddle on screen

Test your game: You can now move the paddle left and right!

Step 10: Player Movement (Touch Controls)

We also need touch controls for mobile devices:

// Create touch buttons
let leftbtn = new Component(100, 100, "rgba(0,0,0,0)", 50, 500);
let rightbtn = new Component(100, 100, "rgba(0,0,0,0)", 600, 500);
display.add(leftbtn);
display.add(rightbtn);

function update(dt) {
    // ... existing code ...

    // Touch controls
    if(leftbtn.clicked() && display.x) {
        player.x -= 700 * dt;
    }
    if(rightbtn.clicked() && display.x) {
        player.x += 700 * dt;
    }
}

What's happening:

Invisible touch buttons on the left and right sides of the screen
clicked() — detects if the button was tapped
Works on both desktop and mobile

Step 11: Restarting the Game

When the game is over, pressing SPACE restarts it:

let gameOver = false;

function update(dt) {
    // Restart
    if(gameOver && display.keys[32]) {
        gameOver = false;
        display.scene = 0;
        score = 0;
        ball.x = 10;
        ball.y = 10;
        ball.speedX = 300;
        ball.speedY = 500;
        ballSpeedX = 300;
        ballSpeedY = 500;
        move.position(player, "bottom", 10);
        display.keys[32] = false;  // Prevent holding SPACE
    }

    if(gameOver) return;  // Skip game logic if game over
}

What's happening:

display.keys[32] — checks if SPACE is pressed
gameOver — prevents game logic from running while on game over screen
display.keys[32] = false — ensures one press = one restart
All game state resets to starting values

Step 12: UI — Score and High Score

We need text to display the score and high score:

const scoreTxt = new Tctxt("30px", "Monospace", "white", 25, 25);
display.add(scoreTxt);

function update(dt) {
    // ... existing code ...

    // Score display
    scoreTxt.setText("Score: " + score + " | High: " + highScore);
}

What's happening:

Tctxt — creates a text component
The score updates every frame
High score is retrieved from localStorage

Step 13: Game Over Screen

When the game ends, show a game over message:

const loseTxt = new Tctxt("28px", "bold impact", "red", 50, 270);
loseTxt.setText("GAME OVER!\nPress SPACE to restart");
display.add(loseTxt, 1);  // Scene 1 = game over

What's happening:

The game over text is added to scene 1
It's hidden during gameplay (scene 0)
When display.scene = 1, it becomes visible

Step 14: High Score with localStorage

We save the high score in the browser's localStorage so it persists between sessions:

// Load high score
if(!localStorage.hs) {
    localStorage.hs = 0;
}
let highScore = Number(localStorage.hs);

// Update high score
if(score > highScore) {
    highScore = score;
    localStorage.hs = highScore;
}

What's happening:

localStorage — stores data in the browser
The high score is saved when the player beats it
It's loaded when the page loads

Step 15: Putting It All Together

Here's the complete code — the exact game you can play at https://limn-engine-doc.vercel.app/ballgame.html:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Ball game</title>
  <script src="asset/epic.js"></script>
  <style>
    canvas{
      border: solid red 5px;
    }
  </style>
</head>
<body bgcolor="darkblue">
  <dialog open style="background:linear-gradient(darkblue,royalblue);"></dialog>
  <script>
    // ===== SETUP =====
    const display = new Display();
    display.perform();
    display.start(800, 600, document.querySelector("dialog"));
    display.rgradient("royalblue", "darkblue");

    // ===== GAME OBJECTS =====
    const player = new Component(100, 30, "magenta", 0, 0);
    const ball = new Component(12, 12, "aqua", 10, 10);
    const floor = new Component(800, 10, "black", 0, 590);

    move.position(player, "bottom", 10);

    // Ball velocity (pixels per second)
    let ballSpeedX = 300;
    let ballSpeedY = 500;
    ball.speedX = 300;
    ball.speedY = 500;

    // ===== HIGH SCORE =====
    if(!localStorage.hs) localStorage.hs = 0;
    let highScore = Number(localStorage.hs);

    // ===== UI =====
    const scoreTxt = new Tctxt("30px", "Monospace", "white", 25, 25);
    const loseTxt = new Tctxt("28px", "bold impact", "red", 50, 270);
    loseTxt.setText("GAME OVER!\nPress SPACE to restart");
    display.add(scoreTxt);
    display.add(loseTxt, 1);  // Scene 1 = game over

    // ===== TOUCH CONTROLS =====
    let leftbtn = new Component(100, 100, "rgba(0,0,0,0)", 50, 500);
    let rightbtn = new Component(100, 100, "rgba(0,0,0,0)", 600, 500);
    display.add(leftbtn);
    display.add(rightbtn);

    let score = 0;
    let gameOver = false;

    // ===== ADD EVERYTHING =====
    display.add(floor);
    display.add(player);
    display.add(ball);

    // ===== GAME LOOP =====
    function update(dt) {
      // --- Restart ---
      if(gameOver && display.keys[32]) {
        gameOver = false;
        display.scene = 0;
        score = 0;
        ball.x = 10;
        ball.y = 10;
        ball.speedX = 300;
        ball.speedY = 500;
        ballSpeedX = 300;
        ballSpeedY = 500;
        move.position(player, "bottom", 10);
        display.keys[32] = false;
      }

      if(gameOver) return;

      // --- Player movement (keyboard) ---
      if(display.keys[37] || display.keys[65]) {
        player.x -= 700 * dt;
      } else if(display.keys[39] || display.keys[68]) {
        player.x += 700 * dt;
      }

      // --- Touch controls ---
      if(leftbtn.clicked() && display.x) {
        player.x -= 700 * dt;
      }
      if(rightbtn.clicked() && display.x) {
        player.x += 700 * dt;
      }

      move.bound(player);

      // --- Ball movement ---
      ball.x += ball.speedX * dt;
      ball.y += ball.speedY * dt;

      // --- Ball vs walls ---
      if(ball.x <= 0) {
        ball.x = 0;
        ball.speedX = Math.abs(ball.speedX);
      }
      if(ball.x + ball.width >= 800) {
        ball.x = 800 - ball.width;
        ball.speedX = -Math.abs(ball.speedX);
      }
      if(ball.y <= 0) {
        ball.y = 0;
        ball.speedY = Math.abs(ball.speedY);
      }

      // --- Ball vs floor (GAME OVER) ---
      if(ball.y + ball.height >= 590) {
        gameOver = true;
        display.scene = 1;
        loseTxt.setText("GAME OVER!\nScore: " + score + "\nHigh Score: " + highScore + "\nPress SPACE to restart");
        return;
      }

      // --- Ball vs paddle ---
      if(ball.crashWith(player) && ball.speedY > 0) {
        ball.y = player.y - ball.height;
        ball.speedY = -Math.abs(ball.speedY);
        score++;
        scoreTxt.setText("Score: " + score);
        display.camera.shake(3, 3);

        // Increase ball speed gradually
        ballSpeedX += 10;
        ballSpeedY += 10;
        ball.speedX = (ball.speedX > 0 ? 1 : -1) * ballSpeedX;
        ball.speedY = (ball.speedY > 0 ? 1 : -1) * ballSpeedY;

        // Update high score
        if(score > highScore) {
          highScore = score;
          localStorage.hs = highScore;
        }
      }

      // --- Score display ---
      scoreTxt.setText("Score: " + score + " | High: " + highScore);
    }
  </script>
</body>
</html>

🎮 Play the Finished Game

You can play the complete game right now:

Click here to play Ball Game Live!

Summary: What You Learned

Concept	How It Works
Display	Creates the canvas and game loop
Component	Every visible object (paddle, ball, floor)
Tctxt	Text display (score, game over)
Collision	`crashWith()` detects when objects touch
Keyboard input	`display.keys[keyCode]`
Touch input	`clicked()` for touch buttons
Delta time	`dt` makes movement frame‑rate independent
Game state	`gameOver` boolean + `display.scene`
localStorage	Saves high score in browser
Scene management	`display.scene = 1` for game over

Next Steps

What to Try	Difficulty
Add sound effects	🟢 Easy
Add a "Start" screen	🟢 Easy
Add power-ups (wider paddle, slower ball)	🟡 Medium
Add bricks to break (like Breakout)	🟡 Medium
Add multiple lives	🟡 Medium

Troubleshooting

Problem	Solution
Paddle doesn't move	Check `display.keys[37]` and `[39]`
Ball doesn't bounce	Check collision conditions and speed values
Game over doesn't trigger	Check `ball.y + ball.height >= 590`
High score doesn't save	Check localStorage is supported in your browser
Touch controls don't work	Make sure buttons are added to display and `clicked()` is called

Congratulations! You've built a complete ball-and-paddle game with Limn Engine. 🏓

Now go customize it — add more features, different colors, or your own creative twist!

🚀 Build Your First Space Shooter Game with Limn Engine

Kehinde Owolabi — Tue, 30 Jun 2026 00:32:18 +0000

🚀 Build Your First Space Shooter Game with Limn Engine

A Complete Step-by-Step Tutorial for JavaScript Beginners

Welcome! In this tutorial, you'll build a complete space shooter game using Limn Engine — a zero‑configuration 2D game engine that runs in your browser.

What you'll build: A spaceship that moves, shoots bullets, fights waves of enemies, and keeps score. All in about 100 lines of code.

By the end, you'll understand:

How to create a game loop
How to handle keyboard input
How to detect collisions
How to use particles for visual effects
How to manage game state (lives, score, game over)

🎮 Want to play the finished game? Click here to play Space Shooter Live!

Before We Start

What You Need

A text editor (VS Code, Notepad, or any code editor)
A web browser (Chrome, Firefox, Edge)
Limn Engine — download epic.js from limn-engine-doc.vercel.app

What You Should Know

Basic JavaScript (variables, functions, arrays, if-statements)
How to open an HTML file in a browser

No game development experience required!

Step 1: The HTML Structure

Every Limn Engine game starts with a simple HTML file.

<!doctype html>
<html>
  <head>
    <script src="asset/epic.js"></script>
  </head>
  <body>
  <script>
    // All your game code goes here
  </script>
  </body>
</html>

What's happening:

<script src="asset/epic.js"> — loads the Limn Engine library
Everything inside the second <script> tag is your game code

Save this as game.html and open it in your browser. You should see a blank canvas with a blue gradient background.

Step 2: Setting Up the Game

The first thing we need is a Display — this is the engine that creates the canvas, runs the game loop, and handles input.

const display = new Display();
display.perform();        // Activates performance mode (dual-canvas rendering)
display.start(800, 600);  // Creates an 800×600 canvas

What's happening:

new Display() — creates the engine
display.perform() — turns on high-performance mode
display.start(800, 600) — creates a canvas 800 pixels wide and 600 pixels tall

Add this code now. If you refresh your browser, you'll see a black canvas.

Step 3: Creating the Player

Every visible object in Limn Engine is a Component — that includes the player, enemies, bullets, and even text.

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

Breakdown:
| Parameter | Value | Meaning |
|-----------|-------|---------|
| 40, 40 | width, height | The player is a 40×40 pixel square |
| "cyan" | color | The player is cyan (light blue) |
| 400, 520 | x, y | Position at 400px from left, 520px from top |
| "rect" | type | It's a rectangle (shape) |

Add this code. Now when you refresh, you'll see a cyan square near the bottom of the screen.

Step 4: Adding a Background

Let's make the background look like space.

display.lgradient("top", "royalblue", "darkblue");

Breakdown:

lgradient — linear gradient (colors blend from one to another)
"top" — the gradient goes from top to bottom
"royalblue" — top color (light blue)
"darkblue" — bottom color (dark blue)

Add this code below display.start(). Your game now has a space sky background.

Step 5: Adding UI — Score and Lives

We need to display the score and remaining lives. For text, we use Tctxt — a special component for text.

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

const livesText = new Tctxt("24px", "Arial", "red", 20, 100);
livesText.setText("Lives: 3: "+" Bullets: 12");
display.add(livesText);

Breakdown:
| Parameter | scoreText | livesText |
|-----------|-----------|-----------|
| "32px" / "24px" | Font size | Smaller for lives |
| "Arial" | Font family | Same font |
| "white" / "red" | Text color | Score is white, lives are red |
| 20, 50 | Position | Score at top-left |
| 20, 100 | Position | Lives below score |

Add this code. Now you have a score and lives display.

Step 6: Adding Particles

We need particles for visual effects like explosions and engine exhaust.

const particles = new ParticleSystem(display);

What's happening:

new ParticleSystem(display) — creates a particle system linked to our display
We'll use this later for explosions and the engine trail

Add this code after creating the display.

Step 7: Game Variables

We need variables to track the game state:

let enemies = [];          // Array to hold all enemies
let bullets = [];          // Array to hold all bullets
let score = 0;             // Player's score
let lives = 3;             // Player's lives
let enemyTimer = 0;        // Timer for spawning enemies
let invincibleFrames = 0;  // Frames of invincibility after being hit
let bulletCounts = 12;     // How many bullets the player has

Add this code after your UI setup.

Step 8: Creating the Update Function

The update function is called 60 times per second — it's where all the game logic happens.

function update(dt) {
    // All game logic goes here
}

What is dt? dt stands for "delta time" — the time since the last frame. It's very small (around 0.016 seconds at 60 FPS). We multiply speeds by dt so the game runs at the same speed on all devices.

Add this empty function after your game variables.

Step 9: Making the Player Move

Inside the update function, let's handle player movement:

function update(dt) {
    // Player movement
    if (display.keys[37]) {         // Left arrow key
        player.speedX = -400 * dt;
    } else if (display.keys[39]) {  // Right arrow key
        player.speedX = 400 * dt;
    } else {
        player.speedX = 0;
    }

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

Key codes:

37 — Left arrow
39 — Right arrow

What's happening:

If the left arrow is pressed, the player moves left at 400 pixels per second
If the right arrow is pressed, the player moves right at 400 pixels per second
If neither is pressed, the player stops
move.bound(player) — prevents the player from going off-screen

Test your game: You can now move the player left and right!

Step 10: Creating Enemies

We need enemies that come from the top of the screen:

function createEnemy() {
    const e = new Component(35, 35, "red", Math.random() * 750, -35, "rect");
    e.speedY = 1.50;
    display.add(e);
    enemies.push(e);
}

Breakdown:

Math.random() * 750 — random X position across the screen
-35 — starts above the screen
e.speedY = 1.50 — moves downward at 1.5 pixels per frame

Now add this to the update function:

function update(dt) {
    // ... existing code ...

    // Spawn enemies
    enemyTimer++;
    if (enemyTimer > 45) {
        enemyTimer = 0;
        createEnemy();
    }
}

What's happening:

Every 45 frames (about 0.75 seconds), a new enemy appears
Enemies spawn at a random X position above the screen
They move downward

Step 11: Shooting Bullets

We need a function to create bullets:

function shoot() {
    if (bulletCounts > 0) {
        // Create bullet at player's position
        const b = new Component(5, 10, "yellow", player.x + 17.5, player.y, "rect");
        b.speedY = -5.00;
        display.add(b);
        bullets.push(b);
        bulletCounts--;
        livesText.setText("Lives: " + lives + ", Bullet: " + bulletCounts);
    }
}

Breakdown:

player.x + 17.5 — centers the bullet on the player (half of player width)
b.speedY = -5.00 — bullet moves upward
bulletCounts-- — uses one bullet

Now add this to the update function:

function update(dt) {
    // ... existing code ...

    // Shoot with SPACE
    if (display.keys[32]) {
        shoot();
        display.keys[32] = false;  // Prevent holding down SPACE
    }
}

Key code: 32 = Spacebar

What's happening:

When SPACE is pressed, we call shoot()
A bullet appears at the player's position
The bullet travels upward
bulletCounts decreases and the UI updates
display.keys[32] = false — ensures one bullet per press

Step 12: Refilling Bullets

We want bullets to refill every 7 seconds:

setInterval(() => {
    bulletCounts = 12;
}, 7000);

What's happening:

Every 7 seconds (7000 milliseconds), bullets reset to 12

Step 13: Updating Bullets

Bullets need to move upward and be removed when off-screen:

function update(dt) {
    // ... existing code ...

    // Update bullets
    for (let i = 0; i < bullets.length; i++) {
        bullets[i].y += bullets[i].speedY * dt;
        if (bullets[i].y < -50) {
            bullets[i].hide();        // Hide from view
            bullets.splice(i, 1);     // Remove from array
            i--;
        }
    }
}

What's happening:

Each bullet moves upward at its speed
If a bullet goes above the screen (y < -50), it's hidden and removed from the array

Step 14: Enemy Logic and Collisions

This is the most important part — handling enemy movement and collisions:

function update(dt) {
    // ... existing code ...

    // Update enemies
    for (let i = 0; i < enemies.length; i++) {
        const e = enemies[i];
        e.y += e.speedY * dt;

        // Enemy vs player collision
        if (e.crashWith(player) && invincibleFrames === 0) {
            lives--;
            livesText.setText("Lives: " + lives + ", Bullet: " + bulletCounts);
            invincibleFrames = 60;
            display.camera.shake(8, 8);
            e.hide();
            enemies.splice(i, 1);
            i--;

            if (lives <= 0) {
                display.stop();
                alert("Game Over! Score: " + score);
                location.reload();
            }
            continue;
        }

        // Enemy vs bullet collision
        for (let j = 0; j < bullets.length; j++) {
            if (e.crashWith(bullets[j])) {
                move.particles.explosion(particles, e.x, e.y, 20);
                score += 10;
                scoreText.setText("Score: " + score);
                display.camera.shake(3, 3);
                e.hide();
                bullets[j].hide();
                enemies.splice(i, 1);
                bullets.splice(j, 1);
                i--;
                break;
            }
        }

        // Enemy escapes bottom
        if (enemies[i] && enemies[i].y > 650) {
            enemies[i].hide();
            score -= 12;
            scoreText.setText("Score: " + score);
            enemies.splice(i, 1);
            i--;

            if (score < 0) {
                display.stop();
                alert("Game Over! Score: " + score);
                location.reload();
            }
        }
    }
}

What's happening:

Enemies move down the screen
If enemy hits player: Lose a life, become invincible, screen shakes
If bullet hits enemy: Explosion, +10 score, screen shakes
If enemy escapes: -12 score, game over if score goes negative

Step 15: Invincibility and Camera Follow

Add invincibility flashing and camera follow:

function update(dt) {
    // Update particles
    particles.update();

    // Camera follows player
    display.camera.follow(player);

    // Invincibility blinking
    if (invincibleFrames > 0) {
        invincibleFrames--;
        player.alpha = 0.5;  // Semi-transparent
    } else {
        player.alpha = 1;    // Fully visible
    }
}

Note: In Limn Engine, alpha controls transparency. 1 is fully visible, 0.5 is half-transparent.

Step 16: Engine Exhaust Particles

Add a trail of particles behind the player:

function update(dt) {
    // ... existing code ...

    // Engine exhaust particles
    particles.emit(player.x + 20, player.y + 40, {
        color: "orange",
        life: 15,
        alphaFade: 0.07,
        speedY: 1,
        width: 5,
        height: 5,
        type: "circle"
    });
}

Particle options explained:
| Option | Value | Meaning |
|--------|-------|---------|
| color | "orange" | The particle color |
| life | 15 | Lives for 15 frames |
| alphaFade | 0.07 | Fades out gradually |
| speedY | 1 | Drifts downward slightly |
| width/height | 5 | Particle size |
| type | "circle" | Round particles |

Step 17: Putting It All Together

Here's the complete code — the exact game you can play at test9.html:

<!doctype html>
<html>
  <head>
    <script src="asset/epic.js"></script>
  </head>
  <body>
  <script>
    const display = new Display();
display.perform();
display.start(800, 600);
const particles = new ParticleSystem(display);

// Player
const player = new Component(40, 40, "cyan", 400, 520, "rect");
display.add(player);
display.lgradient("top", "royalblue", "darkblue")
// UI
const scoreText = new Tctxt("32px", "Arial", "white", 20, 50);
scoreText.setText("Score: 0");
display.add(scoreText);

const livesText = new Tctxt("24px", "Arial", "red", 20, 100);
livesText.setText("Lives: 3: "+" Bullets: 12");
display.add(livesText);

// Game state
let enemies = [], bullets = [], score = 0, lives = 3, enemyTimer = 0, invincibleFrames = 0;

function createEnemy() {
    const e = new Component(35, 35, "red", Math.random() * 750, -35, "rect");
    e.speedY = 1.50;
    display.add(e);
    enemies.push(e);
}
let bulletCounts = 12
function shoot() {
  if(bulletCounts >0){
    const b = new Component(5, 10, "yellow", player.x + 17.5, player.y, "rect");
    b.speedY = -5.00;
    display.add(b);
    bullets.push(b);
    bulletCounts -= 1
    livesText.setText("Lives: " + lives+", Bullet: "+  bulletCounts);
  }
}
setInterval(()=>{
  bulletCounts = 12
},7000)
function update(dt) {
    particles.update();
display.camera.follow(player);

scoreText.x = 20+display.camera.x
scoreText.y = 50+display.camera.y
  livesText.x = 20+display.camera.x
livesText.y = 100+display.camera.y
    // Invincibility blinking
    if (invincibleFrames > 0) {
        invincibleFrames--;
        player.alpha = 0.5;
    } else player.alpha = 1;

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

    // Shoot with SPACE
    if (display.keys[32]) { shoot(); display.keys[32] = false; }

    // Spawn enemies
    if (++enemyTimer > 45) { enemyTimer = 0; createEnemy(); }

    // Bullet update
    for (let i = 0; i < bullets.length; i++) {
        bullets[i].y += bullets[i].speedY * dt;
        if (bullets[i].y < -50) { bullets[i].hide(); bullets.splice(i,1); i--; }
    }

    // Enemy logic and collisions
    for (let i = 0; i < enemies.length; i++) {
        const e = enemies[i];
        e.y += e.speedY * dt;

        // Enemy vs player
        if (e.crashWith(player) && invincibleFrames === 0) {
            lives--;
            livesText.setText("Lives: " + lives+", Bullet: "+  bulletCounts);
            invincibleFrames = 60;
            display.camera.shake(8, 8);
            e.hide(); enemies.splice(i,1); i--;
            if (lives <= 0) { display.stop(); alert("Game Over! Score: " + score); location.reload(); }
            continue;
        }

        // Enemy vs bullet
        for (let j = 0; j < bullets.length; j++) {
            if (e.crashWith(bullets[j])) {
                move.particles.explosion(particles, e.x, e.y, 20);
                score += 10;
                scoreText.setText("Score: " + score);
                display.camera.shake(3, 3);
                e.hide(); bullets[j].hide();
                enemies.splice(i,1); bullets.splice(j,1);
                i--; break;
            }
        }

        if (enemies[i] && enemies[i].y > 650) { enemies[i].hide();score-=12;scoreText.setText("Score: " + score); enemies.splice(i,1); i--;
                                              if(score<0){
                                                display.stop(); alert("Game Over! Score: " + score); location.reload();
                                              }
                                              }
    }

    // Engine exhaust particles
    particles.emit(player.x + 20, player.y + 40, { color: "orange", life: 15, alphaFade: 0.07, speedY: 1, width: 5, height: 5, type: "circle" });
}
  </script>
    </body>
</html>

🎮 Play the Finished Game

You can play the complete game right now:

Click here to play Space Shooter Live!

Summary: What You Learned

Concept	How It Works
Display	Creates the canvas and game loop
Component	Every visible object (player, enemies, bullets)
Tctxt	Text display (score, lives)
ParticleSystem	Visual effects (explosions, exhaust)
Collision	`crashWith()` detects when objects touch
Keyboard input	`display.keys[keyCode]`
Delta time	`dt` makes movement frame‑rate independent
Game state	Arrays, variables, and logic
hide()	Hides objects without destroying them
setInterval	Timer for bullet refills

Next Steps

What to Try	Difficulty
Add a boss enemy	🟡 Medium
Add power‑up pickups	🟡 Medium
Add sound effects	🟢 Easy
Add a start menu	🟢 Easy
Add a high score system	🟡 Medium
Use images instead of shapes	🟢 Easy

Troubleshooting

Problem	Solution
Player doesn't move	Check `display.keys[37]` and `[39]`
Bullets don't appear	Check `shoot()` is called and `bulletCounts > 0`
Enemies don't spawn	Check `enemyTimer > 45` is reached
Game crashes	Check for `hide()` on already hidden objects
Particles don't show	Call `particles.update()` in `update()`
Player doesn't blink	Check `player.alpha` is being set correctly

Congratulations! You've built a complete space shooter game with Limn Engine. 🚀

Now go customize it — add different enemy types, power-ups, or your own graphics!

Level 2 Tutorial — Limn Engine Intermediate Guide

Kehinde Owolabi — Sat, 27 Jun 2026 14:29:01 +0000

🟡 Level 2 Tutorial — Limn Engine Intermediate Guide

Physics, Tilemaps, Camera Follow & More

Welcome to Level 2: Intermediate of Limn Engine! You've mastered the basics — moving objects, collision, text, and simple games. Now it's time to add physics, tilemaps, camera work, and polish that makes your games feel professional.

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. Physics & Gravity	Realistic falling and jumping
2. hitBottom() & move.hitObject()	Floor and platform collision
3. move.glideX / glideY / glideTo	Smooth point-to-point movement
4. move.project	Projectile motion (arcs, bouncing)
5. Camera follow	Track the player
6. Camera zoom	Zoom in/out
7. Sprite & AnimatedSprite	Spritesheet animation
8. TileMap layers with addMap()	Multi-layer levels
9. Tctxt styled text UI	Professional HUD styling
10. Accelerate & decelerate	Vehicle-style momentum
11. Platform game tutorial	Complete platformer
12. Quick reference	All the essentials

Prerequisites

Before starting Level 2, you should be comfortable with:

✅ Creating a Display and starting the game
✅ Adding and moving Components
✅ Keyboard input (display.keys)
✅ Basic collision (crashWith())
✅ move.bound() for boundaries

If you're not confident with these, complete Level 1: Beginner first.

1. Physics & Gravity

Enabling physics on a Component tells Limn Engine to apply gravity automatically every frame. The engine accumulates downward speed into a gravitySpeed value that compounds over time, creating realistic freefall motion.

How It Works

When player.physics = true, the engine's internal move() method:

Adds this.gravity to this.gravitySpeed every frame
Adds this.gravitySpeed to the Component's Y position
After 10 frames of gravity 0.4, the object falls at 4px per frame

const player = new Component(40, 56, "blue", 100, 50, "rect");
display.add(player);

player.physics = true;  // Enable gravity accumulation
player.gravity = 0.4;   // Added to gravitySpeed each frame
player.bounce = 0.2;    // 20% energy kept on floor impact

function update(dt) {
    player.hitBottom(); // Clamp to canvas floor and bounce

    // Left/right movement still works normally alongside physics
    if (display.keys[39]) player.speedX = 4;
    if (display.keys[37]) player.speedX = -4;
    else if (!display.keys[39]) player.speedX = 0;
}

Properties Explained

Property	Type	Purpose
`physics`	boolean	Enable gravity accumulation in move()
`gravity`	number	Amount added to gravitySpeed per frame
`gravitySpeed`	number	Accumulated downward speed — set negative to jump
`bounce`	0–1	Fraction of speed kept on floor impact

Visual Example

Frame 1:  gravitySpeed = 0.4  (falling slow)
Frame 2:  gravitySpeed = 0.8  (falling faster)
Frame 3:  gravitySpeed = 1.2  (falling faster)
Frame 10: gravitySpeed = 4.0  (full speed)

⚠️ Important: You must call player.hitBottom() inside update() — the engine applies gravity but does NOT automatically stop the player at any surface.

2. hitBottom() and move.hitObject()

hitBottom() clamps a physics Component to the canvas floor. move.hitObject() does the same but uses another Component as the landing surface.

hitBottom()

player.hitBottom(); // Uses canvas height
player.hitBottom(400); // Custom ground at y=400

move.hitObject()

const player = new Component(36, 48, "cyan", 100, 0, "rect");
const platform = new Component(200, 20, "#555", 200, 300, "rect");
display.add(player);
display.add(platform);

player.physics = true;
player.gravity = 0.5;
player.bounce = 0.05;

function update(dt) {
    // Land on the platform
    move.hitObject(player, platform);

    // Also stop at the canvas floor (safety net)
    player.hitBottom();
}

Visual Explanation

Without hitBottom:
┌─────────────────────────────┐
│  Player falls through floor  │
│  ↓                           │
│  ↓                           │
│  ↓                           │
│  💀 Player disappears        │
└─────────────────────────────┘

With hitBottom:
┌─────────────────────────────┐
│  Player falls               │
│  ↓                           │
│  ↓                           │
│  ═══════════════════════════ │ ← Floor
│  ✅ Player lands & bounces   │
└─────────────────────────────┘

Quick Reference

Method	Parameters	Purpose
`hitBottom()`	optional groundY	Clamp to canvas floor and bounce
`move.hitObject(id, floor)`	Component, floor Component	Treat another Component's top edge as landing surface

3. move.glideX / glideY / glideTo

The glide functions ease a Component from its current position to a target coordinate over a specified duration using a cubic ease-out curve.

How It Works

The movement starts fast and decelerates smoothly as it approaches the target — no manual lerp code required.

const box = new Component(50, 50, "#7fffb2", 0, 200, "rect");
display.add(box);

// On any keypress, glide the box to a new position
window.addEventListener("keydown", () => {
    // Glide horizontally
    move.glideX(box, 2000, 700);    // to x=700 over 2 seconds

    // Glide vertically
    move.glideY(box, 1500, 400);    // to y=400 over 1.5 seconds

    // Or both axes together in perfect sync
    move.glideTo(box, 2000, 700, 400); // id, ms, x, y
});

Visual Timeline

Time:  0ms    500ms   1000ms   1500ms   2000ms
X:     0      200     400      550      700
       ↑       ↑       ↑        ↑        ↑
       Start   Fast    Medium   Slow     Arrive
              (Easing out — decelerates naturally)

Method Reference

Method	Parameters	Easing
`move.glideX(id, ms, x)`	Component, duration ms, target x	Cubic ease-out
`move.glideY(id, ms, y)`	Component, duration ms, target y	Cubic ease-out
`move.glideTo(id, ms, x, y)`	Component, duration ms, x, y	Both axes in sync

💡 Tip: Glide runs independently of your game loop. You call it once and the Component arrives at the target position precisely at the end of the duration regardless of frame rate.

4. move.project — Projectile Motion

move.project() launches a Component as a physics projectile — you specify velocity, launch angle, and gravity, and the engine handles the arc and bouncing.

const ball = new Component(20, 20, "orange", 100, 450, "rect");
display.add(ball);
ball.bounce = 0.5;

window.addEventListener("dblclick", () => {
    // Launch at 45° with velocity 12 — arcs and bounces on canvas floor
    move.project(ball, 12, 45, 0.3);

    // Custom ground height — bounce on a platform at y=400
    move.project(ball, 12, 45, 0.3, 400);
});

Visual Arc

    45° Launch
        ↗
       /  \
      /    \
     /      \
    /        \
   /          \
  ════════════════════ Ground
  --- Bounce --- Bounce --- Stop

Parameter Reference

Parameter	Type	Purpose
velocity	number	Launch speed in pixels per frame
angle	degrees	0° = right, 90° = up, 45° = classic arc
gravity	number	Added to speedY every frame — controls arc steepness
ground	number (optional)	Custom floor Y — defaults to display.canvas.height

💡 Tip: Angle 0° launches horizontally to the right, 90° launches straight up. Angles above 90° launch backward and upward.

5. Camera Follow

display.camera.follow(target) translates the canvas context so the view tracks a Component — keeping the player centred on screen as they move through a world larger than the canvas.

display.camera.worldWidth = 3000; // Level is 3000px wide
display.camera.worldHeight = 1000; // Level is 1000px tall

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

    // Smooth follow — lerps 10% of the gap each frame (recommended)
    display.camera.follow(player, true);

    // Hard follow — snaps to player exactly
    // display.camera.follow(player);
}

Smooth vs Instant Follow

Mode	Visual Effect	Use Case
`smooth = true`	Gentle trailing camera	Platformers, exploration games
`smooth = false`	Instant centering	Arcade games, precise control

How It Works

Smooth Follow:
Player → → → → → → →
Camera → → → → → → (10% lag behind)
        ↑
    Camera follows but never catches up completely

Instant Follow:
Player → → → → → → →
Camera → → → → → → (perfect sync)

Properties

Property	Purpose
`camera.worldWidth`	World size — camera won't show outside this
`camera.worldHeight`	World size — camera won't show outside this
`camera.x / camera.y`	Current camera offset (read or set manually)

6. Camera Zoom

display.camera.setZoom(amount) scales the entire canvas context. Call it once and the zoom stays until you change it.

// Zoom in once — stays zoomed in
display.camera.setZoom(1.5);

// Zoom out — stays zoomed out
display.camera.setZoom(0.5);

// Back to normal
display.camera.setZoom(1);

How It Actually Works

setZoom() calls display.context.scale(amount, amount) on the canvas context. The scale transform persists until the context is restored or the canvas is cleared.

// Internal implementation:
setZoom(amount) {
    display.context.scale(amount, amount);
}

Interactive Zoom Example

let zoomLevel = 1.0;

// Adjust zoom with keys — only when key is pressed
window.addEventListener("keydown", (e) => {
    if (e.key === "+" || e.key === "=") {
        zoomLevel = Math.min(zoomLevel + 0.1, 2.5);
        display.camera.setZoom(zoomLevel);
    }
    if (e.key === "-") {
        zoomLevel = Math.max(zoomLevel - 0.1, 0.5);
        display.camera.setZoom(zoomLevel);
    }
});

Visual Effect

Zoom 0.5 (Zoom Out):
┌─────────────────────┐
│  See more of world   │
│  ┌───┐               │
│  │ P │  (smaller)    │
│  └───┘               │
└─────────────────────┘

Zoom 1.0 (Normal):
┌─────────────────────┐
│  ┌──────────┐       │
│  │  Player   │       │
│  └──────────┘       │
└─────────────────────┘

Zoom 2.0 (Zoom In):
┌─────────────────────┐
│  ┌────────────────┐  │
│  │    Player       │  │
│  │    (close-up)   │  │
│  └────────────────┘  │
└─────────────────────┘

When to Call setZoom()

Scenario	When to Call
Static zoom	Once at startup
Zoom on key press	Only when key is pressed
Zoom on game event	Only when the event happens
Continuous zoom effect	Every frame (if you want gradual zoom)

💡 Tip: The zoom persists automatically. You only need to call setZoom() again if you want to change the zoom level.

7. Sprite & AnimatedSprite

Sprite animates a horizontal spritesheet by cycling through evenly spaced frames. AnimatedSprite extends it with named animation clips (idle, run, jump).

Sprite (Basic)

// Sprite(src, frameW, frameH, frameCount, frameSpeed, x, y)
const explosion = new Sprite("explode.png", 64, 64, 8, 4, 300, 200);
display.add(explosion);

AnimatedSprite (Named Clips)

const hero = new AnimatedSprite("hero_sheet.png", 64, 64, 200, 300);

// Define animation clips
hero.addAnimation("idle",   0,  3, 10, true);  // loop
hero.addAnimation("run",    4, 11,  5, true);  // loop
hero.addAnimation("jump",  12, 15,  4, false); // one-shot
hero.addAnimation("attack",16, 19,  3, false); // one-shot

display.add(hero);

let attacking = false;

function update(dt) {
    // Switch animations based on state
    if (display.keys[68]) hero.playAnimation("run");
    else hero.playAnimation("idle");

    // One-shot attack
    if (display.keys[90] && !attacking) { // Z key
        hero.playAnimation("attack");
        attacking = true;
        setTimeout(() => attacking = false, 300);
    }

    // Must call every frame to advance frames
    hero.updateAnimation();

    // hero.paused is true when a one-shot animation finishes
}

Spritesheet Format

One image file: hero_sheet.png
┌──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┐
│Frame0│Frame1│Frame2│Frame3│Frame4│Frame5│Frame6│Frame7│
│Idle0 │Idle1 │Run0  │Run1  │Run2  │Jump0 │Jump1 │Attack│
└──────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┘

Each frame = 64x64 pixels
Total width = 8 × 64 = 512 pixels

AnimatedSprite Methods

Method	Parameters	Purpose
`addAnimation(name, s, e, spd, loop)`	string, int, int, int, boolean	Define a named clip
`playAnimation(name)`	string	Switch to that clip — only resets if name changed
`updateAnimation()`	None	Advance the frame counter — call every frame
`paused`	boolean	True when a one-shot animation finishes
`faceLeft() / faceRight()`	None	Flip sprite horizontally

💡 Tip: One-shot animations set paused = true when they reach their last frame, which you can check to know when the animation finished.

8. TileMap Layers with addMap()

The TileMap in Limn Engine is a multi-layer system where each layer is an independent 2D number array. Layers are SWITCHABLE, not stackable — you show one layer at a time.

How Layers Actually Work

// ⚠️ Important: Layers are SWITCHABLE, not STACKABLE
// Only ONE layer is visible at a time!

display.tileFace.show(0);  // Layer 0 visible (layers 1, 2 hidden)
display.tileFace.show(1);  // Layer 1 visible (layers 0, 2 hidden)
display.tileFace.show(2);  // Layer 2 visible (layers 0, 1 hidden)

Setup

// All layers share these tile templates
display.tile = [
    new Component(64, 64, "#2d6a2d", 0, 0), // tile 1 = grass
    new Component(64, 64, "#8B4513", 0, 0), // tile 2 = dirt
    new Component(64, 64, "#228B22", 0, 0), // tile 3 = tree
    new Component(64, 64, "#FFD700", 0, 0), // tile 4 = coin
];

// Layer 0 — Overworld
display.map = [
    [1, 1, 2, 1, 1],
    [2, 1, 1, 2, 1],
    [2, 2, 2, 2, 2],
];
display.tileMap();
display.tileFace.show(0); // Show overworld

// Layer 1 — Dungeon (different map)
display.tileFace.addMap([
    [1, 0, 1, 0, 1],
    [0, 2, 0, 2, 0],
    [1, 0, 1, 0, 1],
]);
display.tileFace.show(1); // Switch to dungeon (overworld hidden)

// Layer 2 — Boss Room
display.tileFace.addMap([
    [1, 1, 1, 1, 1],
    [1, 4, 4, 4, 1],
    [1, 1, 1, 1, 1],
]);
display.tileFace.show(2); // Switch to boss room

Visual Layering (Switchable)

Layer 0 (Overworld):
┌─────────────────────────────┐
│  🟩🟫🟫🟩🟩                 │
│  🟫🟩🟩🟫🟩                 │
│  🟫🟫🟫🟫🟫                 │
└─────────────────────────────┘

Layer 1 (Dungeon):
┌─────────────────────────────┐
│  🟩⬜🟩⬜🟩                 │
│  ⬜🟫⬜🟫⬜                 │
│  🟩⬜🟩⬜🟩                 │
└─────────────────────────────┘

Layer 2 (Boss Room):
┌─────────────────────────────┐
│  🟩🟩🟩🟩🟩                 │
│  🟩🪙🪙🪙🟩                 │
│  🟩🟩🟩🟩🟩                 │
└─────────────────────────────┘

Only ONE layer is visible at a time!

Runtime Switching

// Switch layers based on game state
function goToDungeon() {
    display.tileFace.show(1); // Dungeon visible
    // Overworld tiles are hidden
}

function goToBossRoom() {
    display.tileFace.show(2); // Boss room visible
    // Dungeon tiles are hidden
}

function goToOverworld() {
    display.tileFace.show(0); // Overworld visible
    // Dungeon and boss room hidden
}

Adding Foreground Objects

// Tiles are for ground/walls. Use fake.add() for objects on top:
const tree = new Component(64, 64, null, 400, 300, "image");
tree.setImage("tree.png");
fake.add(tree); // Renders on top of tilemap

const coin = new Component(30, 30, null, 500, 200, "image");
coin.setImage("coin.png");
fake.add(coin); // Renders on top of tilemap

⚠️ Important: Layers do NOT stack! show(1) replaces show(0) — only one layer is visible at a time. This is a design choice for level switching, not a limitation.

Runtime Editing

// Edit a layer at runtime — fake.refresh() called automatically
display.tileFace.remove(1, 0, 2); // remove coin at grid(1,0) on layer 2
display.tileFace.add(3, 2, 1, 1); // add tree at grid(2,1) on layer 1

// Collision still works across all layers
if (display.tileFace.crashWith(player, 2)) {
    // player touched a dirt tile (type 2)
}

// Get all tiles of a type
const allCoins = display.tileFace.tiles(4);

9. Tctxt — Styled Text UI

Tctxt is the correct class for any on-screen text — it gives you font size, font family, colour, alignment, optional background fill with padding, stroke, and baseline control.

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

function update(dt) {
    scoreText.setText("Score: " + score);
    scoreText.fixed(); // lock to screen when camera moves
}

Parameter Reference

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

💡 Tip: The base Component.setText() method can draw text but offers no control over font, alignment, or background. Tctxt replaces it for any UI work.

10. Accelerate & Decelerate

move.accelerate() and move.decelerate() give you vehicle-style movement where speed builds up gradually to a maximum and bleeds off smoothly to zero.

function update(dt) {
    if (display.keys[68]) {
        // Accelerate right, max speed 8, no vertical change
        move.accelerate(player, 0.6, 0, 8, 0);
    } else if (display.keys[65]) {
        // Accelerate left
        move.accelerate(player, -0.6, 0, 8, 0);
    } else {
        // Friction — reduce speed by 0.4 per frame
        move.decelerate(player, 0.4, 0);
    }
    move.bound(player);
}

Visual Comparison

Instant Movement:
Speed:  ────   (jumps to max instantly)
         ↑
    Press key → Speed = 8 immediately

Accelerate/Decelerate:
Speed:  ↗───↘   (gradually speeds up, smoothly stops)
        ↑   ↑
    Press key  Release key

Method Reference

Method	Parameters	Purpose
`move.accelerate(id, ax, ay, mx, my)`	Component, accelX, accelY, maxX, maxY	Add acceleration per frame up to max speed
`move.decelerate(id, dx, dy)`	Component, decelX, decelY	Reduce speed to zero without reversing direction

11. Platform Game Tutorial

This tutorial puts together physics, jumping, accelerated movement, a floor platform, smooth camera follow, and a Tctxt score display into a complete playable platformer.

<!DOCTYPE html>
<html>
<head>
    <title>Platform Game</title>
    <script src="epic.js"></script>
</head>
<body>
    <script>
        const display = new Display();
        display.start(800, 400);
        display.backgroundColor("#1a1a2e");
        display.camera.worldWidth = 3000;

        const player = new Component(36, 48, "cyan", 100, 100, "rect");
        player.physics = true;
        player.gravity = 0.5;
        player.bounce = 0.05;
        display.add(player);

        const floor = new Component(3000, 20, "#444", 0, 380, "rect");
        display.add(floor);

        // A few platforms at different heights
        const p1 = new Component(200, 16, "#666", 400, 300, "rect");
        const p2 = new Component(150, 16, "#666", 800, 240, "rect");
        display.add(p1);
        display.add(p2);

        const scoreUI = new Tctxt(
            "18px","Arial","white",14,28,
            "left",false,"alphabetic",
            "rgba(0,0,0,0.5)",10,4
        );
        scoreUI.setText("Distance: 0");
        display.add(scoreUI);

        function update(dt) {
            // Horizontal movement with acceleration
            if (display.keys[68] || display.keys[39]) {
                move.accelerate(player, 0.7, 0, 7, 0);
            } else if (display.keys[65] || display.keys[37]) {
                move.accelerate(player, -0.7, 0, 7, 0);
            } else {
                move.decelerate(player, 0.5, 0);
            }

            // Jump — only when grounded (gravitySpeed >= 0)
            if ((display.keys[87] || display.keys[38]) && player.gravitySpeed >= 0) {
                player.gravitySpeed = -11;
            }

            // Floor and platform collisions
            move.hitObject(player, floor);
            move.hitObject(player, p1);
            move.hitObject(player, p2);
            player.hitBottom();

            display.camera.follow(player, true);
            scoreUI.setText("Distance: " + Math.floor(player.x));
            scoreUI.fixed();
        }
    </script>
</body>
</html>

✅ What You Get:

WASD or arrow keys to move
W/Up to jump
Multi-platform levels
Smooth camera follow
Live distance counter
Physics-based movement

12. Quick Reference

Feature	Code
Enable physics	`player.physics=true; player.gravity=0.4;`
Floor collision	`player.hitBottom();`
Platform collision	`move.hitObject(player, floor);`
Jump	`if(player.gravitySpeed >= 0) player.gravitySpeed = -10;`
Glide to position	`move.glideTo(obj, 2000, x, y);`
Projectile launch	`move.project(ball, 12, 45, 0.3);`
Camera follow	`display.camera.follow(player, true);`
Zoom (call once)	`display.camera.setZoom(1.5);`
AnimatedSprite	`hero.addAnimation("run",4,11,5,true); hero.playAnimation("run"); hero.updateAnimation();`
TileMap layer (switchable)	`tileFace.addMap(arr); tileFace.show(1);`
Accelerate	`move.accelerate(obj,0.6,0,8,0);`
Decelerate	`move.decelerate(obj,0.4,0);`

What's Next?

You've completed Level 2: Intermediate! 🎉

Level	Description
🟢 Level 1 — Beginner	✅ Basics complete
🟡 Level 2 — Intermediate	✅ You are here
🟠 Level 3 — Advanced	Particles, circle collision, dynamic tilemaps, screen shake
🔴 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."*

Useful Links

Resource	Link
GitHub Repository	github.com/terracodes004/limn-engine-doc
Direct Download (epic.js)	github.com/terracodes004/limn-engine-doc/blob/main/asset/epic.js
Complete API Reference	https://limn-engine-doc.vercel.app/reference.html
Discord Community	discord.gg/ZqnUtTQb8

Draw your game into existence — one physics simulation at a time. 🎮

🎨 Limn Engine Rendering Pipeline — From CSS Background to Dynamic Components

Kehinde Owolabi — Mon, 22 Jun 2026 15:53:13 +0000

🎨 Limn Engine Rendering Pipeline — From CSS Background to Dynamic Components

How Limn Engine Draws Your Game, Layer by Layer

Ever wondered what happens when Limn Engine renders a frame? Behind the simple display.start() lies a carefully designed rendering pipeline that layers everything from CSS backgrounds to dynamic game objects.

This article breaks down every layer of Limn Engine's rendering process — from the bottom (CSS background) to the top (dynamic components).

The Complete Render Order

Limn Engine renders in this exact order, from back to front:

┌─────────────────────────────────────────────────────────────────┐
│  LAYER 0: CSS Background                                      │
│  ↓                                                             │
│  LAYER 1: display.backgroundColor / lgradient / rgradient      │
│  ↓                                                             │
│  LAYER 2: fake.bgComm (Background Component)                   │
│  ↓                                                             │
│  LAYER 3: tileComm (TileMap Layers)                           │
│  ↓                                                             │
│  LAYER 4: commp (Fake Canvas Components)                      │
│  ↓                                                             │
│  LAYER 5: comm (Main Display Components)                      │
│  ↓                                                             │
│  LAYER 6: UI with .fixed() (HUD on top of everything)         │
└─────────────────────────────────────────────────────────────────┘

Layer 0: CSS Background (Bottom Layer)

This is the lowest layer. It's the actual CSS background of the canvas element.

display.canvas.style.backgroundColor = "black";

Why it matters: If all other layers fail or are transparent, this is what shows. It's your safety net.

Limn Engine wraps this with convenience methods:

display.backgroundColor("#0d0d2a");     // Solid color
display.lgradient("top", "blue", "black"); // Linear gradient
display.rgradient("white", "navy");      // Radial gradient

When to use: For simple backgrounds or as a fallback. This layer is fast because it's pure CSS.

Layer 1: Display Background Methods

These are CSS-based backgrounds applied to the canvas.

Method	Purpose
`display.backgroundColor(color)`	Solid CSS color
`display.lgradient(dir, c1, c2)`	Linear gradient
`display.rgradient(c1, c2)`	Radial gradient

// Solid background
display.backgroundColor("lightblue");

// Gradient sky
display.lgradient("top", "royalblue", "darkblue");

What's happening: These set this.canvas.style.background to the appropriate CSS value. The browser handles the rendering.

When to use: When you need a simple, fast background without using the canvas drawing context.

Layer 2: fake.bgComm (Background Component)

This is the first canvas-drawn layer. fake.bgComm is a special Component that renders behind everything on the fake canvas.

fake.bgComm = new Component(1600, 1200, null, 0, 0, "image");
fake.bgComm.setImage("sky.png");

In the Render Loop

// Inside ani()
if(display.once){
    fake.context.save();
    fake.context.translate(-fake.camera.x, -fake.camera.y);

    // RENDER BACKGROUND FIRST
    if(fake.bgComm){
        fake.bgComm.update(fake.context);
    }

    // THEN render tiles
    tileComm.forEach(...);
    // THEN render other fake objects
    commp.forEach(...);

    fake.context.restore();
}

What's happening: This renders once (or when fake.refresh() is called) to the offscreen fake canvas. It then gets composited with other layers.

When to use: For skyboxes, parallax backgrounds, or any large static background image.

Layer 3: tileComm (TileMap Layers)

Tilemaps render on top of the background but behind everything else.

display.tile = [
    new Component(64, 64, "#2d6a2d", 0, 0), // grass
    new Component(64, 64, "#654321", 0, 0)  // dirt
];

display.map = [
    [1,1,1,1,1],
    [1,0,2,0,1],
    [1,1,1,1,1]
];

display.tileMap();
display.tileFace.show();

In the Render Loop

// Render tiles AFTER background
tileComm.forEach(component => {
    component.x.update(fake.context);
});

What's happening: Tiles are rendered as Components on the fake canvas. They can have colors, images, and even physics.

When to use: For ground, walls, platforms, and any grid-based level elements.

Layer 4: commp (Fake Canvas Components)

These are static Components on the fake canvas that render AFTER tiles.

fake.add(tree, 0);      // Adds a tree on top of tiles
fake.add(decoration, 0); // Adds decorations

In the Render Loop

// Render static components AFTER tiles
commp.forEach(component => {
    if (component.scene == fake.scene) {
        component.x.bUpdate(fake.context);
    }
});

What's happening: These are "fake" Components — they exist on the offscreen canvas and render once. They're perfect for decorations, static obstacles, and anything that doesn't move.

When to use: For trees, rocks, decorations, and any static element that sits on top of the ground.

Layer 5: comm (Main Display Components)

These are dynamic Components on the main display that render EVERY frame.

const player = new Component(40, 40, "blue", 100, 100);
display.add(player);

const enemy = new Component(35, 35, "red", 400, 300);
display.add(enemy);

In the Render Loop

comm.forEach(component => {
    if (component.scene == display.scene) {
        if (component.x.angularMovement) {
            component.x.moveAngle();
        } else {
            component.x.move();
        }

        if (TCJSgameGameArea.crashWith(component.x)) {
            component.x.update(display.context);
        }
    }
});

What's happening: These Components are drawn every frame on the main display. They move, animate, and interact with the player.

When to use: For the player, enemies, bullets, and any moving object.

Layer 6: UI with .fixed() (Top Layer)

UI elements that stay locked to the screen position, even when the camera moves.

const healthBar = new Component(200, 20, "green", 20, 20);
const scoreText = new Tctxt("24px", "Arial", "white", 20, 50);
display.add(healthBar);
display.add(scoreText);

function update() {
    healthBar.fixed(); // Stays at screen position (20,20)
    scoreText.fixed(); // Stays at screen position (20,50)
}

What's happening: .fixed() adds the current camera offset to the Component's anchor position, so it appears at the same screen coordinates regardless of camera movement.

When to use: For all UI — health bars, score displays, menus, and dialogue boxes.

The Complete Render Pipeline Visualization

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  LAYER 6:  UI with .fixed()              [TOP]         │    │
│  │            (Health bars, score, menus)                   │    │
│  └─────────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  LAYER 5:  comm (Main Display)                         │    │
│  │            (Player, enemies, bullets - dynamic)         │    │
│  └─────────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  LAYER 4:  commp (Fake Canvas)                         │    │
│  │            (Trees, decorations - static)                │    │
│  └─────────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  LAYER 3:  tileComm (TileMap)                          │    │
│  │            (Ground, walls, platforms)                   │    │
│  └─────────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  LAYER 2:  fake.bgComm (Background Component)          │    │
│  │            (Sky, clouds, mountains)                     │    │
│  └─────────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  LAYER 1:  CSS Background Methods                      │    │
│  │            (backgroundColor, lgradient, rgradient)      │    │
│  └─────────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  LAYER 0:  CSS Background (canvas.style.background)   │    │
│  │            (Fallback - bottom layer)                   │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Performance Impact of Each Layer

Layer	Renders Once	Renders Every Frame	Performance Impact
CSS Background	✅ Browser handles	Minimal	Zero
display.backgroundColor/gradient	✅ Browser handles	Minimal	Zero
fake.bgComm	✅ Once (cached)	✅ Pasted as image	Low
tileComm	✅ Once (cached)	✅ Pasted as image	Low
commp	✅ Once (cached)	✅ Pasted as image	Low
comm	❌ No (dynamic)	✅ Every frame	Medium
UI with .fixed()	❌ No (dynamic)	✅ Every frame	Medium

💡 Performance Secret: The fake canvas cache means Layers 2-4 render ONCE and then just get pasted as an image. This is why Limn can run at 60 FPS on a Toshiba with 4GB RAM.

How to Use This Knowledge

For Better Performance

If you have...	Use...	Why
Static backgrounds	`fake.bgComm`	Renders once, cached forever
Static decorations	`fake.add()`	Renders once, cached forever
Moving objects	`display.add()`	Renders every frame (required)
UI elements	`.fixed()`	Stays on screen, camera-proof

For Better Organization

// Clear separation of layers

// 1. Background
fake.bgComm = new Component(1600, 1200, null, 0, 0, "image");
fake.bgComm.setImage("sky.png");

// 2. Tilemap
const tilemap = new TileMap(display, level, tiles, 1600, 1200);
tilemap.show();

// 3. Static decorations
fake.add(tree);
fake.add(rock);

// 4. Dynamic objects
display.add(player);
display.add(enemy);

// 5. UI
const scoreText = new Tctxt(...);
display.add(scoreText);

The One-Line Summary

"Limn Engine renders from CSS background up to dynamic objects, with three layers cached on the fake canvas for maximum performance and three layers drawn every frame for maximum flexibility."

Draw your game into existence — one layer at a time. 🎨

DEV Community: Kehinde Owolabi

Multiplayer Games with Limn Engine and WebSockets

Multiplayer Games with Limn Engine and WebSockets

📖 Introduction

🎯 What We're Building

🏗️ Architecture Overview

How It Works

🖥️ Step 1: The WebSocket Server (Node.js)

Install Dependencies

Server Code (server.js)

🎮 Step 2: The Client (Limn Engine)

Client Code (multiplayer.html)

📊 Key Concepts Explained

1. WebSocket Communication

2. Interpolation (Smooth Movement)

3. Throttled Sending

🚀 Extending the Game

Add Player Names Above Heads

Add Shooting

Add Score Tracking

⚠️ Limitations (Not Yet Tested)

🎯 The One-Line Summary

🔗 Resources

Memory Management in JavaScript Games — `destroy()`, `hide()`, and Object Pooling

📖 Introduction

🎯 The Problem: What Happens When You Don't Manage Memory?

Scenario 1: The Infinite Bullet

Scenario 2: The Enemy That Won't Die

🔧 Tool 1: destroy() — Permanent Removal

🔧 Tool 2: hide() / show() — Temporary Invisibility

🔧 Tool 3: Object Pooling — Reuse Objects

📊 Comparison: Which Approach to Use?

💡 Pro Tips for Memory Management

1. Always Iterate Backwards When Splicing

2. Use destroy() After Removing from Your Arrays

3. Pre-Allocate Pools for High-Frequency Objects

4. Profile Your Game

🎯 The One-Line Summary

🔗 Resources

🏃 The Ultimate Guide to Limn Engine's `move` Utility

🏃 The Ultimate Guide to Limn Engine's move Utility

📖 Introduction

📊 Complete Function List

🎯 Movement & Positioning Functions

move.teleport()

move.setX() / move.setY()

move.position()

move.stamp() / move.clearStamp()

🧭 Angular & Directional Functions

move.forward() / move.backward()

move.turnLeft() / move.turnRight()

move.circle()

move.pointTo()

📐 Boundaries

move.bound()

move.boundTo()

🌊 Smooth Movement (Glide)

move.glideX() / move.glideY() / move.glideTo()

⚡ Physics

move.accelerate() / move.decelerate()

move.project()

move.hitObject()

✨ Particles

move.particles.*

🔊 Sound

move.sound.*

🐛 Debugging

move.dot()

📊 Quick Reference

💡 The Philosophy Behind move

🎯 The One-Line Summary

🔗 Resources

[Boost]

Limn Engine — Complete API Reference

🔥 Top 20 Most Powerful Functions in Limn Engine

🔥 Top 20 Most Powerful Functions in Limn Engine

📖 Introduction

🎯 The Criteria

📊 How to Read This List

The List

Server Code (`server.js`)

Client Code (`multiplayer.html`)

🔧 Tool 1: `destroy()` — Permanent Removal

🔧 Tool 2: `hide()` / `show()` — Temporary Invisibility

2. Use `destroy()` After Removing from Your Arrays

🏃 The Ultimate Guide to Limn Engine's `move` Utility

`move.teleport()`

`move.setX()` / `move.setY()`

`move.position()`

`move.stamp()` / `move.clearStamp()`

`move.forward()` / `move.backward()`

`move.turnLeft()` / `move.turnRight()`

`move.circle()`

`move.pointTo()`

`move.bound()`

`move.boundTo()`

`move.glideX()` / `move.glideY()` / `move.glideTo()`

`move.accelerate()` / `move.decelerate()`

`move.project()`

`move.hitObject()`

`move.particles.*`

`move.sound.*`

`move.dot()`

💡 The Philosophy Behind `move`

#20 — `display.lgradient()` / `display.rgradient()`

#19 — `display.backgroundColor()`

#18 — `move.teleport()`

#17 — `move.position()`

#16 — `display.scale()`

#15 — `move.boundTo()`

#14 — `component.hide()` / `component.show()`

#13 — `display.camera.shakeRotation()`

#12 — `move.pointTo()`

#11 — `move.circle()`

#10 — `move.glideTo()`

#9 — `move.accelerate()` / `move.decelerate()`

#8 — `move.bound()`

#7 — `move.particles.*`

#6 — `display.camera.follow()`

#5 — `component.fixed()`

#4 — `display.camera.shake()`

#3 — `component.destroy()`

#2 — `fake.add()`

#1 — `display.perform()`

🔄 6. The Main Game Loop (`update` function)