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.
• 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

You can play around with Litecanvas in the Playground without installing nothing.

If you want to test locally, just use one of the installation options.

HTML/CDN

Create a HTML file and add a <script> tag with one of the following CDN links:

Unpkg

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

jsDelivr

<scriptsrc="https://cdn.jsdelivr.net/npm/litecanvas"></script>

ESM Template

For those who are familiar with Node/NPM, we have a basic template.

API

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 CDNloop: { init, update, draw },})functioninit(){// this functions is called one time only// before the game starts}functionupdate(dt){// this functions is called 60 times per second// your game logic goes here}functiondraw(){// 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 480x360litecanvas({width: 480,height: 360,})

Colors

Litecanvas has a default palette with 4 colors:

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

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

Note: You can customize the color palette using the pal() function. Example

Printing messages

litecanvas()functiondraw(){// clear and fill the game screen with color #0 (black)cls(0)// print a gray (color #1) text at x=0, y=0text(0,0,'Hello!!!',1)// use \n to break text linestext(0,30,'multi\nline\ntext')}

By default, the texts are white (color #3).

Live Demo

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()functiondraw(){cls(0)// draw a color filled rectangle at x=10 and y=20// with width=32 and height=32// and color=3 (white)rectfill(10,20,32,32,3)// draw a circle outline at x=64 and y=96// with radius=50// and color=1 (gray)circ(64,96,50,1)}

Live Demo

Drawing sprites

litecanvas({width: 128,})// you can create sprites with strings// each visible char is a pixel// numbers are colors// dots are transparent pixelsletsmile=` .333333. 33333333 33033033 33033033 33333333 30333303 33000033 .333333.`functiondraw(){cls(0)spr(0,0,// position X Ysmile// the pixels)}

Live Demo

Creating and drawing images

litecanvas()// lets create a flag of JapanletjapanFlag=paint(48,32,// the image width and height// we call theses operations once to create a imagefunction(){// lets modify the litecanvas palette to white and redpal(['#fff','#bd0029'])// lets draw the flagcls(0)// the whitecircfill(24,16,8,1)// the sun// reset the palettepal()},{// you can scale your image// by default, scale=1scale: 4,})functiondraw(){cls(0)// draw the our generated japanFlag imageimage(W/2-japanFlag.width/2,// game screen center XH/2-japanFlag.height/2,// game screen center YjapanFlag// the image)}

Live Demo

Note: 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 draw PNG/JPG image files, but you'll need to load them first:

litecanvas()letmyImagefunctioninit(){// load a image from its URLletimg=newImage()img.onload=()=>{myImage=img}img.src='https://litecanvas.js.org/icons/icon-128.png'}functiondraw(){cls(0)if(!myImage){// if not loaded, show this messagetext(10,10,'Loading image...')}else{// when loaded, draw the image fileimage(0,0,myImage)}}

Live Demo

If you need to load multiple assets (images, fonts, music, etc.), I recommend you the Asset Loader Plugin.

Keyboard

litecanvas()functionupdate(){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.letkey=lastkey()}

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

Clicks and Touches

litecanvas()letx,yfunctiontapped(tapX,tapY){// this function is called when a click or a touch happens// tapX and tapY is where the tap happenedx=tapXy=tapY}functiondraw(){cls(0)if(x!=null){// Draw a white circle wherever you tapcircfill(x,y,32,3)}}

Mouse cursor

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

litecanvas()functiondraw(){cls(0)// draw a white circle in the mouse cursor's positioncircfill(MX,MY,32,3)}

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)
• TAU: approximately 6.28 radians (or 360 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.