Table of Contents

Class SolidBody2D

Namespace
Gravitas
Assembly
Gravitas.dll

Represents deterministic pure 2D body state owned by one world context.

public sealed class SolidBody2D : IRecordable
Inheritance
SolidBody2D
Implements
IRecordable
Inherited Members

Constructors

SolidBody2D(IMatterAgent, LSCollider2D)

Creates a pure 2D body bound to a host agent and collider.

public SolidBody2D(IMatterAgent agent, LSCollider2D collider)

Parameters

agent IMatterAgent
collider LSCollider2D

Fields

OnGrounded

Raised when grounded state changes.

public Action<bool>? OnGrounded

Field Value

Action<bool>

Properties

Active

Gets whether the body is initialized and registered.

public bool Active { get; }

Property Value

bool

Agent

Gets the host agent that owns this body.

public IMatterAgent Agent { get; }

Property Value

IMatterAgent

AngularAcceleration

Gets the accumulated yaw acceleration.

public Fixed64 AngularAcceleration { get; }

Property Value

Fixed64

AngularSpeed

Gets the absolute yaw speed.

public Fixed64 AngularSpeed { get; }

Property Value

Fixed64

AngularVelocity

Gets the signed yaw velocity.

public Fixed64 AngularVelocity { get; }

Property Value

Fixed64

CanRotate

Gets whether solver-side response may rotate this pure 2D body around its yaw axis.

public bool CanRotate { get; }

Property Value

bool

CanTranslate

Gets whether solver-side response may translate this pure 2D body.

public bool CanTranslate { get; }

Property Value

bool

Collider

Gets the runtime 2D collider attached to this body.

public LSCollider2D Collider { get; }

Property Value

LSCollider2D

Context

Gets the world context supplied by the host agent.

public GravitasWorldContext Context { get; }

Property Value

GravitasWorldContext

ContinuousCollisionMode

Selects the deterministic tunneling guard used when this pure 2D body commits frame movement.

public ContinuousCollisionMode ContinuousCollisionMode { get; set; }

Property Value

ContinuousCollisionMode

Exceptions

ArgumentOutOfRangeException

The value is not a declared continuous-collision mode.

DynamicId

Gets the ephemeral simulated-body slot, or -1 for a static or unregistered body.

public int DynamicId { get; }

Property Value

int

EffectiveInverseMass

Gets the inverse mass that should be used by pure 2D and mixed response.

public Fixed64 EffectiveInverseMass { get; }

Property Value

Fixed64

EffectiveInverseMomentOfInertia

Gets the inverse scalar moment that should be used by pure 2D angular response.

public Fixed64 EffectiveInverseMomentOfInertia { get; }

Property Value

Fixed64

FreezeAxes

Gets or sets the planar translational and yaw rotational degrees of freedom frozen for pure 2D solver response, integration, CCD, and rotational CCD.

public BodyFreezeAxes2D FreezeAxes { get; set; }

Property Value

BodyFreezeAxes2D

Gravity

Gets or sets the planar gravity acceleration applied to this body.

public Vector2d Gravity { get; set; }

Property Value

Vector2d

GravityScale

Multiplies this body's planar gravity vector. Zero disables body-authored gravity acceleration.

public Fixed64 GravityScale { get; set; }

Property Value

Fixed64

GroundDownDistanceOnAir

Probe distance used while the body is airborne.

public Fixed64 GroundDownDistanceOnAir { get; set; }

Property Value

Fixed64

GroundMinNormalDot

Minimum normalized support-normal dot product with resolved up, in [0, 1]. Defaults to one half (slopes through 60 degrees). Zero permits any positive up-dot; horizontal, downward-facing and zero normals never support.

public Fixed64 GroundMinNormalDot { get; set; }

Property Value

Fixed64

GroundNormal

Gets the current support normal in the X/Z simulation plane.

public Vector2d GroundNormal { get; }

Property Value

Vector2d

GroundPoint

Gets the current support point in the X/Z simulation plane.

public Vector2d GroundPoint { get; }

Property Value

Vector2d

Exceptions

InvalidOperationException

No grounded point is available or the conceptual contact point is outside the scalar range.

GroundProbeMode

Selects the pure 2D query primitive used when probing for planar support.

public GroundProbeMode2D GroundProbeMode { get; set; }

Property Value

GroundProbeMode2D

GroundProbeRadius

Optional explicit radius for swept-circle support probes. A zero value derives the radius from the collider.

public Fixed64 GroundProbeRadius { get; set; }

Property Value

Fixed64

GroundUpDirection

Gets or sets the fallback support up direction in the X/Z simulation plane.

public Vector2d GroundUpDirection { get; set; }

Property Value

Vector2d

GroundedDistanceRay

Probe distance used while the body is already grounded.

public Fixed64 GroundedDistanceRay { get; set; }

Property Value

Fixed64

GroundingMode

Selects whether Gravitas owns planar support detection or preserves host-supplied state.

public GroundingMode GroundingMode { get; }

Property Value

GroundingMode

HasGroundPoint

Gets whether the current support point can be represented in the X/Z simulation plane.

public bool HasGroundPoint { get; }

Property Value

bool

InverseMass

Gets the reciprocal mass, or zero when the mass is non-positive.

public Fixed64 InverseMass { get; }

Property Value

Fixed64

InverseMomentOfInertia

Gets the reciprocal yaw moment of inertia.

public Fixed64 InverseMomentOfInertia { get; }

Property Value

Fixed64

IsDynamic

Gets whether the solver controls this body.

public bool IsDynamic { get; }

Property Value

bool

IsGrounded

Gets whether this body currently has planar support.

public bool IsGrounded { get; }

Property Value

bool

IsKinematic

Gets whether the host controls this body's pose.

public bool IsKinematic { get; }

Property Value

bool

IsPositionFullyFrozen

Gets whether both planar translation axes are frozen.

public bool IsPositionFullyFrozen { get; }

Property Value

bool

IsRotationFullyFrozen

Gets whether pure 2D yaw rotation is frozen.

public bool IsRotationFullyFrozen { get; }

Property Value

bool

IsSleeping

Gets whether the body is sleeping.

public bool IsSleeping { get; }

Property Value

bool

IsStatic

Gets whether this body is excluded from per-frame motion.

public bool IsStatic { get; }

Property Value

bool

LastContinuousCollisionToiIterationCount

Gets the number of continuous-collision impacts consumed by the most recent 2D late simulation step.

public int LastContinuousCollisionToiIterationCount { get; }

Property Value

int

LastContinuousCollisionToiIterationLimitReached

Gets whether a CCD work/state limit or unresolved refinement required a conservative clamp in the most recent 2D late simulation step.

public bool LastContinuousCollisionToiIterationLimitReached { get; }

Property Value

bool

LastGroundedPosition

Gets the body position captured when the current support state was accepted.

public Vector2d LastGroundedPosition { get; }

Property Value

Vector2d

LinearSpeed

Gets the magnitude of LinearVelocity.

public Fixed64 LinearSpeed { get; }

Property Value

Fixed64

LinearVelocity

Gets the authoritative planar linear velocity.

public Vector2d LinearVelocity { get; }

Property Value

Vector2d

LocalCenterOfMassOffset

Gets or sets the authoritative body-local center-of-mass offset in the X/Z simulation plane.

public Vector2d LocalCenterOfMassOffset { get; set; }

Property Value

Vector2d

Mass

Gets or sets mass in kilograms. Non-positive mass disables solver motion.

public Fixed64 Mass { get; set; }

Property Value

Fixed64

Remarks

A changed runtime value must be assigned between fixed steps. It refreshes inertia, invalidates cached impulses and CCD state, and wakes the body without changing its role, pose, velocities, or already accepted accelerations. Equal values are a no-op.

MomentOfInertia

Gets the scalar moment of inertia around the yaw axis.

public Fixed64 MomentOfInertia { get; }

Property Value

Fixed64

MotionType

Gets this body's explicit solver-controlled, host-controlled, or static runtime role.

public PhysicsMobilityType MotionType { get; }

Property Value

PhysicsMobilityType

Position

Gets the authoritative planar X/Z position.

public Vector2d Position { get; }

Property Value

Vector2d

Rotation

Gets the authoritative yaw rotation.

public Fixed64 Rotation { get; }

Property Value

Fixed64

SleepAngularSpeedThreshold

Angular speed at or below which the body can count toward sleeping.

public Fixed64 SleepAngularSpeedThreshold { get; set; }

Property Value

Fixed64

SleepEnabled

Enables deterministic sleep evaluation for this body. Disabling sleep wakes a sleeping body immediately.

public bool SleepEnabled { get; set; }

Property Value

bool

SleepFrameThreshold

Number of consecutive fixed frames below sleep thresholds required before the body sleeps.

public int SleepFrameThreshold { get; set; }

Property Value

int

SleepLinearSpeedThreshold

Linear speed at or below which the body can count toward sleeping.

public Fixed64 SleepLinearSpeedThreshold { get; set; }

Property Value

Fixed64

UseGravityDerivedGroundUpDirection

Gets or sets whether non-zero planar gravity defines the support up direction.

public bool UseGravityDerivedGroundUpDirection { get; set; }

Property Value

bool

WasGrounded

Gets whether this body was grounded before the latest authoritative grounding refresh or manual grounding change.

public bool WasGrounded { get; }

Property Value

bool

WorldCenterOfMass

Gets the authoritative world-space center of mass in the X/Z simulation plane.

public Vector2d WorldCenterOfMass { get; }

Property Value

Vector2d

Exceptions

InvalidOperationException

The center lies outside the representable coordinate domain. Use TryGetWorldCenterOfMass(out Vector2d) when that is possible.

Methods

AddAngularImpulse(Fixed64)

Applies an immediate yaw-velocity change derived from the supplied angular impulse and inverse moment of inertia. The impulse is expressed in mass-distance-squared-per-time units and does not apply a time-step factor.

public void AddAngularImpulse(Fixed64 impulse)

Parameters

impulse Fixed64

The signed yaw impulse applied to the body.

AddForce(Vector2d)

Queues a planar force in mass-distance-per-time-squared units for integration during the next fixed step.

public void AddForce(Vector2d force)

Parameters

force Vector2d

The X/Z-plane force to apply.

AddLinearImpulse(Vector2d)

Applies an X/Z-plane linear impulse immediately as a velocity change. The impulse is expressed in mass-distance-per-time units and does not advance the fixed-step simulation or apply a time-step factor.

public void AddLinearImpulse(Vector2d impulse)

Parameters

impulse Vector2d

The planar linear impulse to apply.

AddTorque(Fixed64)

Queues a yaw torque in mass-distance-squared-per-time-squared units for integration during the next fixed step.

public void AddTorque(Fixed64 torque)

Parameters

torque Fixed64

The signed yaw torque applied to the body.

CheckGround()

Forces an immediate automatic support probe when Gravitas owns grounding.

public void CheckGround()

ClearManualGrounding()

Clears host-owned planar grounded state while leaving automatic support disabled.

public void ClearManualGrounding()

Deactivate()

Removes this body and its collider from the pure 2D runtime service.

public void Deactivate()

GetLocalPoint(Vector2d)

Gets a body-local point from the authoritative 2D body pose and committed collider scale.

public Vector2d GetLocalPoint(Vector2d point)

Parameters

point Vector2d

Returns

Vector2d

GetWorldPoint(Vector2d)

Gets a world-space point from the authoritative 2D body pose and committed collider scale.

public Vector2d GetWorldPoint(Vector2d point)

Parameters

point Vector2d

Returns

Vector2d

Initialize(Vector2d, Fixed64, PhysicsMobilityType)

Initializes and registers the body at an authoritative planar pose.

public void Initialize(Vector2d position, Fixed64 rotation = default, PhysicsMobilityType motionType = PhysicsMobilityType.Dynamic)

Parameters

position Vector2d
rotation Fixed64
motionType PhysicsMobilityType

RecordData(IChronicler)

Records or restores deterministic body state through Chronicler.

public void RecordData(IChronicler chronicler)

Parameters

chronicler IChronicler

ResetCenterOfMassFromCollider()

Clears an explicit center-of-mass override and derives the offset from the bound collider again.

public void ResetCenterOfMassFromCollider()

ResetPosition(Vector2d, Fixed64)

Resets authoritative 2D pose and clears accumulated linear/angular motion for deterministic fixture reuse.

public void ResetPosition(Vector2d position = default, Fixed64 rotation = default)

Parameters

position Vector2d

The new X/Z-plane position.

rotation Fixed64

The new yaw rotation in radians.

SetManualGrounding(Vector2d, Vector2d)

Sets host-owned planar grounded state for manual support sources such as deterministic tilemaps.

public void SetManualGrounding(Vector2d groundPoint, Vector2d groundNormal)

Parameters

groundPoint Vector2d
groundNormal Vector2d

SetMotionType(PhysicsMobilityType)

Changes this registered body's runtime role between fixed-step transactions.

public void SetMotionType(PhysicsMobilityType motionType)

Parameters

motionType PhysicsMobilityType

Remarks

The transition preserves body, collider, pair, joint, and host identity, but clears incompatible motion, sleep, CCD, and solver-cache state before repartitioning. Freeze axes remain independent of the selected role.

Exceptions

ArgumentOutOfRangeException

motionType is undefined.

InvalidOperationException

The body is not currently registered, its context registration has been reset, or a simulation transaction or callback is active.

SetPosition(Vector2d)

Sets the authoritative planar position and refreshes collider state.

public void SetPosition(Vector2d position)

Parameters

position Vector2d

SetRotation(Fixed64)

Sets the authoritative yaw rotation and refreshes collider state.

public void SetRotation(Fixed64 rotation)

Parameters

rotation Fixed64

Sleep()

Puts an eligible body to sleep and clears its motion.

public void Sleep()

TryGetGroundPoint(out Vector2d)

Attempts to get the current support point.

public bool TryGetGroundPoint(out Vector2d point)

Parameters

point Vector2d

Returns

bool

TryGetLocalPoint(Vector2d, out Vector2d)

Attempts to get a body-local point from the authoritative 2D body pose and committed collider scale.

public bool TryGetLocalPoint(Vector2d point, out Vector2d result)

Parameters

point Vector2d
result Vector2d

Returns

bool

TryGetWorldCenterOfMass(out Vector2d)

Attempts to materialize the authoritative world-space center of mass without saturation.

public bool TryGetWorldCenterOfMass(out Vector2d center)

Parameters

center Vector2d

Returns

bool

TryGetWorldPoint(Vector2d, out Vector2d)

Attempts to get a world-space point from the authoritative 2D body pose and committed collider scale.

public bool TryGetWorldPoint(Vector2d point, out Vector2d result)

Parameters

point Vector2d
result Vector2d

Returns

bool

TryReconfigureCollider(ColliderShapeDefinition2D, Vector2d, Vector2d, out LSCollider2D?, out Exception?, Action?)

Attempts to publish replacement native 2D geometry and a body-root pose without replacing body, collider, or host identity.

public ColliderReconfigurationStatus TryReconfigureCollider(ColliderShapeDefinition2D definition, Vector2d localOffset, Vector2d position, out LSCollider2D? blocker, out Exception? notificationException, Action? publishSynchronizedState = null)

Parameters

definition ColliderShapeDefinition2D

The complete replacement geometry in the existing family.

localOffset Vector2d

The unscaled collider offset from the body root.

position Vector2d

The authoritative X/Z body-root position.

blocker LSCollider2D

The first eligible penetrating collider in stable service order.

notificationException Exception

Post-commit publisher or separation failures, aggregated when multiple.

publishSynchronizedState Action

Optional once-only publication of already prepared dependent state.

Returns

ColliderReconfigurationStatus

Whether the change was applied, already matched, or was blocked.

Remarks

Supports circle-to-circle and capsule-to-capsule replacement only in TwoD. The definition contributes geometry; material, filters, hierarchy, events, rotation, motion, and host world Y are retained. Exact touching is allowed; any positive penetration, even below one raw unit, against an eligible registered collider rejects the change, including outside grid coverage. Triggers do not block it. This synchronous operation may scan the registry and allocate. It makes no work, timing, or allocation-failure recovery guarantee. The publisher runs once after physical publication or confirmation of unchanged state, and before pair separation. Rejection never invokes it. Notification failures do not roll back accepted state; pair retirement continues and failures are returned separately in stable order.

Exceptions

ArgumentException

The definition, family, or candidate geometry is invalid.

InvalidOperationException

The runtime mode, registration, fixed-step boundary, or host pose is unsafe.

UseAutomaticGrounding(bool)

Returns grounded-state ownership to Gravitas and optionally refreshes support immediately.

public void UseAutomaticGrounding(bool checkGroundImmediately = true)

Parameters

checkGroundImmediately bool

UseManualGrounding(bool)

Gives the host ownership of grounded state and disables automatic support refresh.

public void UseManualGrounding(bool clearGrounding = true)

Parameters

clearGrounding bool

Wake()

Wakes the body and resumes collision participation.

public void Wake()