breadjs v0.0.36

Bread.js

Bread is a JS library to help Developers who wants to include animations or some interaction using HTML5 Canvas. Acoording to its philosophy, Bread allows you to create a 'world' or 'universe', then you can create bodies, give them a shape and add them to the 'universe'. With the main module you can create 'universe' objects and 'body' objects, these are parent modules. Rectangles, Circles, Sprites, etc, are descendents of Body and they are attached to the behaviour of Body.

Hierarchy:

• bread.js

  • universe.js

  • body.js

    • point.js

      • line.js

        • rectangle.js

      • arc.js

        • circle.js

Library extension

If you want to extend or add new features to the library, please follow this steps:

• You must have installed Node.js (https://nodejs.org/en/) and Node Package Manager
• Run: npm install
• This project is modular, so you must include or modify modules in the src folder.
• Execute grunt build if you want to watch changes over src folder.
• If you just want to build dist/bread.js without watching src, run grunt.
• If you include new files, don't forget to add them in sources, in the Gruntfile.js.

Getting started

Run npm install breadjs . The library is in the dist folder, so include dist/bread.js in your project.

Once you are done with the installation you must create a canvas element, this element will be associated to the universe object, this object will be explained further in this document.

<canvas id="canvas_el"></canvas>

Factories

The library provides a set of factories which provides a handy way to create objects. You may also create objects if you invoke their class. I.E. if we want to create a body of type circle, we can do it like this:

var firstPoint = Bread.circle({
  x: 4, 
  y: 5, 
  angle: 3.1416,
  radius: 10,
  fill:false
});

or

var firstPoint = new Bread.Circle({
    x: 4,
    y: 5,
    angle: 3.1416 
});
firstPoint.defRaduis = 10;
firstPoint.fill = false;

The factories available are the following ones:

• universe.
• point.
• circle.
• rectangle.
• line.
• arc.
• groups.
• text.

Universe

Create a universe by calling the universe factory from the Bread object, you must pass as an argument to this method an object that contains 2 properties: the el property and the frame rate (in case you want to make an animation).

var canvas = document.getElementById('canvas_el');
var firstUniverse = Bread.universe({
    el: canvas,
    frate: 1000 / 24
});

Attributes

• el: Is the canvas HTML element.
• frate: Frame rate for the animation.

Methods

• addIt: Adds a body to the universe, this allows the vody to be rendered in the canvas element:

  firstUniverse.addIt(body);

  body: Is an object of body type. (view the Body documentation)

• addGroup: Adds a group of bodies, it recieves an array of bodies or group (Groups will be covered latter)

  firstUniverse.addGroup([body1, body2, ...]);

• removeIt: Adds a body from the universe:

  firstUniverse.removeIt(body);

  body: Is an object of body type. (view the Body documentation)

• animation: Animates the universe using setTimeout. It takes a callback function were you put all the code you want to be animated

  firstUniverse.animation(function() {..})

Body

Body is the core or the base of all objects that are going to be used inside the universe, it provides some generic methods that all bodies share (accelerate, move, etc).

You may extend this class to your own classes.

var MyMixin = function () {...}
MyMixin.prototype = {...};
var Body = Bread.Body;
var MyCustomBody =  Bread.augment(Body, [MyMixin]);

Attributes

This attributes are the same for all bodies.

• x: position in x.
• y: position in y.
• xspeed: speed over the x axis.
• yspeed: speed over the y axis.
• speed: body speed.
• angle: body angle.
• friction: body friction.

Methods

This methods can be found on all bodies.

• accelerate: sets an acceleration to the body, it receives 2 arguments:

  var accx = 0.1;
  var accy = 0.2;
  body.accelerate(accx, accy);

  accx: Is the increment of the speed over the x axis (type number)

  accy: Is the increment of the speed over the y axis (type number)

• bounce: makes a body bounce by modifying its speed

  var bnx = 0.1;
  var bny = 0.2;
  body.bounce(bnx, bny);

  bnx: Is the speed over the x axis (type number)

  bny: Is the speed over the y axis (type number)

• impulse: changes the body direction and speed, also specifies a friction

  var speed = 0.1;
  var frict = 0.2;
  var angle = PI/2;
  body.impulse(speed, frict, angle);

  speed: Is the new body speed (type number)

  frict: It will reduce the speed when the move method is invoked (type number)

  angle: The new body angle in radians (type number)

• move: changes the position of the object according to its speed:

  body.move();

Point

Point is the smallest (atomic) body that exists in the library, everything has a point.

Class Name: Point;

Factory example:

var pnt1 = Bread.point({
    x: 280,
    y: 120,
    angle: 0
})

Attributes

• reflexAngle: Is the reflex angle.

Methods

This methods can be found on all bodies, except for Body.

• distance: return the distance to other point:

  pnt2 //Must be a body type
  var d = pnt1.distance(pnt2);

  pnt2: Is an object that represents a body (type Body or Point)

• pointTo: this method will modify the angle of the object, and make it target another point:

  pnt2 //Must be a body type
  pnt1.pointTo(pnt2);

  pnt2: Is an object that represents a body (type Body or Point)

• update: updates the current coordinates and the angle:

  var x = 3;
  var y = 7;
  var angle = PI;
  pnt1.update(x, y, angle);

  x: Is the new x position (type number)

  y: Is the new y position (type number)

  angle: The new point angle in radians (type number)

• direction: return an array x,y with the point direction according to its last position:

  var dir = pnt1.direction();

  dir: Is an array that contains the direction over the x axis in the first position and the y axis in the second one

• directionLine() return a line that represents the motion vector.

  var dirL = pnt1.directionLine();

  dirL: Is a line that represents the motion vector of the point.

Line

Line is formed by two or more points. So it shares all point methods and properties.

Class Name: Line;

Factory example:

var line1 = Bread.line({
    x: 270,
    y: 160,
    points: [pnt1]
});

Attributes

• points: Array of all points, every item should be an object of type Point.
• allPoints: Is the same points array, including the initial point (x,y).
• perimeter: The perimeter value.
• slopes: Is an array that contains all slopes in the line.
• fill: Boolean, this attribute allows to fill the line if true when rendered
• close: Boolean, this attribute allows to close the line to its initial point if true.

Methods

• collision: This method detects a collision between the line and other line. Returns a boolean

   line2 //Must be a line type
   var hit = line1.collision(line2);

  line2: Is an object that represents a line (type Line)

  hit: Boolean variable. True if there is a collison otherwise: False

• render: Render the line in the universe. Remember that you must add the line to the universe.

   line1.render();