Home

Awesome

logo

A 2kb webgl 2d sprite renderer, designed for Js13kGames.

NPM version

Demo

Live examples

Install

$ npm install js13k-2d

Then with a module bundler like rollup or webpack, use as you would anything else:

// using ES6 modules
import Renderer from 'js13k-2d';

// using CommonJS modules
var Renderer = require('js13k-2d');

The UMD build is also available on unpkg:

<script src="https://unpkg.com/js13k-2d/dist/renderer.umd.js"></script>

You can find the library on window.Renderer.

Usage

// Import the library
import Renderer from 'js13k-2d';

// Extract classes
const { Point, Sprite } = Renderer;

// Get canvas element, where the scene will be rendered to.
const view = document.getElementById('view');

// Create a scene
const scene = Renderer(view);

// Set background color
scene.background(1, 1, 1);

// Create a texture
const atlas = scene.texture(image);

// Create a frame
const frame = atlas.frame(Point(), Point(32));

// Create a sprite
const sprite = Sprite(frame);

// Add a sprite to the scene
scene.add(sprite);

const loop = () => {
    // Get the actual canvas size
    scene.resize();
    const { width, height } = view; // or scene.gl.canvas

    // Change sprite position
    sprite.position.set(Math.random() * width, Math.random() * height);

    // Render a scene
    scene.render();

    requestAnimationFrame(loop);
};

loop();

For a better understanding of how to use the library, read along or see example folder and have a look at the live examples.

API (in progress)

This library is under development and should be considered as an unstable. There are no guarantees regarding API stability until the release 1.0.

Renderer.Point

The Point object represents a location in a two-dimensional coordinate system, where x represents the horizontal axis and y represents the vertical axis. The class provides the most minimal functionality.

new Renderer.Point(x, y)

Creates a point with a x and y position. If y is omitted, both x and y will be set to x (0 by default). The presence of the keyword new is optional, so it is recommended to omit it for size reduction.

Properties

x: number

Position of the point on the x axis.

y: number

Position of the point on the y axis.

Methods

set(x, y): this

Sets the point to a new x and y position. If y is omitted, both x and y will be set to x (0 by default).

Tips

For a smaller size reduction, you can use this class as the base for your vector class:

class Vector extends Renderer.Point {
    clone() {
        return new Vector(this.x, this.y);
    }

    copy(vec) {
        this.x = vec.x;
        this.y = vec.y;
        return this;
    }

    add(vec) {
        this.x += vec.x;
        this.y += vec.y;
        return this;
    }

    cross(vec) {
        return this.x * vec.y - this.y * vec.x;
    }

    dot(vec) {
        return this.x * vec.x + this.y * vec.y;
    }

    // etc...
}

And even override Renderer.Point. Note: you need to do this before calling Renderer.

Renderer.Point = Vector;

// then
const view = document.getElementById('view');
const scene = Renderer(view);

console.log(new Renderer.Point() instanceof Vector); // true
console.log(scene.camera.at instanceof Vector); // true
console.log(Renderer.Sprite(frame).position instanceof Vector); // true
// etc

Renderer(canvas, options)

Returns an Renderer instance.

Parameters

See WebGL context attributes. Note that the default values ​​for alpha and antialias are overridden to false.

Properties

gl: WebGLRenderingContext

MDN

camera

The object that defines the camera. Has the following properties:

Methods

background(r, g, b, a)

Sets the background color. Values ​​from 0 to 1.

texture(source, alphaTest, smooth, mipmap)

Creates a texture object that stores the information that represents an image.

Parameters

Together, smooth and mipmap are provided with 4 modes of texParameter: NEAREST, LINEAR, NEAREST_MIPMAP_LINEAR and LINEAR_MIPMAP_LINEAR. Note: if mipmap is set to true, then the width and height of the source must be a power of 2.

The Texture object cannot be added to the display list directly. Instead use it as the texture for a Sprite and Frame. You can directly create a texture from an image and then reuse it multiple times like this:

const { Point, Sprite } = Renderer;

const scene = Renderer(view);

const texture = scene.texture(image);

const sprite1 = Sprite(texture);
sprite1.position.set(100, 100);

const sprite2 = Sprite(texture, {
    position: Point(100, 200),
});

scene.add(sprite1);
scene.add(sprite2);

scene.render();
Texture properties

texture.anchor: Renderer.Point

The anchor sets the origin point of the texture. The default is {0,0} this means the texture's origin is the top left. Setting the anchor to {0.5,0.5} means the texture's origin is centered. Setting the anchor to {1,1} would mean the texture's origin point will be the bottom right corner. It's also the pivot point of the sprite that it rotates around.

texture.size: Renderer.Point

Determines the size of the texture in pixels with sprite.scale equal to (1, 1). When creating a texture, its size is set equal to the size of the source.

Texture methods

texture.frame(origin, size, anchor)

Creates a Frame object that stores the information that represents part of an image.

Parameters

The Frame object cannot be added to the display list directly. Instead use it as the texture for a Sprite. The Frame has the same set of properties as the texture.

Example:

const { Point, Sprite } = Renderer;

const scene = Renderer(view);

const atlas = scene.texture(image);

const frame1 = atlas.frame(Point(), Point(32));
const frame2 = atlas.frame(Point(32, 0), Point(32));

const sprite1 = Sprite(frame1);
sprite1.position.set(100, 100);

const sprite2 = Sprite(frame2, {
    position: Point(100, 200),
});

scene.add(sprite1);
scene.add(sprite2);

scene.render();

layer(z)

Gets or creates a layer from the given z.

add(sprite)

Adds a sprite to the layer with z equal to 0.

resize()

Makes inner canvas size equal to the displayed size of the canvas. Returns true if the change was made and false otherwise. This method is called inside render automatically. Directly it needs to be called only if it is necessary to get the actual canvas size before render or to determine the fact of changing the size of the canvas.

render()

Displays all the sprites with the visible field set to true.

Renderer.Layer

Properties

z: number

Z-index of the layer. The larger, the higher the layer is.

Methods

add(sprite)

Adds the sprite to the layer. If the sprite is already present in another layer, it will be removed from it.

Renderer.Sprite

The Sprite object is the textured objects that are rendered to the screen.

new Renderer.Sprite(frame, props)

Creates a sprite from the frame with the specified properties. The presence of the keyword new is optional, so it is recommended to omit it for size reduction.

Properties

frame: frame or texture

alpha: number

The opacity of the sprite.

position: Renderer.Point

The coordinates of the sprite.

rotation: number

The rotation of the sprite in radians.

scale: Renderer.Point

The scale factor of the sprite.

tint: number

The tint applied to the sprite. This is a hex value. A value of 0xffffff will remove any tint effect.

visible: boolean

The visibility of the sprite.

Methods

remove()

Removes the sprite from the scene.