Create a world with 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.

To create physics objects using the LowLevelPhysics2D API, you first need to create a physics world.

Prerequisites

Before you create a physics world, follow these steps:

Create a MonoBehaviour script file: from the main menu, select Assets > Create > C# Script.
To import the LowLevelPhysics2D API namespace, add using UnityEngine.LowLevelPhysics2D; at the top of the script.

Note: You can use the API in any C# script, not only MonoBehaviour script files. But if you use a MonoBehaviour script file, you can configure physics properties 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 of a 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 info
See in Glossary, move GameObjects, and attach spritesA 2D graphic objects. If you are used to working in 3D, Sprites are essentially just standard textures but there are special techniques for combining and managing sprite textures for efficiency and convenience during development. More info
See in Glossary.

Fetch the default world

Unity automatically creates a default world. To fetch it, follow these steps:

Get the defaultWorld property from the PhysicsWorld class.
```
PhysicsWorld world = PhysicsWorld.defaultWorld;
```
Attach the script to a GameObject 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.
Enter Play mode to run the script.

To adjust the properties of the world, refer to Configure global LowLevelPhysics2D API settings.

Unity creates or recreates the default world at the following times:

When the Editor starts.
When you enter or exit Play mode.
When your built application starts.

Create your own world

To create your own world, follow these steps:

Create a public PhysicsWorldDefinition object that holds the world properties and displays them in the Inspector window. For example:
```
public PhysicsWorldDefinition worldDefinition = new PhysicsWorldDefinition();
```
A new definition has a set of default values. For example, gravity is set to –9.81f. For more information about definitions and changing the default values, refer to Configure objects using definitions.

You can also use PhysicsWorld.defaultDefinition to get a definition object with the default values.

Create a PhysicsWorld object with the definition. For example:

PhysicsWorld world = PhysicsWorld.Create(worldDefinition);

Attach the script to a GameObject in your scene.
To adjust the properties of the world, modify the values in the Inspector window.

To configure the world in your script instead, set the properties of the definition object before you create the world. For more information, refer to Configure objects using definitions.
Enter Play mode to run the script and create the world.

Pause a world

A world starts running as soon as you create it. To pause the simulation, set the paused property of the world object to true.

Example

The following example fetches the default world and logs the gravity value to the Console window.

using UnityEngine;
using UnityEngine.LowLevelPhysics2D;

public class GetDefaultWorld : MonoBehaviour
{
    void Awake()
    {
        // Fetch the default physics world
        PhysicsWorld world = PhysicsWorld.defaultWorld;

        // Log the gravity value to check the world is created
        Debug.Log("The gravity in this world is " + world.gravity);
    }    
}

Additional resources

Creating a scene with the LowLevelPhysics2D API

Create an object with the LowLevelPhysics2D API