Documentation

Unity Engine


User Manual

Script Reference

Unity Engine


PhysicsShape

A shape is attached to a body and defines an area to which two distinct types of behaviour are handled: Collision: Contacts between shapes produce a collision response on their respective bodies, assuming their body type is Dynamic. Trigger: Contacts between shapes do not produce a collision response, only the fact that they're overlapping is reported. An unlimited number of shapes can be attached to a single body, known as a compound body. A shape is automatically destroyed when the body it is attached to is destroyed. A shape cannot exist unattached from a body.
Read time 12 minutesLast updated 6 days ago

Definition

public readonly struct PhysicsShape : IEquatable<PhysicsShape>

Constructors

Constructor

Description

PhysicsShape(Unity.U2D.Physics.PhysicsHandle)Create a shape from a physics handle.

Properties

Property

Description

aabbGet the world AABB that bounds this shape. The bounds of the shape is inflated slightly due to speculative collision detection. The inflation is smaller on Static shape types however it is not zero due to time-of-impact collision detection. If an exact AABB is required then you can retrieve that via the shape geometry. See CircleGeometry.CalculateAABB, CapsuleGeometry.CalculateAABB, PolygonGeometry.CalculateAABB and SegmentGeometry.CalculateAABB.
bodyThe body which the shape is attached to.
bouncinessThe bounciness (coefficient of restitution) usually in the range [0, 1]. Values higher than 1 will result in energy being added which can lead to an unstable simulation. This is assigned to the current _surfaceMaterial.
bouncinessMixingDefines the method used when mixing the friction values of two shapes to form a contact. This is assigned to the current _surfaceMaterial.
bouncinessPriorityThe priority for combining the _bounciness properties when two shapes come into contact. If the priority of one shape is higher than the other shape then the higher priority _bouncinessMixing will be used. If the priority of both shapes are the same then simply the higher enumeration value of PhysicsMaterialCombine2D from both shapes will be used. This is assigned to the current _surfaceMaterial.
callbackTargetGet/Set the Object that callbacks for this shape will be sent to. Care should be taken with any Object assigned as a callback target that isn't a Object as this assignment will not in itself keep the object alive and can be garbage collected. To avoid this, you should have at least a single reference to the object in your code. To remove the object assigned here, set the callback target to NULL.
capsuleGeometryGet/Set the Capsule associated with this shape. When getting the shape geometry, the shape type must match the geometry type otherwise a warning will be produced and invalid geometry will be returned. Setting the geometry will change the type of shape represented even if the shape type was different before. Setting the geometry will also result in waking the body the shape is attached to.
chainGet the owning chain. The type of shape must be PhysicsShape.ShapeType.ChainSegment otherwise a warning will be produced. See _isChainSegment and PhysicsChain.
chainSegmentGeometryGet/Set the Chain Segment associated with this shape. When getting the shape geometry, the shape type must match the geometry type otherwise a warning will be produced and invalid geometry will be returned. Setting the geometry will change the type of shape represented even if the shape type was different before. Setting the geometry will also result in waking the body the shape is attached to.
circleGeometryGet/Set the Circle associated with this shape. When getting the shape geometry, the shape type must match the geometry type otherwise a warning will be produced and invalid geometry will be returned. Setting the geometry will change the type of shape represented even if the shape type was different before. Setting the geometry will result in waking the body the shape is attached to.
contactEventsControls whether this shape produces contact events which can be retrieved after the simulation has completed. Any contact events can be used to call the assigned _callbackTarget. A contact event is produced if either shapes involved have contactEvents enabled. A contact event will produce a PhysicsCallbacks.IContactCallback to the _callbackTarget for both shapes involved.
contactFilterThe filter used when determining what contacts this shape participates in.
contactFilterCallbacksControls whether this shape produces contact filter callbacks. A contact filter callback allows direct control over whether a contact will be created between a pair of shapes. This applies to both triggers and non-triggers but only with to Dynamic bodies These are relatively expensive so disabling them can provide a significant performance benefit. A contact filter callback will call the _callbackTarget for both shapes involved if they implement PhysicsCallbacks.IContactFilterCallback.
customColorCustom debug draw color. Any color value other than _clear (RGBA=0) will be used to render the shape.. This value is passed back when using the PhysicsWorld drawing. The alpha value here is always ignored. This is assigned to the current _surfaceMaterial.
definitionGet/Set a shape definition by accessing all of its current properties. This is provided as convenience only and should not be used when performance is important as all the properties defined in the definition are accessed sequentially. You should try to only use the specific properties you need rather than using this feature.
frictionThe Coulomb (dry) friction coefficient, usually in the range [0, 1]. This is assigned to the current _surfaceMaterial.
frictionMixingDefines the method used when mixing the friction values of two shapes to form a contact. This is assigned to the current _surfaceMaterial.
frictionPriorityThe priority for combining the _friction properties when two shapes come into contact. If the priority of one shape is higher than the other shape then the higher priority _frictionMixing will be used. If the priority of both shapes are the same then simply the higher enumeration value of PhysicsMaterialCombine2D from both shapes will be used. This is assigned to the current _surfaceMaterial.
hitEventsControls whether this shape produces hit events which can be retrieved after the simulation has completed.
isChainSegmentCheck if the shape is a Chain type. A Chain type is owned by a chain. See _chain and PhysicsChain.
isOwnedGet if the shape is owned. See PhysicsShape.SetOwner.
isTriggerGet/Set if the shape is a trigger. Changing the state here is relatively expensive and should be avoided. See _isTrigger.
isValidCheck if the shape is valid.
localCenterGet the center of the shape, in local-space.
massConfigurationThe shape mass configuration. Normally this only used on a body where the total of all shapes is used. This allows the calculation of this specific shape in isolation. See PhysicsBody.MassConfiguration.
moverDataThe mover data for the shape mover.
ownerUserDataGet PhysicsUserData that can be used for any purpose, typically by the owner only.
physicsHandleGet the physics handle.
polygonGeometryGet/Set the Polygon associated with this shape. When getting the shape geometry, the shape type must match the geometry type otherwise a warning will be produced and invalid geometry will be returned. Setting the geometry will change the type of shape represented even if the shape type was different before. Setting the geometry will also result in waking the body the shape is attached to.
preSolveCallbacksControls whether this shape produces pre-solve callbacks. This only applies to Dynamic bodies and is ignored for triggers. These are relatively expensive so disabling them can provide a significant performance benefit. A pre-solve callback will call the _callbackTarget for both shapes involved if they implement PhysicsCallbacks.IPreSolveCallback.
rollingResistanceThe rolling resistance usually in the range [0, 1]. This is assigned to the current _surfaceMaterial.
segmentGeometryGet/Set the Segment associated with this shape. When getting the shape geometry, the shape type must match the geometry type otherwise a warning will be produced and invalid geometry will be returned. Setting the geometry will change the type of shape represented even if the shape type was different before. Setting the geometry will also result in waking the body the shape is attached to.
shapeTypeThe type of shape. See PhysicsShape.ShapeType.
startMassUpdateShould the body update its mass properties when this shape is created. Disabling this improves performance when multiple shapes are being added to the same body. The mass of a body can then be explicitly updated by calling PhysicsBody.ApplyMassFromShapes
startStaticContactsNormally shapes on Static bodies don't create contacts when they are added to the world. This overrides that behavior and causes contact creation. This significantly slows down Static body creation which can be important when there are many Static shapes. This is implicitly always true for Triggers, Dynamic bodies and Kinematic bodies.
surfaceMaterialThe surface material for the shape comprising of many properties such as friction, bounciness, rolling resistance etc. Setting the surface material overrides any individual settings for friction, bounciness, rolling resistance etc.
tangentSpeedThe tangent (surface) speed. This is assigned to the current _surfaceMaterial.
transformGet the shape transform. This is simply the body transform. See _transform.
triggerEventsControls whether this shape produces triggers events which can be retrieved after the simulation has completed. A trigger event is only produced if both shapes involved have their triggerEvents enabled. A trigger event will produce a PhysicsCallbacks.ITriggerCallback to the _callbackTarget for both shapes involved.
userDataGet/Set PhysicsUserData that can be used for any purpose. The physics system doesn't use this data, it is entirely for custom use.
worldGet the world the shape is attached to.
worldDrawingControls whether this shape is automatically drawn when the world is drawn.

Methods

Method

Description

ApplyWindApply a wind force to the shape body using the density of air This considers the projected area of the shape in the wind direction. This also considers the relative velocity of the shape. This only has an effect if the shape body is RigidbodyType2D.Dynamic. This only has an effect of shapes of type Circle, Capsule or Polygon.
CastRayCheck if a ray intersects the shape. See PhysicsQuery.CastResult.
CastShapeCalculate if a cast shape intersects the shape. Initially touching shapes are treated as a miss. You should check for overlap first if initial overlap is required. See PhysicsQuery.CastShapeInput and PhysicsQuery.CastResult.
ClosestPointCalculate the closest point on this shape to the specified point.
CreateShapeProxyCreate a shape proxy from the shape.
DestroyDestroy the shape, destroying all PhysicsShape.Contact the shape is involved in. If the object is owned with PhysicsShape.SetOwner then you must provide the owner key it returned. Failing to do so will return a warning and the shape will not be destroyed. The lifetime of the specified owner object is not linked to this shape i.e. this shape will still be owned by the owner object, even if it is destroyed. Shapes of type Chain cannot be destroyed here, they must be destroyed by their owning chain. See PhysicsChain and PhysicsBody.MassConfiguration.
DistanceGet the minimum distance between this shape and the specified shape(s) span.
DrawDraw the PhysicsShape that visually represents its current state in the world.
GetContactsGet all the touching contacts this shape is currently participating in.
GetDensityGet the shape density. See _massConfiguration.
GetOwnerGet the owner object associated with this shape as specified using PhysicsShape.SetOwner.
GetPerimeterGet the length of the perimeter of the shape.
GetPerimeterProjectedGet the length of the perimeter of the shape projected onto the specified axis.
GetTriggerVisitorsGet all the trigger visitors for this shape. The shape must be a trigger, if not, no visitors will be returned.
IntersectCheck the intersection between this shape and another shape.
OverlapPointCheck if a point intersects the shape. This will only work on "closed" shapes. SeePhysicsShape.ShapeType.
SetDensitySet the shape density. See _massConfiguration.
SetOwnerSet the owner object using the specified owner key. You can only set the owner once, multiple attempts will produce a warning. This call does not bind the lifetime of the specified owner object, it is simply a reference. It is also valid to not specify an owner object (NULL) to simply gain an owner key however it can be useful, if simply for debugging purposes and discovery, to know which object is the owner.
SetOwnerUserDataSet PhysicsUserData that can be used for any purpose, typically by the owner only.

Static Methods

Method

Description

CreateShapeCreate a Capsule shape, using its default definition, attached to the specified body. See PhysicsBody.CreateShape.
CreateShapeBatchCreate a batch of Capsule shapes attached to the specified body.
DestroyBatchDestroy a batch of shapes, destroying all PhysicsShape.Contact the shapes are involved in. Any invalid shapes will be ignored including chain segment shapes created via a PhysicsChain (the chain must be destroyed)." Owned shapes will produce a warning and will not be destroyed (See PhysicsShape.SetOwner). See PhysicsBody.MassConfiguration.
SetOwnerSet the owner object using the specified owner key. You can only set the owner once, multiple attempts will produce a warning. This call does not bind the lifetime of the specified owner object, it is simply a reference. Whilst it is valid to not specify an owner object (NULL), it is recommended for debugging purposes.

Structs

Struct

Description

PhysicsShape.ContactThe contact between two shapes. By convention the manifold normal points from shape A to shape B. See PhysicsBody.GetContacts and PhysicsShape.GetContacts.
PhysicsShape.ContactFilterA contact filter is used to control what contacts are created when intersecting other shapes. A contact filter contains a filter with the addition of a group index allowing overrides to the filter.
PhysicsShape.ContactIdThe unique Id of the contact. This contact is volatile and may be destroyed automatically when the world is modified or simulated therefore it should always be checked for validity.
PhysicsShape.ContactManifoldA contact manifold describes the contact points between colliding shapes. Speculative collision is used so some contact points may be separated, a property available per-contact.
PhysicsShape.MoverCollisionCollision results optionally returned from PhysicsWorld.CastMover in PhysicsQuery.WorldMoverResult.
PhysicsShape.MoverDataThe mover data assigned to a _moverData. This is used when PhysicsShape are encountered when using PhysicsWorld.CastMover.
PhysicsShape.ShapeArrayFixed vertex shape array.
PhysicsShape.ShapeProxyA proxy of a shape in a generic form suited to representing all support shape types. You can provide between 1 and PhysicsConstants.MaxPolygonVerticesand a radius.
PhysicsShape.SurfaceMaterialDefines the dynamics of a surface on a shape.

Enums

Enum

Description

PhysicsShape.ContactFilterGroupModeThe mode used to determine how _groupIndex is used.
PhysicsShape.ContactFilterModeThe mode used for the PhysicsShape.ContactFilter when determining if two PhysicsShape can contact. See _contactFilterMode.
PhysicsShape.ShapeTypeThe type of shape. Some shapes are "closed" meaning they have an interior which will produce contacts. Some shapes are "open" meaning they do not have an interior and will only produce contacts when their boundary is intersected.