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
<PackageReference Include="BorrowedTorch.Collisions" Version="1.2.0" />
<PackageVersion Include="BorrowedTorch.Collisions" Version="1.2.0" />
<PackageReference Include="BorrowedTorch.Collisions" />
paket add BorrowedTorch.Collisions --version 1.2.0
#r "nuget: BorrowedTorch.Collisions, 1.2.0"
#:package BorrowedTorch.Collisions@1.2.0
#addin nuget:?package=BorrowedTorch.Collisions&version=1.2.0
#tool nuget:?package=BorrowedTorch.Collisions&version=1.2.0
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'sMotionis 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 againstSettings.UpandFloorMaxAngle(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 byMotion.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 | Versions 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. |
-
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.