matter-map-creator

Matter Maps Creator

This project was created with the intention of helping to create dynamic 2d maps using matter.js, any problem found create an issue, if you want to contribute to the project create a pull request to merge.

This project is a package of modules you can install it in your project to use it in the following ways:

Using npm:

npm install matter-maps-creator

Using yarn:

yarn add matter-maps-creator

Documentation

As said before this is a very simple project to use and understand, so below I will document all the classes and methods that it contains and their features, each class and method is documented within the code itself so when hovering over them inside from a code editor it will be possible to see what each one does.

Classes:

Classes	Utility
Map	This is one of the main classes of the project, it serves to rederize the map, create and add objects to the world.
Animations	Adds animations to bodies.
Particles	Create particles in the world. WARN: IT'S STILL IN TESTS.

Map methods:

Methods	Utility
addCustom	Add a custom body. parameters: bodies, callback?
addRectangle	Add a rectangle body. parameters: x, y, w, h, color, callback?
addCircle	Add a circle body. parameters: x, y, r, color, callback?
addPolygon	Add a polygon body. parameters: x, y, s, r, color, callback?
addTrapezoid	Add a trapezoid body. parameters: x, y, w, h, sl, color, callback?
platform	Add a platform to map. parameters: x, y, size, color, callback?
wreckingball	Add a wreckingball to map. parameters: x, y, size, color, length, chainWidth, chainColor, callback?.
ragdoll	Add a ragdoll to map. parameters: x, y, scale, color, callback?.
car	Add a car to map. parameters: x, y, size, color, wheelAColor, wheelBColor, callback?.
chain	Add a chain to map. parameters: x, y, size, length, color, callback?.
bridge	Add a bridge to map. parameters: x, y, size, length, color, callback?.
build	This method being the last to be invoked, to render the map. parameters: callback?.

Map methods parameters:

addCustom

params	utility
bodies	Body or bodies to be rendered. type: Matter.Body or Matter.Body[]
callback?	Callback function.

addRectangle

params	utility
x	Sets the x Position of the body. type: number
y	Sets the y Position of the body. type: number
w	Sets the width of the body. type: number
h	Sets the height of the body. type: number
color	Body color. type: string
callback?	Callback function.

addCircle

params	utility
x	Sets the x Position of the body. type: number
y	Sets the y Position of the body. type: number
r	Sets the radius of the body. type: number
color	Body color. type: string
callback?	Callback function.

addPolygon

params	utility
x	Sets the x Position of the body. type: number
y	Sets the y Position of the body. type: number
s	Sets the sides of the body. type: number
r	Sets the radius of the body. type: number
color	Body color. type: string
callback?	Callback function.

addTrapezoid

params	utility
x	Sets the x Position of the body. type: number
y	Sets the y Position of the body. type: number
w	Sets the width of the body. type: number
h	Sets the height of the body. type: number
sl	Sets the slope of the body. type: number
color	Body color. type: string
callback?	Callback function.

platform

params	utility
x	Sets the x Position of the body. type: number
y	Sets the y Position of the body. type: number
size	Sets the size of the body. type: number
color	Body color. type: string
callback?	Callback function.

wreckingball

params	utility
x	Sets the x Position of the body. type: number
y	Sets the y Position of the body. type: number
size	Sets the size of the body. type: number
color	Body color. type: string
length	Defines the size of the chain. type: number
chainWidth	Defines the width of the chain. type: number
chainColor	Chain color. type: string
callback?	Callback function.

ragdoll

params	utility
x	Sets the x Position of the body. type: number
y	Sets the y Position of the body. type: number
scale	Sets the scale of the ragdoll. type: number
color	Body color. type: string
callback?	Callback function.

car

params	utility
x	Sets the x Position of the body. type: number
y	Sets the y Position of the body. type: number
size	Sets the size of the body. type: number
color	Body color. type: string
wheelAColor	wheelA color. type: string
wheelBColor	wheelB color. type: string
callback?	Callback function.

chain

params	utility
x	Sets the x Position of the body. type: number
y	Sets the y Position of the body. type: number
size	Sets the size of the body. type: number
length	Sets the length of the chain. type: number
color	Body color. type: string
callback?	Callback function.

bridge

params	utility
x	Sets the x Position of the body. type: number
y	Sets the y Position of the body. type: number
size	Sets the size of the body. type: number
length	Sets the length of the chain. type: number
color	Body color. type: string
callback?	Callback function.

build

callback?	Callback function.

Map class use example:

// setup.js
import { Composite, Engine, Mouse, MouseConstraint, Render, Runner } from 'matter-js';

function setup() {
  const engine: Engine = Engine.create();
  const render: Render = Render.create({
    element: document.body,
    engine: engine,
    options: {
      width: window.innerWidth,
      height: window.innerHeight
    }
  });
  Render.run(render);

  const runner: Runner = Runner.create();
  Runner.run(runner, engine);
  
  return {
    engine: engine,
    render: render,
    runner: runner
  };
}
export default setup;

// mapUseExample.js
import { Map } from 'matter-maps-creator';
import setup from 'setup.js';

const { engine } = setup();

const worldXSize = 30000;
const worldYSize = 15000;
const walls = true;
const map = new Map(engine, worldXSize, worldYSize, walls);

map.addRectangle(3000, 3000, 200, 200, '#005');
map.ragdoll(4000, 4000, 5, '#005');
const platform = map.platform(6000, 5000, 1200, '#606090');

console.log(`Platform: ${platform.id} has rendered.`);

map.build(() => console.log('The map was built and rendered.'));

Animations methods:

Methods	Utility
rotate	Rotates a body constantly. parameters: body, rotation
moveLeft	Constantly moves one body to the left. parameters: body, distance, speed
moveRight	Constantly moves one body to the right. parameters: body, distance, speed
moveUp	Constantly moves one body to the up. parameters: body, distance, speed
moveDown	Constantly moves one body to the down. parameters: body, distance, speed
trail	Create a trail through which the body passes. parameters: body, disappearAfter, appearWhenSpeed, color
cameraFocus	The camera will then follow the body or bodies. parameters: bodies, zoom, center

Animations methods parameters:

rotate

params	utility
body	It is the body that will have the application of the animation. type: Matter.Body
rotation	Sets the rotation speed and direction. type: number

moveLeft

params	utility
body	It is the body that will have the application of the animation. type: Matter.Body
distance	Represents the maximum distance the body will travel in the animation. type: number
speed	Represents the speed of movement up to the maximum distance, the greater the distance, the greater the speed to balance. type: number

moveRight

params	utility
body	It is the body that will have the application of the animation. type: Matter.Body
distance	Represents the maximum distance the body will travel in the animation. type: number
speed	Represents the speed of movement up to the maximum distance, the greater the distance, the greater the speed to balance. type: number

moveUp

params	utility
body	It is the body that will have the application of the animation. type: Matter.Body
distance	Represents the maximum distance the body will travel in the animation. type: number
speed	Represents the speed of movement up to the maximum distance, the greater the distance, the greater the speed to balance. type: number

moveDown

params	utility
body	It is the body that will have the application of the animation. type: Matter.Body
distance	Represents the maximum distance the body will travel in the animation. type: number
speed	Represents the speed of movement up to the maximum distance, the greater the distance, the greater the speed to balance. type: number

trail

params	utility
body	It is the body that will have the application of the animation. type: Matter.Body
disappearAfter	Time to particle spawned disappear after rendered. type: number
appearWhenSpeed	Appear when body velocity is upper to informed number. type: number
color	Particle color. type: string

cameraFocus

params	utility
bodies	Body or bodies to camera focus. type: Matter.Body or Matter.Body[]
zoom	Zoom of camera. type: number
center	If the camera stand centered with body. type: number

Animations class use example:

// setup.js
import { Composite, Engine, Mouse, MouseConstraint, Render, Runner } from 'matter-js';

function setup() {
  const engine: Engine = Engine.create();
  const render: Render = Render.create({
    element: document.body,
    engine: engine,
    options: {
      width: window.innerWidth,
      height: window.innerHeight
    }
  });
  Render.run(render);

  const runner: Runner = Runner.create();
  Runner.run(runner, engine);
  
  return {
    engine: engine,
    render: render,
    runner: runner
  };
}
export default setup;

// mapUseExample.js
import { Map, Animations } from 'matter-maps-creator';
import setup from 'setup.js';

const { engine, render } = setup();

const worldXSize = 30000;
const worldYSize = 15000;
const walls = true;
const map = new Map(engine, worldXSize, worldYSize, walls);
const animations = new Animations(engine, render);

const player = map.addRectangle(2500, 500, 200, 200, '#005');
animations.cameraFocus(player, 20, true);

const platform = map.platform(2500, 3000, 1200, '#606090');
animations.moveRight(platform, 700, 0.014);
animations.moveDown(platform, 900, 0.018);

map.build(() => console.log('The map was built and rendered.'));

Particles methods:

Methods	Utility
directional	It generates directional particles. parameters: options
explosion	It generates explosion of particles. parameters: options
trail	Create a trail through which the body passes. parameters: options
stop	Stop the execution of the particle creation. parameters: executeDelay

Particles methods parameters:

directional

options	utility
x	Defines the x spawn position of the particles. type: number
y	Sets the particle spawn y position. type: number
maxX	Defines the maximum width of the particle at which it will appear. type: number
maxY	Defines the maximum height of the particle at which it will appear. type: number
force	The force with which the particles will be thrown and direction. type: vector - { x: number, y: number }
size	Size of particles. type: number
color	Color of particles. type: string
collision	If particles collide with bodies. type: boolean

explosion

options	utility
x	Defines the x spawn position of the particles. type: number
y	Sets the particle spawn y position. type: number
size	Size of particles. type: number
initialForce	Initial force to use as a reference for mass calculation. type: number
color	Color of particles. type: string
collision	If particles collide with bodies. type: boolean

trail

options	utility
body	Size of particles. type: number
initialForce	Initial force to use as a reference for mass calculation. type: number
color	Color of particles. type: string
collision	If particles collide with bodies. type: boolean

stop

executeDelay	Delay in the execution of the stop code. type: number

Particles class use example:

// setup.js
import { Composite, Engine, Mouse, MouseConstraint, Render, Runner } from 'matter-js';

function setup() {
  const engine: Engine = Engine.create();
  const render: Render = Render.create({
    element: document.body,
    engine: engine,
    options: {
      width: window.innerWidth,
      height: window.innerHeight
    }
  });
  Render.run(render);

  const runner: Runner = Runner.create();
  Runner.run(runner, engine);
  
  return {
    engine: engine,
    render: render,
    runner: runner
  };
}
export default setup;

// mapUseExample.js
import { Map, Animations, Particles } from 'matter-maps-creator';
import setup from 'setup.js';

const { engine, render } = setup();

const worldXSize = 30000;
const worldYSize = 15000;
const walls = true;
const map = new Map(engine, worldXSize, worldYSize, walls);
const animations = new Animations(engine, render);

const playerParticle = new Particles(engine, 50, 300);

const player = map.addRectangle(2500, 500, 200, 200, '#005');
animations.cameraFocus(player, 20, true);
  
setInterval(() => {
  playerParticle.explosion({
    x: player.position.x,
    y: player.position.y,
    size: 15,
    initialForce: 0.1,
    color: '#005',
    collision: false
  });
}, 500);
  
const platformParticle = new Particles(engine, 50, 800);
  
const platform = map.platform(2500, 3000, 1700, '#606090');
  
platformParticle.directional({
  x: platform.position.x,
  y: platform.position.y,
  maxX: 1200,
  maxY: 500,
  force: { x: 0, y: -0.1 },
  size: 15,
  color: '#005',
  collision: false
});

map.build(() => console.log('The map was built and rendered.'));