< Summary

Information
Class: Gravitas.Constraints.Joint3D
Assembly: Gravitas
File(s): /home/runner/work/Gravitas/Gravitas/src/Gravitas/Constraints/3D/Joints/Joint3D.cs
Line coverage
100%
Covered lines: 187
Uncovered lines: 0
Coverable lines: 187
Total lines: 348
Line coverage: 100%
Branch coverage
100%
Covered branches: 48
Total branches: 48
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%1010100%
IsSupportedType(...)100%66100%
IsSupportedLimitKind(...)100%44100%
ValidatePayload(...)100%1212100%

File(s)

/home/runner/work/Gravitas/Gravitas/src/Gravitas/Constraints/3D/Joints/Joint3D.cs

#LineLine coverage
 1//=======================================================================
 2// Joint3D.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 3D joint runtime state.
 17/// </summary>
 18public sealed class Joint3D : IRecordable
 19{
 37220    private readonly Fixed64[] _accumulatedImpulses = new Fixed64[JointSolver3D.MaxRowsPerJoint];
 21    private JointCollisionPolicy _collisionPolicy;
 37222    private bool _isEnabled = true;
 23
 37224    internal Joint3D(
 37225        GravitasConstraint3DService service,
 37226        int id,
 37227        JointDefinition3D definition,
 37228        JointFrame3D localFrameA,
 37229        JointFrame3D localFrameB)
 30    {
 37231        Service = service;
 37232        Context = service.Context;
 37233        Id = id;
 37234        BodyA = definition.BodyA;
 37235        BodyB = definition.BodyB;
 37236        LocalFrameA = localFrameA;
 37237        LocalFrameB = localFrameB;
 37238        Type = definition.Type;
 37239        Limits = definition.Limits;
 37240        Motor = definition.Motor;
 37241        _collisionPolicy = definition.CollisionPolicy;
 37242        IsActive = true;
 37243    }
 44
 45    internal GravitasConstraint3DService Service { get; }
 46
 47    internal RagdollRuntime3D? OwningRagdoll { get; set; }
 48
 49    /// <summary>
 50    /// Gets the owning world context.
 51    /// </summary>
 52    public GravitasWorldContext Context { get; }
 53
 54    /// <summary>
 55    /// Gets this context-local joint ID.
 56    /// </summary>
 57    public int Id { get; }
 58
 59    /// <summary>
 60    /// Gets the first body linked by the joint.
 61    /// </summary>
 62    public SolidBody BodyA { get; }
 63
 64    /// <summary>
 65    /// Gets the second body linked by the joint.
 66    /// </summary>
 67    public SolidBody BodyB { get; }
 68
 69    /// <summary>
 70    /// Gets the first local anchor frame.
 71    /// </summary>
 72    public JointFrame3D LocalFrameA { get; private set; }
 73
 74    /// <summary>
 75    /// Gets the second local anchor frame.
 76    /// </summary>
 77    public JointFrame3D LocalFrameB { get; private set; }
 78
 79    /// <summary>
 80    /// Gets the joint type.
 81    /// </summary>
 82    public JointType3D Type { get; private set; }
 83
 84    /// <summary>
 85    /// Gets optional angular limit data.
 86    /// </summary>
 87    public JointLimit3D Limits { get; private set; }
 88
 89    /// <summary>
 90    /// Gets optional motor data.
 91    /// </summary>
 92    public JointMotor3D Motor { get; private set; }
 93
 94    /// <summary>
 95    /// Gets physical collision filtering behavior for the linked colliders.
 96    /// </summary>
 198097    public JointCollisionPolicy CollisionPolicy => _collisionPolicy;
 98
 99    /// <summary>
 100    /// Gets whether this joint is registered with its owning service.
 101    /// </summary>
 102    public bool IsActive { get; internal set; }
 103
 104    /// <summary>
 105    /// Gets or sets whether this active joint emits solver rows.
 106    /// </summary>
 107    public bool IsEnabled
 108    {
 36120109        get => _isEnabled;
 110        set
 111        {
 86112            ChronicleGuard.ThrowIfTrue(
 86113                !IsActive,
 86114                nameof(Joint3D),
 86115                "Removed joints cannot mutate simulation state.");
 84116            if (_isEnabled == value)
 63117                return;
 118
 21119            bool oldValue = _isEnabled;
 21120            Service.UpdateJointEnabledState(this, oldValue, value);
 21121            _isEnabled = value;
 21122            ClearSolverCache();
 21123            WakeBodies();
 21124        }
 125    }
 126
 127    /// <summary>
 128    /// Gets the number of rows emitted by the most recent solver pass.
 129    /// </summary>
 130    public int LastSolvedRowCount { get; internal set; }
 131
 132    /// <summary>
 133    /// Gets the cumulative absolute incremental impulse emitted since the
 134    /// solver cache was last cleared.
 135    /// </summary>
 136    public Fixed64 AccumulatedImpulseMagnitude { get; internal set; }
 137
 138    /// <summary>
 139    /// Gets deterministic metrics from the most recent solver pass.
 140    /// </summary>
 141    public JointSolveMetrics3D LastSolveMetrics { get; internal set; }
 142
 143    /// <summary>
 144    /// Replaces the motor payload and wakes linked bodies.
 145    /// </summary>
 146    public void SetMotor(JointMotor3D motor)
 147    {
 5148        ChronicleGuard.ThrowIfTrue(
 5149            !IsActive,
 5150            nameof(Joint3D),
 5151            "Removed joints cannot mutate simulation state.");
 3152        motor.Validate();
 3153        Motor = motor;
 3154        ClearSolverCache();
 3155        WakeBodies();
 3156    }
 157
 158    /// <summary>
 159    /// Disables the joint motor and wakes linked bodies.
 160    /// </summary>
 3161    public void ClearMotor() => SetMotor(JointMotor3D.Disabled);
 162
 35792163    internal Fixed64 GetCachedImpulse(int rowIndex) => _accumulatedImpulses[rowIndex];
 164
 1504683165    internal void SetCachedImpulse(int rowIndex, Fixed64 impulse) => _accumulatedImpulses[rowIndex] = impulse;
 166
 167    internal void ClearSolverCache()
 168    {
 11206169        for (int i = 0; i < _accumulatedImpulses.Length; i++)
 5172170            _accumulatedImpulses[i] = Fixed64.Zero;
 171
 431172        LastSolvedRowCount = 0;
 431173        AccumulatedImpulseMagnitude = Fixed64.Zero;
 431174        LastSolveMetrics = default;
 431175    }
 176
 177    internal void WakeBodies()
 178    {
 24179        BodyA.Wake();
 24180        BodyB.Wake();
 24181    }
 182
 183    internal void SetCollisionPolicyFromRecord(JointCollisionPolicy collisionPolicy)
 184    {
 9185        if (_collisionPolicy == collisionPolicy)
 3186            return;
 187
 6188        Service.UpdateJointCollisionPolicy(this, _collisionPolicy, collisionPolicy);
 6189        _collisionPolicy = collisionPolicy;
 6190    }
 191
 34515192    internal bool HasSolverParticipant() => IsSolverBody(BodyA) || IsSolverBody(BodyB);
 193
 194    internal static bool IsSolverBody(SolidBody body) =>
 35928195        body.Active && body.DynamicId >= 0 && body.HasSolverMobility;
 196
 197    internal void ContributeReplayHash(
 198        ref ChronicleHashWriter writer,
 199        GravitasReplayHashMode mode)
 200    {
 1551201        writer.WriteSection("joint.3d", 1);
 1551202        writer.WriteInt32(Id);
 1551203        writer.WriteInt32(BodyA.DynamicId);
 1551204        writer.WriteInt32(BodyB.DynamicId);
 1551205        writer.WriteInt32(BodyA.Collider.Id);
 1551206        writer.WriteInt32(BodyB.Collider.Id);
 1551207        writer.WriteBool(IsActive);
 1551208        writer.WriteBool(IsEnabled);
 1551209        writer.WriteEnum(Type);
 1551210        writer.WriteEnum(Limits.Kind);
 1551211        writer.WriteFixed64(Limits.MaxHingeAngle);
 1551212        writer.WriteFixed64(Limits.MaxConeAngle);
 1551213        writer.WriteFixed64(Limits.MaxTwistAngle);
 1551214        writer.WriteQuaternion(Motor.TargetLocalRotation);
 1551215        writer.WriteFixed64(Motor.AngularDriveStrength);
 1551216        writer.WriteFixed64(Motor.AngularDriveDamping);
 1551217        writer.WriteFixed64(Motor.MaximumMotorImpulse);
 1551218        writer.WriteEnum(CollisionPolicy);
 1551219        writer.WriteVector3d(LocalFrameA.Position);
 1551220        writer.WriteQuaternion(LocalFrameA.Rotation);
 1551221        writer.WriteVector3d(LocalFrameB.Position);
 1551222        writer.WriteQuaternion(LocalFrameB.Rotation);
 223
 1551224        if (mode != GravitasReplayHashMode.AuthoritativeWithSolverCaches)
 125225            return;
 226
 1426227        writer.WriteSection("joint.3d.caches", 1);
 1426228        writer.WriteInt32(LastSolvedRowCount);
 1426229        writer.WriteFixed64(AccumulatedImpulseMagnitude);
 1426230        writer.WriteInt32(LastSolveMetrics.PreparedRowCount);
 1426231        writer.WriteFixed64(LastSolveMetrics.LinearAnchorErrorMagnitude);
 1426232        writer.WriteFixed64(LastSolveMetrics.AngularLimitErrorMagnitude);
 1426233        writer.WriteFixed64(LastSolveMetrics.AccumulatedImpulseMagnitude);
 1426234        writer.WriteFixed64(LastSolveMetrics.IncrementalImpulseMagnitude);
 1426235        writer.WriteFixed64(LastSolveMetrics.MotorImpulseMagnitude);
 1426236        writer.WriteFixed64(LastSolveMetrics.MotorErrorMagnitude);
 1426237        writer.WriteInt32(LastSolveMetrics.ClampedRowCount);
 37076238        for (int i = 0; i < _accumulatedImpulses.Length; i++)
 17112239            writer.WriteFixed64(_accumulatedImpulses[i]);
 1426240    }
 241
 242    /// <summary>
 243    /// Records mutable joint state into a Chronicler pass.
 244    /// </summary>
 245    public void RecordData(IChronicler chronicler)
 246    {
 13247        ChronicleGuard.ThrowIfTrue(
 13248            !IsActive,
 13249            nameof(Joint3D),
 13250            "Removed joints cannot participate in serialization.");
 11251        bool isEnabled = IsEnabled;
 11252        JointType3D type = Type;
 11253        JointLimitKind3D limitKind = Limits.Kind;
 11254        Fixed64 maxHingeAngle = Limits.MaxHingeAngle;
 11255        Fixed64 maxConeAngle = Limits.MaxConeAngle;
 11256        Fixed64 maxTwistAngle = Limits.MaxTwistAngle;
 11257        FixedQuaternion motorTarget = Motor.TargetLocalRotation;
 11258        Fixed64 motorStrength = Motor.AngularDriveStrength;
 11259        Fixed64 motorDamping = Motor.AngularDriveDamping;
 11260        Fixed64 maxMotorImpulse = Motor.MaximumMotorImpulse;
 11261        JointCollisionPolicy collisionPolicy = CollisionPolicy;
 11262        Vector3d frameAPosition = LocalFrameA.Position;
 11263        FixedQuaternion frameARotation = LocalFrameA.Rotation;
 11264        Vector3d frameBPosition = LocalFrameB.Position;
 11265        FixedQuaternion frameBRotation = LocalFrameB.Rotation;
 266
 11267        RecordValues.Look(chronicler, ref isEnabled, "IsEnabled", true);
 11268        RecordValues.Look(chronicler, ref type, "Type", JointType3D.BallSocket);
 11269        RecordValues.Look(chronicler, ref limitKind, "LimitKind", JointLimitKind3D.Unrestricted);
 11270        RecordValues.Look(chronicler, ref maxHingeAngle, "MaxHingeAngle");
 11271        RecordValues.Look(chronicler, ref maxConeAngle, "MaxConeAngle");
 11272        RecordValues.Look(chronicler, ref maxTwistAngle, "MaxTwistAngle");
 11273        RecordValues.Look(chronicler, ref motorTarget, "MotorTarget");
 11274        RecordValues.Look(chronicler, ref motorStrength, "MotorStrength");
 11275        RecordValues.Look(chronicler, ref motorDamping, "MotorDamping");
 11276        RecordValues.Look(chronicler, ref maxMotorImpulse, "MaxMotorImpulse");
 11277        RecordValues.Look(chronicler, ref collisionPolicy, "CollisionPolicy", JointCollisionPolicy.SuppressLinked);
 11278        RecordValues.Look(chronicler, ref frameAPosition, "LocalFrameAPosition");
 11279        RecordValues.Look(chronicler, ref frameARotation, "LocalFrameARotation");
 11280        RecordValues.Look(chronicler, ref frameBPosition, "LocalFrameBPosition");
 11281        RecordValues.Look(chronicler, ref frameBRotation, "LocalFrameBRotation");
 282
 11283        if (chronicler.Mode != SerializationMode.Loading)
 5284            return;
 285
 6286        ChronicleGuard.ThrowIfArgument(!IsSupportedType(type), nameof(Type), "Unsupported 3D joint type.");
 6287        ChronicleGuard.ThrowIfArgument(!IsSupportedLimitKind(limitKind), nameof(Limits), "Unsupported joint limit kind."
 6288        ChronicleGuard.ThrowIfArgument(
 6289            collisionPolicy != JointCollisionPolicy.SuppressLinked
 6290                && collisionPolicy != JointCollisionPolicy.Collide,
 6291            nameof(CollisionPolicy),
 6292            "Unsupported joint collision policy.");
 293
 6294        JointLimit3D limits = limitKind switch
 6295        {
 3296            JointLimitKind3D.Hinge => JointLimit3D.Hinge(maxHingeAngle),
 2297            JointLimitKind3D.ConeTwist => JointLimit3D.ConeTwist(maxConeAngle, maxTwistAngle),
 1298            _ => JointLimit3D.Unrestricted
 6299        };
 6300        JointMotor3D motor = new(motorTarget, motorStrength, motorDamping, maxMotorImpulse);
 6301        ValidatePayload(type, limits);
 302
 5303        Type = type;
 5304        Limits = limits;
 5305        Motor = motor;
 5306        SetCollisionPolicyFromRecord(collisionPolicy);
 5307        LocalFrameA = new JointFrame3D(frameAPosition, frameARotation);
 5308        LocalFrameB = new JointFrame3D(frameBPosition, frameBRotation);
 5309        if (_isEnabled == isEnabled)
 2310            ClearSolverCache();
 311        else
 3312            IsEnabled = isEnabled;
 3313    }
 314
 315    internal static bool IsSupportedType(JointType3D type) =>
 448316        type == JointType3D.BallSocket
 448317        || type == JointType3D.Hinge
 448318        || type == JointType3D.ConeTwist
 448319        || type == JointType3D.Fixed;
 320
 321    internal static bool IsSupportedLimitKind(JointLimitKind3D kind) =>
 6322        kind == JointLimitKind3D.Unrestricted
 6323        || kind == JointLimitKind3D.Hinge
 6324        || kind == JointLimitKind3D.ConeTwist;
 325
 326    internal static void ValidatePayload(
 327        JointType3D type,
 328        in JointLimit3D limits)
 329    {
 447330        ChronicleGuard.ThrowIfArgument(
 447331            type == JointType3D.Hinge
 447332                && limits.Kind != JointLimitKind3D.Unrestricted
 447333                && limits.Kind != JointLimitKind3D.Hinge,
 447334            nameof(limits),
 447335            "Hinge joints accept only hinge limits.");
 447336        ChronicleGuard.ThrowIfArgument(
 447337            type == JointType3D.ConeTwist
 447338                && limits.Kind != JointLimitKind3D.Unrestricted
 447339                && limits.Kind != JointLimitKind3D.ConeTwist,
 447340            nameof(limits),
 447341            "Cone-twist joints accept only cone-twist limits.");
 447342        ChronicleGuard.ThrowIfArgument(
 447343            (type == JointType3D.BallSocket || type == JointType3D.Fixed)
 447344                && limits.Kind != JointLimitKind3D.Unrestricted,
 447345            nameof(limits),
 447346            "Ball-socket and fixed joints do not accept angular limit payloads.");
 444347    }
 348}