collider_creation_and_insertion

A collider is created by a ColliderBuilder that is based on the builder pattern: it is returned by one of the shape constructors of the Collider class (e.g. Collider.ball, Collider.cuboid, or Collider.new which takes any SharedShape), each of its methods returns a builder with the corresponding property set, and its build method returns the Collider. These properties can also be given as keyword arguments of the shape constructors, e.g., Collider.ball(0.5, density=2.0, friction=0.3). Then it needs to be inserted into the physics world with PhysicsWorld.add_collider, which attaches it to the rigid-body given as its optional parent argument, and returns the ColliderHandle identifying the new collider. Colliders can also be inserted together with the rigid-body they are attached to with the colliders argument of PhysicsWorld.add_body. Once inserted, the collider is accessed with world.colliders[handle], which returns a live view: assigning one of its properties modifies the collider of the physics world directly.

info

The following example shows several setters that can be called to customize the collider being built. The input values are just random so using this example as-is will not lead to a useful result.

import math

import rapier3d as rp

# The world that will contain our colliders.
world = rp.PhysicsWorld()

# Builder for a ball-shaped collider.
_ = rp.Collider.ball(0.5)
# Builder for a cuboid-shaped collider.
_ = rp.Collider.cuboid(0.5, 0.2, 0.1)
# Builder for a capsule-shaped collider. The capsule principal axis is the `x` coordinate axis.
_ = rp.Collider.capsule_x(0.5, 0.2)
# Builder for a capsule-shaped collider. The capsule principal axis is the `y` coordinate axis.
_ = rp.Collider.capsule_y(0.5, 0.2)
# Builder for a capsule-shaped collider. The capsule principal axis is the `z` coordinate axis.
_ = rp.Collider.capsule_z(0.5, 0.2)
# Builder for a triangle-mesh-shaped collider.
_ = rp.Collider.trimesh(vertices, indices)
# Builder for a heightfield-shaped collider.
_ = rp.Collider.heightfield(heights, scale)
# Builder for a collider with the given shape.
collider = (
    rp.Collider.new(rp.SharedShape.ball(0.5))
    # The collider translation wrt. the body it is attached to.
    # Default: the zero vector.
    .translation((1.0, 2.0, 3.0))
    # The collider rotation wrt. the body it is attached to, as a rotation vector (axis * angle).
    # Default: the identity rotation.
    .rotation((0.0, math.pi, 0.0))
    # The collider position wrt. the body it is attached to.
    # Default: the identity isometry.
    .position(rp.Isometry3((1.0, 2.0, 3.0), rp.Rotation3.from_scaled_axis((0.0, math.pi, 0.0))))
    # The collider density. If non-zero the collider's mass and angular inertia will be added
    # to the inertial properties of the body it is attached to.
    # Default: 1.0
    .density(1.3)
    # The friction coefficient of this collider.
    # Default: 0.5
    .friction(0.8)
    # Whether this collider is a sensor.
    # Default: False
    .sensor(True)
    # All done, actually build the collider.
    .build()
)

# Insert the collider into the world, without attaching it to a rigid-body.
collider_handle = world.add_collider(collider)

rigid_body_handle = world.add_body(rp.RigidBody.dynamic())
# Or insert the collider into the world and attach it to a rigid-body.
handle = world.add_collider(collider, parent=rigid_body_handle)

A collider can also be disabled, with ColliderBuilder.enabled(False) or, after its creation, by setting its is_enabled property to False. A disabled collider is excluded from all the collision-detection and physics until it is enabled again, which is useful to "turn off" a collider temporarily without removing it (a collider is removed from the world with PhysicsWorld.remove_collider).