BorrowedTorch.Collisions 1.2.0

Prefix Reserved
dotnet add package BorrowedTorch.Collisions --version 1.2.0
                    
NuGet\Install-Package BorrowedTorch.Collisions -Version 1.2.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="BorrowedTorch.Collisions" Version="1.2.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="BorrowedTorch.Collisions" Version="1.2.0" />
                    
Directory.Packages.props
<PackageReference Include="BorrowedTorch.Collisions" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add BorrowedTorch.Collisions --version 1.2.0
                    
#r "nuget: BorrowedTorch.Collisions, 1.2.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package BorrowedTorch.Collisions@1.2.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=BorrowedTorch.Collisions&version=1.2.0
                    
Install as a Cake Addin
#tool nuget:?package=BorrowedTorch.Collisions&version=1.2.0
                    
Install as a Cake Tool

BorrowedTorch.Collisions

Collision volumes on MonoGame's types, for games that need to know what touches what - without a physics engine. 3D volumes (sphere, axis-aligned box, oriented box, capsule, cylinder) and 2D ones on a plane (circle, rectangle, turned rectangle, capsule), with every pair's overlap, contact, closest points, ray cast and sweep; a dynamic AABB tree for the broad phase; and spaces that hold colliders, answer queries, and move a kinematic body and slide it along what it meets - the walking, landing and wall-stopping of a character, in 3D or a side-view 2D.

var space = new CollisionSpace2D();

space.Add(new Aabb2D(new Vector2(-20, -1), new Vector2(20, 0)), ColliderFilter.Default);     // the floor
space.Add(new Aabb2D(new Vector2(5, 0), new Vector2(6, 10)), ColliderFilter.Default);        // a wall

var player = Aabb2D.FromCenter(new Vector2(0, 3), new Vector2(0.4f, 0.9f));
var moved = space.MoveAndSlide(player, velocity * elapsed, SlideSettings2D.Default, QueryFilter.Solid);

player = player.Translated(moved.Motion);
if (moved.IsOnFloor) velocity.Y = 0;                                                          // landed: may jump

Install

dotnet add package BorrowedTorch.Collisions

Targets net10.0. It is compiled against MonoGame 3.8.1.303 (DesktopGL) and does not pass MonoGame on: the game brings its own - DesktopGL, WindowsDX or BorrowedTorch's compute fork, any release from 3.8.1.303 on.

Volumes

3D 2D What it is
Sphere(Center, Radius) Circle(Center, Radius) A ball; radius 0 is a point.
Aabb(Min, Max) Aabb2D(Min, Max) An axis-aligned box or rectangle - also the trees' bounds.
OrientedBox(Center, HalfExtents, Orientation) OrientedBox2D(Center, HalfExtents, Rotation) A turned box (a quaternion) or rectangle (radians).
Capsule(A, B, Radius) Capsule2D(A, B, Radius) Everything within the radius of a segment; FromCenter stands one up.
Cylinder(Center, Axis, HalfHeight, Radius) A flat-ended column along a unit axis.

Each has Bounds, Support(direction), ClosestPoint(point), Contains(point), Translated(offset) and an exact Raycast(ray, maxDistance, out hit). Shape3D and Shape2D hold any one of them, converted implicitly - what the pair tests, trees and spaces take.

Pair tests

Collision3D and Collision2D answer for every pair of kinds - 15 in 3D, 10 in 2D, either order:

Method Gives
Overlaps(a, b) Whether they overlap; touching counts.
TryContact(a, b, out contact) How they meet: Normal from A towards B (move B by Normal * Depth to part them), Depth, and a point on each.
ClosestPoints(a, b) / Distance(a, b) The nearest points and how far apart; 0 where they overlap.
Sweep(moving, motion, target, out hit) When moving, moved along motion, first touches target: the Fraction of the motion, the point, and the target's normal facing the mover. Overlapping at the start is fraction 0, the normal the way out.
Raycast(shape, ray, maxDistance, out hit) Where a ray meets it; a ray starting inside meets it at 0.

Pairs with a quick exact answer take it - spheres, capsules and boxes against each other, a rectangle swept against a rectangle. Every other pair goes through GJK (closest points), EPA (depth) and GJK's ray cast over the volumes' cores (a sphere's center, a capsule's segment) grown by their radii, finished by Newton's steps on the distance. These work in doubles, since the shapes they close in on near a round volume defeat floats, and are exact for the flat volumes; for the round ones depths and distances come to a part in 10^5 or so, and a contact's normal against a curved surface to about 10^-3 radians.

Trees

DynamicAabbTree (and DynamicRectTree in the plane) is the broad phase: proxies with "fat" boxes - grown by a margin and stretched the way they last moved, so small moves leave the tree alone - placed by the surface area heuristic and kept balanced by rotations.

Method Does
CreateProxy(bounds, userData) / MoveProxy(proxy, bounds, displacement) / DestroyProxy(proxy) Keep the tree. MoveProxy is true where the tree changed.
Query(box, callback) Every proxy whose fat box overlaps the box.
Raycast(ray, maxDistance, callback) Every proxy whose fat box the ray meets; the callback clips the ray.
Traverse(ref visitor) Down the tree by any test of a node's box (ITreeVisitor.Classify): disjoint skips the subtree, inside takes every leaf under it untested, crossing goes on down - a frustum query, say.

The query and ray cast take struct callbacks too, allocating nothing.

Spaces

CollisionSpace3D and CollisionSpace2D hold colliders - a volume, a ColliderFilter, an owner and your data - in a tree, and answer:

  • Overlap(shape, filter, results), Raycast(ray, maxDistance, filter, out hit) (the nearest), Sweep(shape, motion, filter, out hit) (the first).

  • MoveAndSlide(shape, motion, settings, filter): a kinematic body moved and stopped by the solid colliders it meets, a skin short of each, the rest of the move carried on kept off every surface met in it: along the newest where that goes into none of the others, along the crease of two in 3D where it would (a valley's bottom), and nowhere where a third closes the crease - or, in 2D, in a corner none of them lets it out of. Then it is pushed out of anything it still overlaps. The result's Motion is how far it went; it says whether the body ended on a floor, against a wall or under a ceiling, by the normals it met against Settings.Up and FloorMaxAngle (45 degrees by default) - with a probe two skins down for a floor the move itself never reached. The space is left alone: move the body's collider by Motion.

  • For a body walking - on a floor before the move, and not going up - two settings, off (0) by default:

    • StepHeight: a wall no higher than this above the body's bottom is stepped onto - up, across what is left of the move, and down onto its top, where that is a floor. A round body (a capsule's end) standing on a step's edge stands on the floor beside it, so it climbs on over the edge in the frames after.
    • SnapDistance: a floor up to this far under the body after the move - going down a slope or off a step - is one it is let down onto and stays on.
    var walking = SlideSettings3D.Default with { StepHeight = 0.3f, SnapDistance = 0.3f };
    
  • MoveAndSlide(shapes, motion, settings, filter): the same for a body of several volumes moving as one - a torso and its feet, say. Each is swept, the earliest touch of any stops them all, and each is pushed out and probed for a floor. With none, the body goes the whole way.

    var moved = space.MoveAndSlide([torso, feet], velocity * elapsed, walking, QueryFilter.Solid);
    
  • FindTriggerOverlaps(pairs): each trigger's overlaps with the solid colliders on its mask.

ColliderFilter(Layers, Mask, IsTrigger): the layers a collider is on, the layers it reacts to (what a sliding body stops at, what a trigger tells of), and whether it is a trigger - which nothing stops at. QueryFilter(Mask, Triggers, Ignored): which layers a query looks at, whether triggers count, and an owner to leave out - the moving body's own.

Building and testing

dotnet test BorrowedTorch.Collisions.sln

The tests set every ordered pair side by side with hand-worked gaps, overlaps and sweeps, check each quick path against the generic one on random poses, and both against what their answers mean - a contact's push parts the pair and less does not, a sweep's fraction is where the pair first touches.

Changelog

  • 1.2.0 - Compiled against MonoGame 3.8.1.303 instead of 3.8.0.1641, as every BorrowedTorch library that does not need the compute fork now is. A game needs MonoGame 3.8.1.303 or newer; 3.8.0 no longer loads it. No API changes.
  • 1.1.0 - Move and slide keeps off every surface met in the move (the crease of two in 3D, stopped by a third; a true corner in 2D), steps up (StepHeight) and keeps to the floor going down (SnapDistance), and moves a body of several volumes as one. Both settings 0 by default, as 1.0.0 slid.
  • 1.0.0 - 3D and 2D volumes and every pair's tests, the dynamic AABB tree, collision spaces with move and slide and triggers.

License

MIT

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net10.0

    • No dependencies.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on BorrowedTorch.Collisions:

Package Downloads
BorrowedTorch.Culling

Frustum culling on MonoGame's types: a frustum from any view-projection matrix - perspective or orthographic - telling spheres, boxes, capsules and cylinders inside, outside or crossing, and a query of a BorrowedTorch.Collisions dynamic AABB tree by it that takes whole subtrees at once.

BorrowedTorch.Engine.AdditionalFeatures

Kindling, Borrowed Torch's game engine: its additional features - sound, post effects, vegetation, fabric, sprites, collisions and culling - for a game's own code to build against beside the engine

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.2.0 69 11/18/2026
1.1.0 68 11/17/2026
1.0.0 110 11/16/2026