Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

World definition reference for the Physics Core 2D API

Explore the properties you can use to configure a physics world in the Unity Editor.
Read time 7 minutesLast updated 12 days ago
Note
This documentation is about writing C# scripts using the 
Unity.U2D.Physics
API. To use 2D physics in the Unity Editor using components like the Rigidbody 2D component, refer to 2D physics instead.
Explore the properties you can use to configure a physics world in the Unity Editor, if you create a public 
PhysicsWorldDefinition
object. For more information, refer to Create a world with the Physics Core 2D API.

Property

Description

GravitySets the gravity Unity applies to all the bodies in the world. The default is -9.81 on the y-axis, which simulates Earth's gravity.
Simulation TypeSets when the physics simulation runs. The options are:
  • Fixed Update: Runs the simulation automatically during the 
    FixedUpdate
    event stage.
  • Update: Runs the simulation automatically during the 
    Update
    event stage.
  • Script: The simulation runs only when you call 
    PhysicsWorld.Simulate
    .
For more information, refer to Event functions.
Simulation Sub StepsSets the number of times the physics simulation runs per step to calculate stable values. If your world includes a complex set of joints, increasing this value can improve performance. The default is 4.
Simulation WorkersSets the number of threads the simulation uses. The default is 64. The number of threads might be limited by the number of available CPU cores on the device.
Transform Write ModeSets the method Unity uses to copy the position of the physics body to the Transform component on the GameObject. The options are:
  • Off: Doesn't copy the position or rotation.
  • Fast 2D: Copies the position and one rotational axis, so any 3D rotations are ignored. This is the default.
  • Slow 3D: Copies the position and the full 3D rotation.
  • Custom: Calls the callback you set using 
    PhysicsWorld.transformWriteCallbackTarget
    , so you can write custom code.
For more information, refer to Move a GameObject.
Transform Tween ModeInterpolates or extrapolates the positions of physics bodies between simulation updates, and writes their positions to Transform components. The options are:
  • Off: Doesn't interpolate or extrapolate positions.
  • Parallel: Interpolates or extrapolates positions on parallel threads using the job system.
  • Sequential: Interpolates or extrapolates positions on a single thread. This option might be faster than Parallel if you have a small number of Transform components in a simple hierarchy.
  • Custom: Calls the callback you set using 
    PhysicsWorld.transformWriteCallbackTarget
    , so you can write custom tweening code.
This property has no effect if you disable Transform Write Mode. For more information, refer to Move a GameObject.
Transform PlaneDetermines which 3D space to convert the final 2D positions to. The options are:
  • XY: The x-axis remains horizontal and the y-axis remains vertical, so that the world faces the camera in 3D space. This is the default.
  • XZ: The x-axis remains horizontal but the y-axis becomes depth, so that the world lies flat in 3D space.
  • ZY: The x-axis becomes depth but the y-axis remains vertical, so that the world stands upright in 3D space.
  • Custom: Uses the custom plane you set in the Transform Plane Custom parameter. For more information, refer to the Transform Plane Custom section.
For more information, refer to Use 2D physics in 3D space using the Physics Core 2D API.
Sync InterpolationAvoids interpolated positions becoming out of sync between the physics body and the Transform component. Enabling this property adds an extra pass to write the interpolated position, which can reduce performance. This property only affects bodies that have Transform Write Mode set to Interpolate.
Sleeping AllowedRemoves bodies from physics calculations when they move at a slower speed than their Sleep Threshold value, to save processor time. When a sleeping body receives a collision or force, Unity wakes up the body and continues to include it in physics calculations. The recommended best practice is to leave this property enabled.
Continuous AllowedEnables continuous collision detection to prevent moving bodies tunnelling through static bodies. For more information, refer to Configure collisions between Physics Core 2D API objects.
Contact Filter CallbacksEnables physics objects optionally calling the 
IContactFilterCallback
method of a shape if it makes contact with another shape, so you can run your own code that determines whether the shapes should collide.
Pre Solve CallbacksEnables physics objects optionally calling the 
OnPreSolve2D
method of a dynamic body before Unity calculates the collision response, so you can run your own code.
Auto Body Update CallbacksEnables physics objects optionally calling the 
IBodyUpdateCallback
method of a body if it's updated, so you can run your own code.
Auto Contact CallbacksEnables physics objects optionally calling the 
OnContactBegin2D
and 
OnContactEnd2D
methods of a shape if it makes contact with another shape, so you can run your own code. For more information, refer to Detect collisions between Physics Core 2D API objects
Auto Trigger CallbacksEnables physics objects optionally calling the 
OnTriggerBegin2D
and 
OnTriggerEnd2D
methods of a shape if it makes contact with another shape, so you can run your own code. For more information, refer to Detect collisions between Physics Core 2D API objects.
Auto Joint Threshold CallbacksEnables physics objects optionally calling the 
OnJointThreshold2D
method of a joint if it exceeds its Force Threshold or Torque Threshold value.
Bounce ThresholdSets the collision velocity in meters per second that causes objects to bounce. Avoid very small values, otherwise Unity can't put bodies to sleep to reduce CPU time.
Contact Hit Event ThresholdSets the relative speed in meters per second that two shapes must reach to generate a contact hit event.
Contact FrequencySets the stiffness of how objects respond to contact in Hertz (cycles per second). A lower value makes contact softer and spongier. A higher value makes contact harder and more rigid.
Contact DampingSets how quickly objects absorb the shock of a collision. A lower value makes objects less likely to settle after a collision. A higher value makes objects settle more quickly. The default value is 10.
Contact SpeedSets the speed Unity can push overlapping objects apart to separate them, in meters per second. The default value is 3.
Maximum Linear SpeedSets the maximum speed of objects in the world, in meters per second.
Draw OptionsDetermines which bodies, shapes, joints, and collisions Unity draws. The options are:
  • Off
  • Selected Bodies: Draws the bodies attached to GameObjects you select in the Hierarchy window.
  • Selected Shapes: Draws the shapes attached to GameObjects you select in the Hierarchy window.
  • Selected Shape Bounds: Draws the bounds of shapes attached to GameObjects you select in the Hierarchy window.
  • Selected Joints: Draws the joints attached to GameObjects you select in the Hierarchy window.
  • All Bodies: Draws all bodies.
  • All Shapes: Draws all shapes.
  • All Shape Bounds: Draws the bounds of all shapes.
  • All Joints: Draws all joints.
  • All Contact Points: Draws the points where shapes touch.
  • All Contact Normal: Draws the direction that force is applied at contact points.
  • All Contact Impulse: Draws the amount of force applied at contact points.
  • All Contact Friction: Draws the friction forces at contact points.
  • All Solver Islands: Draws groups of connected bodies and joints.
  • Default Selected: Draws the physics objects attached to GameObjects you select in the Hierarchy window.
  • Default All: Draws everything.
For more information, refer to Draw a debug visualization of objects.
Draw Fill OptionsDefines which parts of shapes Unity draws. The options are:
  • Interior: Draws the interior of the shape.
  • Outline: Draws the outline of the shape.
  • Orientation: Draws a line that represents the orientation of the shape.
Draw FilterDisables Unity drawing specific types of bodies and shapes.
Draw ThicknessSets the thickness of the lines Unity draws in pixels.
Draw Fill AlphaSets the transparency of the color Unity uses to fill shapes. Accepted values range from 0 to 1. This property has no effect if you disable Outline in Draw Fill Options.
Draw Point ScaleSets the size of the points that Unity draws.
Draw Normal ScaleSets the size of the contact normals for joints that Unity draws.
Draw Force ScaleSets the size of the contact forces for joints that Unity draws.
Draw ColorsSets the different colors Unity uses to draw each element.

Transform Plane Custom

These properties only have an effect if you set Transform Plane to Custom.

Property

Description

TranslateSets the position of the plane in 3D space.
RotateSets the rotation of the plane in 3D space.
ScaleScales the plane.

Additional resources