< Summary

Information
Class: Gravitas.CollisionHandling.MixedContact
Assembly: Gravitas
File(s): /home/runner/work/Gravitas/Gravitas/src/Gravitas/CollisionHandling/Contacts/Mixed/MixedContact.cs
Line coverage
100%
Covered lines: 125
Uncovered lines: 0
Coverable lines: 125
Total lines: 306
Line coverage: 100%
Branch coverage
100%
Covered branches: 28
Total branches: 28
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%
.ctor(...)100%11100%
.ctor(...)100%11100%
.ctor(...)100%11100%
.ctor(...)100%88100%
get_Point3D()100%11100%
get_Point2D()100%11100%
TryGetPoint3D(...)100%11100%
TryGetPoint2D(...)100%11100%
TryGetPlanarOffset2DFrom(...)100%11100%
TryGetPlanarOffset2DFrom(...)100%22100%
GetPlanarXZLeverFrom(...)100%11100%
WithMaterialOverride(...)100%11100%
WithFallbackMaterials(...)100%22100%
FromManifoldContact(...)100%11100%
ToManifoldContact(...)100%11100%
TrySelectClosingContact(...)100%66100%
IsClosingContact(...)100%66100%
IsClosingProjection(...)100%22100%
CreatePlanarReference(...)100%11100%
GetRequiredWorldPoint(...)100%22100%

File(s)

/home/runner/work/Gravitas/Gravitas/src/Gravitas/CollisionHandling/Contacts/Mixed/MixedContact.cs

#LineLine coverage
 1//=======================================================================
 2// MixedContact.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 System;
 9using System.Runtime.CompilerServices;
 10using FixedMathSharp;
 11using FixedMathSharp.Geometry;
 12using Gravitas.Colliders;
 13using Gravitas.Materials;
 14
 15namespace Gravitas.CollisionHandling;
 16
 17/// <summary>
 18/// Contact generated between one 3D collider and one embedded 2D collider.
 19/// </summary>
 20/// <remarks>A single contact may represent one row of a larger manifold. Its depth does not guarantee escape from a non
 21public readonly struct MixedContact
 22{
 23    /// <summary>Creates a mixed contact from world-space witness points.</summary>
 24    public MixedContact(
 25        Vector3d point3D,
 26        Vector3d point2D,
 27        Vector3d normal3DTo2D,
 28        Fixed64 depth,
 29        bool depthIsClamped = false)
 9130        : this(
 9131            ContactAnchor.FromWorldPoint(point3D),
 9132            ContactAnchor.FromWorldPoint(point2D),
 9133            normal3DTo2D,
 9134            depth,
 9135            depthIsClamped,
 9136            hasMaterialOverride: false,
 9137            default,
 9138            default)
 9139    { }
 40
 41    /// <summary>
 42    /// Creates a mixed contact with authoritative rigid-frame witnesses.
 43    /// </summary>
 44    /// <exception cref="ArgumentException">
 45    /// Either rigid-frame anchor is invalid.
 46    /// </exception>
 47    public MixedContact(
 48        ContactAnchor anchor3D,
 49        ContactAnchor anchor2D,
 50        Vector3d normal3DTo2D,
 51        Fixed64 depth,
 52        bool depthIsClamped = false)
 964853        : this(
 964854            anchor3D,
 964855            anchor2D,
 964856            normal3DTo2D,
 964857            depth,
 964858            depthIsClamped,
 964859            hasMaterialOverride: false,
 964860            default,
 964861            default)
 964662    { }
 63
 64    internal MixedContact(
 65        Vector3d point3D,
 66        Vector3d point2D,
 67        Vector3d normal3DTo2D,
 68        Fixed64 depth,
 69        PhysicsMaterial material3D,
 70        PhysicsMaterial material2D,
 71        bool depthIsClamped = false)
 272        : this(
 273            ContactAnchor.FromWorldPoint(point3D),
 274            ContactAnchor.FromWorldPoint(point2D),
 275            normal3DTo2D,
 276            depth,
 277            depthIsClamped,
 278            hasMaterialOverride: true,
 279            material3D,
 280            material2D)
 281    { }
 82
 83    internal MixedContact(
 84        ContactAnchor anchor3D,
 85        ContactAnchor anchor2D,
 86        Vector3d normal3DTo2D,
 87        Fixed64 depth,
 88        PhysicsMaterial material3D,
 89        PhysicsMaterial material2D,
 90        bool depthIsClamped = false)
 179791        : this(
 179792            anchor3D,
 179793            anchor2D,
 179794            normal3DTo2D,
 179795            depth,
 179796            depthIsClamped,
 179797            hasMaterialOverride: true,
 179798            material3D,
 179799            material2D)
 1797100    { }
 101
 102    private MixedContact(
 103        ContactAnchor anchor3D,
 104        ContactAnchor anchor2D,
 105        Vector3d normal3DTo2D,
 106        Fixed64 depth,
 107        bool depthIsClamped,
 108        bool hasMaterialOverride,
 109        PhysicsMaterial material3D,
 110        PhysicsMaterial material2D)
 111    {
 384785112        if (!anchor3D.IsValid)
 1113            throw new ArgumentException("The 3D contact anchor must be valid.", nameof(anchor3D));
 384784114        if (!anchor2D.IsValid)
 1115            throw new ArgumentException("The 2D contact anchor must be valid.", nameof(anchor2D));
 116
 384783117        Anchor3D = anchor3D;
 384783118        Anchor2D = anchor2D;
 384783119        Normal3DTo2D = normal3DTo2D;
 384783120        Depth = depth;
 384783121        DepthIsClamped = depthIsClamped;
 384783122        HasMaterialOverride = hasMaterialOverride;
 384783123        Material3D = hasMaterialOverride ? material3D : PhysicsMaterial.Default;
 384783124        Material2D = hasMaterialOverride ? material2D : PhysicsMaterial.Default;
 384783125        HasContact = true;
 384783126    }
 127
 128    /// <summary>Gets whether this value contains a valid mixed contact.</summary>
 129    public bool HasContact { get; }
 130
 131    /// <summary>Gets the authoritative contact anchor on the 3D collider.</summary>
 132    public ContactAnchor Anchor3D { get; }
 133
 134    /// <summary>Gets the authoritative contact anchor on the embedded 2D collider.</summary>
 135    public ContactAnchor Anchor2D { get; }
 136
 137    /// <summary>Gets the world-space witness point on the 3D collider.</summary>
 65138    public Vector3d Point3D => GetRequiredWorldPoint(Anchor3D, nameof(Point3D));
 139
 140    /// <summary>Gets the world-space witness point on the embedded 2D collider.</summary>
 75141    public Vector3d Point2D => GetRequiredWorldPoint(Anchor2D, nameof(Point2D));
 142
 143    /// <summary>Attempts to resolve the 3D anchor to a world-space point.</summary>
 144    [MethodImpl(MethodImplOptions.AggressiveInlining)]
 84145    public bool TryGetPoint3D(out Vector3d point) => Anchor3D.TryGetWorldPoint(out point);
 146
 147    /// <summary>Attempts to resolve the embedded 2D anchor to a world-space point.</summary>
 148    [MethodImpl(MethodImplOptions.AggressiveInlining)]
 83149    public bool TryGetPoint2D(out Vector3d point) => Anchor2D.TryGetWorldPoint(out point);
 150
 151    [MethodImpl(MethodImplOptions.AggressiveInlining)]
 152    internal bool TryGetPlanarOffset2DFrom(
 153        Vector2d origin,
 154        out Vector2d offset) =>
 1155        TryGetPlanarOffset2DFrom(
 1156            origin,
 1157            Fixed64.Zero,
 1158            Vector2d.Zero,
 1159            out offset);
 160
 161    [MethodImpl(MethodImplOptions.AggressiveInlining)]
 162    internal bool TryGetPlanarOffset2DFrom(
 163        Vector2d origin,
 164        Fixed64 rotation,
 165        Vector2d localPoint,
 166        out Vector2d offset)
 167    {
 991168        ContactAnchor reference =
 991169            CreatePlanarReference(origin, rotation, localPoint);
 991170        if (!Anchor2D.TryGetOffsetFrom(
 991171                reference,
 991172                out Vector3d offset3D))
 173        {
 1174            offset = default;
 1175            return false;
 176        }
 177
 990178        offset = new Vector2d(offset3D.X, offset3D.Z);
 990179        return true;
 180    }
 181
 182    [MethodImpl(MethodImplOptions.AggressiveInlining)]
 183    internal ExactLever3D GetPlanarXZLeverFrom(
 184        Vector2d origin,
 185        Fixed64 rotation,
 186        Vector2d localPoint) =>
 58187        Anchor2D.GetLeverFrom(
 58188            CreatePlanarReference(origin, rotation, localPoint));
 189
 190    /// <summary>
 191    /// Contact normal pointing from the 3D collider toward the embedded 2D collider volume.
 192    /// </summary>
 193    public Vector3d Normal3DTo2D { get; }
 194
 195    /// <summary>Gets the penetration depth along <see cref="Normal3DTo2D"/>.</summary>
 196    public Fixed64 Depth { get; }
 197
 198    /// <summary>
 199    /// Gets whether the exact penetration depth exceeded the scalar domain and
 200    /// <see cref="Depth"/> therefore contains <see cref="Fixed64.MaxValue"/>.
 201    /// </summary>
 202    public bool DepthIsClamped { get; }
 203
 204    /// <summary>Gets whether the contact carries per-feature material values.</summary>
 205    public bool HasMaterialOverride { get; }
 206
 207    /// <summary>Gets the material sampled from the 3D contact feature.</summary>
 208    public PhysicsMaterial Material3D { get; }
 209
 210    /// <summary>Gets the material sampled from the embedded 2D contact feature.</summary>
 211    public PhysicsMaterial Material2D { get; }
 212
 213    internal MixedContact WithMaterialOverride(PhysicsMaterial material3D, PhysicsMaterial material2D) =>
 1797214        new(
 1797215            Anchor3D,
 1797216            Anchor2D,
 1797217            Normal3DTo2D,
 1797218            Depth,
 1797219            material3D,
 1797220            material2D,
 1797221            DepthIsClamped);
 222
 223    internal MixedContact WithFallbackMaterials(PhysicsMaterial material3D, PhysicsMaterial material2D) =>
 1796224        HasMaterialOverride ? this : WithMaterialOverride(material3D, material2D);
 225
 226    internal static MixedContact FromManifoldContact(in ManifoldContact contact) =>
 373247227        new(contact.AnchorA, contact.AnchorB, contact.Normal, contact.Depth,
 373247228            contact.DepthIsClamped, contact.HasMaterialOverride, contact.MaterialA, contact.MaterialB);
 229
 230    internal ManifoldContact ToManifoldContact(int namespace3D = 0, int namespace2D = 0) =>
 9634231        new(ContactManifold.CreateContactId(Anchor3D, namespace3D, Anchor2D, namespace2D),
 9634232            Anchor3D, Anchor2D, Depth, Normal3DTo2D, HasMaterialOverride,
 9634233            Material3D, Material2D, DepthIsClamped, namespace3D, namespace2D);
 234
 235    internal static bool TrySelectClosingContact(ContactManifold manifold,
 236        ContactAnchor center3D, Vector3d linear3D, Vector3d angular3D,
 237        ContactAnchor center2D, Vector2d linear2D, Fixed64 angular2D, out MixedContact contact,
 238        LSCollider2D? owner2D = null)
 239    {
 240        // Preserve a geometric witness for conservative trajectory bounding even when every row separates.
 1761241        contact = manifold.HasContact ? FromManifoldContact(manifold.PrimaryContact) : default;
 1761242        Vector3d spatialLinear2D = ExactContactLever2D.ToSpatial(linear2D);
 1761243        Vector3d spatialAngular2D = new(Fixed64.Zero, -angular2D, Fixed64.Zero);
 8695244        foreach (ManifoldContact row in manifold)
 245        {
 3248246            if (!IsClosingContact(row, center3D, linear3D, angular3D, center2D,
 3248247                spatialLinear2D, spatialAngular2D, angular2D, owner2D)) continue;
 1323248            contact = FromManifoldContact(row);
 1323249            return true;
 250        }
 438251        return false;
 1323252    }
 253
 254    [MethodImpl(MethodImplOptions.AggressiveInlining)]
 255    internal static bool IsClosingContact(in ManifoldContact row, in ContactAnchor center3D,
 256        Vector3d linear3D, Vector3d angular3D, in ContactAnchor center2D,
 257        Vector3d spatialLinear2D, Vector3d spatialAngular2D, Fixed64 angular2D, LSCollider2D? owner2D)
 258    {
 3354259        ContactAnchor normalAnchor2D = owner2D == null ? row.AnchorB
 3354260            : ExactContactLever2D.GetDetectedNormalAnchor(owner2D, row.FeatureNamespaceB, center2D, row.AnchorB);
 3354261        ExactLever3D.GetRelativePointVelocityRatio(linear3D, angular3D,
 3354262            row.AnchorA.GetLeverFrom(center3D), spatialLinear2D, spatialAngular2D,
 3354263            normalAnchor2D.GetLeverFrom(center2D), row.Normal,
 3354264            out Signed832 numerator, out Signed832 denominator, secondPlanarAngularVelocity: angular2D);
 265        // A is always 3D and B is always 2D. Negative relative normal speed closes the row.
 3354266        return numerator.Sign < 0 && (!Fixed64.TryGetSignedRawRatio(numerator, denominator, 0,
 3354267            out Fixed64 speed) || speed < -Fixed64.Epsilon);
 268    }
 269
 270    internal static bool IsClosingProjection(Vector3d displacement, Vector3d outwardNormal)
 271    {
 747272        if (Vector3d.TryDot(displacement, outwardNormal, out Fixed64 speed))
 743273            return speed < -Fixed64.Epsilon;
 274
 275        // A rounded unit normal can push a full-range projection beyond Q32.32.
 276        // Its exact sign still exists, and overflow already proves that its
 277        // magnitude exceeds the ordinary rounded closing-speed deadband.
 4278        return WideGeometry.GetDifferenceDotProduct3D(
 4279            displacement.X, Fixed64.Zero, displacement.Y, Fixed64.Zero, displacement.Z, Fixed64.Zero,
 4280            outwardNormal.X, Fixed64.Zero, outwardNormal.Y, Fixed64.Zero, outwardNormal.Z, Fixed64.Zero).Sign < 0;
 281    }
 282
 283    private ContactAnchor CreatePlanarReference(
 284        Vector2d origin,
 285        Fixed64 rotation,
 286        Vector2d localPoint) =>
 1049287        new(
 1049288            new Vector3d(
 1049289                origin.X,
 1049290                Anchor2D.Origin.Y,
 1049291                origin.Y),
 1049292            FixedQuaternion.FromAxisAngle(Vector3d.Up, -rotation),
 1049293            new Vector3d(
 1049294                localPoint.X,
 1049295                Fixed64.Zero,
 1049296                localPoint.Y));
 297
 298    private static Vector3d GetRequiredWorldPoint(ContactAnchor anchor, string propertyName)
 299    {
 140300        if (anchor.TryGetWorldPoint(out Vector3d point))
 138301            return point;
 302
 2303        throw new InvalidOperationException(
 2304            $"{propertyName} is outside the representable coordinate range. Use the corresponding TryGet method.");
 305    }
 306}

Methods/Properties

.ctor(FixedMathSharp.Vector3d,FixedMathSharp.Vector3d,FixedMathSharp.Vector3d,FixedMathSharp.Fixed64,System.Boolean)
.ctor(Gravitas.CollisionHandling.ContactAnchor,Gravitas.CollisionHandling.ContactAnchor,FixedMathSharp.Vector3d,FixedMathSharp.Fixed64,System.Boolean)
.ctor(FixedMathSharp.Vector3d,FixedMathSharp.Vector3d,FixedMathSharp.Vector3d,FixedMathSharp.Fixed64,Gravitas.Materials.PhysicsMaterial,Gravitas.Materials.PhysicsMaterial,System.Boolean)
.ctor(Gravitas.CollisionHandling.ContactAnchor,Gravitas.CollisionHandling.ContactAnchor,FixedMathSharp.Vector3d,FixedMathSharp.Fixed64,Gravitas.Materials.PhysicsMaterial,Gravitas.Materials.PhysicsMaterial,System.Boolean)
.ctor(Gravitas.CollisionHandling.ContactAnchor,Gravitas.CollisionHandling.ContactAnchor,FixedMathSharp.Vector3d,FixedMathSharp.Fixed64,System.Boolean,System.Boolean,Gravitas.Materials.PhysicsMaterial,Gravitas.Materials.PhysicsMaterial)
get_Point3D()
get_Point2D()
TryGetPoint3D(FixedMathSharp.Vector3d&)
TryGetPoint2D(FixedMathSharp.Vector3d&)
TryGetPlanarOffset2DFrom(FixedMathSharp.Vector2d,FixedMathSharp.Vector2d&)
TryGetPlanarOffset2DFrom(FixedMathSharp.Vector2d,FixedMathSharp.Fixed64,FixedMathSharp.Vector2d,FixedMathSharp.Vector2d&)
GetPlanarXZLeverFrom(FixedMathSharp.Vector2d,FixedMathSharp.Fixed64,FixedMathSharp.Vector2d)
WithMaterialOverride(Gravitas.Materials.PhysicsMaterial,Gravitas.Materials.PhysicsMaterial)
WithFallbackMaterials(Gravitas.Materials.PhysicsMaterial,Gravitas.Materials.PhysicsMaterial)
FromManifoldContact(Gravitas.CollisionHandling.ManifoldContact&)
ToManifoldContact(System.Int32,System.Int32)
TrySelectClosingContact(Gravitas.CollisionHandling.ContactManifold,Gravitas.CollisionHandling.ContactAnchor,FixedMathSharp.Vector3d,FixedMathSharp.Vector3d,Gravitas.CollisionHandling.ContactAnchor,FixedMathSharp.Vector2d,FixedMathSharp.Fixed64,Gravitas.CollisionHandling.MixedContact&,Gravitas.Colliders.LSCollider2D)
IsClosingContact(Gravitas.CollisionHandling.ManifoldContact&,Gravitas.CollisionHandling.ContactAnchor&,FixedMathSharp.Vector3d,FixedMathSharp.Vector3d,Gravitas.CollisionHandling.ContactAnchor&,FixedMathSharp.Vector3d,FixedMathSharp.Vector3d,FixedMathSharp.Fixed64,Gravitas.Colliders.LSCollider2D)
IsClosingProjection(FixedMathSharp.Vector3d,FixedMathSharp.Vector3d)
CreatePlanarReference(FixedMathSharp.Vector2d,FixedMathSharp.Fixed64,FixedMathSharp.Vector2d)
GetRequiredWorldPoint(Gravitas.CollisionHandling.ContactAnchor,System.String)