Unity 2d Physics Lowlevel

Unity Low-Level 2D Physics

Retrieval Sources

This system lives in the UnityEngine.LowLevelPhysics2D namespace (1581 ScriptReference pages locally) and, unlike many newer/preview-ish Unity APIs, it has a genuinely substantial Manual tree explaining it: Manual/2d-physics-api/ contains 34 real explanatory pages (confirmed on disk, not just a bare ScriptReference dump), each carrying working code samples. So this skill is NOT purely signature-only — there is real conceptual documentation, and it is cited below alongside the exact ScriptReference member pages that were verified to exist. Every page in this table was confirmed present on disk before being cited (via ls, find, or direct Read). The official Unity example project referenced repeatedly across the Manual pages is github.com/Unity-Technologies/PhysicsExamples2D (an external resource, not verified locally, but named verbatim in the docs).

Key Guidelines

Physics World Management

A PhysicsWorld is the simulation container — nothing exists in this API outside of one. PhysicsWorld.defaultWorld is a ready-made world Unity auto-creates (and recreates on Editor start, Play mode enter/exit, and application start), and is the fastest way to get moving; for anything with custom settings, fill a PhysicsWorldDefinition struct and call PhysicsWorld.Create(definition). The definition's most important field is gravity (Vector2, defaults to (0, -9.81)), but it also carries simulationType (see Simulation Stepping below), simulationSubSteps (default 4), simulationWorkers, transformWriteMode/transformPlane/transformTweening (how/whether simulation results get written back to real Transforms — see the GameObject-bridge subsection), sleepingAllowed, continuousAllowed, and a large block of draw* fields controlling the automatic Scene/Game-view debug visualization. Unlike Physics2D, this is not a single global static system — you can have multiple independent PhysicsWorld instances (up to PhysicsConstants.MaxWorlds) simulated concurrently on separate threads, each fully isolated from the others (Manual/2d-physics-api/2d-physics-api-multithreading.html). A world can be paused via paused = true, and every object created in it must be explicitly destroyed or is cascade-destroyed when the world itself is destroyed (see Debug Visualization & Object Lifetime).

using UnityEngine;
using UnityEngine.LowLevelPhysics2D;

public class CustomWorldExample : MonoBehaviour
{
    private PhysicsWorld world;

    void Awake()
    {
        PhysicsWorldDefinition worldDefinition = new PhysicsWorldDefinition
        {
            gravity = new Vector2(0f, -20f),      // heavier gravity than the -9.81 default
            simulationType = PhysicsWorld.SimulationType.FixedUpdate,
            simulationSubSteps = 4
        };
        world = PhysicsWorld.Create(worldDefinition);
    }

    void OnDestroy() => world.Destroy(); // worlds are never auto-cleaned up except the default world
}

Body Creation & Configuration

A PhysicsBody holds position, rotation, and velocity but has no shape/area of its own — you attach one or more PhysicsShapes to it to give it collidable geometry (Manual/2d-physics-api/2d-physics-api-physics-object.html). Bodies are created from a PhysicsBodyDefinition via world.CreateBody(definition) (or world.CreateBody() for an all-defaults body). The type field is PhysicsBody.BodyType, a 3-value enum with real solver semantics, not just an on/off kinematic flag: Dynamic (positive mass, velocity driven by forces, moved by the solver), Kinematic (zero mass, velocity set directly by you, still moved by the solver — collides with and pushes Dynamic bodies), and Static (zero mass, zero velocity, may only be moved manually) — verified verbatim from ScriptReference/LowLevelPhysics2D.PhysicsBody.BodyType.html. BodyConstraints (None/PositionX/PositionY/Rotation/Position/All) is the low-level equivalent of Rigidbody's freeze-position/rotation checkboxes. Mass (massConfiguration: mass, center, rotationalInertia) is normally recalculated automatically every time a shape is added/removed/modified; for bulk shape addition, set PhysicsShapeDefinition.startMassUpdate = false per shape while adding many, then call body.ApplyMassFromShapes() once at the end to avoid redundant recalculation.

using UnityEngine;
using UnityEngine.LowLevelPhysics2D;

public class DynamicBodyExample : MonoBehaviour
{
    void Start()
    {
        PhysicsWorld world = PhysicsWorld.defaultWorld;

        PhysicsBody body = world.CreateBody(new PhysicsBodyDefinition
        {
            position = new Vector2(0f, 8f),
            type = PhysicsBody.BodyType.Dynamic,
            constraints = PhysicsBody.BodyConstraints.Rotation, // free to move, can't spin
            linearDamping = 0.05f
        });

        body.CreateShape(new CircleGeometry { radius = 0.5f });
    }
}

Shape Definition & Surface Materials

PhysicsShape is the collidable-area component, attached to a body via one of PhysicsBody.CreateShape's overloads — one per geometry type: CircleGeometry, CapsuleGeometry, PolygonGeometry, SegmentGeometry (verified declarations, e.g. public PhysicsShape CreateShape(CircleGeometry geometry) and the overload taking an additional PhysicsShapeDefinition). A PhysicsShapeDefinition configures isTrigger, density (affects mass, not size), contactFilter (layer/category filtering — see Collision & Trigger Interactions), and surfaceMaterial. PhysicsShape.SurfaceMaterial bundles friction, bounciness, rollingResistance, tangentSpeed (conveyor-belt-style surface motion), plus a MixingMode enum (Average/Mean/Multiply/Minimum/Maximum) and a *Priority field per property so that when two touching shapes disagree on friction/bounciness mixing mode, the higher-priority (and on ties, higher-enum-value) shape's mode wins. Density can be read/written after creation via GetDensity()/SetDensity(density, updateBodyMass) — the updateBodyMass flag lets you skip the mass recalculation for speed when setting many shapes' densities in a row.

using UnityEngine;
using UnityEngine.LowLevelPhysics2D;

public class ShapeSurfaceExample : MonoBehaviour
{
    void Start()
    {
        PhysicsWorld world = PhysicsWorld.defaultWorld;
        PhysicsBody body = world.CreateBody(new PhysicsBodyDefinition { type = PhysicsBody.BodyType.Dynamic });

        PhysicsShapeDefinition bouncyDefinition = new PhysicsShapeDefinition
        {
            density = 2f,
            surfaceMaterial = new PhysicsShape.SurfaceMaterial { friction = 0.1f, bounciness = 0.9f }
        };
        body.CreateShape(new CircleGeometry { radius = 0.5f }, bouncyDefinition);
    }
}

Joints

Every joint follows the same pattern as bodies/shapes: fill a PhysicsXxxJointDefinition struct (set bodyA/bodyB plus joint-specific fields), then call world.CreateJoint(definition), which returns the matching PhysicsXxxJoint (each overload of PhysicsWorld.CreateJoint is strongly typed per definition — verified via ScriptReference/LowLevelPhysics2D.PhysicsWorld.CreateJoint.html). Six constraint kinds exist, each with its own semantics: Distance keeps two bodies a target distance apart (with optional spring/motor/limit, all spring-gated); Fixed spring-welds position and rotation together (not perfectly rigid — has linearFrequency/angularFrequency); Hinge pins a shared pivot point so the second body rotates freely about it (spring-to-angle, motor with speed+torque, angle limits); Slider restricts the second body to translate along an axis fixed to the first body's rotation; Wheel combines Slider-style translation (suspension) with free rotation — the vehicle-suspension joint; Relative is different from the rest — it drives a target relative linear/angular velocity rather than a positional constraint. PhysicsIgnoreJoint is a degenerate case: it links bodyA/bodyB purely to suppress collision between them, with no positional or velocity constraint at all. Fields common to every joint definition: forceThreshold/torqueThreshold (fire OnJointThreshold2D when exceeded), tuningFrequency/tuningDamping (overall joint stiffness), collideConnected (whether the two connected bodies can still collide with each other), and drawScale for debug visualization. Destroying either connected body automatically destroys the joint.

using UnityEngine;
using UnityEngine.LowLevelPhysics2D;

public class HingeJointExample : MonoBehaviour
{
    void Start()
    {
        PhysicsWorld world = PhysicsWorld.defaultWorld;

        PhysicsBody anchor = world.CreateBody(new PhysicsBodyDefinition { type = PhysicsBody.BodyType.Static });
        PhysicsBody door = world.CreateBody(new PhysicsBodyDefinition
        {
            position = new Vector2(1f, 0f),
            type = PhysicsBody.BodyType.Dynamic
        });
        door.CreateShape(PolygonGeometry.CreateBox(new Vector2(2f, 0.2f)));

        PhysicsHingeJointDefinition hingeDefinition = new PhysicsHingeJointDefinition
        {
            bodyA = anchor,
            bodyB = door,
            enableMotor = true,
            motorSpeed = 90f,
            maxMotorTorque = 50f,
            enableLimit = true,
            lowerAngleLimit = 0f,
            upperAngleLimit = 90f
        };
        PhysicsJoint hinge = world.CreateJoint(hingeDefinition);
    }
}

Collision & Trigger Interactions

Each PhysicsShape behaves as either a solid collider (default) or a trigger, controlled by PhysicsShapeDefinition.isTrigger. Filtering happens through PhysicsShape.ContactFilter { categories, contacts, groupIndex } assigned into the shape definition — this API defaults to the standard 32 GameObject layers, but can opt into its own 64-layer system by enabling "Use Full Layers" on the PhysicsLowLevelSettings2D asset; PhysicsLayers.GetLayerMask("Name") resolves a PhysicsMask correctly under either mode, and PhysicsMask.All/PhysicsMask.None are shortcuts. There are two distinct, verified ways to observe collisions/triggers: (1) implement PhysicsCallbacks.IContactCallback (OnContactBegin2D/OnContactEnd2D) or PhysicsCallbacks.ITriggerCallback (OnTriggerBegin2D/OnTriggerEnd2D) on any object, then wire it up — this requires the world's autoContactCallbacks/autoTriggerCallbacks to be enabled, the shape's contactEvents/triggerEvents set true, and the shape's callbackTarget pointed at your callback object; or (2) poll PhysicsWorld.contactBeginEvents/triggerBeginEvents (and the matching *EndEvents), which return ReadOnlySpans directly over engine memory — faster but explicitly documented as less safe to hold onto past the current frame. Fast-moving dynamic-vs-dynamic tunneling isn't prevented automatically (continuous collision is automatic only for dynamic-vs-static); opt a fast mover in with PhysicsBody.fastCollisionsAllowed = true.

using UnityEngine;
using UnityEngine.LowLevelPhysics2D;

public class ContactListener : MonoBehaviour, PhysicsCallbacks.IContactCallback
{
    void Start()
    {
        PhysicsWorld world = PhysicsWorld.defaultWorld;
        world.autoContactCallbacks = true; // must be enabled on the world

        PhysicsBody body = world.CreateBody(new PhysicsBodyDefinition { type = PhysicsBody.BodyType.Dynamic });
        PhysicsShape shape = body.CreateShape(new CircleGeometry { radius = 0.5f });
        shape.contactEvents = true;
        shape.callbackTarget = this; // must implement IContactCallback
    }

    public void OnContactBegin2D(PhysicsEvents.ContactBeginEvent contactEvent)
    {
        Debug.Log($"Contact started between {contactEvent.contactId.contact.shapeA} and {contactEvent.contactId.contact.shapeB}");
    }

    public void OnContactEnd2D(PhysicsEvents.ContactEndEvent contactEvent) { }
}

Queries (Raycasts, Overlaps & Casts)

Query entry points live as instance methods on PhysicsWorld — CastRay (a bounded line segment, not an infinite ray), CastGeometry/CastShape (sweep a shape through the world), OverlapPoint/OverlapAABB/OverlapShape (static-volume tests), plus boolean-only TestOverlap* variants for a cheaper yes/no answer. All are declared thread-safe, unlike object creation/destruction. Every cast/overlap call takes a PhysicsQuery.QueryFilter (layer/category filtering, mirroring ContactFilter) and an explicit Unity.Collections.Allocator (Temp, TempJob, or Persistent only), and returns a NativeArray<T> of results (WorldCastResult for casts, WorldOverlapResult for overlaps) that must be disposed — the docs explicitly call out leaks otherwise (the sole exception being an empty result array). PhysicsQuery.WorldCastMode controls how many/which order results come back (Closest confirmed; All/AllSorted also present per the enum's ScriptReference page). Separately, PhysicsQuery also exposes narrow-phase, static, shape-pair-vs-shape-pair test methods (e.g. CircleAndCircle, PolygonAndCapsule, SegmentAndPolygon) and each geometry struct (CircleGeometry, CapsuleGeometry, etc.) carries its own Intersect/CastRay/CastShape/ClosestPoint/OverlapPoint instance methods for lower-level geometry math without going through a world at all.

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

public class RaycastExample : MonoBehaviour
{
    void CheckGround(Vector2 origin)
    {
        PhysicsWorld world = PhysicsWorld.defaultWorld;
        var input = new PhysicsQuery.CastRayInput
        {
            origin = origin,
            translation = Vector2.down * 2f
        };
        var filter = new PhysicsQuery.QueryFilter();

        using NativeArray<PhysicsQuery.WorldCastResult> results =
            world.CastRay(input, filter, PhysicsQuery.WorldCastMode.Closest, Allocator.Temp);

        if (results.Length > 0)
            Debug.Log($"Hit {results[0].shape} at {results[0].point}");
        // 'using' disposes the NativeArray automatically at scope exit
    }
}

Simulation Stepping & Multithreading

PhysicsWorldDefinition.simulationType (a PhysicsWorld.SimulationType enum) picks when a world advances: FixedUpdate (default, mirrors classic physics timing), Update (steps once per rendered frame instead), or Script — in Script mode the world does nothing until you explicitly call world.Simulate(deltaTime), which the docs state only works when simulationType == Script; there's also a static batch overload, PhysicsWorld.Simulate(ReadOnlySpan<PhysicsWorld> worlds, deltaTime), that can advance several worlds concurrently depending on PhysicsLowLevelSettings2D.concurrentSimulations. Internally the solver can use up to simulationWorkers threads (capped by PhysicsConstants.MaxWorkers) per world, using a "Write Once, Read Many" (WORM) lock: any number of threads can read a world simultaneously, but only one can write, and separate worlds are fully independent so each can be written from a different thread concurrently. Crucially, not everything is safe to call from a job or worker thread — Create, CreateBatch, Destroy, and DestroyBatch (on bodies, shapes, joints, chains) are explicitly documented as not thread-safe; only reads and the per-instance simulation/query methods are.

using UnityEngine;
using UnityEngine.LowLevelPhysics2D;

public class ManualStepExample : MonoBehaviour
{
    private PhysicsWorld world;

    void Awake()
    {
        world = PhysicsWorld.Create(new PhysicsWorldDefinition
        {
            simulationType = PhysicsWorld.SimulationType.Script // required for manual Simulate() to have any effect
        });
    }

    void FixedUpdate()
    {
        world.Simulate(Time.fixedDeltaTime); // deterministic, lockstep-friendly stepping (e.g. for networked physics/replays)
    }
}

Chains, Shape Composition & Destructible Geometry

PhysicsChain (created via body.CreateChain(ChainGeometry, PhysicsChainDefinition)) is the low-level equivalent of an edge-loop collider — a strip or closed loop of line segments, the natural fit for tilemap boundaries or terrain outlines, configured with the same surfaceMaterial/contactFilter shape as regular shapes plus isLoop to close the strip into a loop, and a groupIndex override on its contact filter that always/never forces collision with same-group shapes regardless of category/mask (mirroring classic Physics2D's collision-group override). PhysicsComposer performs CSG-style boolean composition of geometry — AddLayer stacks CircleGeometry/CapsuleGeometry/PolygonGeometry/PhysicsShape/raw point loops together with an Operation (OR/AND/NOT/XOR), then CreatePolygonGeometry/CreateChainGeometry bakes the result into geometry you can feed straight into CreateShapeBatch/CreateChain. Composer work happens through Unity.Collections (NativeArray/NativeList with an explicit Allocator), so it is Burst/job-adjacent, unmanaged-memory territory rather than ordinary GC'd C#. PhysicsDestructor provides Slice and Fragment static utilities for runtime geometry breaking (e.g. shattering a shape into pieces along a cut line or fracture pattern) — confirmed to exist in ScriptReference, but no dedicated Manual conceptual page was found for it under 2d-physics-api/, so treat its exact intended workflow as signature-level only.

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

public class ComposedShapeExample : MonoBehaviour
{
    void Start()
    {
        PhysicsComposer composer = PhysicsComposer.Create(Allocator.Temp);
        composer.AddLayer(new CircleGeometry { radius = 1f }, PhysicsTransform.identity, PhysicsComposer.Operation.OR);
        composer.AddLayer(new CircleGeometry { radius = 0.6f, center = new Vector2(0.8f, 0f) }, PhysicsTransform.identity, PhysicsComposer.Operation.OR);

        using NativeArray<PolygonGeometry> combined = composer.CreatePolygonGeometry(Vector2.one, Allocator.Temp);

        PhysicsBody body = PhysicsWorld.defaultWorld.CreateBody(new PhysicsBodyDefinition { type = PhysicsBody.BodyType.Dynamic });
        body.CreateShapeBatch(combined, PhysicsShapeDefinition.defaultDefinition);

        composer.Destroy();
    }
}

Debug Visualization & Object Lifetime Management

Every shape created through this API is drawn automatically in the Scene view, Game view, and Play mode with no opt-in required in-editor — controlled by Draw*-prefixed fields on PhysicsWorldDefinition (drawOptions picks which categories draw — bodies, shapes, joints, contacts, solver islands; drawColors sets per-category colors) and a per-shape customColor override on PhysicsShapeDefinition. To see this in an actual Player build (not just the Editor), the target platform must support compute shaders and the PhysicsLowLevelSettings2D asset must have "Draw In Build" enabled. Beyond the automatic draw, PhysicsWorld exposes immediate-mode manual draw calls — DrawLine, DrawCircle, DrawPoint, DrawGeometry — each taking an explicit Color and, optionally, a lifeTime (default one frame). On lifetime: every major object type (PhysicsWorld, PhysicsBody, PhysicsShape, PhysicsJoint, PhysicsChain) has an instance Destroy(), and destruction cascades — destroying a body destroys its attached shapes/chains/joints, destroying a world destroys everything in it. Calling Destroy() on an already-destroyed object logs a console error, so check isValid first when destruction order isn't guaranteed. Batch variants (CreateBodyBatch/DestroyBodyBatch, CreateShapeBatch/DestroyShapeBatch, DestroyJointBatch) exist for bulk work. SetOwner() returns a unique integer key that subsequent Destroy() calls must supply to succeed — documented explicitly as "a deterrent, not cryptographically secure" ownership protection, not a real security boundary.

Relationship to Classic Rigidbody2D/GameObject Workflow

This API and the classic Rigidbody2D/Collider2D component system are completely separate simulations that never interact — a PhysicsBody never collides with a Rigidbody2D, and there is no shared collision matrix (Manual/2d-physics-api/2d-physics-api-introduction.html: "The API doesn't interact with or affect the built-in Unity 2D physics components"). There are no built-in Inspector components in this system at all — every object is created directly from code, though a PhysicsBodyDefinition/PhysicsShapeDefinition field exposed as public on a MonoBehaviour does get an Inspector-editable struct view, giving back some of the classic component-editing convenience. Physics objects are not automatically tied to any GameObject or Transform — the sole bridge is PhysicsBody.transformObject (a Transform reference) combined with PhysicsBody.transformWriteMode (Off/Current/Interpolate/Extrapolate) and the world's own transformWriteMode (Off/Fast2D/Slow3D) — both must be non-Off for simulation results to actually be written onto a real Transform each step; Fast2D is cheaper but forces rotation onto a single axis (zeroing any other-axis/3D rotation), while Slow3D writes a full 3D rotation. A PhysicsWorld.TransformPlane (XY/XZ/ZY) setting controls which plane that 2D simulation gets remapped onto in 3D space — letting a Box2D-only, Vector2-internal simulation drive objects lying flat on the ground (XZ) or standing upright side-on (ZY), not just facing the camera. Because objects need no GameObject at all, this API is equally usable for fully headless/off-screen simulation (e.g. background particle-like physics, AI spatial reasoning) with nothing ever rendered.

Common Mistakes

Quick Reference

…(truncated)