Combine LowLevelPhysics2D API shapes

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 combine physics shapes into a compound shape, create a composer using a PhysicsComposer object. For example, create a car shape by combining a car body and two wheels.

Follow these steps:

1. At the top of your script, import the Unity.Collections library that contains the allocator APIs the composer uses:

   using Unity.Collections;
   

2. Create the Geometry shapes you want to combine. For more information, refer to Create a physics object.

3. Create a new PhysicsComposer object. Pass in an allocator, which creates temporary memory for building up the combined object. For example:

   PhysicsComposer physicsComposer = PhysicsComposer.Create(Allocator.Temp);
   

   For more information about allocators, refer to Allocator.

4. Add each object to the composer as a layer, specifying its geometry, its position, and how to combine the shape with the existing layers. For example:

   physicsComposer.AddLayer(circleGeometry, PhysicsTransform.identity, PhysicsComposer.Operation.OR);
   

   For more information about Operation, refer to the Layer operations section.

5. Create the combined shape using CreatePolygonGeometry. Pass in a scale, and an allocator that creates the memory to store the combined shape. For example:

   using NativeArray<PolygonGeometry> combinedShape = composer.CreatePolygonGeometry(new Vector2(1f, 1f), Allocator.Temp);
   

   Note: using automatically disposes of the memory allocated for the NativeArray when it goes out of scope. For more information, refer to Destroy LowLevelPhysics2D API objects and manage memory.

6. Create a body with the combined shape using the CreateShapeBatch method. For example:

   body.CreateShapeBatch(combinedShape, PhysicsShapeDefinition.defaultDefinition);
   

The PhysicsComposer API combines CircleGeometry, CapsuleGeometry, PolygonGeometry, PhysicsShape, or any closed region defined by a set of Vector2 points.

Layer operations

The following PhysicsComposer.Operation operations are available:

• OR: Adds the shape.
• AND: Keeps only the overlapping areas between the new shape and the existing shape.
• NOT: Subtracts the new shape from the existing shapes.
• XOR: Removes overlapping areas, but keeps non-overlapping areas.

Example

The following example combines a circle and a capsule shape. Attach this script to 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 in a 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, then enter Play mode to check the combined shape.

using UnityEngine;
using UnityEngine.LowLevelPhysics2D;
using Unity.Collections;

public class CombineShapes : MonoBehaviour
{
    // Create the definition for a circle object
    public CircleGeometry MyCircleGeometry = CircleGeometry.defaultGeometry;
    public PhysicsTransform CircleTransform = new Vector2(0f, 0f);

    // Create the definition for a capsule object
    public CapsuleGeometry MyCapsuleGeometry = CapsuleGeometry.defaultGeometry;
    public PhysicsTransform CapsuleTransform = new Vector2(0.75f, 0f);

    private void Awake()
    {
        PhysicsWorld m_PhysicsWorld = PhysicsWorld.defaultWorld;
        
        // Create a composer to combine shapes
        PhysicsComposer composer = PhysicsComposer.Create(Allocator.Temp);
        
        // Add both shapes to the composer
        composer.AddLayer(MyCircleGeometry, CircleTransform);
        composer.AddLayer(MyCapsuleGeometry, CapsuleTransform, PhysicsComposer.Operation.OR);

        // Combine the shapes
        using NativeArray<PolygonGeometry> combinedShape = composer.CreatePolygonGeometry(new Vector2(1f, 1f), Allocator.Temp);
        
        // Create a body with the combined shapes
        PhysicsBody body = m_PhysicsWorld.CreateBody();       
        body.CreateShapeBatch(combinedShape, PhysicsShapeDefinition.defaultDefinition);

        // Destroy the composer to also destroy the temporary allocator.
        composer.Destroy();
    }   
}

Additional resources

• Connect LowLevelPhysics2D API objects with joints
• PhysicsCore2D repository on GitHub.