Murl Engine Lua Addon API  Version 1.0 beta
Murl.Graph.IBody

The IBody graph node interface.

Body nodes are the basis for objects controlled by the framework's built-in physics engine. A body has several properties that affect how it behaves in the simulated environment, such as mass, friction coefficients, contact softness etc. In addition, to be able to react to collisions with other bodies, it needs to have one or more Graph::ICollider nodes attached, which can have different shapes like planes, spheres or generic triangle meshes.

To gain more control over which bodies can collide with other bodies, it is possible to define up to 32 individual body groups. Each body may belong to any number of these groups (including no group), regarding both triggering of and responding to pending collision events (See SetTriggerGroupMask() and SetResponseGroupMask(), respectively). These groups also determine a body's reaction to the influence of a Graph::IField.

See Graph::ICollidable to define a body's collision surface.
See Graph::IField to define fields acting on a body.


Table members

Methods


GetNodeInterface()

Get the constant Graph::INode interface. This method returns a constant pointer to the node's Graph::INode interface, to be able to query common node properties such as active state, visibility or ID.

Murl.Graph.INode GetNodeInterface()

Returns
Murl.Graph.INode The constant Graph::INode interface, or null if not available

GetTransformInterface()

Get the constant Graph::ITransform interface. This method returns a constant pointer to the node's Graph::ITransform interface, to be able to query the node's transformation matrix and depth order.

Murl.Graph.ITransform GetTransformInterface()

Returns
Murl.Graph.ITransform The constant Graph::ITransform interface, or null if not available

SetTriggerGroupMask(mask)

Set the active collision trigger groups for this body. The group assignment for triggering collisions is performed via a UInt32 bit mask (up to 32 simultaneous groups), any individual bit set in the given mask results in generating a collision event in the respective group (e.g. group #5 for bit 5).

Boolean SetTriggerGroupMask(Integer mask)

Parameters
maskThe group assignment bit mask.
Returns
Boolean true if successful.

GetTriggerGroupMask()

Get the active collision trigger groups for this body.

Integer GetTriggerGroupMask()

Returns
Integer The bit mask specifying active trigger groups.

SetResponseGroupMask(mask)

Set the active response groups for this body. The group assignment for responding to collisions and field influence is performed via a UInt32 bit mask (up to 32 simultaneous groups), any individual bit set in the given mask results in a response to a pending collision event or field influence in the respective group (e.g. group #5 for bit 5).

Boolean SetResponseGroupMask(Integer mask)

Parameters
maskThe group assignment bit mask.
Returns
Boolean true if successful.

GetResponseGroupMask()

Get the active response groups for this body.

Integer GetResponseGroupMask()

Returns
Integer The bit mask specifying active response groups.

SetMass(mass)

Set the body's mass. This also affects the internal inverse mass value; therefore it is not possible to set different values for mass and inverse mass.

Boolean SetMass(Number mass)

Parameters
massThe body's mass.
Returns
Boolean true if successful.

GetMass()

Get the body's mass.

Number GetMass()

Returns
Number The body's mass.

SetInverseMass(inverseMass)

Set the body's inverse mass. To define VERY heavy bodies, it is possible to set the inverse mass to zero, which results in an infinite mass for this body. In that case, the body will not show any reaction on collision impacts from other (less heavy) bodies. This also affects the internal mass value; therefore it is not possible to set different values for mass and inverse mass.

Boolean SetInverseMass(Number inverseMass)

Parameters
inverseMassThe body's inverse mass.
Returns
Boolean true if successful.

GetInverseMass()

Get the body's inverse mass.

Number GetInverseMass()

Returns
Number The body's inverse mass.

SetDragCoefficient(value)

Set the body's drag coefficient (aka "cw" or "cd" value).

Boolean SetDragCoefficient(Number value)

Parameters
valueThe body's drag coefficient.
Returns
Boolean true if successful.

GetDragCoefficient()

Get the body's drag coefficient.

Number GetDragCoefficient()

Returns
Number The body's drag coefficient.

SetSize(size)

Set the physical size of the body. This sets the actual physical size of the body, which is used internally to calculate things like inertia tensor etc. It may actually differ from the "real" size that is defined by the body's attached colliders.

Boolean SetSize(Murl.Math.Vector size)

Parameters
sizeA vector containing the body's size in X, Y and Z dimensions.
Returns
Boolean true if successful.

GetSize()

Get the body's physical size.

Murl.Math.Vector GetSize()

Returns
Murl.Math.Vector A vector containing the body's size in X, Y and Z dimensions.

SetForceEffectEnabled(enabled)

Enable/disable force effects on this body. For certain special use cases, it may be desired to restrict the way a body reacts on external influences. When both force effect and torque effect (see SetTorqueEffectEnabled()) are enabled, the body reacts normally. When force effect is enabled and torque effect disabled, any applied off-center forces will result in a translation movement only. For disabled force effect and enabled torque effect, the result will be a rotational movement only.

Boolean SetForceEffectEnabled(Boolean enabled)

Parameters
enabledIf true, force effect is enabled.
Returns
Boolean true if successful.

IsForceEffectEnabled()

Check if force effect is enabled.

Boolean IsForceEffectEnabled()

Returns
Boolean true if enabled.

SetTorqueEffectEnabled(enabled)

Enable/disable torque effects on this body. See SetForceEffectEnabled() for details.

Boolean SetTorqueEffectEnabled(Boolean enabled)

Parameters
enabledIf true, torque effect is enabled.
Returns
Boolean true if successful.

IsTorqueEffectEnabled()

Check if torque effect is enabled.

Boolean IsTorqueEffectEnabled()

Returns
Boolean true if enabled.

SetCollisionEffectEnabled(enabled)

Enable/disable collision effect on this body.

Boolean SetCollisionEffectEnabled(Boolean enabled)

Parameters
enabledIf true, collision effect is enabled.
Returns
Boolean true if successful.

IsCollisionEffectEnabled()

Check if collision effect is enabled.

Boolean IsCollisionEffectEnabled()

Returns
Boolean true if enabled.

SetCollisionReportingEnabled(enabled)

Enable/disable collision reporting on this body.

Boolean SetCollisionReportingEnabled(Boolean enabled)

Parameters
enabledIf true, collision reporting is enabled.
Returns
Boolean true if successful.

IsCollisionReportingEnabled()

Check if collision reporting is enabled.

Boolean IsCollisionReportingEnabled()

Returns
Boolean true if enabled.

ApplyRelativeForceAndTorqueAtRelativePoint(p, f)

Apply both force and torque, given a relative force at a relative position. The given input force vector is always relative to the untransformed body, e.g. for an untransformed aeroplane with its nose pointing towards the -Z axis, its cockpit towards the +Y axis and its right wing towards the +X axis, a force vector of (0,0,-1) will always produce forward thrust, regardless of the plane's actual orientation in world space. The given position vector specifies the actual point where that force is applied; this point is also relative to the untransformed body. If that point is not equal to (0,0,0), the result will not only be a positional movement of the body, but will also result in some torque value applied to the body, resulting in a spin. For the previous example, if the plane's up vector is along the +Y axis, a position vector of (0,1,0) will apply a torque forcing the plane's nose "down". See also ApplyAbsoluteForceAndTorqueAtRelativePoint().

ApplyRelativeForceAndTorqueAtRelativePoint(Murl.Math.Vector p, Murl.Math.Vector f)

Parameters
pThe position vector relative to the untransformed body.
fThe force direction vector relative to the untransformed body.

ApplyAbsoluteForceAndTorqueAtRelativePoint(p, f)

Apply both force and torque, given an absolute force at a relative position. The given input force vector is absolute in world space. Taking the plane example from ApplyRelativeForceAndTorqueAtRelativePoint(), with the world's north direction towards -Z, east towards +X and increasing altitude towards +Y, applying a vector of (1,0,0) will always represent west wind (blowing from west to east) acting on the plane, regardless of its position and orientation in world space. The given position vector specifies the actual point where that force is applied; this point is relative to the untransformed body. If this vector equals (0,0,0), no torque will be applied, and the plane will simply be blown off its course, keeping its orientation. A vector of e.g. (0,0,-1) would result in a torque forcing the plane's nose towards the direction of the wind.

ApplyAbsoluteForceAndTorqueAtRelativePoint(Murl.Math.Vector p, Murl.Math.Vector f)

Parameters
pThe position vector relative to the untransformed body.
fThe absolute force direction in world space.

ApplyRelativeForceAndTorqueAtAbsolutePoint(p, f)

Apply both force and torque, given a relative force at an absolute position. See also ApplyRelativeForceAndTorqueAtRelativePoint() and ApplyAbsoluteForceAndTorqueAtRelativePoint(). TODO: Find a nice example.

ApplyRelativeForceAndTorqueAtAbsolutePoint(Murl.Math.Vector p, Murl.Math.Vector f)

Parameters
pThe absolute position vector in world space.
fThe absolute force direction in world space.

ApplyAbsoluteForceAndTorqueAtAbsolutePoint(p, f)

Apply both force and torque, given an absolute force at an absolute position. See also ApplyRelativeForceAndTorqueAtRelativePoint() and ApplyAbsoluteForceAndTorqueAtRelativePoint(). TODO: Find a nice example.

ApplyAbsoluteForceAndTorqueAtAbsolutePoint(Murl.Math.Vector p, Murl.Math.Vector f)

Parameters
pThe absolute position vector in world space.
fThe absolute force direction in world space.

ApplyRelativeForceAtRelativePoint(p, f)

Apply force only, given a relative force at a relative position. This method only applies a force influence, without applying any torque. See also ApplyRelativeForceAndTorqueAtRelativePoint().

ApplyRelativeForceAtRelativePoint(Murl.Math.Vector p, Murl.Math.Vector f)

Parameters
pThe position vector relative to the untransformed body.
fThe force direction vector relative to the untransformed body.

ApplyAbsoluteForceAtRelativePoint(p, f)

Apply force only, given an absolute force at a relative position. This method only applies a force influence, without applying any torque. See also ApplyAbsoluteForceAndTorqueAtRelativePoint().

ApplyAbsoluteForceAtRelativePoint(Murl.Math.Vector p, Murl.Math.Vector f)

Parameters
pThe position vector relative to the untransformed body.
fThe force direction vector relative to the untransformed body.

ApplyRelativeForceAtAbsolutePoint(p, f)

Apply force only, given a relative force at an absolute position. This method only applies a force influence, without applying any torque. See also ApplyRelativeForceAndTorqueAtAbsolutePoint().

ApplyRelativeForceAtAbsolutePoint(Murl.Math.Vector p, Murl.Math.Vector f)

Parameters
pThe position vector relative to the untransformed body.
fThe force direction vector relative to the untransformed body.

ApplyAbsoluteForceAtAbsolutePoint(p, f)

Apply force only, given an absolute force at an absolute position. This method only applies a force influence, without applying any torque. See also ApplyAbsoluteForceAndTorqueAtAbsolutePoint().

ApplyAbsoluteForceAtAbsolutePoint(Murl.Math.Vector p, Murl.Math.Vector f)

Parameters
pThe position vector relative to the untransformed body.
fThe force direction vector relative to the untransformed body.

ApplyRelativeTorqueAtRelativePoint(p, f)

Apply torque only, given a relative force at a relative position. This method only applies a torque influence, without applying any force. See also ApplyRelativeForceAndTorqueAtRelativePoint().

ApplyRelativeTorqueAtRelativePoint(Murl.Math.Vector p, Murl.Math.Vector f)

Parameters
pThe position vector relative to the untransformed body.
fThe force direction vector relative to the untransformed body.

ApplyAbsoluteTorqueAtRelativePoint(p, f)

Apply torque only, given an absolute force at a relative position. This method only applies a torque influence, without applying any force. See also ApplyAbsoluteForceAndTorqueAtRelativePoint().

ApplyAbsoluteTorqueAtRelativePoint(Murl.Math.Vector p, Murl.Math.Vector f)

Parameters
pThe position vector relative to the untransformed body.
fThe force direction vector relative to the untransformed body.

ApplyRelativeTorqueAtAbsolutePoint(p, f)

Apply torque only, given a relative force at an absolute position. This method only applies a torque influence, without applying any force. See also ApplyRelativeForceAndTorqueAtAbsolutePoint().

ApplyRelativeTorqueAtAbsolutePoint(Murl.Math.Vector p, Murl.Math.Vector f)

Parameters
pThe position vector relative to the untransformed body.
fThe force direction vector relative to the untransformed body.

ApplyAbsoluteTorqueAtAbsolutePoint(p, f)

Apply torque only, given an absolute force at an absolute position. This method only applies a torque influence, without applying any force. See also ApplyAbsoluteForceAndTorqueAtAbsolutePoint().

ApplyAbsoluteTorqueAtAbsolutePoint(Murl.Math.Vector p, Murl.Math.Vector f)

Parameters
pThe position vector relative to the untransformed body.
fThe force direction vector relative to the untransformed body.

GetLinearMomentum()

Get the currently acting linear momentum.

Murl.Math.Vector GetLinearMomentum()

Returns
Murl.Math.Vector A vector containing the current linear momentum.

GetAngularMomentum()

Get the currently acting angular momentum.

Murl.Math.Vector GetAngularMomentum()

Returns
Murl.Math.Vector A vector containing the current angular momentum.

GetLinearVelocity()

Get the body's current linear velocity.

Murl.Math.Vector GetLinearVelocity()

Returns
Murl.Math.Vector A vector containing the current linear velocity.

GetAngularVelocity()

Get the body's current angular velocity.

Murl.Math.Vector GetAngularVelocity()

Returns
Murl.Math.Vector A vector containing the current angular velocity.

GetNumberOfCollisions()

Get the number of individual collisions. This returns the total number of individual collisions that occurred during the last simulation step on the body. After each step, this number is reset to zero, and new collisions are evaluated.

Integer GetNumberOfCollisions()

Returns
Integer The total number of individual collisions.

GetCollisionDepth(collisionIndex)

Get the depth of the collision along the collision's normal vector.

Number GetCollisionDepth(Integer collisionIndex)

Parameters
collisionIndexThe collision index, in the range from 0 to GetNumberOfCollisions().
Returns
Number The collision depth, or 0.0 if the index was out of range.

GetCollisionBody(collisionIndex, bodyIndex)

Get a body involved in a specific collision. Individual collisions always occur between only two bodies; if during a simulation step a body collides with more than one other body (or with the same body at more than one contact point), a number of individual pair-wise collisions are generated.

Murl.Graph.IBody GetCollisionBody(Integer collisionIndex, Integer bodyIndex)

Parameters
collisionIndexThe collision index, in the range from 0 to GetNumberOfCollisions().
bodyIndexThe index of the collision body, either 0 for this body or 1 for the other one.
Returns
Murl.Graph.IBody a pointer to the involved body, or null if the index was out of range.

GetCollisionGeometry(collisionIndex, bodyIndex)

Get the actual collider of a body involved in a specific collision.

Murl.Graph.ICollider GetCollisionGeometry(Integer collisionIndex, Integer bodyIndex)

Parameters
collisionIndexThe collision index, in the range from 0 to GetNumberOfCollisions().
bodyIndexThe index of the collision body, either 0 for this body or 1 for the other one.
Returns
Murl.Graph.ICollider a pointer to involved body's collider, or null if the index was out of range.

GetCollisionSurfaceIndex(collisionIndex, bodyIndex)

Get the surface index of a collision.

Integer GetCollisionSurfaceIndex(Integer collisionIndex, Integer bodyIndex)

Parameters
collisionIndexThe collision index, in the range from 0 to GetNumberOfCollisions().
bodyIndexThe index of the collision body for which to get the index, either 0 for this body or 1 for the other one.
Returns
Integer The surface index.

GetCollisionPartner(collisionIndex)

DEPRECATED: Get the partner of a specific collision. Use GetCollisionBody(collisionIndex, 1) instead.

Murl.Graph.IBody GetCollisionPartner(Integer collisionIndex)

Parameters
collisionIndexThe collision index, in the range from 0 to GetNumberOfCollisions().
Returns
Murl.Graph.IBody a pointer to the collision's other involved body, or null if the index was out of range.

ResolveCollisions(partner, margin)

Resolve all collisions, optionally with a given partner only. This method tries to resolve all pending collisions of this body, optionally restricted to collisions with a given partner only. The result is a direction vector that represents the world space offset to be applied to the body so that it does not collide with any other objects anymore. If no collisions are pending, a zero direction vector is returned. Applying the resulting offset vector to a body's position should be done only on bodies for which the collision/force/torque effect is manually disabled, e.g. a player character that should be precisely controlled by explicitly setting its velocity instead of applying forces. Setting the "margin" parameter to a positive non-zero value pushes all collisions "inward" by that distance. This allows to also detect collisions that do not actually occur, but become relevant during collision resolution. Ideally, this value should be set to the maximum distance a body can be moved between subsequent ticks, but may be lower. However, any collision geometry used must be enlarged by that value to give the same result.

Murl.Math.Vector ResolveCollisions(Murl.Graph.IBody partner, Number margin)

Parameters
partnerThe collision partner to query, or null if all partners should be queried.
marginThe collision margin.
Returns
Murl.Math.Vector The offset vector.

GetBodyTransform()

Get a mutable reference to the body's current world transform matrix.

Murl.Math.Matrix GetBodyTransform()

Returns
Murl.Math.Matrix The world transform.

GetNumberOfStages()

Get the body's number of stages.

Integer GetNumberOfStages()

Returns
Integer The number of stages.