Manual
Manual
Bodies and colliders
Physics 2D makes entities fall, collide, bounce and push each other. An entity with a collider is something to bump into, and one with a Rigidbody 2D as well moves as the physics says. This page covers bodies, every kind of collider and how to edit its shape, the materials colliders are made of, which layers collide, one-way platforms, and the Physics 2D settings.
Physics 2D in a game
Physics 2D is a package, abyss.physics2d, built on Box2D 3.1.1. The 2D and 3D templates come with it, and Window ▸ Package Manager installs it in any game (see Using packages). Its components are the package's own C# components, and its C# types are in the Abyss.Physics2D namespace.
Physics runs on the game's fixed clock, a sixtieth of a second unless Project Settings ▸ Time says otherwise (see Systems at a fixed rate). Each fixed step, Box2D moves the bodies, and where each one ends up is written to its entity's Transform: across X and Y, turned about Z.
A world unit is a meter, which Box2D is tuned for. A sprite is its pixels over its image's Pixels Per Unit, 100 unless its import says otherwise, so a 64-pixel crate is 0.64 meters across (see Sprites).
Rigidbody 2D
A Rigidbody 2D makes its entity a body that physics moves. Its colliders are the colliders on its own entity, and those on the entities under it that have no Rigidbody 2D nearer.
| Field | What it does |
|---|---|
| Type | Dynamic: moved by gravity, by what it meets and by forces. Kinematic: moved by its velocity alone, as code sets it; it pushes dynamic bodies and is not pushed. Static: not moved by physics at all, for ground and walls. |
| Use Auto Mass | Works its mass out from its colliders, each its area times its Density, and shows the result in Mass. |
| Mass | Its mass, in kilograms, whatever its colliders' sizes. 1 to begin with. |
| Gravity Scale | How much of gravity pulls it: 1 all of it, 0 none, −1 upward. |
| Linear Damping | How quickly its moving slows of itself, as in air. |
| Angular Damping | How quickly its turning slows of itself. |
| Freeze Rotation | It never turns, as a character that stays upright. |
| Interpolate | None: drawn where the last step put it. Interpolate: drawn between where the last two steps put it, smooth at any frame rate, a step behind. |
| Collision Detection | Discrete: checked where it is at each step; a fast, small body can pass through a thin one. Continuous: checked along its way between steps too, for bullets, at a cost. |
| Linear Velocity | How fast it moves, in meters a second. |
| Angular Velocity | How fast it turns, in degrees a second, anticlockwise. |
Linear Velocity and Angular Velocity are what the last step left. Set them from a system, and the next step takes them up: that is how a game moves a Kinematic body, or gives a Dynamic one a new speed. Setting a body's Transform from code puts it there at once, as a teleport.
An entity with colliders and no Rigidbody 2D at or above it is ground: it never moves, and stays where its GlobalTransform puts it, scaled as it is. A Static body counts as ground too, and two grounds never collide with each other.
Push a body from code
Forces, impulses and moves are asked of the Physics2D service, which does them at the next fixed step. Any system may ask:
Physics2D physics = context.Services.Get<Physics2D>();
physics.AddImpulse(player, new Vector2(0f, 8f)); // a jump: a body of mass 2 rises at 4 meters a secondphysics.AddForce(ship, thrust); // a push, in newtons, for one stepphysics.AddTorque(wheel, 5f); // a turn for one step, anticlockwisephysics.AddAngularImpulse(top, 1f); // a spin at oncephysics.MovePosition(platform, new Vector2(3f, -0.4f)); // there by the end of the next step, then stoppedphysics.MoveRotation(platform, 30f); // turned to 30 degrees over the next stepA force lasts one step, so a steady push is asked every step, from a fixed system (schedule.Fixed). An impulse acts at once and can be asked from any system. MovePosition moves a body over a step, pushing what is in its way, where setting its Transform would jump it there through whatever is between; asked each step, it keeps moving. MoveRotation turns a body by at most 45 degrees a step. Asked of an entity that has no Rigidbody 2D by the next step, they do nothing.
Code that is not a system, such as a flow, gets the service with world.Services.Get<Physics2D>() (see C# in a game).
Colliders
A collider gives an entity a shape to meet things with. It is on the nearest Rigidbody 2D at or above its entity, so a body can be made of its children: a cart whose wheels and bed are children with colliders is one body of all of them. Each child collider is placed by its own Transform and those between it and the body (moved, turned, scaled, flipped) and is on its own entity's layer. The colliders of one body never collide with each other. A child with a Rigidbody 2D of its own is a body of its own.
Every collider has these fields:
| Field | What it does |
|---|---|
| Offset | Where its middle, or its points, are from the entity's middle. |
| Is Trigger | A trigger meets nothing and is passed through, and is told of what goes into it (see Contacts and queries). |
| Material | The Physics Material 2D it is made of: how it slides and bounces. None uses the Default Material of the Physics 2D settings. |
| Density | How heavy it is for its size, in kilograms a square meter: what its body's mass is worked out from, where the Rigidbody 2D says Use Auto Mass. Not on edges and tilemaps. |
Sizes and points are in the entity's own units, scaled with it.
A collider added in the editor fits what the entity draws: a box its sprite's rectangle, a circle round it, a capsule along its longer side, a polygon at its corners. An entity that draws nothing keeps the collider's own starting size. When you resize a sprite in the editor, every collider on its entity is stretched with it, so a fitted collider stays fitted.
Box Collider 2D
A box, Size wide and high, 1 by 1 to begin with. Edge Radius rounds its corners: the box grows by that much all round.
Circle Collider 2D
A circle of Radius, 0.5 to begin with, scaled by the larger of its entity's X and Y scale.
Capsule Collider 2D
A box with round ends, the shape a character usually moves as. Size is how wide and high it is, round ends included, 0.5 by 1 to begin with. Direction is Vertical, its round ends at the top and bottom, or Horizontal, at the sides. A capsule no longer than it is wide is a circle.
Polygon Collider 2D
A shape of up to 64 Points, in order round it, concave or convex, with a hollow between them left out. It starts as a square a unit across. Edge Radius rounds its corners. A polygon whose sides cross is met as the hull of its points, and one with fewer than three points, or three in a line, meets nothing.
Edge Collider 2D
A line through up to 32 Points, in order, met from either side: the outline of the ground, a slope, a ledge. It starts as a line a unit long.
Tilemap Collider 2D
Put on an entity with a Tilemap, it meets things with the tilemap's outline: a loop round each region of solid tiles joined by their sides, each straight run of it one edge, so nothing sliding along it catches on a seam between two tiles; and the top of each row of one-way tiles, met from above alone. It is made again as the tiles change.
How each tile is met is set in the Tile Palette, for the tiles of the brush: its Collision is Solid, met from every side, None, not met at all (grass, a torch), or One-Way, met from above alone; and its Shape is what of its cell it fills (Full, Traced from its art, or Drawn by hand).
Its fields are Is Trigger and Material. Its one-way tiles behave as a Platform Effector 2D on its entity says, or, where it has none, are met from along its entity's up across a half turn. Its solid tiles are met from every side whatever the effector says.
Edit Collider
Edit Collider, the button at the top of a collider's section, edits its shape in the Scene view with green dots:
- A box and a capsule have a dot in the middle of each side. Drag one to move that side, the far side staying where it is. Hold Shift to keep the shape's proportions, or Alt to move both sides about the middle, as with the Rect tool.
- A circle has four dots on its edge, which set its radius.
- A polygon and an edge have a dot at each point. Drag a dot to move it, click the line between two to add a point there, and hold Ctrl and click a dot to delete it: three to 64 points for a polygon, two to 32 for an edge.
While it is on, the Move, Rotate, Scale and Rect tools' handles are hidden. Escape in the Scene view, the button again, choosing a tool, or picking something else ends it. Each drag is one Ctrl+Z.
In the Scene view, the colliders of what is picked are outlined in green, while you edit and while the game plays.
Physics Material 2D
A Physics Material 2D is a data asset saying how a collider slides and bounces. In the Project panel, Create ▸ Physics 2D ▸ Physics Material 2D makes one as an .asset file. Drop it on a collider's Material slot, which takes only these.
| Field | What it does |
|---|---|
| Friction | How much it holds against sliding, from 0, as on ice, to 1. 0.4 to begin with. |
| Bounciness | How much it bounces back, from 0, stopping dead, to 1, bouncing as high as it fell. 0 to begin with. |
A collider naming none is made of the Default Material of the Physics 2D settings, and where that names none too, of friction 0.4 and no bounce.
Layers and what collides
Each collider is on its entity's layer, set in the Inspector's header (see Layers). Collisions in the Physics 2D settings is a triangle of ticks by the layers' names: two layers left unticked pass through each other.
To keep two particular entities from meeting, ask the service. Each can be a body or one collider of one. From the next step there is no touch between them, no push, no trigger going in, and a character's move passes through, until they are asked to meet again:
physics.IgnoreCollision(sword, thrower); // a thrown sword misses its throwerphysics.IgnoreCollision(sword, thrower, false); // and meets it againbool apart = physics.GetIgnoreCollision(sword, thrower);Queries still find both. What is asked is kept until the game stops.
Platform Effector 2D
A Platform Effector 2D makes the colliders on its own entity a one-way platform. It is met only from along its up, so what falls onto it from above lands on it, and what jumps up through it from below or walks into its side passes through, bodies and characters alike.
| Field | What it does |
|---|---|
| Use One Way | Met from along its up alone. Off, it is met from every side. |
| Surface Arc | How wide the way it is met from is, in degrees about its up: 180 is the whole top side. |
| Rotational Offset | How far its up is turned from its entity's, in degrees anticlockwise: 180 is met from below. |
Its up is its entity's, as its GlobalTransform turns it, turned Rotational Offset more. Something deep inside it passes on whichever way it goes, so a body jumping up through it is not caught halfway, and lands on it once it is above. While it is picked, its arc is drawn from its middle in the Scene view.
To have a character drop down through a platform it stands on, keep the two from meeting for a while; see Drop through a one-way platform.
Physics 2D settings
Edit ▸ Project Settings… ▸ Physics 2D holds the settings for every body. They are saved in settings/physics-2d.json, which a built game carries.
| Field | What it does |
|---|---|
| Gravity | The pull on every body, in meters a second squared: (0, −9.81) is the Earth's. |
| Sub Steps | How many times Box2D works each step out, from 1 to 16: more is steadier, and slower. 4 to begin with. |
| Default Material | What a collider naming no material is made of. |
| Queries Hit Triggers | Whether raycasts, shape casts and overlaps find triggers. Off, they pass through them. |
| Queries Start In Colliders | Whether a raycast or a shape cast that starts inside a collider hits it there. Off, it passes over it. |
| Collisions | Which layers' colliders meet which. |
A game reads them as the resource Res<Physics2DSettings>, or with world.Settings<Physics2DSettings>(), and may change them while it plays, such as gravity for a low-gravity zone, for that run only (see Project settings declared in code).
In the Scripting API
- Rigidbody2D, with BodyType2D, Interpolation2D and CollisionDetection2D: a body and how it moves.
- BoxCollider2D, CircleCollider2D, CapsuleCollider2D, PolygonCollider2D, EdgeCollider2D and TilemapCollider2D: the colliders.
- PhysicsMaterial2D: what a collider is made of.
- PlatformEffector2D: a one-way platform.
- Physics2D: forces, impulses and moves asked of bodies, and which pairs do not meet.
- Physics2DSettings: the Physics 2D page of Project Settings.
