API Docs for: 0.7.1
Show:

File: src/shapes/Shape.js

  1. module.exports = Shape;
  2.  
  3. var vec2 = require('../math/vec2');
  4.  
  5. /**
  6.  * Base class for shapes.
  7.  * @class Shape
  8.  * @constructor
  9.  * @param {object} [options]
  10.  * @param {array} [options.position]
  11.  * @param {number} [options.angle=0]
  12.  * @param {number} [options.collisionGroup=1]
  13.  * @param {number} [options.collisionMask=1]
  14.  * @param {boolean} [options.sensor=false]
  15.  * @param {boolean} [options.collisionResponse=true]
  16.  * @param {object} [options.type=0]
  17.  */
  18. function Shape(options){
  19.     options = options || {};
  20.  
  21.     /**
  22.      * The body this shape is attached to. A shape can only be attached to a single body.
  23.      * @property {Body} body
  24.      */
  25.     this.body = null;
  26.  
  27.     /**
  28.      * Body-local position of the shape.
  29.      * @property {Array} position
  30.      */
  31.     this.position = vec2.fromValues(0,0);
  32.     if(options.position){
  33.         vec2.copy(this.position, options.position);
  34.     }
  35.  
  36.     /**
  37.      * Body-local angle of the shape.
  38.      * @property {number} angle
  39.      */
  40.     this.angle = options.angle || 0;
  41.  
  42.     /**
  43.      * The type of the shape. One of:
  44.      *
  45.      * * {{#crossLink "Shape/CIRCLE:property"}}Shape.CIRCLE{{/crossLink}}
  46.      * * {{#crossLink "Shape/PARTICLE:property"}}Shape.PARTICLE{{/crossLink}}
  47.      * * {{#crossLink "Shape/PLANE:property"}}Shape.PLANE{{/crossLink}}
  48.      * * {{#crossLink "Shape/CONVEX:property"}}Shape.CONVEX{{/crossLink}}
  49.      * * {{#crossLink "Shape/LINE:property"}}Shape.LINE{{/crossLink}}
  50.      * * {{#crossLink "Shape/BOX:property"}}Shape.BOX{{/crossLink}}
  51.      * * {{#crossLink "Shape/CAPSULE:property"}}Shape.CAPSULE{{/crossLink}}
  52.      * * {{#crossLink "Shape/HEIGHTFIELD:property"}}Shape.HEIGHTFIELD{{/crossLink}}
  53.      *
  54.      * @property {number} type
  55.      */
  56.     this.type = options.type || 0;
  57.  
  58.     /**
  59.      * Shape object identifier.
  60.      * @type {Number}
  61.      * @property id
  62.      */
  63.     this.id = Shape.idCounter++;
  64.  
  65.     /**
  66.      * Bounding circle radius of this shape
  67.      * @property boundingRadius
  68.      * @type {Number}
  69.      */
  70.     this.boundingRadius = 0;
  71.  
  72.     /**
  73.      * Collision group that this shape belongs to (bit mask). See <a href="http://www.aurelienribon.com/blog/2011/07/box2d-tutorial-collision-filtering/">this tutorial</a>.
  74.      * @property collisionGroup
  75.      * @type {Number}
  76.      * @example
  77.      *     // Setup bits for each available group
  78.      *     var PLAYER = Math.pow(2,0),
  79.      *         ENEMY =  Math.pow(2,1),
  80.      *         GROUND = Math.pow(2,2)
  81.      *
  82.      *     // Put shapes into their groups
  83.      *     player1Shape.collisionGroup = PLAYER;
  84.      *     player2Shape.collisionGroup = PLAYER;
  85.      *     enemyShape  .collisionGroup = ENEMY;
  86.      *     groundShape .collisionGroup = GROUND;
  87.      *
  88.      *     // Assign groups that each shape collide with.
  89.      *     // Note that the players can collide with ground and enemies, but not with other players.
  90.      *     player1Shape.collisionMask = ENEMY | GROUND;
  91.      *     player2Shape.collisionMask = ENEMY | GROUND;
  92.      *     enemyShape  .collisionMask = PLAYER | GROUND;
  93.      *     groundShape .collisionMask = PLAYER | ENEMY;
  94.      *
  95.      * @example
  96.      *     // How collision check is done
  97.      *     if(shapeA.collisionGroup & shapeB.collisionMask)!=0 && (shapeB.collisionGroup & shapeA.collisionMask)!=0){
  98.      *         // The shapes will collide
  99.      *     }
  100.      */
  101.     this.collisionGroup = options.collisionGroup !== undefined ? options.collisionGroup : 1;
  102.  
  103.     /**
  104.      * Whether to produce contact forces when in contact with other bodies. Note that contacts will be generated, but they will be disabled. That means that this shape will move through other body shapes, but it will still trigger contact events, etc.
  105.      * @property {Boolean} collisionResponse
  106.      */
  107.     this.collisionResponse = options.collisionResponse !== undefined ? options.collisionResponse : true;
  108.  
  109.     /**
  110.      * Collision mask of this shape. See .collisionGroup.
  111.      * @property collisionMask
  112.      * @type {Number}
  113.      */
  114.     this.collisionMask = options.collisionMask !== undefined ? options.collisionMask : 1;
  115.  
  116.     /**
  117.      * Material to use in collisions for this Shape. If this is set to null, the world will use default material properties instead.
  118.      * @property material
  119.      * @type {Material}
  120.      */
  121.     this.material = options.material || null;
  122.  
  123.     /**
  124.      * Area of this shape.
  125.      * @property area
  126.      * @type {Number}
  127.      */
  128.     this.area = 0;
  129.  
  130.     /**
  131.      * Set to true if you want this shape to be a sensor. A sensor does not generate contacts, but it still reports contact events. This is good if you want to know if a shape is overlapping another shape, without them generating contacts.
  132.      * @property {Boolean} sensor
  133.      */
  134.     this.sensor = options.sensor !== undefined ? options.sensor : false;
  135.  
  136.     if(this.type){
  137.         this.updateBoundingRadius();
  138.     }
  139.  
  140.     this.updateArea();
  141. }
  142.  
  143. Shape.idCounter = 0;
  144.  
  145. /**
  146.  * @static
  147.  * @property {Number} CIRCLE
  148.  */
  149. Shape.CIRCLE =      1;
  150.  
  151. /**
  152.  * @static
  153.  * @property {Number} PARTICLE
  154.  */
  155. Shape.PARTICLE =    2;
  156.  
  157. /**
  158.  * @static
  159.  * @property {Number} PLANE
  160.  */
  161. Shape.PLANE =       4;
  162.  
  163. /**
  164.  * @static
  165.  * @property {Number} CONVEX
  166.  */
  167. Shape.CONVEX =      8;
  168.  
  169. /**
  170.  * @static
  171.  * @property {Number} LINE
  172.  */
  173. Shape.LINE =        16;
  174.  
  175. /**
  176.  * @static
  177.  * @property {Number} BOX
  178.  */
  179. Shape.BOX =   32;
  180.  
  181. Object.defineProperty(Shape, 'RECTANGLE', {
  182.     get: function() {
  183.         console.warn('Shape.RECTANGLE is deprecated, use Shape.BOX instead.');
  184.         return Shape.BOX;
  185.     }
  186. });
  187.  
  188. /**
  189.  * @static
  190.  * @property {Number} CAPSULE
  191.  */
  192. Shape.CAPSULE =     64;
  193.  
  194. /**
  195.  * @static
  196.  * @property {Number} HEIGHTFIELD
  197.  */
  198. Shape.HEIGHTFIELD = 128;
  199.  
  200. /**
  201.  * Should return the moment of inertia around the Z axis of the body given the total mass. See <a href="http://en.wikipedia.org/wiki/List_of_moments_of_inertia">Wikipedia's list of moments of inertia</a>.
  202.  * @method computeMomentOfInertia
  203.  * @param  {Number} mass
  204.  * @return {Number} If the inertia is infinity or if the object simply isn't possible to rotate, return 0.
  205.  */
  206. Shape.prototype.computeMomentOfInertia = function(mass){};
  207.  
  208. /**
  209.  * Returns the bounding circle radius of this shape.
  210.  * @method updateBoundingRadius
  211.  * @return {Number}
  212.  */
  213. Shape.prototype.updateBoundingRadius = function(){};
  214.  
  215. /**
  216.  * Update the .area property of the shape.
  217.  * @method updateArea
  218.  */
  219. Shape.prototype.updateArea = function(){
  220.     // To be implemented in all subclasses
  221. };
  222.  
  223. /**
  224.  * Compute the world axis-aligned bounding box (AABB) of this shape.
  225.  * @method computeAABB
  226.  * @param  {AABB} out The resulting AABB.
  227.  * @param  {Array} position World position of the shape.
  228.  * @param  {Number} angle World angle of the shape.
  229.  */
  230. Shape.prototype.computeAABB = function(out, position, angle){
  231.     // To be implemented in each subclass
  232. };
  233.  
  234. /**
  235.  * Perform raycasting on this shape.
  236.  * @method raycast
  237.  * @param  {RayResult} result Where to store the resulting data.
  238.  * @param  {Ray} ray The Ray that you want to use for raycasting.
  239.  * @param  {array} position World position of the shape (the .position property will be ignored).
  240.  * @param  {number} angle World angle of the shape (the .angle property will be ignored).
  241.  */
  242. Shape.prototype.raycast = function(result, ray, position, angle){
  243.     // To be implemented in each subclass
  244. };
  245.