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.

AllowedMotion

Gets or sets the body's permitted translations and rotations in world space.

public MotionAxes AllowedMotion { get; set; }

Property Value

MotionAxes

Defaults to All.

Remarks

Each assignment replaces the previous restrictions. For example, PlaneXY permits translation along X and Y and rotation about Z. Restricted directions have zero effective inverse mass or inverse inertia in the solver. Restrictions preserve the scalar Mass and body-space InverseInertia. Changes to mass properties or shapes update the response while retaining the restrictions. Assigning All restores the response derived from those original properties.

Changes immediately clear prohibited velocity components, invalidate cached impulses, and schedule activation. Restrictions also apply to kinematic velocity. They govern simulated motion; position and orientation can still be assigned directly. Setting None does not change MotionType.

Do not change this property concurrently with Step(float, bool).

Exceptions

ArgumentOutOfRangeException

Thrown for undefined flag bits.

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 kinematic velocity schedules the body for activation on the next step. For dynamic bodies, a small tolerance is applied to the activation check. Locked rotation components are cleared.

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 for dynamic bodies. If the magnitudes of both the angular and linear velocity remain below the specified values for the duration of DeactivationTime, its island can be 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 and linear are both approximately 0.316. Kinematic bodies ignore these thresholds and only rest when both velocities are exactly zero.

Exceptions

ArgumentOutOfRangeException

Thrown if either the linear or angular threshold is negative.

DeactivationTime

Gets or sets the deactivation time. Dynamic bodies must remain below the DeactivationThreshold for this time before their island can be deactivated. Kinematic bodies must have zero linear and angular velocity for this time. Default value: 1 second.

public TimeSpan DeactivationTime { get; set; }

Property Value

TimeSpan

Exceptions

ArgumentOutOfRangeException

Thrown when the assigned value is negative.

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 and AllowedMotion is All, every sub-step performs an extra Newton iteration to solve ω × (I ω) implicitly. The solver is skipped while any axes are locked.

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 linear-only speculative contacts are enabled for this body.

public bool EnableSpeculativeContacts { get; set; }

Property Value

bool

Remarks

Speculative contacts help prevent tunneling from fast linear motion by generating contacts before actual penetration occurs. Prediction and speculative bounding box expansion use only linear velocity, with shape orientations held fixed during sweeps. Speculative constraints ignore angular surface velocity and update only linear velocity. They do not prevent tunneling caused by rotation. Bodies still rotate normally, and ordinary overlap contacts retain their angular response. Enabling speculative contacts may increase contact count and solver cost. Default is false.

Force

Accumulated force converted to a velocity change at the end of the next Step(float, bool) call. The change is applied during the following step, and this value is reset to zero after conversion.

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 JSymmetricMatrix InverseInertia { get; }

Property Value

JSymmetricMatrix

Remarks

For world-space inverse inertia, see InverseInertiaWorld. For non-dynamic bodies, the solver treats inertia as infinite regardless of this value. AllowedMotion preserves this tensor and restricts the solver's effective inertia.

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.", true)]
public bool IsStatic { get; set; }

Property Value

bool

IsValid

Gets a value indicating whether the underlying rigid body data is still valid.

public bool IsValid { get; }

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 JSymmetricMatrix, 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. AllowedMotion changes the effective response along individual axes without changing this scalar mass.

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.
  • Switching to Kinematic preserves velocities. Set both velocities to zero if the body should become stationary.
  • Constraints remain registered and are suspended while neither connected body is dynamic.
  • Any queued forces, torques, and force-derived velocity changes are discarded.
  • 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 a dynamic or kinematic body for activation on the next step. Moving a static body activates connected bodies. Any currently active cached contacts involving this body are invalidated.

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 a dynamic or kinematic body for activation on the next step. Moving a static body activates connected bodies. Any currently active cached contacts involving this body are invalidated.

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 used by the engine.

public object? Tag { get; set; }

Property Value

object

Torque

Accumulated torque converted to an angular velocity change at the end of the next Step(float, bool) call. The change is applied during the following step, and this value is reset to zero after conversion.

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 kinematic velocity schedules the body for activation on the next step. For dynamic bodies, a small tolerance is applied to the activation check. Locked translation components are cleared.

Exceptions

InvalidOperationException

Thrown if the body's MotionType is Static.

World

Gets 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 at a world-space position. The force and resulting torque are converted to velocity changes at the end of the next Step(float, bool) call and applied during the following step.

[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 accumulate. It is converted to a velocity change at the end of the next Step(float, bool) call and applied during the following step.

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.", true)]
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.", true)]
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.

Remarks

If registration or mass calculation fails, the shape remains detached and the body's mass properties remain unchanged.

Exceptions

ArgumentNullException

Thrown if shape is null.

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.

Remarks

If registration or mass calculation fails, the shape remains detached and the body's mass properties remain unchanged.

Exceptions

ArgumentException

Thrown if the shape is already registered elsewhere.

ArgumentNullException

Thrown if shape is null.

ArgumentOutOfRangeException

Thrown when massInertiaMode is not a valid MassInertiaUpdateMode value.

AddShape(RigidBodyShape, bool) 

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

Parameters

shape RigidBodyShape
setMassInertia bool

AddShape(IEnumerable<RigidBodyShape>, bool) 

[Obsolete("Use AddShapes with MassInertiaUpdateMode instead.", true)]
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

ArgumentNullException

Thrown if shapes or any contained shape is null.

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

ArgumentNullException

Thrown if shapes or any contained shape is null.

ArgumentException

Thrown if any shape is already attached to a body.

ArgumentOutOfRangeException

Thrown when massInertiaMode is not a valid MassInertiaUpdateMode value.

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.

ClearContactCache()

Clears the cached contact manifold state for all current contacts of this body.

public void ClearContactCache()

Remarks

This discards cached contact points and accumulated impulses, forcing contact manifolds to be rebuilt on the next simulation step. This is useful after discontinuous user-driven transform changes such as teleports. Do not call this concurrently with Step(float, bool).

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.", true)]
public void ClearShapes(bool setMassInertia = true)

Parameters

setMassInertia bool

DebugDraw(IDebugDrawer)

Draws the body's collision shapes at their current positions and rotations.

public void DebugDraw(IDebugDrawer drawer)

Parameters

drawer IDebugDrawer

The debug drawer receiving the shapes.

Remarks

Emits world-space triangles through DrawTriangle(in JVector, in JVector, in JVector, uint). Point clouds and custom shapes may appear with gaps or overlapping faces.

DebugDraw(IDebugDrawer, in DebugDrawSettings)

Draws the body's collision shapes using the supplied settings.

public void DebugDraw(IDebugDrawer drawer, in DebugDrawSettings settings)

Parameters

drawer IDebugDrawer

The debug drawer receiving the shapes.

settings DebugDrawSettings

The visualization settings.

Remarks

Uses Segments for built-in curved surfaces, ShapeSubdivisions for approximate surfaces, and CurrentColor for the triangles.

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.

Exceptions

ArgumentNullException

Thrown if shape is null.

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.

Exceptions

ArgumentException

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

ArgumentNullException

Thrown if shape is null.

ArgumentOutOfRangeException

Thrown when massInertiaMode is not a valid MassInertiaUpdateMode value.

RemoveShape(RigidBodyShape, bool) 

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

Parameters

shape RigidBodyShape
setMassInertia bool

RemoveShape(IEnumerable<RigidBodyShape>, bool) 

[Obsolete("Use RemoveShapes with MassInertiaUpdateMode instead.", true)]
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.

Exceptions

ArgumentNullException

Thrown if shapes or any contained shape is null.

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.

Exceptions

ArgumentNullException

Thrown if shapes or any contained shape is null.

ArgumentException

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

ArgumentOutOfRangeException

Thrown when massInertiaMode is not a valid MassInertiaUpdateMode value.

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.

Remarks

Activation and deactivation are applied through the body's simulation island. Static bodies cannot be activated by this method, although moving a static body can wake connected non-static bodies.

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 JSymmetricMatrix, float, bool)

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

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

Parameters

inertia JSymmetricMatrix

The symmetric 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, including for a speculative contact before the bodies overlap.

[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 when contact tracking begins between two bodies.

EndCollide

Event triggered when an arbiter expires during a simulation step because contact has ended. 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. Explicit arbiter, body, or shape removal does not raise this event.

Edit this page