< Summary

Information
Class: Gravitas.Colliders.ColliderScalePolicy
Assembly: Gravitas
File(s): /home/runner/work/Gravitas/Gravitas/src/Gravitas/Colliders/Geometry/ColliderScalePolicy.cs
Line coverage
100%
Covered lines: 133
Uncovered lines: 0
Coverable lines: 133
Total lines: 267
Line coverage: 100%
Branch coverage
100%
Covered branches: 26
Total branches: 26
Branch coverage: 100%
Method coverage

Feature is only available for sponsors

Upgrade to PRO version

Metrics

MethodBranch coverage Crap Score Cyclomatic complexity Line coverage
CapturePlanar(...)100%44100%
Capture(...)100%22100%
CaptureScale(...)100%22100%
ValidateAncestry(...)100%22100%
TryExtractPlanarTransform(...)100%1010100%
Validate(...)100%11100%
Validate(...)100%11100%
IsPositive(...)100%22100%
IsPositive(...)100%44100%
Scale(...)100%11100%
Scale(...)100%11100%
Scale(...)100%11100%
Scale(...)100%11100%
ScalePositive(...)100%11100%
ScalePositive(...)100%11100%
ScalePositive(...)100%11100%
ScalePositive(...)100%11100%

File(s)

/home/runner/work/Gravitas/Gravitas/src/Gravitas/Colliders/Geometry/ColliderScalePolicy.cs

#LineLine coverage
 1//=======================================================================
 2// ColliderScalePolicy.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 FixedMathSharp;
 9
 10namespace Gravitas.Colliders;
 11
 12/// <summary>
 13/// Owns Gravitas's physical-scale admission boundary. FixedTransform permits
 14/// signed and zero authored scale; collider geometry requires positive authored
 15/// ancestry and positive resulting world dimensions on every axis it consumes.
 16/// </summary>
 17internal static class ColliderScalePolicy
 18{
 19    internal static Vector2d CapturePlanar(
 20        FixedTransform transform,
 21        out Fixed4x4 worldMatrix,
 22        out Fixed64 worldRotation,
 23        bool captureRotation = true)
 24    {
 11339825        ChronicleGuard.ThrowIfNull(transform, nameof(transform));
 11339826        FixedTransform? current = transform;
 22690127        while (current != null)
 28        {
 11351829            Validate(current.LocalScaleXZ);
 11350330            current = current.Parent;
 31        }
 32
 11338333        Vector2d worldScale = default;
 11338334        worldRotation = default;
 11338335        bool captured = transform.TryGetLocalToWorldMatrix(out worldMatrix)
 11338336            && TryExtractPlanarTransform(
 11338337                worldMatrix,
 11338338                out worldScale,
 11338339                out worldRotation,
 11338340                captureRotation);
 11338341        ChronicleGuard.ThrowIfArgument(
 11338342            !captured,
 11338343            nameof(transform),
 11338344            "2D collider transform hierarchy must compose to a representable, nonsheared X/Z transform.");
 11337245        Validate(worldScale);
 11337246        return worldScale;
 47    }
 48
 49    internal static Vector3d Capture(
 50        FixedTransform transform,
 51        out Fixed4x4 worldMatrix,
 52        out FixedQuaternion worldRotation)
 53    {
 14011954        ChronicleGuard.ThrowIfNull(transform, nameof(transform));
 14011955        ValidateAncestry(transform);
 56
 14010157        Vector3d worldScale = default;
 14010158        worldRotation = default;
 14010159        bool captured = transform.TryGetLocalToWorldMatrix(out worldMatrix)
 14010160            && Fixed4x4.Decompose(
 14010161                worldMatrix,
 14010162                out _,
 14010163                out worldRotation,
 14010164                out worldScale);
 14010165        ChronicleGuard.ThrowIfArgument(
 14010166            !captured,
 14010167            nameof(transform),
 14010168            "Collider transform hierarchy must compose to a representable, nonsheared transform.");
 14009969        Validate(worldScale);
 14009970        return worldScale;
 71    }
 72
 73    internal static Vector3d CaptureScale(FixedTransform transform)
 74    {
 30689375        ValidateAncestry(transform);
 30688876        if (transform.Parent == null)
 30687077            return transform.LocalScale;
 78
 1879        Vector3d worldScale = default;
 1880        bool capturedMatrix =
 1881            transform.TryGetLocalToWorldMatrix(out Fixed4x4 worldMatrix);
 1882        bool capturedScale = Fixed4x4.Decompose(
 1883            worldMatrix,
 1884            out _,
 1885            out _,
 1886            out worldScale);
 1887        ChronicleGuard.ThrowIfArgument(
 1888            !(capturedMatrix & capturedScale),
 1889            nameof(transform),
 1890            "Collider transform hierarchy must compose to a representable, nonsheared transform.");
 1591        Validate(worldScale);
 1592        return worldScale;
 93    }
 94
 95    private static void ValidateAncestry(FixedTransform transform)
 96    {
 44701297        FixedTransform? current = transform;
 89405198        while (current != null)
 99        {
 447062100            Validate(current.LocalScale);
 447039101            current = current.Parent;
 102        }
 446989103    }
 104
 105    private static bool TryExtractPlanarTransform(
 106        Fixed4x4 matrix,
 107        out Vector2d scale,
 108        out Fixed64 rotation,
 109        bool captureRotation)
 110    {
 111        // A planar collider requires a block-diagonal X/Z and Y basis. Checking
 112        // both directions prevents scale extraction from silently discarding
 113        // hierarchy coupling that happens not to move local Y=0 points.
 113381114        if ((matrix.M12 != Fixed64.Zero)
 113381115            | (matrix.M21 != Fixed64.Zero)
 113381116            | (matrix.M23 != Fixed64.Zero)
 113381117            | (matrix.M32 != Fixed64.Zero))
 118        {
 5119            scale = Vector2d.Zero;
 5120            rotation = Fixed64.Zero;
 5121            return false;
 122        }
 123
 124        // The exact unit basis needs neither decomposition nor yaw materialization.
 113376125        if ((matrix.M11 == Fixed64.One) & (matrix.M13 == Fixed64.Zero)
 113376126            & (matrix.M31 == Fixed64.Zero) & (matrix.M33 == Fixed64.One))
 127        {
 108407128            scale = Vector2d.One;
 108407129            rotation = Fixed64.Zero;
 108407130            return true;
 131        }
 132
 4969133        Fixed4x4 planarMatrix = Fixed4x4.Identity;
 4969134        planarMatrix.M11 = matrix.M11;
 4969135        planarMatrix.M13 = matrix.M13;
 4969136        planarMatrix.M31 = matrix.M31;
 4969137        planarMatrix.M33 = matrix.M33;
 4969138        if (!Fixed4x4.Decompose(
 4969139                planarMatrix,
 4969140                out _,
 4969141                out FixedQuaternion planarRotation,
 4969142                out Vector3d planarScale)
 4969143            || planarScale.X <= Fixed64.Zero)
 144        {
 4145            scale = Vector2d.Zero;
 4146            rotation = Fixed64.Zero;
 4147            return false;
 148        }
 149
 4965150        scale = planarScale.ToVector2d();
 4965151        rotation = Fixed64.Zero;
 152        // Body-owned poses replace host yaw. Keep the same decomposition and
 153        // admission checks, but omit yaw materialization when it is unused.
 4965154        if (captureRotation)
 155        {
 171156            Vector3d right = planarRotation.Rotate(Vector3d.Right);
 171157            rotation = PlanarRotation.Canonicalize(
 171158                FixedMath.Atan2(right.Z, right.X));
 159        }
 4965160        return true;
 161    }
 162
 163    internal static void Validate(Vector2d scale)
 164    {
 228685165        ChronicleGuard.ThrowIfArgument(
 228685166            !IsPositive(scale),
 228685167            nameof(scale),
 228685168            "2D collider scale must be greater than zero on the X and Z axes throughout its transform ancestry.");
 228670169    }
 170
 171    internal static void Validate(Vector3d scale)
 172    {
 649129173        ChronicleGuard.ThrowIfArgument(
 649129174            !IsPositive(scale),
 649129175            nameof(scale),
 649129176            "3D collider scale must be greater than zero on every axis throughout its transform ancestry.");
 649098177    }
 178
 179    private static bool IsPositive(Vector2d scale) =>
 228685180        scale.X > Fixed64.Zero && scale.Y > Fixed64.Zero;
 181
 182    private static bool IsPositive(Vector3d scale) =>
 649129183        scale.X > Fixed64.Zero
 649129184        && scale.Y > Fixed64.Zero
 649129185        && scale.Z > Fixed64.Zero;
 186
 187    internal static Fixed64 Scale(
 188        Fixed64 value,
 189        Fixed64 ownerScale,
 190        Fixed64 partScale) =>
 365350191        Scale(value, ownerScale, partScale, Fixed64.One);
 192
 193    internal static Fixed64 Scale(
 194        Fixed64 value,
 195        Fixed64 ownerScale,
 196        Fixed64 partScale,
 197        Fixed64 divisor)
 198    {
 608111199        ChronicleGuard.ThrowIfArgument(
 608111200            !Fixed64.TryMultiplyDivide(value, ownerScale, partScale, divisor, out Fixed64 result),
 608111201            nameof(value),
 608111202            "Scaled collider geometry must be representable.");
 608111203        return result;
 204    }
 205
 206    internal static Vector2d Scale(
 207        Vector2d value,
 208        Vector2d ownerScale,
 209        Vector2d partScale) =>
 63761210        Scale(value, ownerScale, partScale, Fixed64.One);
 211
 212    internal static Vector2d Scale(
 213        Vector2d value,
 214        Vector2d ownerScale,
 215        Vector2d partScale,
 216        Fixed64 divisor) =>
 76012217        new(
 76012218            Scale(value.X, ownerScale.X, partScale.X, divisor),
 76012219            Scale(value.Y, ownerScale.Y, partScale.Y, divisor));
 220
 221    internal static Fixed64 ScalePositive(
 222        Fixed64 dimension,
 223        Fixed64 ownerScale,
 224        Fixed64 partScale)
 225    {
 354182226        Fixed64 result = Scale(dimension, ownerScale, partScale);
 354182227        ChronicleGuard.ThrowIfArgument(
 354182228            result <= Fixed64.Zero,
 354182229            nameof(dimension),
 354182230            "Scaled collider dimensions must remain greater than zero.");
 354176231        return result;
 232    }
 233
 234    internal static Vector2d ScalePositive(
 235        Vector2d dimensions,
 236        Vector2d ownerScale,
 237        Vector2d partScale,
 238        Fixed64 divisor) =>
 4228239        new(
 4228240            ScalePositive(dimensions.X, ownerScale.X, partScale.X, divisor),
 4228241            ScalePositive(dimensions.Y, ownerScale.Y, partScale.Y, divisor));
 242
 243    internal static Vector3d ScalePositive(
 244        Vector3d dimensions,
 245        Vector3d ownerScale,
 246        Vector3d partScale,
 247        Fixed64 divisor) =>
 27427248        new(
 27427249            ScalePositive(dimensions.X, ownerScale.X, partScale.X, divisor),
 27427250            ScalePositive(dimensions.Y, ownerScale.Y, partScale.Y, divisor),
 27427251            ScalePositive(dimensions.Z, ownerScale.Z, partScale.Z, divisor));
 252
 253    private static Fixed64 ScalePositive(
 254        Fixed64 dimension,
 255        Fixed64 ownerScale,
 256        Fixed64 partScale,
 257        Fixed64 divisor)
 258    {
 90737259        Fixed64 result = Scale(dimension, ownerScale, partScale, divisor);
 90737260        ChronicleGuard.ThrowIfArgument(
 90737261            result <= Fixed64.Zero,
 90737262            nameof(dimension),
 90737263            "Scaled collider dimensions must remain greater than zero.");
 90737264        return result;
 265    }
 266
 267}