Table of Contents

Class RigidBody

Namespace
Jitter2.Dynamics
Assembly
Jitter2.dll

A body with a position, orientation, velocity, and collision shapes.

public sealed class RigidBody : IPartitionedSetIndex, IDebugDrawable, IFormattable
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. Restrictions survive changes to shapes and mass properties; they do not change Mass or InverseInertia. Use All to remove them.

Changing the restrictions clears prohibited velocity components and saved solver impulses, and schedules the body to wake. Restrictions apply to dynamic and kinematic motion, but do not prevent direct changes to Position or Orientation. 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 velocity wakes the body on the next step, unless it is zero, or nearly zero for a dynamic body. 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 how much linear and angular velocity is lost each simulation step. Zero disables damping; one stops the body. Each step multiplies velocity by one minus the factor.

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

Property Value

(float linear, float angular)

Remarks

Values must be within [0, 1]. Defaults are linear = 0.002 and angular = 0.005. Damping is applied per step, so using shorter steps increases damping over the same elapsed time.

Exceptions

ArgumentOutOfRangeException

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

Data

Gets a reference to this body's low-level simulation data.

public ref RigidBodyData Data { get; }

Property Value

RigidBodyData

Remarks

Prefer the body's properties: direct field changes bypass collision bounds and other updates. Obtain a fresh reference after stepping or changing the world: its storage can move. Do not access it concurrently with Step(float, bool). It is invalid after the body is removed.

DeactivationThreshold

Obsolete: use DeactivationVelocity, which takes the linear value first.

[Obsolete("Use DeactivationVelocity instead. Note that it takes the linear value first.", true)]
public (float angular, float linear) DeactivationThreshold { get; set; }

Property Value

(float linear, float angular)

DeactivationTime

Gets or sets the deactivation time. Dynamic bodies must remain below the DeactivationVelocity 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.

DeactivationVelocity

Gets or sets the deactivation velocity for dynamic bodies. If the magnitudes of both the linear and angular velocity remain below the specified values for the duration of DeactivationTime, its island can be deactivated. The values are given in length units/s and rad/s, respectively.

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

Property Value

(float linear, float angular)

Remarks

Values must be non-negative. Default values: linear and angular are both approximately 0.316. Kinematic bodies ignore these values and only rest when both velocities are exactly zero.

Exceptions

ArgumentOutOfRangeException

Thrown if either the linear or angular value is negative.

EnableCcd

Gets or sets whether continuous collision detection (CCD) is enabled for this body.

public bool EnableCcd { get; set; }

Property Value

bool

Remarks

CCD helps prevent fast-moving or rotating bodies from passing through other shapes. It costs additional collision detection and solver work; enable it only where needed. Default is false. Enable it on both bodies when both move quickly, since a moving body without CCD may otherwise be missed.

CcdIterations controls the number of collision discovery passes. A finite number of passes cannot guarantee that every collision is found.

CCD contacts do not apply restitution.

EnableGyroscopicForces

Gets or sets whether gyroscopic forces affect the body's rotation.

public bool EnableGyroscopicForces { get; set; }

Property Value

bool

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

Remarks

Includes the change in rotation caused by a spinning body's uneven mass distribution, as seen with spinning tops or long rods. This adds solver work each substep. It is only applied when AllowedMotion is All.

Force

The force accumulated for the body. It acts one step late: the end of the next Step(float, bool) turns it into a velocity change and resets it to zero, and the step after that applies the change.

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

Zero allows frictionless sliding; higher values resist sliding more strongly. Default is 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

Switching to Static clears velocities and schedules the body to sleep. Switching to Kinematic preserves velocities; set them to zero if the body should stop. Every change discards pending forces, torques, and their velocity changes.

Constraints remain registered, but are suspended while neither connected body is dynamic. Static and kinematic bodies do not respond to forces or impulses, regardless of their stored mass.

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

Changing this value updates collision bounds and discards saved contacts. Dynamic and kinematic bodies are scheduled to wake on the next step; moving a static body wakes the bodies connected to it.

Position

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

public JVector Position { get; set; }

Property Value

JVector

Remarks

Changing this value updates collision bounds and discards saved contacts. Dynamic and kinematic bodies are scheduled to wake on the next step; moving a static body wakes the bodies connected to it. The position of NullBody must remain at the world origin.

Restitution

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

public float Restitution { get; set; }

Property Value

float

Remarks

Ranges from 0 (no bounce, the default) to 1 (fully elastic bounce). Not applied to contacts predicted by CCD (EnableCcd).

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

Gets or sets application data associated with this body. The engine does not use this value.

public object? Tag { get; set; }

Property Value

object

Torque

The torque accumulated for the body. Like Force, it acts one step late.

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 velocity wakes the body on the next step, unless it is zero, or nearly zero for a dynamic body. 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)

Adds a force at a world-space position to Force and the resulting torque to Torque. Both act one step late.

[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)

Adds a force at the center of mass to Force. It acts one step late.

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

Parameters

force JVector

The force to add.

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()

Discards saved contact points and impulses for this body.

public void ClearContactCache()

Remarks

Contact points are rebuilt on the next simulation step. Use after changing low-level body data directly, for example when restoring a saved state. Setting Position or Orientation already clears the cache. 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, it is marked for deactivation.

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. Deactivation is only a request: the island falls asleep once all of its bodies are below their DeactivationVelocity and AllowDeactivation is true. Motion above these values cancels the request. Use ForceSleepIsland(Island) to put an island to sleep immediately.

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

Preserves the relative mass contributions of the attached shapes while scaling the total to mass. If there are no shapes, uses an identity inertia tensor scaled by the mass.

Exceptions

ArgumentException

Thrown if the specified mass is zero or negative.

ToString()

Returns a short description of the body's ID, motion type, activation state, and position.

public override string ToString()

Returns

string

ToString(string?)

Formats the body's description using the specified position format and the current culture.

public string ToString(string? format)

Parameters

format string

Returns

string

ToString(string?, IFormatProvider?)

Formats the body's description using the specified position format and culture.

public string ToString(string? format, IFormatProvider? formatProvider)

Parameters

format string

A numeric format for the position, or null or empty to use the general format.

formatProvider IFormatProvider

The format provider, or null to use the current culture.

Returns

string

Events

BeginCollide

Raised when a new contact pair begins, including a predicted CCD contact before the bodies overlap.

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

Event Type

Action<Arbiter>

Remarks

The Arbiter contains the bodies and their contact points.

EndCollide

Raised during a simulation step when a contact pair ends. Do not retain the arbiter after the callback; it may be reused for another pair.

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

Event Type

Action<Arbiter>

Remarks

Explicit arbiter, body, or shape removal does not raise this event.

Edit this page