PackageBox2D.Dynamics
Classpublic class b2Island

Position Correction Notes ========================= I tried the several algorithms for position correction of the 2D revolute joint. I looked at these systems: - simple pendulum (1m diameter sphere on massless 5m stick) with initial angular velocity of 100 rad/s. - suspension bridge with 30 1m long planks of length 1m. - multi-link chain with 30 1m long links. Here are the algorithms: Baumgarte - A fraction of the position error is added to the velocity error. There is no separate position solver. Pseudo Velocities - After the velocity solver and position integration, the position error, Jacobian, and effective mass are recomputed. Then the velocity constraints are solved with pseudo velocities and a fraction of the position error is added to the pseudo velocity error. The pseudo velocities are initialized to zero and there is no warm-starting. After the position solver, the pseudo velocities are added to the positions. This is also called the First Order World method or the Position LCP method. Modified Nonlinear Gauss-Seidel (NGS) - Like Pseudo Velocities except the position error is re-computed for each constraint and the positions are updated after the constraint is solved. The radius vectors (aka Jacobians) are re-computed too (otherwise the algorithm has horrible instability). The pseudo velocity states are not needed because they are effectively zero at the beginning of each iteration. Since we have the current position error, we allow the iterations to terminate early if the error becomes smaller than b2_linearSlop. Full NGS or just NGS - Like Modified NGS except the effective mass are re-computed each time a constraint is solved. Here are the results: Baumgarte - this is the cheapest algorithm but it has some stability problems, especially with the bridge. The chain links separate easily close to the root and they jitter as they struggle to pull together. This is one of the most common methods in the field. The big drawback is that the position correction artificially affects the momentum, thus leading to instabilities and false bounce. I used a bias factor of 0.2. A larger bias factor makes the bridge less stable, a smaller factor makes joints and contacts more spongy. Pseudo Velocities - the is more stable than the Baumgarte method. The bridge is stable. However, joints still separate with large angular velocities. Drag the simple pendulum in a circle quickly and the joint will separate. The chain separates easily and does not recover. I used a bias factor of 0.2. A larger value lead to the bridge collapsing when a heavy cube drops on it. Modified NGS - this algorithm is better in some ways than Baumgarte and Pseudo Velocities, but in other ways it is worse. The bridge and chain are much more stable, but the simple pendulum goes unstable at high angular velocities. Full NGS - stable in all tests. The joints display good stiffness. The bridge still sags, but this is better than infinite forces. Recommendations Pseudo Velocities are not really worthwhile because the bridge and chain cannot recover from joint separation. In other cases the benefit over Baumgarte is small. Modified NGS is not a robust method for the revolute joint due to the violent instability seen in the simple pendulum. Perhaps it is viable with other constraint types, especially scalar constraints where the effective mass is a scalar. This leaves Baumgarte and Full NGS. Baumgarte has small, but manageable instabilities and is very fast. I don't think we can escape Baumgarte, especially in highly demanding cases where high constraint fidelity is not needed. Full NGS is robust and easy on the eyes. I recommend this as an option for higher fidelity simulation and certainly for suspension bridges and long chains. Full NGS might be a good choice for ragdolls, especially motorized ragdolls where joint separation can be problematic. The number of NGS iterations can be reduced for better performance without harming robustness much. Each joint in a can be handled differently in the position solver. So I recommend a system where the user can select the algorithm on a per joint basis. I would probably default to the slower Full NGS and let the user select the faster Baumgarte method in performance critical scenarios.



Public Methods
 MethodDefined by
  
b2Island(bodyCapacity:int, contactCapacity:int, jointCapacity:int, allocator:b2ContactListener, listener:*)
b2Island
  
AddBody(body:b2Body):void
b2Island
  
AddContact(contact:b2Contact):void
b2Island
  
AddJoint(joint:b2Joint):void
b2Island
  
Clear():void
b2Island
  
Report(constraints:Array):void
b2Island
  
Solve(step:b2TimeStep, gravity:b2Vec2, correctPositions:Boolean, allowSleep:Boolean):void
b2Island
  
SolveTOI(subStep:b2TimeStep):void
b2Island
Property detail
m_bodiesproperty
b2internal var m_bodies:Array
m_bodyCountproperty 
b2internal var m_bodyCount:int
m_contactCapacityproperty 
b2internal var m_contactCapacity:int
m_contactCountproperty 
b2internal var m_contactCount:int
m_contactsproperty 
b2internal var m_contacts:Array
m_positionIterationCountproperty 
b2internal var m_positionIterationCount:int
Constructor detail
b2Island()constructor
public function b2Island(bodyCapacity:int, contactCapacity:int, jointCapacity:int, allocator:b2ContactListener, listener:*)Parameters
bodyCapacity:int
 
contactCapacity:int
 
jointCapacity:int
 
allocator:b2ContactListener
 
listener:*
Method detail
AddBody()method
public function AddBody(body:b2Body):voidParameters
body:b2Body
AddContact()method 
public function AddContact(contact:b2Contact):voidParameters
contact:b2Contact
AddJoint()method 
public function AddJoint(joint:b2Joint):voidParameters
joint:b2Joint
Clear()method 
public function Clear():void
Report()method 
public function Report(constraints:Array):voidParameters
constraints:Array
Solve()method 
public function Solve(step:b2TimeStep, gravity:b2Vec2, correctPositions:Boolean, allowSleep:Boolean):voidParameters
step:b2TimeStep
 
gravity:b2Vec2
 
correctPositions:Boolean
 
allowSleep:Boolean
SolveTOI()method 
public function SolveTOI(subStep:b2TimeStep):voidParameters
subStep:b2TimeStep