pid_controller

It is generally not recommended to move a rigid-body by setting its pose directly: teleporting it would ignore every obstacle on the way. The recommended alternative is generally to push it with a force (or an impulse) that is strong enough to reach the target. However, pushing with a single constant force/impulse will generally overshoot the target. Thus, ideally, the force or impulse should be carefully selected and updated each frame as the rigid-body gets closer to its target.

This is what a PID controller (Proportional-Integral-Derivative) is designed to calculate: given the target pose, it computes the ideal velocity change bringing the body closer to it. This is the building block of the velocity-based character controllers, but it is useful for anything that must follow a target without being teleported: a dynamic moving platform, an object held by the player, a following camera, etc.

info

The gains of the controller are what makes it reach its target quickly or smoothly. The proportional gain is applied to the position errors and is usually set to a multiple of the inverse of the timestep length (e.g. $60$ for a timestep of $1 / 60$ seconds). The derivative gain is applied to the velocity errors and is usually set in $[0, 1]$, where $0$ means no damping and $1$ means that the velocity errors are corrected within a single timestep.

The PID controller is the PidController class. It is created with a proportional gain of $60$, an integral gain of $1$, and a derivative gain of $0.8$, on every coordinate axis (all of them being controlled), unless other gains are given to the Kp, Ki, and Kd arguments of its constructor (either a single float for every linear and angular coordinate axis, or one gain per coordinate axis). They can be read and modified afterwards, per coordinate axis, with its lin_kp, ang_kp, lin_ki, ang_ki, lin_kd, and ang_kd properties (each one is a Vec3, and can be set from a vector or from a single float for every axis). At each frame, PidController.rigid_body_correction computes the velocity correction (a PidCorrection, with its linear and angular parts) bringing a rigid-body closer to its target pose (and to its target velocities, given as an optional RigidBodyVelocity to its target_vels argument, zero by default): it is up to you to add it to the linvel and angvel of that rigid-body before the next PhysicsWorld.step.

The coordinate axes (linear and/or angular) controlled by the controller can be selected in order, for example, to only control the translations of a body while leaving its rotations to the simulation (with the axes argument of its constructor or its axes property, a combination of the AxesMask flags):

# The proportional, integral, and derivative gains of the controller, acting on the linear
# axes only: the body is pushed toward its target without its rotation being controlled.
axes = rp.AxesMask.LIN_X | rp.AxesMask.LIN_Y | rp.AxesMask.LIN_Z
pid = rp.PidController(axes=axes, Kp=60.0, Ki=0.0, Kd=0.8)
target = rp.Isometry3.from_translation(3.0, 2.0, 0.0)

for _ in range(200):
    dt = world.integration_parameters.dt
    body = world.rigid_bodies[body_handle]
    # The correction is the velocity change bringing the body closer to its target pose
    # (and to its target velocities, zero here).
    correction = pid.rigid_body_correction(dt, body, target, target_vels=rp.RigidBodyVelocity())
    body.linvel = body.linvel + correction.linear
    body.angvel = body.angvel + correction.angular

    world.step()

note

The integral part of the controller accumulates the position errors of the previous timesteps, which is what allows it to compensate a permanent perturbation (e.g. the gravity applied to a hovering body). These accumulated errors are readable with the PidController.lin_integral and PidController.ang_integral properties. This is also what makes PidController.rigid_body_correction modify the controller, and what has to be reset with PidController.reset whenever the controller is given a target it never had a chance to reach. The PdController is the variant without that integral part (its constructor takes no Ki argument): its rigid_body_correction method doesn’t modify it (and doesn’t need the timestep length), and its behavior is generally good enough for games.