# Class: dbody

A rigid body has various properties from the point of view of the simulation. Some properties change over time:

- Position vector (x,y,z) of the body's point of reference. Currently the point of reference must correspond to the body's center of mass.
- Linear velocity of the point of reference, a vector (vx,vy,vz).
- Orientation of a body, represented by a quaternion (qs,qx,qy,qz) or a 3x3 rotation matrix.
- Angular velocity vector (wx,wy,wz) which describes how the orientation changes over time. Other body properties are usually constant over time:
- Mass of the body.
- Position of the center of mass with respect to the point of reference. In the currentimplementation the center of mass and the point of reference must coincide.
- Inertia matrix. This is a 3x3 matrix that describes how the body's mass is distributed around the center of mass.

## Hierarchy

    o-+ ode
      o-+ dgeom
        o-+ dbody

## Methods:

### Method overview:

- actdepth
- addforce
- addrelforce
- addreltorque
- addtorque
- affect
- angularthreshold
- angvel
- autodisable
- connected
- defaults
- disablesteps
- disabletime
- finitemode
- force
- gravity
- joint
- jointcount
- jointenergy
- jointforces
- local2world
- localpointvel
- lock
- lockrotaxis
- massaddbox
- massaddcappedcyl
- massaddcylinder
- massaddsphere
- massadjust
- massbox
- masscappedcyl
- masscylinder
- massparam
- massrotate
- masssphere
- masstranslate
- masszero
- minactdepth
- minenableforce
- new
- nextminenableforce
- nocollissionwithconnected
- reaffect
- rotdrag
- state
- torque
- vectorfromworld
- vectortoworld
- veldrag
- velocity
- velthreshold
- world2local
- worldpointvel

new ()
  returns: (dbody)
  creates a new body
actdepth (dbody self)
  returns: (int)
  returns -1 if it was activated by a body that has a minactdepth >= 0
addforce ([float fx,fy,fz],[float x,y,z],[rel])
  returns: ()
  adds force to the body. If coordinates are given, the force is added at this point, which will add some force at the torque. If a 7th parameter (boolean) is given, the point is in relative coordinates.
addrelforce ([float fx,fy,fz],[float x,y,z],[rel])
  returns: ()
  adds force to the body in the body's orientation. If coordinates are given, the force is added at this point, which will add some force at the torque. If a 7th parameter (boolean) is given, the point is in relative coordinates.
addreltorque ([float fx,fy,fz])
  returns: ()
  adds torque force to the body in the body's orientation
addtorque ([float fx,fy,fz])
  returns: ()
  adds torque force to the body
affect (dbody,[int affect])
  returns: ([int affect])
  sets/gets body affection. If two bodies collide and at least one reaffect bit of the other body is set that is set in affect, the other body is affected by the body.
angularthreshold ([float])
  returns: ([float])
  rotational minimum limit when the body should become disabled.
angvel (dbody self,[float fx,fy,fz])
  returns: ([float vx,vy,vz])
  sets/gets angular velocity of the body
autodisable ([boolean on])
  returns: ([boolean])
  if true, the body can become disabled if it doesn't do much. This will speed up the simulation alot if you have lot's of objects that are just lieing around.
connected (dbody,dbody)
  returns: (boolean)
  true if both bodies are connected through a joint
defaults (dbody)
  returns: ()
  resets the autodisable properties to the settings of the world.
disablesteps ([int])
  returns: ([int])

  trace depth when an enabled body touches a group of disabled bodies.

disabletime ([float])
  returns: ([float])
  amount of time to be waited until the body becomes autodisabled.
finitemode ([boolean on],[float x,y,z])
  returns: ([boolean on,float x,y,z])
  Sets/gets mode and axis of the finite rotation The mode controls the way a body's orientation is updated at each time step.
  - true: An 'infinitesimal' orientation update is used. This is fast to compute, but it can occasionally cause inaccuracies for bodies that are rotating at high speed, especially when those bodies are joined to other bodies. This is the default for every new body that is created.
  - false: A 'finite' orientation update is used. This is more costly to compute, but will be more accurate for high speed rotations. Note however that high speed rotations can result in many types of error in a simulation, and this mode will only fix one of those sources of error. The three floats set the finite rotation axis for a body. This is axis only has meaning when the finite rotation mode is set. If this axis is zero (0,0,0), full finite rotations are performed on the body.If this axis is nonzero, the body is rotated by performing a partial finite rotation along the axis direction followed by an infinitesimal rotation along an orthogonal direction. This can be useful to alleviate certain sources of error caused by quickly spinning bodies. For example, if a car wheel is rotating at high speed you can call this function with the wheel's hinge axis as the argument to try and improve its behavior.
force ()
  returns: ([float x,y,z])
  sets gets power of force
gravity ([boolean on])
  returns: ([boolean on])
  sets/gets if gravity is on for this body
joint (dbody,int i)
  returns: ([djoint])
  returns the i-th joint the body is connected to.
jointcount (dbody)
  returns: (int)
  the number of joints that the body is connected to.
jointenergy (dbody,[float multiplier])
  returns: (float kineticenergy)
  returns the kineticenergy applied to the body by connected bodies. Since the sum can become too small, an additional multiplier can be applied.
jointforces (dbody)
  returns: (float fx,fy,fz,forcesumlength,forcelengthsum)
  returns the sum of all force vectors that is contributed by all joints that are attached to the body, the total length of the forcevector and the sum of all lengths of forces together. Note that the sum of all lengths is never 0 if a force is applied, while all other values can be 0.
local2world (dbody,float x,y,z)
  returns: (float x,y,z)
  converts local to world coordinates
localpointvel (dbody,float x,y,z)
  returns: (float x,y,z)
  retrieve velocity at relative point x,y,z
lock (dbody,[int axis,float value],[planewidth],[planeveldamp])
  returns: ([int axis,float value,planewidth,planeveldamp])
  sets/gets locking for body. One axis can be set to be locked at a certain value. x=1,y=2,z=3,0=no locking. Planewidth is the width in which the body can move. Planeveldamp is the damping applied to the velocity in the locking axis. The damping should be >=0 and <=1. Default values are for unused arguments is 0.
lockrotaxis (dbody,[int axis,float x,y,z])
  returns: ([int axis,float x,y,z])
  sets/gets locking rotation axis for body. Chose the axis with the axis number (x=1,y=2,z=3,0=no lock) and set the direction where this axis should look to.
massaddbox (dbody self,float density,lx,ly,lz,[any total])
  returns: ()
  adds mass of a box. If a 6th argument is passed, the density is calculated to total mass
massaddcappedcyl (dbody self, float density,int axis, float radius,length, [any total])
  returns: ()
  adds mass of a cappedcylinder with density, radius and length. The axis indicates the orientation of the cylinder: 1=x, 2=y, 3=z. A capped cylinder is a cylinder that has spheres at its end.
massaddcylinder (dbody self, float density,int axis, float radius,length, [any total])
  returns: ()
  adds mass of a cylinder with density, radius and length. The axis indicates the orientation of the cylinder: 1=x, 2=y, 3=z.
massaddsphere (dbody self, float density,radius,[any total])
  returns: ()
  adds the mass to the mass of a sphere with density and radius. If a third argument is applied, the density will be calculated to the total mass of the sphere.
massadjust (dbody self, float newmass)
  returns: ()
  sets new mass
massbox (dbody self,float density,lx,ly,lz,[any total])
  returns: ()
  sets mass of a box. If a 6th argument is passed, the density is calculated to total mass
masscappedcyl (dbody self, float density,int axis, float radius,length, [any total])
  returns: ()
  sets mass of a cappedcylinder with density, radius and length. The axis indicates the orientation of the cylinder: 1=x, 2=y, 3=z. A capped cylinder is a cylinder that has spheres at its end.
masscylinder (dbody self, float density,int axis, float radius,length, [any total])
  returns: ()
  sets mass of a cylinder with density, radius and length. The axis indicates the orientation of the cylinder: 1=x, 2=y, 3=z.
massparam (dbody self,[float mass,cx,cy,cz, i11,i22,i33,i12,i13,i23])
  returns: ([float mass,cx,cy,cz, i11,i22,i33,i12,i13,i23])
  sets/gets massproperties of the body. Refer to the ode docs here, this function is for advanced people who know what they want.
massrotate (dbody self, float x,y,z)
  returns: ()
  rotates (radians) the mass of the body.
masssphere (dbody self, float density,radius,[any total])
  returns: ()
  sets the mass to the mass of a sphere with density and radius. If a third argument is applied, the density will be calculated to the total mass of the sphere.
masstranslate (dbody self,float x,y,z)
  returns: ()
  translates the mass.
masszero ()
  returns: ()
  sets mass of body to zero
minactdepth (dbody self,[int])
  returns: ([int])
  sets/gets minimum activation depth, if ==-1 => disabled (default). Use this to reduce the number of activated bodys outgoing from a activator source.
minenableforce (dbody self,[float f])
  returns: ([float f])
  sets/gets the required force to enable the body (default=0).
nextminenableforce (dbody self,[float f])
  returns: ([float f])
  sets/gets the required force to enable the body (default=0), once it was activated - it overwrites the minenableforce then. This is usefull if you have a brickwall and the bricks need lot's of force to be loosed. But once loosed, it shouldn't need much effort anymore to reenable them.
nocollissionwithconnected ([boolean on])
  returns: ([boolean on])
  sets/gets boolean, default=true. If it is true for two bodies that are connected, the collissioncheck is rejected if the two bodies of the collission are connected by a joint, before the complex collissioncheck is done - so it saves performance. If only one of the bodies has this flag set, it will be not affected by the other body. If the flag is false for both of them, they will collide normally with each other.
reaffect (dbody,[int reaffect])
  returns: ([int reaffect])
  sets/gets body reaffection. If two bodies collide and at least one affect bit of the other body is set that is set in reaffect, the body is affected by the other body.
rotdrag (body,[float x,y,z])
  returns: ([float x,y,z])
  this vector is multiplied with the angular velocity vector of the body each step. Don't set the vector to values >1 or <0, otherwise your body will either flicker around or accelerate to infinity. This is a useful value to let the system lose energy which is stabilizing the simulation quite well.
state ([boolean enable])
  returns: ([boolean])
  returns true if the body is enabled. Disables/Enables body if boolean value is passed. Disabled bodies don't use CPU power.
torque ([float x,y,z])
  returns: ([float x,y,z])
  sets/gets power of torque force
vectorfromworld (dbody,float x,y,z)
  returns: (float x,y,z)
  converts world rotation into local
vectortoworld (dbody,float x,y,z)
  returns: (float x,y,z)
  rotate a vector into world coordinates
veldrag (body,[float x,y,z])
  returns: ([float x,y,z])
  this vector is multiplied with the velocity vector of the body each step. Don't set the vector to values >1 or <0, otherwise your body will either flicker around or accelerate to infinity. This is a useful value to let the system lose energy which is stabilizing the simulation quite well.
velocity (dbody self,[float fx,fy,fz])
  returns: ([float vx,vy,vz])
  sets/gets linear velocity of the body
velthreshold ([float])
  returns: ([float])
  when the velocity drops below this value, the body becomes autodisabled.
world2local (dbody,float x,y,z)
  returns: (float x,y,z)
  converts world to local coordinates
worldpointvel (dbody,float x,y,z)
  returns: (float x,y,z)
  retrieve velocity at world point x,y,z

## Inherited Methods:

### From dgeom

body, category, delete, disabledspace, enabledspace, fdirnormal, fdirpriority, getcontactinfo, local2world, maxcontactinfo, maxcontacts, motion1, motion2, nocontactgenerator, pos, rotaxis, rotdeg, rotrad, setcategory, surfaceid, test, testnear, transformer, world2local