Litecanvas

 

Litecanvas is a lightweight HTML5 canvas 2D engine suitable for small web games, prototypes, game jams, animations, creative coding, learning game programming and game design, etc.

   

Warning

This project is still in the "alpha" stage. Break changes may occur frequently. All feedback is welcome and appreciated.

Features

• Tiny: Only ~4KB (minified + gzipped).
• Simple API: Just few functions to draw shapes and some utilities.
• Predefined colors: Just use a number (from 0 to 11) to choose a color in our 12-color palette.
• ZzFX: Play or create sound effects with ZzFX.
• Extensible: Use or create plugins to add functionalities or change the engine.
• Playground: Access or install the playground webapp to code and share games (even offline).

Getting Started

Installation

You can get started using our online playground.

Or installing our package via NPM:

npm i litecanvas

Or just create a HTML file and add a <script> tag with our CDN link:

<script src="https://unpkg.com/litecanvas"></script>

Basic game structure

litecanvas({
    // This is required only in ESM format.
    // Note: the next examples will assume that you are
    // testing through the playground or the CDN
    loop: { init, update, draw },
})

function init() {
    // this functions is called one time only
    // before the game starts
}

function update(dt) {
    // this functions is called 60 times per second
    // your game logic goes here
}

function draw() {
    // this functions is called 60 times per second
    // your game rendering goes here
}

Note: if you installed via NPM you need to import the package first:
import litecanvas from "litecanvas"

Set the width and height of the game screen

// example: a game screen size equal to 480x360
litecanvas({
    width: 480,
    height: 360,
})

Colors

Litecanvas has a default palette with 12 colors:

#	Color	#	Color
0	Black	6	Dark blue
1	Dark grey	7	Light blue
2	Light grey	8	Dark green
3	White	9	Light green
4	Red	10	Brown
5	Yellow	11	Beige

Each time a Litecanvas' function ask for a color, you should use an of theses colors by its index.

// example: draw a white rectangle
color = 3
rectfill(0, 0, 32, 32, color)

Printing messages

litecanvas()

function draw() {
    // clear and fill the game screen with color #0 (black)
    cls(0)

    // print a red "Hello" text at x=0, y=0
    text(0, 0, 'Hello', 4)
}

Drawing shapes

You can use the following functions to draw shapes:

• rect(x, y, width, height, color) draw a rectangle outline
• rectfill(x, y, width, height, color) draw a color-filled rectangle
• circ(x, y, radius, color) draw a circle outline
• circfill(x, y, radius, color) draw a color-filled circle
• oval(x, y, rx, ry, color) draw a ellipse outline
• ovalfill(x, y, rx, ry, color) draw a color-filled ellipse

litecanvas()

function draw() {
    cls(0)

    // draw a color filled rectangle at x=0 and y=0
    // with width=32 and height=32
    // and color=3 (white)
    rectfill(0, 0, 32, 32, 3)

    // draw a circle outline at x=64 and y=32
    // with radius=40
    // and color=5 (yellow)
    circ(64, 32, 40, 5)
}

Drawing sprites

litecanvas({
  width: 128
})

// you can create sprites with strings
// each visible char is a pixel
// numbers are colors
// dots are transparent pixels
const smile = `
    .555555.
    55555555
    55055055
    55055055
    55555555
    50555505
    55000055
    .555555.`

function draw() {
    cls(0)

    spr(
        0, 0, // position X Y
        8, 8, // sprite Width and Height
        smile // the pixels
    )
}

Creating and drawing images

litecanvas()

// lets create the flag of the Japan
const japan = paint(
    48, 32, // image width and height
    function () {
        // the result of this drawings
        // goes to an offscreen canvas
        rectfill(0, 0, 48, 32, 3)
        circfill(24, 16, 8, 4)
    }, {
        // you can scale your image
        // by default, scale=1
        scale: 4
    }
)

function draw() {
    cls(0)

    // now the japan variable holds a image
    image(W/2 - japan.width/2, H/2 - japan.height/2, japan)
}

It's very useful when you need to draw something the same way every time. This way, you create an image of that drawing, working as a kind of cache.

You can also use the image() function to draw PNG/JPG images, but you'll need to load them first:

litecanvas()

let PngImage

function init() {
    // load a image from its URL
    const img = new Image()
    img.onload = () => {
        PngImage = img
    }
    img.src = 'https://litecanvas.js.org/icons/icon-128.png'
}

function draw() {
    cls(0)

    if (!PngImage) {
        // if not loaded, show this message
        text(10, 10, 'Loading image...')
    } else {
        // when loaded, draw the image file
        image(0, 0, PngImage)
    }
}

To help you load multiple assets (images, fonts, music, etc.), you can I recommend you the Asset Loader Plugin.

Keyboard

litecanvas()

function update() {
    if (iskeydown('space')) {
        // checks if the spacebar key is down
    }

    if (iskeypressed('a')) {
        // checks if the "a" key was pressed
    }

    // Returns the last key pressed in your keyboard.
    const key = lastkey()

    console.log(key)
}

Note: you can call iskeydown() or iskeypressed() (without arguments) to check for any key.

Clicks and Touches

litecanvas()

let x, y

function tapped(tapX, tapY) {
    // this function is called when a click or a touch happens
    // tapX and tapY is where the tap happened
    x = tapX
    y = tapY
}

function draw() {
    cls(0)

    if (x != null) {
        // Draw a red circle wherever you tap
        circfill(x, y, 32, 4)
    }
}

Mouse cursor

Use MX and MY variables (automatically declared by Litecanvas) to track the position of the mouse cursor.

litecanvas()

function draw() {
    cls(0)

    // draw a red circle in the mouse cursor's position
    circfill(MX, MY, 32, 4)
}

Litecanvas' variables

Like MX and MY, Litecanvas also declares these other variables:

• W: the width of the game canvas
• H: the height of the game canvas
• T: the amount of seconds since the game started
• PI: approximately 3.14 radians (or 180 degrees)
• TWO_PI: approximately 6.28 radians (or 360 degrees)
• HALF_PI: approximately 1.57 radians (or 90 degrees)

And much more!

You can find a complete list of everything litecanvas has to offer on our cheatsheet.

Demos

Try some demos in the playground:

• Bouncing Ball
• Scroller
• 3D projection
• Rendering Benchmark

See other demos in samples folder

Contributing

1. Fork this repository and clone it.
2. Install the dependencies: npm i
3. Create a new branch and make your changes.
4. Format the code: npm run format
5. Create new tests in tests directory, if necessary.
6. Test with npm run test
7. Create your pull request.
8. Done!

Note: You'll need Node.JS installed in your machine.

Inspirations

• floppy: a micro game engine for beginners.
• PICO-8: fantasy console for making, sharing and playing tiny games.
• js13kGames: a JavaScript coding competition with size limit set to 13 kilobytes.
• raylib: a simple and easy-to-use gamedev library.
• p5.js/Processing: a library for creative coding.
• Pygame Zero: A zero-boilerplate games programming framework for Python 3.