Introduction to the LowLevelPhysics2D API

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.

The LowLevelPhysics2D API lets you create and control 2D physics objects in C# scriptsA piece of code that allows you to create your own Components, trigger game events, modify Component properties over time and respond to user input in any way you like. More info
See in Glossary. The API is based on version 3 of the Box2D physics system.

The API doesn’t interact with or affect the built-in Unity 2D physics components such as Rigidbody 2D and Collider 2D. The two systems are separate.

Requirements

The API works on platforms that support compute shadersA program that runs on the GPU. More info
See in Glossary.

The API is compatible with the Universal Render PipelineA series of operations that take the contents of a Scene, and displays them on a screen. Unity lets you choose from pre-built render pipelines, or write your own. More info
See in Glossary (URP), the High Definition Render Pipeline (HDRP), and the Built-In Render Pipeline.

About the API

The API has the following advantages over the standard 2D physics components such as Rigidbody 2D and Collider 2D:

• Create physics in your sceneA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
  See in Glossary with or without using GameObjectsThe 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 info
  See in Glossary. You can create an unlimited number of objects, and create batches of multiple objects.
• Performance is better, because Unity stores data contiguously in memory, and the simulation runs on up to 64 CPU cores simultaneously.
• The system is more deterministic, so you get the same results each time you run the simulation.
• The API supports using 64 layers for collisionA 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 detection, instead of the standard 32.
• Most APIs are thread-safe, so you can use the job system to run physics code on multiple threads.
• The API returns objects as structs, so you can use them in Unity’s Data-Oriented Technology Stack (DOTS).

The API lets you do the following for example:

• Combine shapes into your own physics shapes, for example a gear with teeth.
• Create multiple, isolated physics worlds in the same scene that run in parallel.
• Run 2D physics in 3D space, for example to create a 2D world that lies flat on the ground.
• Use multiple threads to cast rays that query intersections and overlaps.

There are no built-in components. You create physics objects directly in your scene. However you can use the API to expose sets of properties in the Inspector window of the Unity Editor that act like components. This allows you to configure properties similarly to Rigidbody 2D and Collider 2D components.

Debug drawing

The LowLevelPhysics2D API automatically draws a debug visualization of physics objects in the Scene viewAn interactive view into the world you are creating. You use the Scene View to select and position scenery, characters, cameras, lights, and all other types of Game Object. More info
See in Glossary, Game view, and in development buildsA development build includes debug symbols and enables the Profiler. More info
See in Glossary. You can also draw your own debug shapes. For more information, refer to Draw a debug visualization of LowLevelPhysics2D API objects.

Example projects

For example projects that use the LowLevelPhysics2D API, refer to the PhysicsCore2D repository on GitHub.

Additional resources

• PhysicsCore2D repository on GitHub