Table of Contents

Class RigidBody

Namespace
Jitter2.Dynamics
Assembly
Jitter2.dll

Represents the primary entity in the Jitter physics world.

public sealed class RigidBody : IPartitionedSetIndex, IDebugDrawable
Inheritance
RigidBody
Implements
Inherited Members

Fields

RigidBodyId

Unique identifier for this rigid body, assigned by the World upon creation. This ID remains stable for the lifetime of the body.

public readonly ulong RigidBodyId

Field Value

ulong

Properties

AffectedByGravity

Gets or sets whether the body is affected by the world's gravity during integration.

public bool AffectedByGravity { get; set; }

Property Value

bool

Remarks

Only applies when MotionType is Dynamic. Default is true.

AngularVelocity

Gets or sets the angular velocity of the rigid body in world space.

public JVector AngularVelocity { get; set; }

Property Value

JVector

Remarks

Measured in radians per second. The vector direction is the rotation axis, and its magnitude is the rotation speed. Setting a non-zero velocity schedules the body for activation on the next step.

Exceptions

InvalidOperationException

Thrown if the body's MotionType is Static.

Connections

Contains all bodies this body is in contact with or shares a constraint with.

public ReadOnlyList<RigidBody> Connections { get; }

Property Value

ReadOnlyList<RigidBody>

Constraints

Contains all constraints connected to this body.

public ReadOnlyHashSet<Constraint> Constraints { get; }

Property Value

ReadOnlyHashSet<Constraint>

Contacts

Contains all contacts in which this body is involved.

public ReadOnlyHashSet<Arbiter> Contacts { get; }

Property Value

ReadOnlyHashSet<Arbiter>

Damping

Gets or sets the damping factors for linear and angular motion. A damping factor of 0 means the body is not damped, while 1 brings the body to a halt immediately. Damping is applied when calling Step(float, bool). Jitter multiplies the respective velocity each step by 1 minus the damping factor. Note that the values are not scaled by time; a smaller time-step in Step(float, bool) results in increased damping.

public (float linear, float angular) Damping { get; set; }

Property Value

(float angular, float linear)

Remarks

The damping factors must be within the range [0, 1]. Default values: linear = 0.002, angular = 0.005.

Exceptions

ArgumentOutOfRangeException

Thrown if either the linear or angular damping value is less than 0 or greater than 1.

Data

Returns a by-ref view of the unmanaged simulation state for this body.

public ref RigidBodyData Data { get; }

Property Value

RigidBodyData

Remarks

Due to performance considerations, simulation data (position, velocity, etc.) is stored in a contiguous block of unmanaged memory. This property provides direct access to that data.

Usage notes:

  • Prefer using RigidBody properties instead of accessing fields directly.
  • Do not cache the returned reference across simulation steps.
  • Modifying fields directly can break invariants (e.g., world-space inertia) unless you know what you're doing.

DeactivationThreshold

Gets or sets the deactivation threshold. If the magnitudes of both the angular and linear velocity remain below the specified values for the duration of DeactivationTime, the body is deactivated. The threshold values are given in rad/s and length units/s, respectively.

public (float angular, float linear) DeactivationThreshold { get; set; }

Property Value

(float angular, float linear)

Remarks

Values must be non-negative. Default values: angular = 0.1, linear = 0.1.

Exceptions

ArgumentOutOfRangeException

Thrown if either the linear or angular threshold is negative.

DeactivationTime

Gets or sets the deactivation time. If the magnitudes of both the angular and linear velocity of the rigid body remain below the DeactivationThreshold for the specified time, the body is deactivated. Default value: 1 second.

public TimeSpan DeactivationTime { get; set; }

Property Value

TimeSpan

EnableGyroscopicForces

Enables the implicit gyroscopic–torque solver for this RigidBody.

public bool EnableGyroscopicForces { get; set; }

Property Value

bool

true to integrate gyroscopic torque each step; otherwise false (default).

Remarks

When true, every sub-step performs an extra Newton iteration to solve ω × (I ω) implicitly.

The benefit becomes noticeable for bodies with a high inertia anisotropy or very fast spin-rates. Typical examples are long, thin rods, spinning tops, propellers, and other objects whose principal inertia values differ by an order of magnitude. In those cases the flag eliminates artificial precession.

EnableSpeculativeContacts

Gets or sets whether speculative contacts are enabled for this body.

public bool EnableSpeculativeContacts { get; set; }

Property Value

bool

Remarks

Speculative contacts help prevent tunneling for fast-moving bodies by generating contacts before actual penetration occurs. This may increase contact count and solver cost. Default is false.

Force

Represents the force to be applied to the body during the next call to Step(float, bool). This value is automatically reset to zero after the call.

public JVector Force { get; set; }

Property Value

JVector

Friction

Gets or sets the coefficient of friction used for contact resolution.

public float Friction { get; set; }

Property Value

float

Remarks

The friction coefficient determines the resistance to sliding motion. Values typically range from 0 (no friction) upwards. Higher values represent strong friction or adhesion effects. Default value: 0.2.

Exceptions

ArgumentOutOfRangeException

Thrown if the value is negative.

Handle

Gets the handle to the rigid body data, see Data.

public JHandle<RigidBodyData> Handle { get; }

Property Value

JHandle<RigidBodyData>

InverseInertia

Gets the inverse inertia tensor in body (local) space.

public JMatrix InverseInertia { get; }

Property Value

JMatrix

Remarks

For world-space inverse inertia, see InverseInertiaWorld. For non-dynamic bodies, the solver treats inertia as infinite regardless of this value.

IsActive

Indicates whether the rigid body is active or considered to be in a sleeping state. Use SetActivationState(bool) to alter the activation state.

public bool IsActive { get; }

Property Value

bool

IsStatic 

[Obsolete("Use the MotionType property instead.")]
public bool IsStatic { get; set; }

Property Value

bool

Island

Gets the collision island associated with this rigid body.

public Island Island { get; }

Property Value

Island

Mass

Gets the mass of the rigid body. To modify the mass, use SetMassInertia(float) or SetMassInertia(in JMatrix, float, bool).

public float Mass { get; }

Property Value

float

Remarks

This value is only meaningful for Dynamic bodies. Static and kinematic bodies are treated as having infinite mass by the solver regardless of this value.

MotionType

Gets or sets how the rigid body participates in the simulation.

public MotionType MotionType { get; set; }

Property Value

MotionType

Remarks

Changing this property has immediate side effects:

  • Switching to Static zeroes velocities, removes connections, and deactivates the body.
  • Switching from Static rebuilds connections from existing contacts.
  • Dynamic bodies use their mass and inertia; static and kinematic bodies are treated as having infinite mass by the solver.

Exceptions

ArgumentOutOfRangeException

Thrown if the value is not a valid MotionType.

Orientation

Gets or sets the world-space orientation of the rigid body.

public JQuaternion Orientation { get; set; }

Property Value

JQuaternion

Remarks

Setting this property updates the broadphase proxies for all attached shapes and schedules the body for activation on the next step.

Position

Gets or sets the world-space position of the rigid body.

public JVector Position { get; set; }

Property Value

JVector

Remarks

Setting this property updates the broadphase proxies for all attached shapes and schedules the body for activation on the next step.

Restitution

Gets or sets the restitution (bounciness) of this object.

public float Restitution { get; set; }

Property Value

float

Remarks

The restitution value determines how much energy is retained after a collision, with 0 representing an inelastic collision (no bounce) and 1 representing a perfectly elastic collision (full bounce). Values between 0 and 1 create a partially elastic collision effect. Default value: 0.0.

Exceptions

ArgumentOutOfRangeException

Thrown if the value is not between 0 and 1.

Shapes

Gets the list of shapes added to this rigid body.

public ReadOnlyList<RigidBodyShape> Shapes { get; }

Property Value

ReadOnlyList<RigidBodyShape>

Tag

A managed pointer to custom user data. This is not utilized by the engine.

public object? Tag { get; set; }

Property Value

object

Torque

Represents the torque to be applied to the body during the next call to Step(float, bool). This value is automatically reset to zero after the call.

public JVector Torque { get; set; }

Property Value

JVector

Velocity

Gets or sets the linear velocity of the rigid body in world space.

public JVector Velocity { get; set; }

Property Value

JVector

Remarks

Measured in units per second. Setting a non-zero velocity schedules the body for activation on the next step.

Exceptions

InvalidOperationException

Thrown if the body's MotionType is Static.

World

Gets or sets the world assigned to this body.

public World World { get; }

Property Value

World

Methods

AddForce(in JVector, in JVector, bool)

Applies a force to the rigid body, altering its velocity. This force is applied for a single frame only and is reset to zero with the following call to Step(float, bool).

[ReferenceFrame(ReferenceFrame.World)]
public void AddForce(in JVector force, in JVector position, bool wakeup = true)

Parameters

force JVector

The force to be applied.

position JVector

The position where the force will be applied.

wakeup bool

If true (default), the body will be activated if it is currently sleeping. If false, the force is only applied if the body is already active; sleeping bodies will remain asleep and ignore the force.

AddForce(in JVector, bool)

Applies a force to the rigid body, thereby altering its velocity.

public void AddForce(in JVector force, bool wakeup = true)

Parameters

force JVector

The force to be applied. This force is effective for a single frame only and is reset to zero during the next call to Step(float, bool).

wakeup bool

If true (default), the body will be activated if it is currently sleeping. If false, the force is only applied if the body is already active; sleeping bodies will remain asleep and ignore the force.

AddImpulse(in JVector, in JVector, bool) 

[Obsolete("Use ApplyImpulse instead.")]
public void AddImpulse(in JVector impulse, in JVector position, bool wakeup = true)

Parameters

impulse JVector
position JVector
wakeup bool

AddImpulse(in JVector, bool) 

[Obsolete("Use ApplyImpulse instead.")]
public void AddImpulse(in JVector impulse, bool wakeup = true)

Parameters

impulse JVector
wakeup bool

AddShape(RigidBodyShape)

Adds a shape to the body.

public void AddShape(RigidBodyShape shape)

Parameters

shape RigidBodyShape

The shape to be added.

Exceptions

ArgumentException

Thrown if the shape is already registered elsewhere.

AddShape(RigidBodyShape, MassInertiaUpdateMode)

Adds a shape to the body.

public void AddShape(RigidBodyShape shape, MassInertiaUpdateMode massInertiaMode)

Parameters

shape RigidBodyShape

The shape to be added.

massInertiaMode MassInertiaUpdateMode

Controls whether the body's mass and inertia are recomputed after the shape is added.

Exceptions

ArgumentException

Thrown if the shape is already registered elsewhere.

AddShape(RigidBodyShape, bool) 

[Obsolete("Use AddShape with MassInertiaUpdateMode instead.")]
public void AddShape(RigidBodyShape shape, bool setMassInertia = true)

Parameters

shape RigidBodyShape
setMassInertia bool

AddShape(IEnumerable<RigidBodyShape>, bool) 

[Obsolete("Use AddShapes with MassInertiaUpdateMode instead.")]
public void AddShape(IEnumerable<RigidBodyShape> shapes, bool setMassInertia = true)

Parameters

shapes IEnumerable<RigidBodyShape>
setMassInertia bool

AddShapes(IEnumerable<RigidBodyShape>)

Adds several shapes to the rigid body at once. Mass properties are recalculated only once, if requested.

public void AddShapes(IEnumerable<RigidBodyShape> shapes)

Parameters

shapes IEnumerable<RigidBodyShape>

The shapes to add.

Exceptions

ArgumentException

Thrown if any shape is already attached to a body.

AddShapes(IEnumerable<RigidBodyShape>, MassInertiaUpdateMode)

Adds several shapes to the rigid body at once. Mass properties are recalculated only once, if requested.

public void AddShapes(IEnumerable<RigidBodyShape> shapes, MassInertiaUpdateMode massInertiaMode)

Parameters

shapes IEnumerable<RigidBodyShape>

The shapes to add.

massInertiaMode MassInertiaUpdateMode

Controls whether the body's mass and inertia are recomputed after the shapes are added.

Remarks

Shapes are added sequentially. If an exception is thrown, shapes processed before the failure remain attached to the body.

Exceptions

ArgumentException

Thrown if any shape is already attached to a body.

ApplyImpulse(in JVector, in JVector, bool)

Applies an instantaneous impulse at a world-space position, directly changing both linear and angular velocity.

[ReferenceFrame(ReferenceFrame.World)]
public void ApplyImpulse(in JVector impulse, in JVector position, bool wakeup = true)

Parameters

impulse JVector

The impulse to be applied.

position JVector

The position where the impulse will be applied.

wakeup bool

If true (default), the body will be activated if it is currently sleeping. If false, the impulse is only applied if the body is already active; sleeping bodies will remain asleep and ignore the impulse.

ApplyImpulse(in JVector, bool)

Applies an instantaneous impulse to the rigid body, directly changing its velocity.

public void ApplyImpulse(in JVector impulse, bool wakeup = true)

Parameters

impulse JVector

The impulse to be applied.

wakeup bool

If true (default), the body will be activated if it is currently sleeping. If false, the impulse is only applied if the body is already active; sleeping bodies will remain asleep and ignore the impulse.

ClearShapes()

Removes all shapes associated with the rigid body.

public void ClearShapes()

ClearShapes(MassInertiaUpdateMode)

Removes all shapes associated with the rigid body.

public void ClearShapes(MassInertiaUpdateMode massInertiaMode)

Parameters

massInertiaMode MassInertiaUpdateMode

Controls whether the body's mass and inertia are recomputed after the shapes are removed.

ClearShapes(bool) 

[Obsolete("Use ClearShapes with MassInertiaUpdateMode instead.")]
public void ClearShapes(bool setMassInertia = true)

Parameters

setMassInertia bool

DebugDraw(IDebugDrawer)

Generates a rough triangle approximation of the shapes of the body. Since the generation is slow this should only be used for debugging purposes.

public void DebugDraw(IDebugDrawer drawer)

Parameters

drawer IDebugDrawer

The debug drawer to receive the generated triangles.

Remarks

This method tessellates all attached shapes and is not suitable for real-time use. It uses a shared static list internally and is not thread-safe.

PredictOrientation(float)

Predicts the orientation of the body after a given time step using angular velocity. This does not simulate forces or collisions — it assumes constant angular velocity.

public JQuaternion PredictOrientation(float dt)

Parameters

dt float

The time step to extrapolate forward.

Returns

JQuaternion

The predicted orientation after dt.

PredictPose(float, out JVector, out JQuaternion)

Predicts the pose (position and orientation) of the body after a given time step using simple extrapolation. This method is intended for rendering purposes and does not modify the simulation state.

public void PredictPose(float dt, out JVector position, out JQuaternion orientation)

Parameters

dt float

The time step to extrapolate forward.

position JVector

The predicted position after dt.

orientation JQuaternion

The predicted orientation after dt.

PredictPosition(float)

Predicts the position of the body after a given time step using linear extrapolation. This does not simulate forces or collisions — it assumes constant velocity.

public JVector PredictPosition(float dt)

Parameters

dt float

The time step to extrapolate forward.

Returns

JVector

The predicted position after dt.

RemoveShape(RigidBodyShape)

Removes a specified shape from the rigid body.

public void RemoveShape(RigidBodyShape shape)

Parameters

shape RigidBodyShape

The shape to remove from the rigid body.

Remarks

This operation has a time complexity of O(n), where n is the number of shapes attached to the body.

Exceptions

ArgumentException

Thrown if the specified shape is not part of this rigid body.

RemoveShape(RigidBodyShape, MassInertiaUpdateMode)

Removes a specified shape from the rigid body.

public void RemoveShape(RigidBodyShape shape, MassInertiaUpdateMode massInertiaMode)

Parameters

shape RigidBodyShape

The shape to remove from the rigid body.

massInertiaMode MassInertiaUpdateMode

Controls whether the body's mass and inertia are recomputed after the shape is removed.

Remarks

This operation has a time complexity of O(n), where n is the number of shapes attached to the body.

Exceptions

ArgumentException

Thrown if the specified shape is not part of this rigid body.

RemoveShape(RigidBodyShape, bool) 

[Obsolete("Use RemoveShape with MassInertiaUpdateMode instead.")]
public void RemoveShape(RigidBodyShape shape, bool setMassInertia = true)

Parameters

shape RigidBodyShape
setMassInertia bool

RemoveShape(IEnumerable<RigidBodyShape>, bool) 

[Obsolete("Use RemoveShapes with MassInertiaUpdateMode instead.")]
public void RemoveShape(IEnumerable<RigidBodyShape> shapes, bool setMassInertia = true)

Parameters

shapes IEnumerable<RigidBodyShape>
setMassInertia bool

RemoveShapes(IEnumerable<RigidBodyShape>)

Removes several shapes from the body.

public void RemoveShapes(IEnumerable<RigidBodyShape> shapes)

Parameters

shapes IEnumerable<RigidBodyShape>

The shapes to remove from the rigid body.

Remarks

This operation has a time complexity of O(n), where n is the number of shapes attached to the body.

Exceptions

ArgumentException

Thrown if at least one shape is not part of this rigid body.

RemoveShapes(IEnumerable<RigidBodyShape>, MassInertiaUpdateMode)

Removes several shapes from the body.

public void RemoveShapes(IEnumerable<RigidBodyShape> shapes, MassInertiaUpdateMode massInertiaMode)

Parameters

shapes IEnumerable<RigidBodyShape>

The shapes to remove from the rigid body.

massInertiaMode MassInertiaUpdateMode

Controls whether the body's mass and inertia are recomputed after the shapes are removed.

Remarks

This operation has a time complexity of O(n), where n is the number of shapes attached to the body.

Exceptions

ArgumentException

Thrown if at least one shape is not part of this rigid body.

SetActivationState(bool)

Instructs the engine to activate or deactivate the body at the beginning of the next time step. The current state does not change immediately.

public void SetActivationState(bool active)

Parameters

active bool

If true, the body will be activated; if false, deactivated.

SetMassInertia()

Computes the mass and inertia of this body from all attached shapes, assuming unit density.

public void SetMassInertia()

Remarks

The mass contributions of all shapes are summed. If no shapes are attached, the body is assigned a mass of 1 and an identity inertia tensor.

Exceptions

InvalidOperationException

Thrown if the computed inertia matrix is not invertible. This may occur if a shape has invalid mass properties.

SetMassInertia(in JMatrix, float, bool)

Sets the new mass properties of this body by specifying both inertia and mass directly.

public void SetMassInertia(in JMatrix inertia, float mass, bool setAsInverse = false)

Parameters

inertia JMatrix

The inertia tensor (or inverse inertia tensor if setAsInverse is true) in body (local) space, about the center of mass.

mass float

The mass (or inverse mass if setAsInverse is true). When setting inverse mass, a value of zero represents infinite mass.

setAsInverse bool

If true, inertia and mass are interpreted as inverse values.

Exceptions

ArgumentException

Thrown if:

  • mass is zero or negative when setAsInverse is false.
  • mass is negative or infinite when setAsInverse is true.
  • inertia is not invertible when setAsInverse is false.

SetMassInertia(float)

Computes the inertia from all attached shapes, then uniformly scales it to match the specified mass.

public void SetMassInertia(float mass)

Parameters

mass float

The desired total mass of the body. Must be positive.

Remarks

This is equivalent to calling SetMassInertia() and then scaling the resulting inertia tensor so the body has the desired total mass. Use this when you want shape-derived inertia proportions but a specific total mass (e.g., for gameplay tuning).

Exceptions

ArgumentException

Thrown if the specified mass is zero or negative.

Events

BeginCollide

Event triggered when a new arbiter is created, indicating that two bodies have begun colliding.

[CallbackThread(ThreadContext.MainThread)]
public event Action<Arbiter>? BeginCollide

Event Type

Action<Arbiter>

Remarks

This event provides an Arbiter object which contains details about the collision. Use this event to handle logic that should occur at the start of a collision between two bodies.

EndCollide

Event triggered when an arbiter is destroyed, indicating that two bodies have stopped colliding. The reference to this arbiter becomes invalid after this call.

[CallbackThread(ThreadContext.MainThread)]
public event Action<Arbiter>? EndCollide

Event Type

Action<Arbiter>

Remarks

This event provides an Arbiter object which contains details about the collision that has ended. Use this event to handle logic that should occur when the collision between two bodies ends.

Edit this page