Note: This documentation is about writing C# scripts using the LowLevelPhysics2D API. To use 2D physics in the Unity Editor using components like the Rigidbody 2D component, refer to 2D physics instead.
In the LowLevelPhysics2D API, collisionsA collision occurs when the physics engine detects that the colliders of two GameObjects make contact or overlap, when at least one has a Rigidbody component and is in motion. More info
See in Glossary are enabled by default.
By default the following applies:
To change this behaviour, do the following:
LowLevelPhysics2D API to use its own set of 64 layers, instead of GameObjectThe fundamental object in Unity scenes, which can represent characters, props, scenery, cameras, waypoints, and more. A GameObject’s functionality is defined by the Components attached to it. More infoNote: To configure how a physics object reacts to collisions, for example how bouncy it is, refer to Configure LowLevelPhysics2D API scenes with definitions.
Follow these steps:
The PhysicsMask API now uses the layers in the Physics Layer Names section of the Physics Low Level Settings 2D asset.
Use the Physics Layer Names section to add, edit, or remove layers. For more information, refer to Physics Low Level Settings window reference.
Follow these steps:
Create the layers you need. For more information, refer to Physics Low Level Settings window reference.
Create a physics object with a public PhysicsShapeDefinition and attach it to a GameObject.
Select the GameObject, then in the InspectorA Unity window that displays information about the currently selected GameObject, asset or project settings, allowing you to inspect and edit the values. More info
See in Glossary window open the Contact Filter dropdown.
Set Categories to the layers you want the object to be on. For example, the first built-in layer called Default.
Set Contacts to the layers you want the object to collide with. For example Nothing for no layers.
Follow these steps:
Create the layers you need. For more information, refer to Physics Low Level Settings window reference.
Create a PhysicsMask object with the layer you want the object to be on. For example:
PhysicsMask objectLayer = PhysicsLayers.GetLayerMask("Car");
PhysicsLayers.GetLayerMask gets the layer mask whether you’re using GameObject layers or the LowLevelPhysics2D API layers.
Create another PhysicsMask object with the layers you want the object to collide with.
PhysicsMask objectLayer = PhysicsLayers.GetLayerMask("Walls");
Create a ContactFilter object with the two physics layer masks. For example:
PhysicsShape.ContactFilter myContactFilter = new PhysicsShape.ContactFilter { categories = objectLayer, contacts = contactLayer },
You can also use PhysicsMask.All to represent all layers, or PhysicsMask.None to represent no layers.
Assign the ContactFilter to the PhysicsShape when you create it. For example:
PhysicsShapeDefinition shapeDefinition = new PhysicsShapeDefinition{
contactFilter = myContactFilter
};
If PhysicsMask is a bitmask rather than a set of layers, add the PhysicsMask.ShowAsPhysicsMask attribute. Unity then displays the mask as bit values.
For more information, refer to PhysicsMask.
Because physics bodies move in steps, fast-moving objects can sometimes pass through other objects without activating a collision. This is called tunnelling.
The 2D physics system automatically uses continuous collision detectionAn automatic process performed by Unity which determines whether a moving GameObject with a Rigidbody and collider component has come into contact with any other colliders. More info
See in Glossary to prevent tunnelling when dynamic objects approach static objects. However if a very fast-moving object still passes through another object, enable the fastCollisionsAllowed property of the physics body to force continuous collision detectionA collision detection method that calculates and resolves collisions over the entire physics simulation step. This can prevent fast-moving objects from tunnelling through walls during a simulation step. More info
See in Glossary. Enabling this setting can reduce performance.
The following example sets a falling circle to be on the MyNewLayer layer and collide only with other MyNewLayer layer objects. It passes through the larger circle that’s in the default layer.
To use the example:
using UnityEngine;
using UnityEngine.LowLevelPhysics2D;
public class ContactFilters : MonoBehaviour
{
void Start()
{
CircleGeometry smallCircleShape = new CircleGeometry{ radius = 0.5f };
CircleGeometry largeCircleShape = new CircleGeometry{ radius = 3f };
PhysicsWorld world = PhysicsWorld.defaultWorld;
// Create a small falling circle
PhysicsBody object1 = world.CreateBody(new PhysicsBodyDefinition
{
position = new Vector2(0.5f, 8f),
type = PhysicsBody.BodyType.Dynamic
});
// Create a shape on the MyNewLayer layer, which only collides with the MyNewLayer layer
PhysicsMask objectLayer = PhysicsLayers.GetLayerMask("MyNewLayer");
PhysicsMask collisionLayer = PhysicsLayers.GetLayerMask("MyNewLayer");
PhysicsShape.ContactFilter contactFilter = new PhysicsShape.ContactFilter {
categories = objectLayer,
contacts = collisionLayer
};
PhysicsShapeDefinition smallCircleDefinition = new PhysicsShapeDefinition{
contactFilter = contactFilter
};
object1.CreateShape(smallCircleShape, smallCircleDefinition);
// Create a larger static circle below, on the default layer
PhysicsBody object2 = world.CreateBody(new PhysicsBodyDefinition
{
position = new Vector2(0f, 0f),
type = PhysicsBody.BodyType.Static
});
object2.CreateShape(largeCircleShape);
}
}