< Summary

Information
Class: Gravitas.Constraints.Joint2D
Assembly: Gravitas
File(s): /home/runner/work/Gravitas/Gravitas/src/Gravitas/Constraints/2D/Joints/Joint2D.cs
Line coverage
100%
Covered lines: 222
Uncovered lines: 0
Coverable lines: 222
Total lines: 404
Line coverage: 100%
Branch coverage
100%
Covered branches: 64
Total branches: 64
Branch coverage: 100%
Method coverage

Feature is only available for sponsors

Upgrade to PRO version

Metrics

MethodBranch coverage Crap Score Cyclomatic complexity Line coverage
.ctor(...)100%11100%
get_CollisionPolicy()100%11100%
get_IsEnabled()100%11100%
set_IsEnabled(...)100%22100%
SetMotor(...)100%11100%
ClearMotor()100%11100%
GetCachedImpulse(...)100%11100%
SetCachedImpulse(...)100%11100%
ClearSolverCache()100%22100%
WakeBodies()100%11100%
SetCollisionPolicyFromRecord(...)100%22100%
HasSolverParticipant()100%22100%
IsSolverBody(...)100%44100%
ContributeReplayHash(...)100%44100%
RecordData(...)100%1818100%
IsSupportedType(...)100%66100%
IsSupportedLimitKind(...)100%66100%
IsSupportedMotorKind(...)100%44100%
ValidatePayload(...)100%1010100%
ResolveRegistrationLimits(...)100%44100%
ResolveCurrentAnchorDistance(...)100%11100%
ResolveCurrentAnchorDistance(...)100%11100%

File(s)

/home/runner/work/Gravitas/Gravitas/src/Gravitas/Constraints/2D/Joints/Joint2D.cs

#LineLine coverage
 1//=======================================================================
 2// Joint2D.cs
 3//=======================================================================
 4// MIT License, Copyright (c) 2026-present David Oravsky (mrdav30)
 5// See LICENSE file in the project root for full license information.
 6//=======================================================================
 7
 8using Chronicler;
 9using Chronicler.Hashing;
 10using FixedMathSharp;
 11using FixedMathSharp.Chronicler;
 12
 13namespace Gravitas.Constraints;
 14
 15/// <summary>
 16/// Context-owned deterministic pure 2D joint runtime state.
 17/// </summary>
 18public sealed class Joint2D : IRecordable
 19{
 21420    private readonly Fixed64[] _accumulatedImpulses = new Fixed64[JointSolver2D.MaxRowsPerJoint];
 21    private JointCollisionPolicy _collisionPolicy;
 21422    private bool _isEnabled = true;
 23
 21424    internal Joint2D(
 21425        GravitasConstraint2DService service,
 21426        int id,
 21427        in JointDefinition2D definition)
 28    {
 21429        Service = service;
 21430        Context = service.Context;
 21431        Id = id;
 21432        BodyA = definition.BodyA;
 21433        BodyB = definition.BodyB;
 21434        LocalFrameA = definition.LocalFrameA;
 21435        LocalFrameB = definition.LocalFrameB;
 21436        Type = definition.Type;
 21437        Limits = ResolveRegistrationLimits(definition);
 21438        Motor = definition.Motor;
 21439        _collisionPolicy = definition.CollisionPolicy;
 21440        IsActive = true;
 21441    }
 42
 43    internal GravitasConstraint2DService Service { get; }
 44
 45    internal RagdollRuntime2D? OwningRagdoll { get; set; }
 46
 47    /// <summary>
 48    /// Gets the owning world context.
 49    /// </summary>
 50    public GravitasWorldContext Context { get; }
 51
 52    /// <summary>
 53    /// Gets this context-local joint ID.
 54    /// </summary>
 55    public int Id { get; }
 56
 57    /// <summary>
 58    /// Gets the first body linked by the joint.
 59    /// </summary>
 60    public SolidBody2D BodyA { get; }
 61
 62    /// <summary>
 63    /// Gets the second body linked by the joint.
 64    /// </summary>
 65    public SolidBody2D BodyB { get; }
 66
 67    /// <summary>
 68    /// Gets the first local anchor frame.
 69    /// </summary>
 70    public JointFrame2D LocalFrameA { get; private set; }
 71
 72    /// <summary>
 73    /// Gets the second local anchor frame.
 74    /// </summary>
 75    public JointFrame2D LocalFrameB { get; private set; }
 76
 77    /// <summary>
 78    /// Gets the joint type.
 79    /// </summary>
 80    public JointType2D Type { get; private set; }
 81
 82    /// <summary>
 83    /// Gets optional scalar limit data.
 84    /// </summary>
 85    public JointLimit2D Limits { get; private set; }
 86
 87    /// <summary>
 88    /// Gets optional scalar motor data.
 89    /// </summary>
 90    public JointMotor2D Motor { get; private set; }
 91
 92    /// <summary>
 93    /// Gets physical collision filtering behavior for the linked colliders.
 94    /// </summary>
 28995    public JointCollisionPolicy CollisionPolicy => _collisionPolicy;
 96
 97    /// <summary>
 98    /// Gets whether this joint is registered with its owning service.
 99    /// </summary>
 100    public bool IsActive { get; internal set; }
 101
 102    /// <summary>
 103    /// Gets or sets whether this active joint emits solver rows.
 104    /// </summary>
 105    public bool IsEnabled
 106    {
 739107        get => _isEnabled;
 108        set
 109        {
 42110            ChronicleGuard.ThrowIfTrue(
 42111                !IsActive,
 42112                nameof(Joint2D),
 42113                "Removed joints cannot mutate simulation state.");
 40114            if (_isEnabled == value)
 21115                return;
 116
 19117            bool oldValue = _isEnabled;
 19118            Service.UpdateJointEnabledState(this, oldValue, value);
 19119            _isEnabled = value;
 19120            ClearSolverCache();
 19121            WakeBodies();
 19122        }
 123    }
 124
 125    /// <summary>
 126    /// Gets the number of rows emitted by the most recent solver pass.
 127    /// </summary>
 128    public int LastSolvedRowCount { get; internal set; }
 129
 130    /// <summary>
 131    /// Gets the cumulative absolute incremental impulse emitted since the
 132    /// solver cache was last cleared.
 133    /// </summary>
 134    public Fixed64 AccumulatedImpulseMagnitude { get; internal set; }
 135
 136    /// <summary>
 137    /// Gets deterministic metrics from the most recent solver pass.
 138    /// </summary>
 139    public JointSolveMetrics2D LastSolveMetrics { get; internal set; }
 140
 141    /// <summary>
 142    /// Replaces the motor payload and wakes linked bodies.
 143    /// </summary>
 144    public void SetMotor(JointMotor2D motor)
 145    {
 8146        ChronicleGuard.ThrowIfTrue(
 8147            !IsActive,
 8148            nameof(Joint2D),
 8149            "Removed joints cannot mutate simulation state.");
 6150        motor.Validate();
 6151        ValidatePayload(Type, Limits, motor);
 5152        Motor = motor;
 5153        ClearSolverCache();
 5154        WakeBodies();
 5155    }
 156
 157    /// <summary>
 158    /// Disables the joint motor and wakes linked bodies.
 159    /// </summary>
 3160    public void ClearMotor() => SetMotor(JointMotor2D.Disabled);
 161
 459162    internal Fixed64 GetCachedImpulse(int rowIndex) => _accumulatedImpulses[rowIndex];
 163
 13598164    internal void SetCachedImpulse(int rowIndex, Fixed64 impulse) => _accumulatedImpulses[rowIndex] = impulse;
 165
 166    internal void ClearSolverCache()
 167    {
 4824168        for (int i = 0; i < _accumulatedImpulses.Length; i++)
 2144169            _accumulatedImpulses[i] = Fixed64.Zero;
 170
 268171        LastSolvedRowCount = 0;
 268172        AccumulatedImpulseMagnitude = Fixed64.Zero;
 268173        LastSolveMetrics = default;
 268174    }
 175
 176    internal void WakeBodies()
 177    {
 24178        BodyA.Wake();
 24179        BodyB.Wake();
 24180    }
 181
 182    internal void SetCollisionPolicyFromRecord(JointCollisionPolicy collisionPolicy)
 183    {
 11184        if (_collisionPolicy == collisionPolicy)
 3185            return;
 186
 8187        Service.UpdateJointCollisionPolicy(this, _collisionPolicy, collisionPolicy);
 8188        _collisionPolicy = collisionPolicy;
 8189    }
 190
 669191    internal bool HasSolverParticipant() => IsSolverBody(BodyA) || IsSolverBody(BodyB);
 192
 193    internal static bool IsSolverBody(SolidBody2D body) =>
 801194        body.Active && body.DynamicId >= 0 && body.HasSolverMobility;
 195
 196    internal void ContributeReplayHash(
 197        ref ChronicleHashWriter writer,
 198        GravitasReplayHashMode mode)
 199    {
 14200        writer.WriteSection("joint.2d", 1);
 14201        writer.WriteInt32(Id);
 14202        writer.WriteInt32(BodyA.DynamicId);
 14203        writer.WriteInt32(BodyB.DynamicId);
 14204        writer.WriteInt32(BodyA.Collider.Id);
 14205        writer.WriteInt32(BodyB.Collider.Id);
 14206        writer.WriteBool(IsActive);
 14207        writer.WriteBool(IsEnabled);
 14208        writer.WriteEnum(Type);
 14209        writer.WriteEnum(Limits.Kind);
 14210        writer.WriteFixed64(Limits.TargetDistance);
 14211        writer.WriteFixed64(Limits.MinTranslation);
 14212        writer.WriteFixed64(Limits.MaxTranslation);
 14213        writer.WriteFixed64(Limits.MinAngle);
 14214        writer.WriteFixed64(Limits.MaxAngle);
 14215        writer.WriteEnum(Motor.Kind);
 14216        writer.WriteFixed64(Motor.Target);
 14217        writer.WriteFixed64(Motor.DriveStrength);
 14218        writer.WriteFixed64(Motor.Damping);
 14219        writer.WriteFixed64(Motor.MaximumMotorImpulse);
 14220        writer.WriteEnum(CollisionPolicy);
 14221        writer.WriteVector2d(LocalFrameA.Anchor);
 14222        writer.WriteFixed64(LocalFrameA.Angle);
 14223        writer.WriteVector2d(LocalFrameB.Anchor);
 14224        writer.WriteFixed64(LocalFrameB.Angle);
 225
 14226        if (mode != GravitasReplayHashMode.AuthoritativeWithSolverCaches)
 12227            return;
 228
 2229        writer.WriteSection("joint.2d.caches", 1);
 2230        writer.WriteInt32(LastSolvedRowCount);
 2231        writer.WriteFixed64(AccumulatedImpulseMagnitude);
 2232        writer.WriteInt32(LastSolveMetrics.PreparedRowCount);
 2233        writer.WriteFixed64(LastSolveMetrics.LinearAnchorErrorMagnitude);
 2234        writer.WriteFixed64(LastSolveMetrics.AngularErrorMagnitude);
 2235        writer.WriteFixed64(LastSolveMetrics.LimitErrorMagnitude);
 2236        writer.WriteFixed64(LastSolveMetrics.AccumulatedImpulseMagnitude);
 2237        writer.WriteFixed64(LastSolveMetrics.IncrementalImpulseMagnitude);
 2238        writer.WriteFixed64(LastSolveMetrics.MotorImpulseMagnitude);
 2239        writer.WriteFixed64(LastSolveMetrics.MotorErrorMagnitude);
 2240        writer.WriteInt32(LastSolveMetrics.ClampedRowCount);
 36241        for (int i = 0; i < _accumulatedImpulses.Length; i++)
 16242            writer.WriteFixed64(_accumulatedImpulses[i]);
 2243    }
 244
 245    /// <summary>
 246    /// Records mutable joint state into a Chronicler pass.
 247    /// </summary>
 248    public void RecordData(IChronicler chronicler)
 249    {
 16250        ChronicleGuard.ThrowIfTrue(
 16251            !IsActive,
 16252            nameof(Joint2D),
 16253            "Removed joints cannot participate in serialization.");
 14254        bool isEnabled = IsEnabled;
 14255        JointType2D type = Type;
 14256        JointLimitKind2D limitKind = Limits.Kind;
 14257        Fixed64 targetDistance = Limits.TargetDistance;
 14258        Fixed64 minTranslation = Limits.MinTranslation;
 14259        Fixed64 maxTranslation = Limits.MaxTranslation;
 14260        Fixed64 minAngle = Limits.MinAngle;
 14261        Fixed64 maxAngle = Limits.MaxAngle;
 14262        JointMotorKind2D motorKind = Motor.Kind;
 14263        Fixed64 motorTarget = Motor.Target;
 14264        Fixed64 motorStrength = Motor.DriveStrength;
 14265        Fixed64 motorDamping = Motor.Damping;
 14266        Fixed64 maxMotorImpulse = Motor.MaximumMotorImpulse;
 14267        JointCollisionPolicy collisionPolicy = CollisionPolicy;
 14268        Vector2d frameAAnchor = LocalFrameA.Anchor;
 14269        Fixed64 frameAAngle = LocalFrameA.Angle;
 14270        Vector2d frameBAnchor = LocalFrameB.Anchor;
 14271        Fixed64 frameBAngle = LocalFrameB.Angle;
 272
 14273        RecordValues.Look(chronicler, ref isEnabled, "IsEnabled", true);
 14274        RecordValues.Look(chronicler, ref type, "Type", JointType2D.Pin);
 14275        RecordValues.Look(chronicler, ref limitKind, "LimitKind", JointLimitKind2D.Unrestricted);
 14276        RecordValues.Look(chronicler, ref targetDistance, "TargetDistance");
 14277        RecordValues.Look(chronicler, ref minTranslation, "MinTranslation");
 14278        RecordValues.Look(chronicler, ref maxTranslation, "MaxTranslation");
 14279        RecordValues.Look(chronicler, ref minAngle, "MinAngle");
 14280        RecordValues.Look(chronicler, ref maxAngle, "MaxAngle");
 14281        RecordValues.Look(chronicler, ref motorKind, "MotorKind", JointMotorKind2D.Disabled);
 14282        RecordValues.Look(chronicler, ref motorTarget, "MotorTarget");
 14283        RecordValues.Look(chronicler, ref motorStrength, "MotorStrength");
 14284        RecordValues.Look(chronicler, ref motorDamping, "MotorDamping");
 14285        RecordValues.Look(chronicler, ref maxMotorImpulse, "MaxMotorImpulse");
 14286        RecordValues.Look(chronicler, ref collisionPolicy, "CollisionPolicy", JointCollisionPolicy.SuppressLinked);
 14287        RecordValues.Look(chronicler, ref frameAAnchor, "LocalFrameAAnchor");
 14288        RecordValues.Look(chronicler, ref frameAAngle, "LocalFrameAAngle");
 14289        RecordValues.Look(chronicler, ref frameBAnchor, "LocalFrameBAnchor");
 14290        RecordValues.Look(chronicler, ref frameBAngle, "LocalFrameBAngle");
 291
 14292        if (chronicler.Mode != SerializationMode.Loading)
 6293            return;
 294
 8295        ChronicleGuard.ThrowIfArgument(!IsSupportedType(type), nameof(Type), "Unsupported 2D joint type.");
 8296        ChronicleGuard.ThrowIfArgument(!IsSupportedLimitKind(limitKind), nameof(Limits), "Unsupported 2D joint limit kin
 8297        ChronicleGuard.ThrowIfArgument(!IsSupportedMotorKind(motorKind), nameof(Motor), "Unsupported 2D joint motor kind
 8298        ChronicleGuard.ThrowIfArgument(
 8299            collisionPolicy != JointCollisionPolicy.SuppressLinked
 8300                && collisionPolicy != JointCollisionPolicy.Collide,
 8301            nameof(CollisionPolicy),
 8302            "Unsupported joint collision policy.");
 303
 8304        JointLimit2D limits = limitKind switch
 8305        {
 2306            JointLimitKind2D.Distance => JointLimit2D.Distance(targetDistance),
 2307            JointLimitKind2D.Slider => JointLimit2D.Slider(minTranslation, maxTranslation),
 2308            JointLimitKind2D.Angular => JointLimit2D.Angular(minAngle, maxAngle),
 2309            _ => JointLimit2D.Unrestricted
 8310        };
 8311        JointFrame2D localFrameA = new(frameAAnchor, frameAAngle);
 8312        JointFrame2D localFrameB = new(frameBAnchor, frameBAngle);
 8313        if (type == JointType2D.Distance && limits.Kind == JointLimitKind2D.Unrestricted)
 1314            limits = JointLimit2D.Distance(ResolveCurrentAnchorDistance(BodyA, BodyB, localFrameA, localFrameB));
 315
 8316        JointMotor2D motor = motorKind switch
 8317        {
 2318            JointMotorKind2D.Angular => JointMotor2D.Angular(motorTarget, motorStrength, motorDamping, maxMotorImpulse),
 3319            JointMotorKind2D.Linear => JointMotor2D.Linear(motorTarget, motorStrength, motorDamping, maxMotorImpulse),
 3320            _ => JointMotor2D.Disabled
 8321        };
 8322        ValidatePayload(type, limits, motor);
 323
 7324        Type = type;
 7325        Limits = limits;
 7326        Motor = motor;
 7327        SetCollisionPolicyFromRecord(collisionPolicy);
 7328        LocalFrameA = localFrameA;
 7329        LocalFrameB = localFrameB;
 7330        if (_isEnabled == isEnabled)
 5331            ClearSolverCache();
 332        else
 2333            IsEnabled = isEnabled;
 2334    }
 335
 336    internal static bool IsSupportedType(JointType2D type) =>
 250337        type == JointType2D.Distance
 250338        || type == JointType2D.Pin
 250339        || type == JointType2D.Weld
 250340        || type == JointType2D.Prismatic;
 341
 342    internal static bool IsSupportedLimitKind(JointLimitKind2D kind) =>
 8343        kind == JointLimitKind2D.Unrestricted
 8344        || kind == JointLimitKind2D.Distance
 8345        || kind == JointLimitKind2D.Slider
 8346        || kind == JointLimitKind2D.Angular;
 347
 348    internal static bool IsSupportedMotorKind(JointMotorKind2D kind) =>
 8349        kind == JointMotorKind2D.Disabled
 8350        || kind == JointMotorKind2D.Angular
 8351        || kind == JointMotorKind2D.Linear;
 352
 353    internal static void ValidatePayload(
 354        JointType2D type,
 355        in JointLimit2D limits,
 356        in JointMotor2D motor)
 357    {
 254358        ChronicleGuard.ThrowIfArgument(
 254359            type == JointType2D.Distance
 254360                && limits.Kind != JointLimitKind2D.Unrestricted
 254361                && limits.Kind != JointLimitKind2D.Distance,
 254362            nameof(limits),
 254363            "Distance joints accept only distance limits.");
 254364        ChronicleGuard.ThrowIfArgument(
 254365            type == JointType2D.Prismatic
 254366                && limits.Kind != JointLimitKind2D.Unrestricted
 254367                && limits.Kind != JointLimitKind2D.Slider,
 254368            nameof(limits),
 254369            "Prismatic joints accept only slider limits.");
 254370        ChronicleGuard.ThrowIfArgument(
 254371            type != JointType2D.Prismatic
 254372                && motor.Kind == JointMotorKind2D.Linear,
 254373            nameof(motor),
 254374            "Linear motors are supported only by prismatic joints.");
 251375    }
 376
 377    private static JointLimit2D ResolveRegistrationLimits(in JointDefinition2D definition)
 378    {
 214379        if (definition.Type == JointType2D.Distance && definition.Limits.Kind == JointLimitKind2D.Unrestricted)
 1380            return JointLimit2D.Distance(ResolveCurrentAnchorDistance(definition));
 381
 213382        return definition.Limits;
 383    }
 384
 385    private static Fixed64 ResolveCurrentAnchorDistance(in JointDefinition2D definition)
 386    {
 1387        return ResolveCurrentAnchorDistance(
 1388            definition.BodyA,
 1389            definition.BodyB,
 1390            definition.LocalFrameA,
 1391            definition.LocalFrameB);
 392    }
 393
 394    private static Fixed64 ResolveCurrentAnchorDistance(
 395        SolidBody2D bodyA,
 396        SolidBody2D bodyB,
 397        in JointFrame2D localFrameA,
 398        in JointFrame2D localFrameB)
 399    {
 2400        Vector2d anchorA = bodyA.Position + Vector2d.Rotate(localFrameA.Anchor, bodyA.Rotation);
 2401        Vector2d anchorB = bodyB.Position + Vector2d.Rotate(localFrameB.Anchor, bodyB.Rotation);
 2402        return (anchorB - anchorA).Magnitude;
 403    }
 404}