DOCS

Rigidbody Physics

There are different kinds of physics bodies you can create in 3dverse: static body, rigid body, and kinematic rigid body. Note that these bodies are all rigid bodies in the classical sense, in that they stay solid and do not deform during collision. The main difference between the static body and rigid body is that the former is static (expected not to move) during simulation whereas the latter is dynamic (expected to move). Each of these physics bodies require you to attach some kind of geometry to them which will define their geometry in the physics engine. Remember that the physics engine only “sees” these geometries, and will detect collision of your physics bodies by checking for overlap between these geometries.

Physics bodies

Every physics body must have a physics material component and some sort of geometry component.

Static body

When to use a static body?

For an entity that will not move during simulation such as a wall, the ground, or a building.

A static body will not be affected by forces such as gravity.

To make your entity a static body it needs the following components:

  • physics material
  • One geometry component from this list: box geometry, capsule geometry, sphere geometry, cylinder geometry, plane geometry or collision geometry reference

Rigid body

When to use a rigid body?

For an entity that that you want to be affected by forces such as gravity. Collision resolution of rigid bodies is made to seem very “physically accurate”.

A rigid body will collide against all other physics bodies.

To make your entity a rigid body it needs the following components:

  • physics material
  • one geometry component from this list: box geometry, capsule geometry, sphere geometry, cylinder geometry or collision geometry reference (but the collision geometry must be convex, NOT triangular)
  • rigid body (with isKinematic = false)

Fun fact: in real-world physics, a rigid body is any physical body that does not deform or change shape under physics forces. The distance between any two given points of a rigid body remains constant in time, regardless of external forces exerted on it.

Kinematic Rigid body

When to use a kinematic rigid body?

For an entity that you want to move manually during simulation (e.g. by affecting its transform), such as a rotating door. A kinematic rigid body will not be affected by any forces such as gravity.

If you move a kinematic rigid body it will collide against rigid bodies, but not against static or kinematic rigid bodies (i.e. if you move it into a static body or another kinematic rigid body, it will go through, but if you move it into a rigid body, this will move your rigid body).

To make your entity a kinematic rigid body it needs the following components:

  • physics material
  • one geometry component from this list: box geometry, capsule geometry, sphere geometry, cylinder geometry, plane geometry or collision geometry reference
  • rigid body (with isKinematic = true)

Physics material

As you can see above, every physics body must have a physics material component. The values set in this component help determine how the physics body will react during collision. More specifically, when a physics body collides with another the average of their physics material values (e.g. static friction, dynamic friction, restitution) will be used to resolve the collision.

Static FrictionThe friction coefficient applied between this surface and another surface if they are not moving lateral to each other. Usually a value from 0 to 1. A value of zero feels like ice, a value of 1 will make it very hard to get the object moving.
Dynamic FrictionThe friction coefficient applied between this surface and another surface if they are moving relative to each other. Usually a value from 0 to 1. A value of zero feels like ice, a value of 1 will make it very hard to get the object moving. If set to greater than staticFriction, the effective value of staticFriction will be increased to match.
RestitutionRestitution coefficient, or bounciness of surface. A coefficient of 0 indicates as little bounce as possible, higher values up to 1.0 result in more bounce. Should be in the range [0,1].
Contact VelocitySee Advanced.
Modify ContactSee Advanced.
Is TriggerSee Trigger.

Physics geometries

The geometry of your physics body can be a box, a plane, a sphere, a capsule, a cylinder, or a collision geometry. To add one to your entity, add its corresponding geometry component (i.e. box geometry, sphere geometry, etc). To make sure the attributes of these geometries are well set up, enable debug lines.

Box

Compatible with: static body, rigid body, kinematic rigid body, character controller

DimensionLength, height, width of your box (in local space, not affected by scale)
OffsetOffset of box (in local space, not affected by scale). This is useful if you need to offset the box’s position relative to your mesh. Origin is center of box.

Plane

Compatible with: static body, kinematic rigid body

DistanceDistance from world space origin
NormalPlane normal

Planes divide space into "above" and "below" them. Everything "below" the plane will collide with it.

Sphere

Compatible with: static body, rigid body, kinematic rigid body

RadiusRadius of sphere
OffsetOffset of sphere (in local space, not affected by scale). Origin is center of sphere.

Cylinder

Compatible with: static body, rigid body, kinematic rigid body

AxisAxis that the cylinder is aligned against. 0 for X, 1 for Y, 2 for Z.
RadiusRadius of cylinder
HeightHeight of cylinder
OffsetOffset of cylinder (in local space, not affected by scale). Origin is center of cylinder.

Capsule

Compatible with: static body, rigid body, kinematic rigid body, character controller

AxisAxis that the capsule is aligned against. 0 for X, 1 for Y, 2 for Z. The capsule depicted below is aligned against X axis (so would have axis = 0).
RadiusSee below
HeightSee below
OffsetOffset of capsule (in local space, not affected by scale). Origin is center of capsule.

Collision Geometry

Compatible with: See below

ValueUUID of collision geometry asset

If you want to use a triangular mesh or a convex mesh as a geometry for your physics body, you need to create a collision geometry. A collision geometry is an asset that you can create from a mesh you provide it.

There are two types of collision geometry:

  • Convex
    • This is a convex mesh, that will encapsulate all the points of your mesh. A mesh is convex if, given any two points within it, the mesh contains the line between them.
    • Compatible with: static body, rigid body, kinematic rigid body
  • Triangular
    • This is a triangular mesh, that will encapsulate all the points of your mesh. It will wrap as closely to the original mesh you provide as possible.
    • Compatible with: static body, kinematic rigid body

[object Object]

[object Object]

Between the two, the convex collision geometry is the recommended default choice. A convex collision geometry is less computationally heavy as it contains less vertices than the triangular collision geometry. Also, triangular collision geometries cannot be assigned to rigid bodies.

To create a collision geometry, right click on an entity with a mesh reference component in your scene graph and select “Create convex collision geometry” or “Create triangular collision geometry”.

Once the collision geometry is created, your entity will be automatically assigned a collision geometry reference component and the collision geometry will be attached to it.

Trigger

A trigger physics body is a physics body with isTrigger set to true in its physics material component.

When to use a trigger?

Make your physics body a trigger if you want to be notified of and react to collisions in your application code that involve that trigger body. Trigger bodies do not have any collision resolution though, they are simply collision “sensors”.

Trigger bodies are used for triggering events, and whatever collision that may occur with them is detected, but not resolved by the physics engine. Triggers are very useful in games! A trigger event will allow your application code to react to two entities colliding and apply some logic to that. See Physics-Based Events for more info on trigger events.

More info

The recommendations of “when to use” each physics body are best practices. For example, a static body is recommended for a non-moving entity. Although you probably shouldn’t, don’t be surprised if you can actually move a static body during simulation by changing its transform. However, collision detection may not work as well and you may get unexpected results because of the way the physics engine is optimized. So it’s important to configure your physics bodies correctly and follow the recommendations outlined in this doc.

Previous
Intro to Physics