Manual
Manual
Contacts and queries
Your code learns what happened in Physics 2D from the Physics2D service: which bodies began or stopped touching, what went into a trigger, and what touches now. It asks the same service what is in the way: raycasts, shape casts and overlaps. This page covers both.
The Physics 2D service
A system gets the service from its context, and code that is not a system, such as a flow, from the world:
Physics2D physics = context.Services.Get<Physics2D>(); // in a systemPhysics2D same = world.Services.Get<Physics2D>(); // anywhere elseThe types are in the Abyss.Physics2D namespace. Everything the service says is of the world as the last fixed step left it, and every system reading it sees the same. See Bodies and colliders for what a body and ground are.
What touched
CollisionsEntered lists the bodies whose colliders began touching, and CollisionsExited those whose colliders stopped. Each is a pair of bodies, listed once however many of their colliders touch, so a collider made again as it changes neither exits nor enters. A pair exits as the two move apart, as one is taken away, or as their layers stop meeting. A trigger touches nothing here, and two grounds never touch.
foreach (Collision2D hit in physics.CollisionsEntered){ if (hit.Involves(player) && hit.NormalToward(player).Y > 0.7f) // landed on something { float impact = hit.RelativeVelocity.Length(); // how hard, in meters a second ulong what = hit.Other(player); }}Each is a Collision2D:
| Member | What it is |
|---|---|
A, B | The two bodies: each an entity with a Rigidbody 2D, or ground. Which is A says nothing. |
ColliderA, ColliderB | The entity of each body's collider that touched first, or parted last: the body itself, or an entity under it. |
Point | Where they met, in the world. Zero where they parted. |
Normal | The direction from A into B they met along, a unit long. Zero where they parted. |
RelativeVelocity | How fast B went against A where they met, in meters a second, as they went into the step. Its length is how hard they hit: what an impact sound's loudness or a fall's damage is made from. |
Involves(entity) | Whether the entity is one of the two bodies or one of the two colliders. |
Other(entity) | The other body, given one body or one of its colliders. |
OtherCollider(entity) | The other body's collider. |
NormalToward(entity) | The normal of the surface the entity met, pointing out of the other into it: up, for something landing on the ground. |
Triggers
A collider with Is Trigger ticked meets nothing and is passed through. TriggersEntered lists the bodies that went into a trigger, and TriggersExited those that came out of one, as they moved out or as either was taken away. Each is listed once however many of its colliders went in. A trigger finds bodies that move and bodies that do not, but ground in ground is nothing, and a body's own trigger never finds that body.
Each is a Trigger2D:
| Member | What it is |
|---|---|
Trigger | The entity of the trigger: its own entity, whether it is a body's own collider or one under it. |
Other | The body that went in or came out: an entity with a Rigidbody 2D, or ground. |
OtherCollider | The entity of its collider that went in first, or came out last. |
Involves(entity) | Whether the entity is the trigger, the body or its collider. |
This plugin's system counts coins: every entity with a Coin component and a trigger collider is picked up, and despawned, when something goes into it.
public struct Score{ public int Coins;}
// In a plugin's Build:World world = schedule.World;ComponentId coin = world.Component<Coin>().Id;ResourceType<Score> score = world.RegisterResource<Score>();world.InsertResource(score);
schedule.Fixed.Add("Pick up coins", [], default, [score.Write()], context =>{ Physics2D physics = context.Services.Get<Physics2D>(); ref Score total = ref context.ResourceMut<Score>(0).Value; foreach (Trigger2D entered in physics.TriggersEntered) { if (world.ComponentsOf(entered.Trigger).Contains(coin)) // check entered.Other to count only the player's { total.Coins++; context.Commands.Despawn(entered.Trigger); } }}, structural: StructuralAccess.None.AndDespawn);What touches now
The entered and exited lists say what changed. To ask what is touching now, every step:
CollisionsStaying: each pair of bodies whose colliders touch, once a pair, with a collider of each, a point, the normal and how fast they go against each other there.TriggersStaying: each body inside a trigger, once a trigger.TouchingOf(entity): the bodies an entity touches. For a body or ground, those whose colliders touch its own and the triggers it is inside; for a trigger, the bodies inside it.IsTouching(a, b): whether two bodies touch, or one is inside the other's trigger, named by the trigger's own entity.
if (physics.IsTouching(player, lava)){ // still standing in it}Which steps a system sees
Physics 2D's step runs alone, before the game's own fixed systems. A fixed system (schedule.Fixed) sees what touched in the step just taken. A system of the frame sees what touched in every step since the frame before, which may be none, one or several, depending on how long the frame was. Either way nothing is missed or seen twice. See Systems at a fixed rate.
Raycasts
Raycast asks what a ray from a point along a direction hits first, within a distance, on the layers asked about. It returns a RaycastHit2D, or null where it hits nothing:
if (physics.Raycast(feet, -Vector2.UnitY, 0.1f, LayerMask.Of(Layers.Ground)) is { } ground){ // ground.Entity, ground.Collider, ground.Point, ground.Normal, ground.Distance}
RaycastHit2D[] pierced = physics.RaycastAll(muzzle, aim, 30f); // every body it hits, the nearest firstThe direction may be of any length; a zero direction hits nothing. Left out, the distance is as far as there is, and the layers are every layer. Layers.Ground is a constant the build writes for each layer named in Project Settings ▸ Tags and Layers (see Layers).
| Member | What it is |
|---|---|
Entity | The body whose collider it hit: an entity with a Rigidbody 2D, or ground. |
Collider | The entity of the collider it hit: the body itself, or an entity under it. |
Point | Where, in the world. |
Normal | The surface's normal there, a unit long, pointing back toward where the ray came from. |
Distance | How far it went to get there, in meters. |
RaycastAll lists each body once, where the ray first hits it.
Shape casts
A shape cast sweeps a shape from a point along a direction and returns what it meets first, as a raycast does. The shape stops Distance along, touching what it met, within half a centimeter.
RaycastHit2D? landing = physics.CircleCast(center, 0.3f, velocity, 2f);RaycastHit2D? slide = physics.BoxCast(center, new Vector2(1f, 0.5f), 0f, Vector2.UnitX, 3f);RaycastHit2D? squeeze = physics.CapsuleCast(center, new Vector2(0.5f, 1f), CapsuleDirection2D.Vertical, 0f, Vector2.UnitX, 3f);| Method | The shape |
|---|---|
CircleCast(origin, radius, direction, distance, layers) | A circle of that radius, in meters. |
BoxCast(origin, size, angle, direction, distance, layers) | A box that wide and high, turned that many degrees anticlockwise. |
CapsuleCast(origin, size, capsuleDirection, angle, direction, distance, layers) | A capsule sized as a Capsule Collider 2D is, round ends included, long along its direction, and turned. |
Overlaps
An overlap returns the bodies whose colliders are at a point, or in or touching a shape, each once:
ulong[] near = physics.OverlapCircle(center, 3f);ulong[] under = physics.OverlapPoint(cursor);ulong[] hit = physics.OverlapBox(swordTip, new Vector2(0.6f, 0.3f), facing, LayerMask.Of(Layers.Enemies));ulong[] crowd = physics.OverlapCapsule(center, new Vector2(1f, 2f), CapsuleDirection2D.Vertical);What queries find
Every query is asked of the world as the last step left it. An entity made or moved since is found where the next step puts it.
- Layers: a query finds colliders on the layers its mask names, every layer when left out. The Collisions matrix of the Physics 2D settings has no say, and neither do pairs kept from meeting with
IgnoreCollision. - Triggers: a query finds triggers as it finds solid colliders, unless Queries Hit Triggers is off in the Physics 2D settings.
- Starting inside: a raycast or a shape cast that starts inside a collider hits it where it starts, at no distance, its normal back along the way it was going. With Queries Start In Colliders off, it passes over that collider to what is beyond, so a ray down from a body's middle finds what is under it rather than the body itself.
The service is safe to ask from any system, and from several at once.
In the Scripting API
- Physics2D: what touched, what touches now, and what is in the way.
- Collision2D and Trigger2D: two bodies that touched, and a body in a trigger.
- RaycastHit2D: what a ray or a swept shape hit.
- CapsuleDirection2D: which way a capsule is long.
- LayerMask: the layers a query asks about.
