LITECANVAS

Litecanvas is a lightweight HTML5 canvas engine suitable for small web games, prototypes, game jams, animations, creative programming, learning game programming and game design, etc. Just install our NPM package or load/download the CDN by adding it as a script tag in your HTML.

CDN: https://unpkg.com/litecanvas/dist/dist.js

NPM: npm install litecanvas

Note: This project is still under development. All feedback is appreciated! For bugs, suggestions or contribuitions open a issue in our Github Repository.

Basic boilerplate

litecanvas({
  loop: {
    init, update, draw, resized,
    tap, tapping, untap, tapped
  }
})

function init() {
  // run once before the game starts
}

function update(dt) {
  // called at 60 fps by default
  // note: `dt` is a fixed deltatime (number)
}

function draw() {
  // use to draw your game graphics
}

function resized() {
  // called when the browser was resized
  // also called once before init()
}

function tap(x, y, tapId) {
  // called when a tap (click/touch) starts
  // equivalent to "mousedown" and "touchstart" browser events

  // note:
  //   Use the tapId to handle multiple touches
  //   Each touch has a unique tapId >= 1
  //   mouse's tapId always equal to 0 (zero)
}

function untap(x, y, tapId) {
  // called when a tap end
  // equivalent to "mouseup" and "touchend" browser events
}

function tapping(x, y, tapId) {
  // called when a tap moves
  // equivalent to "mousemove" and "touchmove" browser events
}

function tapped(x, y, tapId) {
  // called when a tap stars and ends in a short time
  // equivalent to "click" browser events
}

Default Colors

Every time a function asks for a color argument, choose one of these numbers.

Game Configuration

// Initialize the game
litecanvas(settings = {});

// the game loop callbacks
// if loop = undefined, will use global functions:
// window.init(), window.update(dt), window.draw(), etc
settings.loop = {
  init: Function?,
  update: Function?,
  draw: Function?,
  resized: Function?,
  tap: Function?,
  untap: Function?
  tapping: Function?,
  tapped: Function?
}

// the canvas (by default a new canvas is created)
settings.canvas = null

// make the game screen fill the entire screen
settings.fullscreen = true

// the game screen size
// by default, the game fills the entire screen
settings.width = null
settings.height = settings.width || null

// Determines whether the game loop should
// be paused when the "blur" event happens.
settings.pauseOnBlur = true

// Determines whether the canvas should
// scale to fill the canvas
settings.autoscale = true

// target FPS
settings.fps = 60

// enable smooth drawing
settings.antialias = false

// disables antialias
// and force the autoscale to use integers
settings.pixelart = false

// exposes all methods and properties (see below)
// in the global scope
settings.global = true

// set to `false` to disable the default tap handler
// useful to create your own mouse/touch handler
settings.tapEvents = true

// set to `false` to disable the `iskeydown()` method
// useful to create your own keyboard handler
settings.keyboardEvents = true

Global Variables

// the game canvas
CANVAS: HTMLCanvasElement

// the game screen width
WIDTH: number

// the game screen height
HEIGHT: number

// the center X of game screen
CENTERX: number

// the center Y of game screen
CENTERY: number

// the FPS meter
FPS: number

// the amount of time since the game started
ELAPSED: number

// the current mouse's X-position
// or -1 (if the mouse was not used or detected)
MOUSEX: number

// the current mouse's Y-position
// or -1 (if the mouse was not used or detected)
MOUSEY: number

// the default sound played in `sfx()`
DEFAULT_SFX: number[]

// Math constants
PI: number // approximately 3.14 radians (180º)

TWO_PI: number // approximately 6.28 radians (360º)

HALF_PI: number // approximately 1.57 radians (90º)

Functions for Drawing

/**
 * SHAPES DRAWING-RELATED FUNCTIONS
 */

// clear the canvas
// if color is a number, fill the entire screen with which color
// if null just clear the screen
cls(color: number | null): void

// draw a color-filled rectangle
// radii is for border radius
rectfill(x, y, w, h, color = 0, radii?: number | number[]): void

// draw a outline rectangle
// radii is for border radius
rect(x, y, w, h, color = 0, radii?: number | number[]): void

// draw a color-filled circle
circfill(x, y, r, color = 0): void

// draw a outline circle
circ(x, y, r, color = 0): void

// draw a line from one point (x1, y1) to another (x2, y2)
line(x1, y1, x2, y2, color = 0): void

// Sets the thickness of lines
linewidth(value: number): void

// Sets the line dash pattern used when drawing lines
linedash(value: number[], ofsset?: number): void

/**
 * TEXT DRAWING-RELATED FUNCTIONS
 */

// Draw a text
text(x, y, text, color? = 3): void

// Sets the text alignment and baseline
// default values: align = 'start', baseline = 'top'
// see: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textAlign
// see: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textBaseline
textalign(align: string, baseline: string): void

// Sets the font family for texts
textfont(fontName: string): void

// Sets the font size (default: 32)
textsize(size: number): void

// Used to draw a text as 'bold' or/and 'italic'
// use "normal" or empty string to reset the font style
textstyle(style: string)

// Returns the text dimensions like width and height
// when size is omitted, it will use the current
// font size defined by textsize()
textmetrics(text: string, size?: number)

/**
 * IMAGE DRAWING-RELATED FUNCTIONS
 */

// draw a image
image(x, y, image: Image|HTMLCanvasElement): void

// create a offcanvas and to make an image on it
// data can be a array of strings (to draw pixel art)
// see: https://github.com/litecanvas/game-engine/blob/main/samples/pixelart/pixelart.js
// or data can be a function with drawing operations
// see: https://github.com/litecanvas/game-engine/blob/main/samples/paint/paint.js
// the options are:
//   * scale?: default = 1.
//   * canvas?: by default creates a new canvas.
paint(width, height, data: string[]|function, options?): OffscreenCanvas

/**
 * ADVANCED DRAWING-RELATED FUNCTIONS
 */

// Set or get the current canvas context 2D
// see: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D
ctx(context?: CanvasRenderingContext2D): CanvasRenderingContext2D

// save the canvas context
push(): void

// restore the canvas context
pop(): void

// Adds a translation transformation to the current matrix
translate(x: number, y: number): void

// Adds a scaling transformation to the canvas units
// horizontally (x) and/or vertically (y)
scale(x: number, y?: number): void

// Adds a rotation to the transformation matrix
rotate(radians: number): void

// Updates the transformation matrix
// when `resetFirst = true` uses `context.setTransform()`
// see: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setTransform
// when `resetFirst = false` uses `context.transform()`
// see: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/transform
transform(a, b, c, d, e, f, resetFirst = true): void

// Sets the alpha (opacity) value to apply when drawing new shapes and images
// see: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/globalAlpha
alpha(value: number): void

// Fills the current path
// see: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/fill
fill(color: number, path?: Path2D): void

// Outlines the current path
// see: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/stroke
stroke(color: number, path?: Path2D): void

// Create a clipping region based in a Path2D instance
// see: https://github.com/litecanvas/game-engine/blob/main/samples/clip/clip.js
// note: before call `clip()` you must save the context using `push()` and `pop()`
clip(path: Path2D)

// Create (or clone) a Path2D instance
// see: https://developer.mozilla.org/en-US/docs/Web/API/Path2D/Path2D
path(arg?: Path2D | string): Path2D

Functions for Sound

// Plays ZzFX sound effects and returns the played sound array or `false`.
// example: sfx([2,.05,598,.07,0,.19,0,1.32,9.9,-70,0,0,0,0,0,0,.3,.02,0,.04])
// see: https://killedbyapixel.github.io/ZzFX/
// note: if the first argument is omitted, a default sound is played (see DEFAULT_SFX)
// example: sfx() or sfx(null)
sfx(ZzFXparams?: number[], pitchSlide = 0, volumeFactor = 1): number[] | boolean

// Sets the ZzFX global volume factor.
// note: use 0 (zero) to mute all ZzFX sounds.
volume(value: number): void

Functions for Keyboard

// Checks if which key is currently pressed in your keyboard.
// note: you can check if any key is pressed using `iskeydown("any")`.
// note: to check the space key use `iskeydown(" ")`.
iskeydown(key: string): boolean

Math


// Generates a pseudo-random float between min (inclusive)
// and max (exclusive)
rand(min = 0, max = 1.0): number;

// Generates a pseudo-random integer between min (inclusive)
// and max (inclusive)
randi(min = 0, max = 1): number;

// If a value is passed, initializes the random number generator (RNG)
// with an explicit seed value. Otherwise, returns the current seed state.
// By default, the initial seed is the current timestamp (from `Date.now()`).
seed(value: number | null): number;

// Calculates a linear (interpolation) value over `t`.
// example: lerp(0, 50, 0.5) returns 25
// learn more: https://gamedev.net/tutorials/programming/general-and-gameplay-programming/a-brief-introduction-to-lerp-r4954/
lerp(a: number, b: number, t: number): number

// Convert degrees to radians
deg2rad(n: number): number

// Convert radians to degrees
rad2deg(n: number): number

// Constrains a number between `min` and `max`.
// example: clamp(50, 0, 100) return 50
// example: clamp(150, 0, 100) return 100
// example: clamp(-10, 0, 100) return 0
clamp(value: number, min: number, max: number): number

// Wraps a number between `min` (inclusive) and `max` (exclusive).
// example: wrap(50,0,100) return 50
// example: wrap(125, 0, 100) return 25
wrap(value, min, max): number

// Re-maps a number from one range to another.
// example: map(2, 0, 10, 0, 100) returns 20
map(val, min1, max1, min2, max2, withinBounds = false ): number

// Maps a number from one range to a value between 0 and 1.
// example: norm(50, 0, 100) returns 0.5
norm(value, min, max): number

// Returns the sine of a number in radians.
sin(angle: number): number

// Returns the cosine of a number in radians.
cos(angle: number): number

// Returns the tangent of a number in radians.
tan(angle: number): number

// Returns the angle between the positive x-axis
// and the origin (0, 0) to the point (x, y).
atan2(y:number, x: number): number

// Returns the square root of the sum of squares of its arguments.
hypot(...ns: number): number

// Returns the absolute value of a number.
abs(n: number): number

// Rounds up and returns the smallest integer greater than or
// equal to a given number.
ceil(n: number): number

// Returns the value of a number rounded to the nearest integer.
round(n: number): number

// Rounds down and returns the largest integer less than or
// equal to a given number.
floor(n: number): number

// Returns the integer part of a number
// by removing any fractional digits.
trunc(n: number): number

// Returns the smallest of the numbers given as
// input parameters, or `Infinity` if there are no parameters.
// example: min(-10, 15, -1) returns -10
min(...ns: number): number

// Returns the largest of the numbers given as input parameters,
// or `-Infinity` if there are no parameters.
// example: max(-10, 15, -1) returns 15
max(...ns: number): number

// Returns the value of a base raised to a power.
// example: pow(2, 3) returns 2³ or 8
pow(x: number, y: number): number

// Returns E (Euler's number) raised to the power of a number.
// example: exp(1) returns 2.7182... (approximately)
exp(n: number): number

// Returns the square root of a number.
sqrt(n: number): number

// Returns 1 or -1, indicating the sign of a number.
// If the number is 0, it will returns 0.
sign(n: number): number

/** UTILS */

// Check a collision between two rectangles.
// All arguments are required and must be numbers.
colrect(x1, y1, w1, h1, x2, y2, w2, h2): boolean

// Check a collision between two circles.
// All arguments are required and must be numbers.
colcirc(x1, y1, r1, x2, y2, r2): boolean

Engine API

// Loads a plugin.
// see: https://github.com/litecanvas/game-engine/blob/main/samples/plugin-basics/plugin-basics.js
use(callback): void

// Resizes the game canvas.
// Also, emits the "resized" (use `listen` to observe this event).
resize(width: number, height: number): void

// Sets the scale of the game's delta time (dt).
// By default is equal to 1.
// Values higher than 1 increase the speed of time,
// while values smaller than 1 decrease it.
// A value of 0 freezes time (equivalent to pausing).
timescale(value: number): void

// Sets the target FPS at runtime
setfps(value: number): void

// the following functions are most used by plugins...

// Create or update an global variables (and instance properties)
setvar(name: string, value: any): void

// Gets the color value given its index.
// example: getcolor(0) returns "#111"
getcolor(index: number): string

// Registers a game event callback and
// returns a function that unregister this callback.
listen(event: string, callback: Function): Function

// Triggers a game event and call its registered callbacks.
emit(event: string, arg1?, arg2?, arg3?, arg4?): void

Playground Features

Extra packages

The following packages are automatically loaded into the playground:

Public assets

We have a few assets you can use to help prototype ideas.

Cool 1-bit sprites made by Kenney

let sprites;

litecanvas({
  pixelart: true
})

function init() {
  // first, load the spritesheet image
  loadImage('/images/sprites.png', (res, { splitFrames }) => {
    // after loaded, split the image in multiple 16x16 sprites
    sprites = splitFrames(res, 16, 16)
  })
}

function draw() {
  cls(0)
  if (LOADING) return; // wait the asset loader

  push()
  // These sprites are 16x16 (pretty small),
  // so let's zoom in 3x
  scale(3)
  // draw each sprite
  for (let y = 0, index = 0; y < 8; y++) {
    for (let x = 0; x < 8; x++, index++) {
      // each index is a sprite
      image(x * 16, y * 16, sprites[index])
    }
  }
  pop()
}

Monogram font by datagoblin

litecanvas()

function init() {
  // first, load the font
  loadFont('monogram', '/fonts/monogram.ttf')
}

function draw() {
  cls(0)
  if (LOADING) return; // wait the asset loader

  textfont('monogram') // important: set the font family
  textsize(64)
  text(0, 0, 'Hello world')
}

Useful tools

litepixel: Tiny pixel art editor for litecanvas games.
ZzFX Designer: UI to generate ZzFX sounds.