Manual
Manual
What touched and what is in the way
Physics 3D tells your code what touched in each step, what went into and out of triggers, and what a ray or a shape finds in the world. This page covers collisions and triggers in code, keeping two entities from meeting, raycasts, shape casts and overlaps.
Everything here is asked of the Physics3D service: context.Services.Get<Physics3D>() in a system, or world.Services.Get<Physics3D>() elsewhere. It is safe to ask from any system, parallel ones included.
Bodies, colliders and entities
What touches is told body by body, with the colliders that touched:
- A body is the entity with the Rigidbody 3D, or a piece of ground: an entity with colliders and no Rigidbody 3D at or above it.
- A collider is named by its own entity: the body's own, or a child's under it.
So a cart with wheels as children is one body. A hit on a wheel names the cart as the body and the wheel as the collider.
Collisions
Three lists say which bodies' colliders touch:
| Property | What it holds |
|---|---|
CollisionsEntered | The bodies that began touching, each pair once however many of their colliders did. |
CollisionsExited | The bodies that stopped touching: moved apart, one taken away, or no longer on layers that meet. |
CollisionsStaying | Every pair touching as the last step left them, those that just began among them. |
Each is a Collision3D:
| Member | What it holds |
|---|---|
A, B | The two bodies. Which is which means nothing. |
ColliderA, ColliderB | The collider of each that touched first, or parted last. |
Point | Where they met, in the world. Zero where they parted. |
Normal | The direction from A into B they met along, a unit long. |
RelativeVelocity | How fast B went against A where they met, in meters a second. |
Impulse | How hard they hit: the push B was given, in newton-seconds. Zero in CollisionsStaying. |
Involves(entity) | Whether the entity is either body or either collider. |
Other(entity), OtherCollider(entity) | What the entity, a body or its collider, touched. |
NormalToward(entity) | The normal of the surface the entity met, pointing into it: up, for something landing on the ground. |
Impulse counts the bodies' masses, so a heavy crate hitting hard counts for more than a pebble just as fast: use it for how loud an impact sounds or how much damage a fall does. A vase that breaks when it is hit hard enough:
[AbyssComponent]public partial struct Vase{ [Tooltip("The impulse that breaks it, in newton-seconds.")] public float Strength = 3f;}
// In a plugin's Build:ComponentType<Vase> vase = world.Component<Vase>();schedule.Add("Vases break", [vase.Read()], context =>{ Physics3D physics = context.Services.Get<Physics3D>(); foreach (Chunk chunk in context.Chunks) { ReadOnlySpan<Vase> vases = chunk.GetReadOnlySpan<Vase>(0); ReadOnlySpan<ulong> entities = chunk.Entities; for (int row = 0; row < entities.Length; row++) { foreach (Collision3D hit in physics.CollisionsEntered) { if (hit.Involves(entities[row]) && hit.Impulse.Length() > vases[row].Strength) { context.Commands.Despawn(entities[row]); break; } } } }}, structural: StructuralAccess.None.AndDespawn);Two bodies that never move by physics, ground, Static and Kinematic bodies, never touch each other: a kinematic platform passing through a wall makes no collision. A body that falls asleep where it rests is still touching what it rests on, and leaves CollisionsStaying only when it is moved away or taken away.
Triggers
A collider with Is Trigger ticked meets nothing: bodies pass through it, and your code is told what went in and came out.
| Property | What it holds |
|---|---|
TriggersEntered | The bodies that went into a trigger, each once however many of their colliders did. |
TriggersExited | The bodies that came out of a trigger: moved out, or it or they taken away. |
TriggersStaying | Every body inside a trigger as the last step left them. |
Each is a Trigger3D: Trigger, the trigger's own entity; Other, the body that went in; and OtherCollider, its collider that went in first or came out last. Involves(entity) says whether an entity is any of the three.
// goal and player are entities your code holds, such as from EntityRef fields.foreach (Trigger3D entered in physics.TriggersEntered){ if (entered.Trigger == goal && entered.Other == player) { // the player reached the goal }}A trigger finds what moves and what does not, and a body asleep in it stays in it. A trigger never finds the body it is part of, nor another trigger, and a trigger that is ground never finds ground or a Static body.
Which step a system sees
Physics steps at the fixed rate, so a frame may hold no step, one or several. What the lists of what entered, exited and broke hold depends on where the system asking runs:
- A fixed system (
[AbyssSystem(Fixed = true)]) sees what happened in its own step. The physics step runs before your game's fixed systems, so it is the step just taken. - A system of the frame sees what happened in every step since the frame before, and nothing in a frame that had no step.
Either way, each collision or trigger event is seen in one step's or one frame's lists only, never again after, and every system asking at the same point sees the same lists.
CollisionsStaying and TriggersStaying are what touches now, as the last step left it, whenever you ask.
What touches now
| Method | What it says |
|---|---|
IsTouching(a, b) | Whether two bodies touch, or one is inside the other's trigger, named by the trigger's entity. |
TouchingOf(entity) | For a body or a piece of ground, the bodies whose colliders touch it and the triggers it is inside; for a trigger, the bodies inside it. |
bool onPad = physics.IsTouching(player, pressurePad);ulong[] inZone = physics.TouchingOf(healingZone);Pairs that do not meet
IgnoreCollision keeps two entities from meeting from the next step on: no touch, no push and no trigger going in between them. Each is a body, or one collider of one. It is how a thrown sword misses its thrower.
physics.IgnoreCollision(sword, thrower); // they pass through each otherphysics.IgnoreCollision(sword, thrower, false); // they meet againbool ignored = physics.GetIgnoreCollision(sword, thrower);Ignored pairs last until the game stops. Queries still find both. To keep whole layers from meeting, use the Collisions grid of the Physics 3D settings instead.
Raycasts
A raycast finds what a line from a point, in a direction, hits first:
if (physics.Raycast(eye, forward, 50f, LayerMask.Of(Layers.Enemies)) is { } seen){ // seen.Entity, the body; seen.Collider, its collider hit; // seen.Point, seen.Normal and seen.Distance}
RaycastHit3D[] pierced = physics.RaycastAll(muzzle, aim, 30f); // every body hit, the nearest first| Parameter | What it is |
|---|---|
origin | Where the ray starts, in the world. |
direction | Which way it goes, of any length. A zero direction hits nothing. |
distance | How far it goes, in meters. Left out, as far as there is. |
layers | The layers whose colliders it can hit. Left out, every layer. |
Raycast returns a RaycastHit3D, or null where it hits nothing. RaycastAll returns every body hit, each once where it is first hit, the nearest first. A hit holds Entity, the body; Collider, the collider's entity; Point; Normal, pointing back toward where the ray came from; and Distance, in meters. LayerMask.Of(Layers.Enemies) names layers by the constants the build writes for the project's layers (see Layers).
Shape casts
A shape cast sweeps a sphere, a box or a capsule along a direction, and says what it meets first. The shape stops Distance along, touching what it met there:
RaycastHit3D? landing = physics.SphereCast(feet, 0.3f, -Vector3.UnitY, 2f);RaycastHit3D? crate = physics.BoxCast(center, new Vector3(1f, 1f, 1f), Quaternion.Identity, forward, 5f);RaycastHit3D? room = physics.CapsuleCast(center, 0.4f, 1.8f, Quaternion.Identity, forward, 1f);| Method | The shape |
|---|---|
SphereCast(origin, radius, direction, distance, layers) | A ball of radius, its middle starting at origin. |
BoxCast(origin, size, rotation, direction, distance, layers) | A box size wide, high and deep, turned by rotation. |
CapsuleCast(origin, radius, height, rotation, direction, distance, layers) | A capsule of radius and height end to end, upright along its own Y as rotation turns it, as a Capsule Collider 3D's. |
Each returns a RaycastHit3D, or null where it meets nothing; distance and layers can be left out, as for a raycast.
Overlaps
An overlap finds every body whose colliders are in or touch a shape where it is, or at a point. Each body is listed once:
ulong[] near = physics.OverlapSphere(center, 3f);ulong[] inside = physics.OverlapBox(center, new Vector3(4f, 2f, 4f), rotation, LayerMask.Of(Layers.Enemies));ulong[] standing = physics.OverlapCapsule(center, 0.4f, 1.8f);ulong[] here = physics.OverlapPoint(point);The rotation of a box or a capsule can be left out, for one not turned at all, and so can the layers, for every layer.
What queries find
- Where the last step left things. An entity made or moved since is found where the next step puts it.
- On the layers you ask about, collider by collider for a body on several. The Collisions grid has no say, and neither do pairs asked not to meet.
- Triggers too, unless Queries Hit Triggers in the Physics 3D settings is off.
- What a ray or a shape starts inside is hit there, at a distance of 0, its normal back along the way it was going. With Queries Start In Colliders off, it is passed over for what is beyond, so a ray down from a body's middle finds what is under it.
In the Scripting API
- Physics3D: what touched, what touches now, and every query.
- Collision3D and Trigger3D: two bodies that touched, and a body in a trigger.
- RaycastHit3D: what a ray or a shape hit.
- LayerMask: the layers a query looks on.
