Limn Engine — Complete API Reference

📚 Limn Engine — Complete API Reference

Quick Navigation

Class Purpose Level Display Canvas, game loop, input, camera, scenes 🟢 L1 Component Every visible game object 🟢 L1 Camera Viewport control (follow, shake, zoom) 🟡 L2 move Movement, physics, particles, helpers 🟢 L1 state Read-only query helpers 🟢 L1 TileMap Grid-based levels 🟡 L2 Tctxt Rich text with backgrounds 🟢 L1 Sound Single audio file 🟢 L1 SoundManager Multiple sounds, volume control 🔴 L4 ParticleSystem Emit, burst, continuous emitters 🟠 L3 Sprite Spritesheet animation 🟡 L2

Display

The heart of every Limn Engine game. Creates the canvas, runs the game loop, captures input, manages the camera, and controls scenes.

Constructor

const display = new Display();

Enter fullscreen mode Exit fullscreen mode

Properties

Property Type Description .canvas HTMLCanvasElement The game canvas .context CanvasRenderingContext2D 2D drawing context .keys Array Boolean array indexed by keyCode .scene Number Current active scene (default 0) .camera Camera Attached camera instance .deltaTime Number Time since last frame (seconds) .fps Number Current frames per second .frameNo Number Total frames elapsed .x / .y Number false

Methods

Method Parameters Description .start(w, h, node) width, height, parentNode Initialise canvas and start game loop .perform() — Activate dual-canvas pipeline (call before .start()) .add(comp, scene) Component, scene number Register a Component for rendering .stop() — Pause the game loop .scale(w, h) width, height Resize canvas after start .backgroundColor(color) CSS color Set background colour .lgradient(dir, c1, c2) direction, color, color Linear gradient background .rgradient(c1, c2) color, color Radial gradient background .fullScreen() — Enter fullscreen .exitScreen() — Exit fullscreen .tileMap() — Build TileMap from display.map and display.tile

Usage

const display = new Display();
display.perform();
display.start(800, 600);
display.backgroundColor("#0a0a2a");

const player = new Component(40, 40, "blue", 100, 100);
display.add(player);

Enter fullscreen mode Exit fullscreen mode

Component

Every visible object in your game. Combines position, size, appearance, velocity, physics, and collision.

Constructor

new Component(width, height, color, x, y, type)
// type: "rect" | "image" | "text" (default: "rect")

Enter fullscreen mode Exit fullscreen mode

Properties

Property Type Description .x / .y Number Position in world coordinates .aX / .aY Number Anchor for .fixed() method .width / .height Number Dimensions in pixels .speedX / .speedY Number Velocity .angle Number Rotation angle in radians .angularMovement Boolean If true, uses moveAngle() instead of move() .physics Boolean Enable gravity accumulation .gravity Number Downward pull per frame .gravitySpeed Number Accumulated vertical velocity .bounce Number (0–1) Energy retained on impact .changeAngle Boolean Apply rotation on draw .isCircle Boolean Set by .enableCircleCollision()

Methods

Method Parameters Description .setImage(src) file path Load image — falls back to red rect on error .setColor(color) CSS color Switch back to rect mode .setText(text, font, color) string, string, string Switch to text mode .move() — Apply velocity and gravity (auto-called) .moveAngle() — Move along current angle direction .hitBottom(groundY?) optional number Clamp to floor and bounce .stopMove() — Set speedX/Y to 0 .clicked() — Returns true if clicked .crashWith(other) Component AABB collision detection .enableCircleCollision(radius?) optional number Enable circle collision .crashWithCircle(other) Component Circle-to-circle collision .hide() — Stop drawing (still updates) .show() — Resume drawing .fixed(ctx) ctx=display Lock to screen position (call every frame) .destroy() — Remove permanently from engine

Usage

const player = new Component(40, 40, "blue", 100, 100);
player.physics = true;
player.gravity = 0.4;
player.bounce = 0.2;
display.add(player);

function update() {
    if (display.keys[39]) player.speedX = 4;
    player.hitBottom();
    move.bound(player);
}

Enter fullscreen mode Exit fullscreen mode

Camera

Controls what part of the game world is visible. Access via display.camera.

Properties

Property Type Description .x / .y Number Current camera offset .worldWidth / .worldHeight Number World bounds (clamping) .rotationShake Number Current rotational shake angle

Methods

Method Parameters Description .follow(target, smooth) Component, boolean Track a Component. smooth=true for lerp. .setZoom(amount) Number Scale view (call every frame) .shake(x, y) Number, Number Brief positional shake .shakeRotation(angle) radians Brief rotational shake

Usage

display.camera.worldWidth = 2000;
display.camera.worldHeight = 2000;

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

function onExplosion() {
    display.camera.shake(8, 8);
    display.camera.shakeRotation(0.05);
}

Enter fullscreen mode Exit fullscreen mode

move Utility

Global object with helpers for movement, positioning, physics, and particles.

Movement Methods

Method Parameters Description .bound(id) Component Clamp to all canvas edges .boundTo(id, l, r, t, b) Component, numbers/false Clamp to custom boundaries .teleport(id, x, y) Component, numbers Instantly set position .setX(id, x) Component, number Set X only .setY(id, y) Component, number Set Y only .forward(id, steps) Component, number Move forward along angle .backward(id, steps) Component, number Move backward along angle .turnLeft(id, radians) Component, number Rotate left .turnRight(id, radians) Component, number Rotate right .glideX(id, ms, x) Component, duration, target Ease to X over ms .glideY(id, ms, y) Component, duration, target Ease to Y over ms .glideTo(id, ms, x, y) Component, duration, x, y Ease both axes .project(id, speed, angle, gravity, ground?) Component, speed, degrees, gravity, groundY Projectile motion .hitObject(id, floor) Component, floor Component Land on a Component surface .accelerate(id, ax, ay, mx, my) Component, accelX, accelY, maxX, maxY Add acceleration up to max .decelerate(id, dx, dy) Component, decelX, decelY Reduce speed smoothly .pointTo(id, tx, ty) Component, targetX, targetY Rotate to face target .circle(id, speed) Component, degrees/frame Increment angle for orbit .position(id, direction, offset) Component, “top/bottom/left/right/center”, offset Snap to edge or center .stamp(id) Component Clone a Component

Particle Presets

Method Description .particles.explosion(ps, x, y, n) Orange-red burst with gravity .particles.smoke(ps, x, y) Single upward grey puff .particles.sparkle(ps, x, y) 5 yellow circles, radial spread .particles.rain(ps, x, y, n) Thin blue rects falling fast .particles.blood(ps, x, y, n) Red circles with downward gravity .particles.magic(ps, x, y) 20 multicolour rotating rects

Audio Shortcuts

Method Description .sound.play(name) Play a sound by name .sound.playMusic(name) Start background music .sound.stopMusic() Stop current music .sound.setMasterVolume(vol) Global volume (0–1) .sound.mute() Mute all audio .sound.unmute() Unmute all audio

Usage

function update() {
    move.bound(player);
    move.pointTo(turret, mouse.x, mouse.y);
    if (display.keys[68]) move.accelerate(player, 0.5, 0, 8, 0);
    else move.decelerate(player, 0.3, 0);
}

Enter fullscreen mode Exit fullscreen mode

state Utility

Read-only helpers for querying Component properties.

Method Returns Description .distance(a, b) Number Euclidean distance between two Components .rect(id) [x, y, w, h] Position and size as array .pos(id) “x,y” Position as string .Angle(id) Number Current angle in radians .physics(id) Boolean Whether physics is enabled .changeAngle(id) Boolean Whether rotation is applied on draw

TileMap

Grid-based level system. Tiles are full Components.

Setup

display.tile = [
    new Component(32, 32, "green", 0, 0), // tile 1
    new Component(32, 32, "brown", 0, 0)  // tile 2
];

display.map = [
    [1, 1, 1, 1, 1],
    [1, 0, 2, 0, 1],
    [1, 1, 1, 1, 1]
];

display.tileMap();
display.tileFace.show();

Enter fullscreen mode Exit fullscreen mode

Properties

Property Description display.map 2D number array — level layout (0 = empty) display.tile Component array — tile templates display.tileFace TileMap instance

Methods

Method Parameters Description .show(layer) layer=0 Render a layer into the fake canvas .addMap(map) 2D array Add a new layer .tiles(id) optional tileId Get all tiles or filter by type .crashWith(obj, id) Component, optional tileId Collision against tiles .add(id, tx, ty, layer) tileId, gridX, gridY, layer=0 Place a tile at runtime .remove(tx, ty, layer) gridX, gridY, layer=0 Remove a tile at runtime .rTile(tx, ty) gridX, gridY Get Tile object at position

Usage

// Runtime editing
display.tileFace.add(1, 5, 3);
display.tileFace.remove(5, 3);

// Collision
if (display.tileFace.crashWith(player, 1)) {
    // hit a wall
}

// Get all coins (tile type 2)
const coins = display.tileFace.tiles(2);

Enter fullscreen mode Exit fullscreen mode

Tctxt

Rich text Component with background, padding, alignment, and baseline control.

Constructor

new Tctxt(size, font, color, x, y, align, stroke, baseline, bgColor, padX, padY)

Enter fullscreen mode Exit fullscreen mode

Parameter Type Example size string "22px" font string "Arial" color string "white" x / y number 20, 40 align string "left" / "center" / "right" stroke boolean false (fill) / true (outline) baseline string "alphabetic" / "top" / "middle" bgColor string "rgba(0,0,0,0.6)" or null padX / padY number 12, 6

Methods

Method Description .setText(txt) Update displayed string .fixed() Lock to screen position (call every frame)

Usage

const score = new Tctxt(
    "24px", "Arial", "white", 20, 40,
    "left", false, "alphabetic", "rgba(0,0,0,0.5)", 10, 5
);
score.setText("Score: 0");
display.add(score);

function update() {
    score.setText("Score: " + scoreValue);
    score.fixed();
}

Enter fullscreen mode Exit fullscreen mode

Sound

Load and play a single audio file. Supports overlapping via cloning.

Constructor

new Sound(src, options)

Enter fullscreen mode Exit fullscreen mode

Option Type Default volume Number (0–1) 1 loop Boolean false autoplay Boolean false

Methods

Method Parameters Description .play(volume) optional volume Play sound (clones if overlapping) .stop() — Stop and rewind .pause() — Pause at current position .setVolume(vol) Number (0–1) Change volume .setLoop(loop) Boolean Enable/disable loop .isPlaying() — Returns true if currently playing

Usage

const jump = new Sound("jump.wav");
const music = new Sound("theme.mp3", { loop: true, volume: 0.5 });

jump.play();
music.play();

Enter fullscreen mode Exit fullscreen mode

SoundManager

Central hub for loading, organising, and mixing multiple sounds.

Constructor

window.soundManager = new SoundManager();

Enter fullscreen mode Exit fullscreen mode

Properties

Property Type Default .masterVolume Number (0–1) 1 .sfxVolume Number (0–1) 0.8 .musicVolume Number (0–1) 0.7

Methods

Method Parameters Description .load(name, src, options) name, path, options Preload a sound by name .preload(list, callback) array, function Load multiple sounds .play(name, volume) name, optional volume Play a sound by name .stop(name) name Stop a named sound .playMusic(name, loop) name, boolean Start background music .stopMusic() — Stop current music .setMasterVolume(vol) Number (0–1) Global volume .setSFXVolume(vol) Number (0–1) SFX volume .setMusicVolume(vol) Number (0–1) Music volume .mute() — Mute all audio .unmute() — Unmute all audio

Usage

const sm = new SoundManager();
window.soundManager = sm;

sm.load("coin", "coin.wav");
sm.load("explosion", "boom.wav");
sm.load("music_theme", "theme.mp3");

sm.playMusic("music_theme");

function update() {
    if (collectCoin) sm.play("coin");
}

Enter fullscreen mode Exit fullscreen mode

ParticleSystem

Spawn and manage particles. Must call .update() every frame.

Constructor

const ps = new ParticleSystem(display);

Enter fullscreen mode Exit fullscreen mode

Methods

Method Parameters Description .emit(x, y, options) x, y, options Spawn one particle .burst(x, y, count, options) x, y, count, options Spawn many at once .createEmitter(x, y, options) x, y, options Continuous emitter .update() — Advance all particles (call every frame) .clear() — Remove all particles and emitters

Particle Options

Option Type Default Description life Number 60 Frames until death speedX / speedY Number 0 Initial velocity randomSpeed Number — Random velocity spread gravity Number 0 Downward acceleration friction Number 0.98 Speed multiplier per frame alphaFade Number 0.02 Fade-out rate scale / scaleFade Number 1 / 0 Scale and shrink rate rotationSpeed Number 0 Rotation per frame color String “white” Particle colour colors Array — Random colour picker randomColor Boolean false Pick random from colors type String “rect” “rect”, “circle”, or “image”

Emitter Options

Option Type Default Description rate Number 10 Particles per second randomSpread Boolean false Random direction randomOffset Number 0 Random position radius speed Number 2 Speed for randomSpread

Usage

const ps = new ParticleSystem(display);

function update() {
    ps.update();

    // Single particle
    ps.emit(player.x, player.y, {
        color: "cyan", life: 30, speedY: -2
    });

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

    // Emitter
    const fire = ps.createEmitter(400, 300, {
        rate: 40,
        randomSpread: true,
        speed: 2,
        color: "#ff4400",
        life: 35,
        gravity: -0.06
    });
    fire.setPosition(player.x + 20, player.y + 30);
}

Enter fullscreen mode Exit fullscreen mode

Sprite & AnimatedSprite

Spritesheet animation. All frames in one horizontal image.

Sprite Constructor

new Sprite(image, frameWidth, frameHeight, frameCount, frameSpeed, x, y)

Enter fullscreen mode Exit fullscreen mode

AnimatedSprite Constructor

new AnimatedSprite(image, frameWidth, frameHeight, x, y)

Enter fullscreen mode Exit fullscreen mode

Methods

Method Parameters Description .addAnimation(name, start, end, speed, loop) string, int, int, int, boolean Define a named clip .playAnimation(name) string Switch to named animation .updateAnimation() — Advance frame counter (call every frame) .faceLeft() — Flip horizontally .faceRight() — Unflip horizontally .play() — Resume paused animation .stop() — Pause animation .reset() — Reset to first frame .gotoFrame(frame) int Jump to specific frame

Properties

Property Type Description .paused Boolean True when one-shot animation finishes .loop Boolean Whether animation loops .flipX / .flipY Boolean Flip sprite horizontally/vertically .currentFrame Number Current frame index

Usage

// Basic Sprite
const explosion = new Sprite("explode.png", 64, 64, 8, 4, 300, 200);
display.add(explosion);

// AnimatedSprite with clips
const hero = new AnimatedSprite("hero.png", 64, 64, 400, 300);
hero.addAnimation("idle", 0, 3, 10, true);
hero.addAnimation("walk", 4, 11, 5, true);
hero.addAnimation("jump", 12, 15, 4, false);
display.add(hero);

function update() {
    if (isMoving) hero.playAnimation("walk");
    else hero.playAnimation("idle");
    hero.updateAnimation();
}

Enter fullscreen mode Exit fullscreen mode

Key Code Table

Key Code Key Code ← Left Arrow 37 A 65 ↑ Up Arrow 38 W 87 → Right Arrow 39 D 68 ↓ Down Arrow 40 S 83 Space 32 Enter 13 Escape 27 Shift 16 Z 90 X 88 0–9 48–57 F1–F12 112–123

Fake Canvas (Dual-Renderer)

Offscreen buffer for high-performance rendering. Activated by display.perform().

Properties

Property Type Description .bgComm Component false .scene Number Current scene of fake canvas

Methods

Method Parameters Description .add(component, scene) Component, scene Add static Component to fake canvas .refresh() — Force fake canvas redraw on next frame

Usage

display.perform();
display.start(800, 600);

// Background (renders behind everything)
fake.bgComm = new Component(1600, 1200, null, 0, 0, "image");
fake.bgComm.setImage("sky.png");

// Static objects (tilemaps, backgrounds)
fake.add(backgroundTilemap);

// Dynamic objects (player, enemies)
display.add(player);

Enter fullscreen mode Exit fullscreen mode

Render Order

1. fake.bgComm — Background (sky, distant scenery)
2. tileComm — Tilemap layers (ground, walls)
3. commp — Other fake canvas components (trees, decorations)
4. comm — Main display components (player, enemies, UI with .fixed())

Quick Reference Card

What you want Code Start the engine const display = new Display(); display.start(800, 600); Add a Component const b = new Component(w, h, color, x, y); display.add(b); Move with keys (frame-independent) if(display.keys[39]) player.speedX = 250 * dt; St