Unity Physics2D Settings Notes

8 minute read

When building a game in Unity it is important to configure the physics settings for the particular game that is being made. The games we are making are 2D games, so we have been tweaking the configuration of the Physics2D settings. These settings are available in the menu from Edit -> Project Settings -> Physics 2D. In playing with these setting, we have found that their descriptions can be confusing.

Below are some notes on how we have found these settings to work. At the time of this writing we are working with Unity 2018.1 so the settings match what is available there.


Gravity

We are not using gravity in our game, but this one is pretty straight forward. It allows configuring gravity on the x and y axes for 2D games. If gravity is being applied to an object with a RigidBody2D, then this amount of acceleration will be applied to the object via the physics system.


Default Material

This is another straight forward one; if no physics2d material is selected on a collider, then the material configured here will be used by default. See the Unity documentation for more information on Physics Material 2D.


Velocity Iterations

This is the first setting that is not clear. The Unity documentation explains that increasing the number will make the physics more accurate, but will require more CPU time. What does it actually mean for the physics to be more accurate? Will this increase accuracy in a different way from the Position Iterations setting below, which has a similar description?

This setting directly translates to a corresponding setting in the underlying 2D physics engine Box2D. The Box2D documentation also does not make it clear. Looking through the source code I can see that there is a for loop that iterates a number of times equal to the value of this setting. Within this for loop it calls a couple different SolveVelocityConstraints functions involves joints and a contactSolver. It seems like each call to these methods theoretically improves the accuracy of the calculation.

The Box2D code contains some comments talking about several algorithms that can be used. It appears they are using iterative methods of solving a linear system of equations. As these algorithms are iterative, each iteration reduces the margin of error up to a point. I still can’t say precisely what this setting does. The Unity description is accurate, though increasing this value will result in more accurate physics calculations regarding the velocity of objects in the physics simulation. Finding the best value to use will likely require some experimentation and tweaking, and is likely different for different games.


Position Iterations

Like Velocity Iterations this setting is not clear. The Unity documentation contains almost the exact same wording as Velocity Iterations except with the word velocity replaced with position. Increasing this value will make the physics more accurate, but will require more CPU time.

Similarly to Velocity Iterations, this setting directly translates to a corresponding setting in the underlying 2D physics engine Box2D. Again looking through the source code I can see that there is a for loop that iterates a number of times equal to the value of this setting. Within this for loop it calls a couple different SolvePositionConstraints functions involves joints and a contactSolver. It seems like each call to these methods theoretically improves the accuracy of the calculation.

The Box2D code contains some comments talking about several algorithms that can be used. It appears they are using iterative methods of solving a linear system of equations. As these algorithms are iterative, each iteration reduces the margin of error up to a point. I still can’t say precisely what this setting does. The Unity description is accurate, though increasing this value will result in more accurate physics calculations regarding the position of objects in the physics simulation. Finding the best value to use will likely require some experimentation and tweaking, and is likely different for different games.


Velocity Threshold

This setting is pretty straightforward. Two objects that collide with a velocity, relative to each other, lower than this value will not bounce off of each other.


Max Linear Correction

The Unity documentation indicates that this value can be used to prevent overshoot.

This setting maps to a corresponding setting in the underlying 2D physics engine Box2D. Box2D uses this value to clamp a correction value for the position angle as part of the iterative solver algorithm. The correction value is also used to exit the iterative algorithm early when the error is below a small threshold. Increasing the value of this setting may result in increased CPU time by preventing the iterative solver algorithm from exiting early.


Max Angular Correction

Like Max Linear Correction, the Unity documentation indicates that this value is used to prevent overshoot.

Again, this setting maps to a corresponding setting in the underlying 2D physics engine Box2D. The Box2D code uses this value to clamp a correction value for the position angle as part of the iterative solver algorithm. The correction value is also used to exit the iterative algorithm early when the error is below a small threshold. Increasing the value of this setting may result in increased CPU time by preventing the iterative solver algorithm from exiting early.


Max Translation Speed

This setting puts a cap on the maximum distance an object can move in a single physics tick. This maps to a corresponding setting in the underlying 2D physics engine Box2D. Even though it is exposed by Unity, the Box2D code contains comments indicating it probably should not be changed.


Max Rotation Speed

This setting puts a cap on the maximum rotation distance an object can move in a single physics tick. This maps to a corresponding setting in the underlying 2D physics engine Box2D. Even though it is exposed by Unity, the Box2D code contains comments indicating it probably should not be changed.


Baumgarte Scale

This setting corresponds to a setting in the underlying 2D physics engine Box2D. Both the Unity documentation and the Box2D documentation do not provide a clear picture of what this setting does. Baumgarte is an algorithm for solving overlaps. The documentation indicates that a value of 1 would allow solving the overlaps in a single physics tick, but that it often produces overshoot. Both Unity and Box2D use a default value of 0.2 and it seems like this value is best left at the default.


Baumgarte Time of Impact Scale

This setting corresponds to a setting in the underlying 2D physics engine Box2D. This setting seems to pair with the Baumgarte Scale setting, and both the Unity documentation and the Box2D documentation do not provide a clear picture of what this setting does. The documentation indicates that a value of 1 would allow solving the overlaps in a single physics tick, but that it often produces overshoot. Both Unity and Box2D use a default value of 0.75 and it seems like this value is best left at the default.


Time to Sleep

This setting configures the time (in seconds) that a RigidBody2D must be stationary before it goes to sleep. When a RigidBody2D is sleeping it does not use any CPU cycles until it is woken up by a collision or force being applied to it.


Linear Sleep Tolerance

This setting works together with the time to sleep setting. A RigidBody2D will not be considered stationary unless its linear velocity is lower than the value of this setting.


Angular Sleep Tolerance

This setting works together with the time to sleep setting. A RigidBody2D will not be considered stationary unless its angular velocity is lower than the value of this setting.


Default Contact Offset

This setting configures the default contact offset value for colliders. Two colliders will result in a collision if the distance between them is less than the sum of their contact offsets.

For 2D physics it appears that the configured default value is always used for colliders. For 3D physics the collider contact offset can be changed on individual colliders via the Collider.contactOffset property; a corresponding property for Collider2D does not exist at the time of this writing.


Auto Simulation

When this setting is enabled, the physics simulation is automatically updated. If this setting is disabled, then the physics simulation will need to be manually updated by calling Physics2d.Simulate(float) where the float step value should be a framerate independent value. Disabling this setting will not prevent MonoBehaviour.FixedUpdate from running.


Queries Hit Triggers

When this setting is enabled, raycasts (and other cast types) will hit triggers. If this setting is disabled, casts will not hit triggers.


Queries Start in Colliders

We originally thought this meant that queries (e.g. raycasts, boxcasts, etc.) would not “hit” the collider they start from. It turns out it actually depends on the cast. If the cast is happening directly from a collider (e.g. Collider2D.Cast variants), then the collider will not be detected as a hit regardless of how this setting is configured.

This setting is primarily for detecting hits with colliders that are part of other game objects. If object A overlaps with the collider of object B and object A performs a cast, then whether B is detected as a hit or not by the cast depends on how this setting is configured. If it is checked, then B is detected as a hit. If it is unchecked then B is ignored by the cast.


Change Stops Callbacks

When this setting is enabled, a change in an object involved in a collision (e.g. object deleted, moved, etc.) will cause the remaining callbacks to be stopped. If this setting is disabled, then all callbacks will be fired even when a change occurs to an object involved in a collision.


Callbacks on Disable

When this setting is enabled, disabling a collider that is currently taking part in a collision will result in the OnCollisionExit2D or OnTriggerExit2D callbacks being fired. If this setting is disabled, then disabling a collider will not result on the exit callbacks firing.


Auto Sync Transforms

When this setting is enabled, changes made directly to an object’s transform will be automatically synced with the physics system. If this setting is disabled, the transform changes must be manually synced to the physics system, but it is not clear how exactly this is accomplished – possibly by also adjusting colliders and rigidbodies associated with the object containing the moved transform.