Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

Physics Simulation Definition asset reference

Explore the properties you can use to configure a Physics Simulation Definition asset in the Unity Editor.
Read time 9 minutesLast updated 14 days ago
Note
This documentation is about using Pose, Area, and Constraint components. 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 Simulation Definition asset in the Unity Editor. A Physics Simulation Definition asset wraps a 
PhysicsWorldDefinition
 object, which sets the properties of a physics world, such as gravity. For more information, refer to Create multiple simulation worlds with 2D Physics Core.

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.
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.
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 Run 2D physics in 3D space with 2D Physics Core.
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 tunneling through static bodies. For more information, refer to Configure collisions between 2D Physics Core objects.
Event Grouping AllowedTriggers contact and trigger events only when the first or last shape in a group makes contact with another shape. Enabling this property reduces the number of contact events, but might reduce performance.
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. This property applies only to dynamic objects. Disabling this property can improve performance.
Pre Solve CallbacksEnables physics objects optionally calling the 
OnPreSolve2D
 method of a dynamic object before Unity calculates the collision response, so you can run your own code. This property applies only to dynamic objects. Disabling this property can improve performance.
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 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.
Contact Recycle DistanceSets the distance in meters that two shapes can move relative to each other before Unity recalculates their contact point instead of reusing it. Set this property to 0 to disable reusing contact points. Reusing contact points improves stability and performance, but Unity skips some updates, such as friction, until the contact is no longer recycled.
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: Doesn't draw any bodies, shapes, joints, or collisions.
  • 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 Forces: Draws the amount of force applied at contact points.
  • All Contact Friction: Draws the friction forces at contact points.
  • All Custom: Draws custom drawings you add.
  • 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 Visualize and edit 2D Physics Core scenes.
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 Contact TypeSets which point of a contact Unity draws when Draw Options includes contact points. The options are:
  • Point: Draws the actual contact point.
  • Anchor A: Draws the contact point of the first shape in the contact.
  • Anchor B: Draws the contact point of the second shape in the contact.
  • Average: Draws the position halfway between Anchor A and Anchor B. This is the default.
Draw FilterDisables Unity drawing specific types of bodies and shapes.
Draw TargetSets which Editor views Unity draws the world into. The options are:
  • Both: Draws the world in the Scene view and the Game view. This is the default.
  • Scene View: Draws the world only in the Scene view.
  • Game View: Draws the world only in the Game view.
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 OrderSets the relative order Unity draws this world. Unity draws worlds with a lower value first, so worlds with a higher value draw on top.
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.

Capacity

The properties in this section affect the amount of internal memory Unity uses to create a world.
If you leave these properties at zero, Unity uses its own minimum defaults.

Property

Description

Static Shape CountSets the number of static shapes you expect to create in the world.
Dynamic Shape CountSets the number of dynamic and kinematic shapes you expect to create in the world.
Static Body CountSets the number of static bodies you expect to create in the world.
Dynamic Body CountSets the number of dynamic and kinematic bodies you expect to create in the world.
Contact CountSets the number of contacts you expect in the world.

Additional resources