![]() |
Murl Engine Lua Addon API
Version 1.0 beta
|
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.
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()
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()
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)
mask | The group assignment bit mask. |
Get the active collision trigger groups for this body.
Integer GetTriggerGroupMask()
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)
mask | The group assignment bit mask. |
Get the active response groups for this body.
Integer GetResponseGroupMask()
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.
mass | The body's mass. |
Get the body's mass.
Number GetMass()
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)
inverseMass | The body's inverse mass. |
Get the body's inverse mass.
Number GetInverseMass()
Set the body's drag coefficient (aka "cw" or "cd" value).
Boolean SetDragCoefficient(Number value)
value | The body's drag coefficient. |
Get the body's drag coefficient.
Number GetDragCoefficient()
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)
size | A vector containing the body's size in X, Y and Z dimensions. |
Get the body's physical size.
Murl.Math.Vector GetSize()
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)
enabled | If true, force effect is enabled. |
Check if force effect is enabled.
Boolean IsForceEffectEnabled()
Enable/disable torque effects on this body. See SetForceEffectEnabled() for details.
Boolean SetTorqueEffectEnabled(Boolean enabled)
enabled | If true, torque effect is enabled. |
Check if torque effect is enabled.
Boolean IsTorqueEffectEnabled()
Enable/disable collision effect on this body.
Boolean SetCollisionEffectEnabled(Boolean enabled)
enabled | If true, collision effect is enabled. |
Check if collision effect is enabled.
Boolean IsCollisionEffectEnabled()
Enable/disable collision reporting on this body.
Boolean SetCollisionReportingEnabled(Boolean enabled)
enabled | If true, collision reporting is enabled. |
Check if collision reporting is enabled.
Boolean IsCollisionReportingEnabled()
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)
p | The position vector relative to the untransformed body. |
f | The force direction vector relative to the untransformed body. |
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)
p | The position vector relative to the untransformed body. |
f | The absolute force direction in world space. |
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)
p | The absolute position vector in world space. |
f | The absolute force direction in world space. |
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)
p | The absolute position vector in world space. |
f | The absolute force direction in world space. |
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)
p | The position vector relative to the untransformed body. |
f | The force direction vector relative to the untransformed body. |
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)
p | The position vector relative to the untransformed body. |
f | The force direction vector relative to the untransformed body. |
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)
p | The position vector relative to the untransformed body. |
f | The force direction vector relative to the untransformed body. |
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)
p | The position vector relative to the untransformed body. |
f | The force direction vector relative to the untransformed body. |
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)
p | The position vector relative to the untransformed body. |
f | The force direction vector relative to the untransformed body. |
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)
p | The position vector relative to the untransformed body. |
f | The force direction vector relative to the untransformed body. |
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)
p | The position vector relative to the untransformed body. |
f | The force direction vector relative to the untransformed body. |
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)
p | The position vector relative to the untransformed body. |
f | The force direction vector relative to the untransformed body. |
Get the currently acting linear momentum.
Murl.Math.Vector GetLinearMomentum()
Get the currently acting angular momentum.
Murl.Math.Vector GetAngularMomentum()
Get the body's current linear velocity.
Murl.Math.Vector GetLinearVelocity()
Get the body's current angular velocity.
Murl.Math.Vector GetAngularVelocity()
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()
Get the depth of the collision along the collision's normal vector.
Number GetCollisionDepth(Integer collisionIndex)
collisionIndex | The collision index, in the range from 0 to GetNumberOfCollisions(). |
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)
collisionIndex | The collision index, in the range from 0 to GetNumberOfCollisions(). |
bodyIndex | The index of the collision body, either 0 for this body or 1 for the other one. |
Get the actual collider of a body involved in a specific collision.
Murl.Graph.ICollider GetCollisionGeometry(Integer collisionIndex, Integer bodyIndex)
collisionIndex | The collision index, in the range from 0 to GetNumberOfCollisions(). |
bodyIndex | The index of the collision body, either 0 for this body or 1 for the other one. |
Get the surface index of a collision.
Integer GetCollisionSurfaceIndex(Integer collisionIndex, Integer bodyIndex)
collisionIndex | The collision index, in the range from 0 to GetNumberOfCollisions(). |
bodyIndex | The index of the collision body for which to get the index, either 0 for this body or 1 for the other one. |
DEPRECATED: Get the partner of a specific collision. Use GetCollisionBody(collisionIndex, 1) instead.
Murl.Graph.IBody GetCollisionPartner(Integer collisionIndex)
collisionIndex | The collision index, in the range from 0 to GetNumberOfCollisions(). |
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)
partner | The collision partner to query, or null if all partners should be queried. |
margin | The collision margin. |
Get a mutable reference to the body's current world transform matrix.
Murl.Math.Matrix GetBodyTransform()
Get the body's number of stages.
Integer GetNumberOfStages()