planck-js/lib/joint/PulleyJoint.js

2D physics engine for JavaScript/HTML5 game development

/*
 * Copyright (c) 2016      Ali Shakiba http://shakiba.me/planck.js
 * Copyright (c) 2006-2011 Erin Catto  http://www.box2d.org
 *
 * This software is provided 'as-is', without any express or implied
 * warranty.  In no event will the authors be held liable for any damages
 * arising from the use of this software.
 * Permission is granted to anyone to use this software for any purpose,
 * including commercial applications, and to alter it and redistribute it
 * freely, subject to the following restrictions:
 * 1. The origin of this software must not be misrepresented; you must not
 * claim that you wrote the original software. If you use this software
 * in a product, an acknowledgment in the product documentation would be
 * appreciated but is not required.
 * 2. Altered source versions must be plainly marked as such, and must not be
 * misrepresented as being the original software.
 * 3. This notice may not be removed or altered from any source distribution.
 */

module.exports = PulleyJoint;

var options = require('../util/options');
var create = require('../util/create');
var Settings = require('../Settings');

var Math = require('../common/Math');
var Vec2 = require('../common/Vec2');
var Vec3 = require('../common/Vec3');
var Mat22 = require('../common/Mat22');
var Mat33 = require('../common/Mat33');
var Rot = require('../common/Rot');
var Sweep = require('../common/Sweep');
var Transform = require('../common/Transform');
var Velocity = require('../common/Velocity');
var Position = require('../common/Position');

var Joint = require('../Joint');

PulleyJoint.TYPE = 'pulley-joint';
PulleyJoint.MIN_PULLEY_LENGTH = 2.0; // minPulleyLength

PulleyJoint._super = Joint;
PulleyJoint.prototype = create(PulleyJoint._super.prototype);

/**
 * Pulley joint definition. This requires two ground anchors, two dynamic body
 * anchor points, and a pulley ratio.
 */
var PulleyJointDef = {
  collideConnected : true
};

/**
 * The pulley joint is connected to two bodies and two fixed ground points. The
 * pulley supports a ratio such that: length1 + ratio * length2 <= constant
 * 
 * Yes, the force transmitted is scaled by the ratio.
 * 
 * Warning: the pulley joint can get a bit squirrelly by itself. They often work
 * better when combined with prismatic joints. You should also cover the the
 * anchor points with static shapes to prevent one side from going to zero
 * length.
 * 
 * @param {Vec2} groundAnchorA The first ground anchor in world coordinates.
 *          This point never moves.
 * @param {Vec2} groundAnchorB The second ground anchor in world coordinates.
 *          This point never moves.
 * @param {Vec2} localAnchorA The local anchor point relative to bodyA's origin.
 * @param {Vec2} localAnchorB The local anchor point relative to bodyB's origin.
 * @param {float} ratio The pulley ratio, used to simulate a block-and-tackle.
 * 
 * @prop {float} lengthA The reference length for the segment attached to bodyA.
 * @prop {float} lengthB The reference length for the segment attached to bodyB.
 */
function PulleyJoint(def, bodyA, bodyB, groundA, groundB, anchorA, anchorB,
    ratio) {
  if (!(this instanceof PulleyJoint)) {
    return new PulleyJoint(def, bodyA, bodyB, groundA, groundB, anchorA,
        anchorB, ratio);
  }

  def = options(def, PulleyJointDef);
  Joint.call(this, def, bodyA, bodyB);
  this.m_type = PulleyJoint.TYPE;

  this.m_groundAnchorA = groundA;
  this.m_groundAnchorB = groundB;
  this.m_localAnchorA = bodyA.GetLocalPoint(anchorA);
  this.m_localAnchorB = bodyB.GetLocalPoint(anchorB);
  this.m_lengthA = Vec2.Distance(anchorA, groundA);
  this.m_lengthB = Vec2.Distance(anchorB, groundB);
  this.m_ratio = def.ratio || ratio;
  Assert(ratio > Math.EPSILON);

  this.m_constant = this.m_lengthA + this.m_ratio * this.m_lengthB;

  this.m_impulse = 0.0;

  // Solver temp
  this.m_uA; // Vec2
  this.m_uB; // Vec2
  this.m_rA; // Vec2
  this.m_rB; // Vec2
  this.m_localCenterA; // Vec2
  this.m_localCenterB; // Vec2
  this.m_invMassA; // float
  this.m_invMassB; // float
  this.m_invIA; // float
  this.m_invIB; // float
  this.m_mass; // float

  // Pulley:
  // length1 = norm(p1 - s1)
  // length2 = norm(p2 - s2)
  // C0 = (length1 + ratio * length2)_initial
  // C = C0 - (length1 + ratio * length2)
  // u1 = (p1 - s1) / norm(p1 - s1)
  // u2 = (p2 - s2) / norm(p2 - s2)
  // Cdot = -dot(u1, v1 + cross(w1, r1)) - ratio * dot(u2, v2 + cross(w2, r2))
  // J = -[u1 cross(r1, u1) ratio * u2 ratio * cross(r2, u2)]
  // K = J * invM * JT
  // = invMass1 + invI1 * cross(r1, u1)^2 + ratio^2 * (invMass2 + invI2 *
  // cross(r2, u2)^2)
}

/**
 * Get the first ground anchor.
 */
PulleyJoint.prototype.GetGroundAnchorA = function() {
  return this.m_groundAnchorA;
}

/**
 * Get the second ground anchor.
 */
PulleyJoint.prototype.GetGroundAnchorB = function() {
  return this.m_groundAnchorB;
}

/**
 * Get the current length of the segment attached to bodyA.
 */
PulleyJoint.prototype.GetLengthA = function() {
  return this.m_lengthA;
}

/**
 * Get the current length of the segment attached to bodyB.
 */
PulleyJoint.prototype.GetLengthB = function() {
  return this.m_lengthB;
}

/**
 * Get the pulley ratio.
 */
PulleyJoint.prototype.GetRatio = function() {
  return this.m_ratio;
}

/**
 * Get the current length of the segment attached to bodyA.
 */
PulleyJoint.prototype.GetCurrentLengthA = function() {
  var p = this.m_bodyA.GetWorldPoint(this.m_localAnchorA);
  var s = this.m_groundAnchorA;
  return Vec2.Distance(p, s);
}

/**
 * Get the current length of the segment attached to bodyB.
 */
PulleyJoint.prototype.GetCurrentLengthB = function() {
  var p = this.m_bodyB.GetWorldPoint(this.m_localAnchorB);
  var s = this.m_groundAnchorB;
  return Vec2.Distance(p, s);
}

PulleyJoint.prototype.ShiftOrigin = function(newOrigin) {
  this.m_groundAnchorA -= newOrigin;
  this.m_groundAnchorB -= newOrigin;
}

PulleyJoint.prototype.GetAnchorA = function() {
  return this.m_bodyA.GetWorldPoint(this.m_localAnchorA);
}

PulleyJoint.prototype.GetAnchorB = function() {
  return this.m_bodyB.GetWorldPoint(this.m_localAnchorB);
}

PulleyJoint.prototype.GetReactionForce = function(inv_dt) {
  return Vec3.Mul(inv_dt * this.m_impulse, this.m_uB);
}

PulleyJoint.prototype.GetReactionTorque = function(inv_dt) {
  return 0.0;
}

PulleyJoint.prototype.InitVelocityConstraints = function(step) {
  this.m_localCenterA = this.m_bodyA.m_sweep.localCenter;
  this.m_localCenterB = this.m_bodyB.m_sweep.localCenter;
  this.m_invMassA = this.m_bodyA.m_invMass;
  this.m_invMassB = this.m_bodyB.m_invMass;
  this.m_invIA = this.m_bodyA.m_invI;
  this.m_invIB = this.m_bodyB.m_invI;

  var cA = this.m_bodyA.c_position.c;
  var aA = this.m_bodyA.c_position.a;
  var vA = this.m_bodyA.c_velocity.v;
  var wA = this.m_bodyA.c_velocity.w;

  var cB = this.m_bodyB.c_position.c;
  var aB = this.m_bodyB.c_position.a;
  var vB = this.m_bodyB.c_velocity.v;
  var wB = this.m_bodyB.c_velocity.w;

  var qA = Rot(aA);
  var qB = Rot(aB);

  this.m_rA = Rot.Mul(qA, Vec2.Sub(this.m_localAnchorA, this.m_localCenterA));
  this.m_rB = Rot.Mul(qB, Vec2.Sub(this.m_localAnchorB, this.m_localCenterB));

  // Get the pulley axes.
  this.m_uA = Vec2.Sub(Vec2.Add(cA, this.m_rA), this.m_groundAnchorA);
  this.m_uB = Vec2.Sub(Vec2.Add(cB, this.m_rB), this.m_groundAnchorB);

  var lengthA = this.m_uA.Length();
  var lengthB = this.m_uB.Length();

  if (lengthA > 10.0 * Settings.linearSlop) {
    this.m_uA.Mul(1.0 / lengthA);
  } else {
    this.m_uA.SetZero();
  }

  if (lengthB > 10.0 * Settings.linearSlop) {
    this.m_uB.Mul(1.0 / lengthB);
  } else {
    this.m_uB.SetZero();
  }

  // Compute effective mass.
  var ruA = Vec2.Cross(this.m_rA, this.m_uA); // float
  var ruB = Vec2.Cross(this.m_rB, this.m_uB); // float

  var mA = this.m_invMassA + this.m_invIA * ruA * ruA; // float
  var mB = this.m_invMassB + this.m_invIB * ruB * ruB; // float

  this.m_mass = mA + this.m_ratio * this.m_ratio * mB;

  if (this.m_mass > 0.0) {
    this.m_mass = 1.0 / this.m_mass;
  }

  if (step.warmStarting) {
    // Scale impulses to support variable time steps.
    this.m_impulse *= step.dtRatio;

    // Warm starting.
    var PA = -(this.m_impulse) * this.m_uA; // Vec2
    var PB = (-this.m_ratio * this.m_impulse) * this.m_uB; // Vec2

    vA += this.m_invMassA * PA;
    wA += this.m_invIA * Vec2.Cross(this.m_rA, PA);
    vB += this.m_invMassB * PB;
    wB += this.m_invIB * Vec2.Cross(this.m_rB, PB);
  } else {
    this.m_impulse = 0.0;
  }

  this.m_bodyA.c_velocity.v = vA;
  this.m_bodyA.c_velocity.w = wA;
  this.m_bodyB.c_velocity.v = vB;
  this.m_bodyB.c_velocity.w = wB;
}

PulleyJoint.prototype.SolveVelocityConstraints = function(step) {
  var vA = this.m_bodyA.c_velocity.v;
  var wA = this.m_bodyA.c_velocity.w;
  var vB = this.m_bodyB.c_velocity.v;
  var wB = this.m_bodyB.c_velocity.w;

  var vpA = Vec2.Add(vA, Vec2.Cross(wA, this.m_rA));
  var vpB = Vec2.Add(vB, Vec2.Cross(wB, this.m_rB));

  var Cdot = -Vec2.Dot(this.m_uA, vpA) - this.m_ratio
      * Vec2.Dot(this.m_uB, vpB); // float
  var impulse = -this.m_mass * Cdot; // float
  this.m_impulse += impulse;

  var PA = Vec2().WSet(-impulse, this.m_uA); // Vec2
  var PB = Vec2().WSet(-this.m_ratio * impulse, this.m_uB); // Vec2
  vA.WAdd(this.m_invMassA, PA);
  wA += this.m_invIA * Vec2.Cross(this.m_rA, PA);
  vB.WAdd(this.m_invMassB, PB);
  wB += this.m_invIB * Vec2.Cross(this.m_rB, PB);

  this.m_bodyA.c_velocity.v = vA;
  this.m_bodyA.c_velocity.w = wA;
  this.m_bodyB.c_velocity.v = vB;
  this.m_bodyB.c_velocity.w = wB;
}

PulleyJoint.prototype.SolvePositionConstraints = function(step) {
  var cA = this.m_bodyA.c_position.c;
  var aA = this.m_bodyA.c_position.a;
  var cB = this.m_bodyB.c_position.c;
  var aB = this.m_bodyB.c_position.a;

  var qA = Rot(aA), qB = Rot(aB);

  var rA = Rot.Mul(qA, Vec2.Sub(this.m_localAnchorA, this.m_localCenterA));
  var rB = Rot.Mul(qB, Vec2.Sub(this.m_localAnchorB, this.m_localCenterB));

  // Get the pulley axes.
  var uA = Vec2.Sub(Vec2.Add(cA, this.m_rA), this.m_groundAnchorA);
  var uB = Vec2.Sub(Vec2.Add(cB, this.m_rB), this.m_groundAnchorB);

  var lengthA = uA.Length();
  var lengthB = uB.Length();

  if (lengthA > 10.0 * Settings.linearSlop) {
    uA.Mul(1.0 / lengthA);
  } else {
    uA.SetZero();
  }

  if (lengthB > 10.0 * Settings.linearSlop) {
    uB.Mul(1.0 / lengthB);
  } else {
    uB.SetZero();
  }

  // Compute effective mass.
  var ruA = Vec2.Cross(rA, uA);
  var ruB = Vec2.Cross(rB, uB);

  var mA = this.m_invMassA + this.m_invIA * ruA * ruA; // float
  var mB = this.m_invMassB + this.m_invIB * ruB * ruB; // float

  var mass = mA + this.m_ratio * this.m_ratio * mB; // float

  if (mass > 0.0) {
    mass = 1.0 / mass;
  }

  var C = this.m_constant - lengthA - this.m_ratio * lengthB; // float
  var linearError = Math.abs(C); // float

  var impulse = -mass * C; // float

  var PA = Vec2().WSet(-impulse, uA); // Vec2
  var PB = Vec2().WSet(-this.m_ratio * impulse, uB); // Vec2

  cA.WAdd(this.m_invMassA, PA);
  aA += this.m_invIA * Vec2.Cross(rA, PA);
  cB.WAdd(this.m_invMassB, PB);
  aB += this.m_invIB * Vec2.Cross(rB, PB);

  this.m_bodyA.c_position.c = cA;
  this.m_bodyA.c_position.a = aA;
  this.m_bodyB.c_position.c = cB;
  this.m_bodyB.c_position.a = aB;

  return linearError < Settings.linearSlop;
}