PIXI Container Helpers

pixi-container-helpers is a set of helper functions help position your containers in various ways.

Installation

To install this module through npm, simply use the following command:

$ npm install pixi-container-helpers

and to use it, you can import it as an ES6 module:

// Webpack
import pixi-container-helpers from 'pixi-container-helpers';

// Browser
import pixi-container-helpers from './node_modules/pixi-container-helpers/pixi-container-helpers.js';

API

pixi-container-helpers is just a set of functions that can be imported individually that work with your existing containers.

gridAlign

Places the items in the container into a grid.

param	type	description	default
container	PIXI.Container	The container to place the items of into a grid.
width	number	The number of items that can fit into the grid horizontally before breaking to a new row.
options	Object
options.horizontalPadding	number	The amount of padding that should be between grid columns.	0
options.verticalPadding	number	The amount of padding that should be between rows.	0

Example:

import { gridAlign } from 'pixi-container-helpers';

const group = new PIXI.Container();

// Places the items of the container into a grid with 4 items per row.
gridAlign(group, 4);

placeOnCircle

Places the items in the container onto a circle.

param	type	description	default
container	PIXI.Container	The container to place the items of onto a circle.
radius	number	The radius of the circle to place the items onto.
options	Object
options.rotateItems	boolean	Indicates whether the items should be rotated to point towards the center of the circle or not.	false
options.rotateItemsInverse	boolean	Indicates whether the items should be rotated so that the opposite end points towards the center of the circle or not.	false

Example:

import { placeOnCircle } from 'pixi-container-helpers';

const group = new PIXI.Container();

// Places the items of the container onto a circle with a radius of 50.
placeOnCircle(group, 50);

placeOnLine

Places the items in the container onto a line.

param	type	description	default
container	PIXI.Container	The container to place the items of onto a line.
startX	number	The starting x location of the line.
startY	number	The starting y location of the line.
endX	number	The ending x location of the line.
endY	number	The ending y location of the line.

Example:

import { placeOnLine } from 'pixi-container-helpers';

const group = new PIXI.Container();

// Places the items of the container onto a line going from (10, 10) to (200, 300).
placeOnLine(group, 10, 10, 200, 300);

placeOnPolygon

Places the items in the container onto a polygon.

param	type	description	default
container	PIXI.Container	The container to place the items of onto a polygon.
polygon	Polygon	The Polygon object to place the items onto.

Example:

import {
    Vector,
    Polygon,
    placeOnPolygon,
} from 'pixi-container-helpers';

const group = new PIXI.Container();

// Places the items of the container onto a square.
const polygon = new Polygon(new Vector(100, 100), [
            new Vector(0, 0),
            new Vector(100, 0),
            new Vector(100, 100),
            new Vector(0, 100),
        ]);
placeOnPolygon(group, polygon);

placeInCircle

Places the items in the container into a circle in a random fashion.

param	type	description	default
container	PIXI.Container	The container to place the items of into a circle.
radius	number	The radius of the circle to place the items into.

Example:

import { placeInCircle } from 'pixi-container-helpers';

const group = new PIXI.Container();

// Places the items of the container into a circle with a radius of 50.
placeInCircle(group, 50);

placeInPolygon

Places the items in the container into a polygon in a random fashion.

param	type	description	default
container	PIXI.Container	The container to place the items of into a polygon.
polygon	Polygon	The Polygon to place the items of into.

Example:

import {
    Vector,
    Polygon,
    placeInPolygon,
} from 'pixi-container-helpers';

const group = new PIXI.Container();

// Places the items of the container into a square.
const polygon = new Polygon(new Vector(100, 100), [
            new Vector(0, 0),
            new Vector(100, 0),
            new Vector(100, 100),
            new Vector(0, 100),
        ]);
placeInPolygon(group, polygon);

setAlpha

Sets the alpha of the container items from a starting value to an unknown value with an optional step value that can be added to increase the rate of change.

param	type	description	default
container	PIXI.Container	The container to set the alpha of the items of.
start	number	The starting alpha of the container items.
step	number	The rate of change of the alpha.	1

Example:

import { setAlpha } from 'pixi-container-helpers';

const group = new PIXI.Container();

// Sets the alpha of the items in ascending order.
setAlpha(group, 0, 1 / 5);

setAlphaEase

Sets the alpha of the items in the container from a starting value to an ending value using a provided easing function.

param	type	description	default
container	PIXI.Container	The container to set the alpha of the items of.
start	number	The starting alpha of the container items.
end	number	The ending alpha of the container items.
easing	Function	The easing function to use which accepts a single parameter, time.

Example:

import { setAlphaEase } from 'pixi-container-helpers';

/**
 * Ease-In Sine.
 * 
 * @param {number} x A value between 0 and 1 representing the percent of the animation that has completed.
 * 
 * @returns {number} Returns a value between 0 and 1 which should be used to multiply the value to animate by.
 */
function easeInSine(x) {
    return 1 - Math.cos((x * Math.PI) / 2);
}

// Eases opacity of the items in the group from 0 to 1 using a ease-in-sine function.
setAlphaEase(group, 0, 1, easeInSine);

rotateAroundPoint

Places the items onto a circle and rotates them around a pivot point. Note that the method needs to be placed in some sort of game loop in order to update the positions of the items.

param	type	description	default
container	PIXI.Container	The container to set the alpha of the items of.
x	number	The x location of the point to rotate around.
y	number	The y location of the point to rotate around.
radius	number	The radius of the circle to place the items on.
delta	number	The delta time from the update function.
speed	number	Used to slow down or speed up the rotation of the items.	1

Example:

import { rotateAroundPoint } from 'pixi-container-helpers';
import Deltaframe from 'deltaframe';

const deltaframe = new Deltaframe;

// Create the group and set the pivot point to it's center so that it will rotate around it's center point.
const group = new PIXI.Container();
group.pivot.set(group.width / 2, group.height / 2);

// Every frame update we set the group to rotate around its pivot point.
deltaframe.start((time, delta, deltaAverage) => rotateAroundPoint(group, 100, 100, delta));

Tests

The tests for pixi-container-helpers are browser based so to run them you will first need to start the local testing server like so:

$ npm run test

then you will need to navigate to https://localhost:3000 in your browser to run all of the available tests.

License

MIT