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 component, added to the entity of a (non-fixed) rigid-body. Its target field is a PidTarget holding the world-space pose (and optionally the velocities) the rigid-body must be driven toward. Before each simulation step, the plugin computes the velocity correction bringing the rigid-body closer to its target, and adds it to its velocity. So moving the target is just a matter of modifying the PidController::target field.

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 field, an AxesMask):

Example 2D

fn setup_physics(mut commands: Commands) {
    // 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.
    let pid = PidController::new(60.0, 0.0, 0.8, AxesMask::LIN_AXES)
        .with_target(PidTarget::from_translation(Vec2::new(300.0, 200.0)));

    commands.spawn((
        Transform::from_xyz(0.0, 100.0, 0.0),
        RigidBody::Dynamic,
        Collider::ball(50.0),
        pid,
    ));
}

/* Move the target of the controller inside of a system. */
fn update_target(time: Res<Time>, mut controllers: Query<&mut PidController>) {
    let t = time.elapsed_secs();
    for mut controller in controllers.iter_mut() {
        // The plugin drives the rigid-body toward this pose before each simulation step.
        controller.target = PidTarget::from_translation(Vec2::new(300.0 * t.cos(), 200.0));
    }
}

Example 3D

fn setup_physics(mut commands: Commands) {
    // 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.
    let pid = PidController::new(60.0, 0.0, 0.8, AxesMask::LIN_AXES)
        .with_target(PidTarget::from_translation(Vec3::new(3.0, 2.0, 0.0)));

    commands.spawn((
        Transform::from_xyz(0.0, 1.0, 0.0),
        RigidBody::Dynamic,
        Collider::ball(0.5),
        pid,
    ));
}

/* Move the target of the controller inside of a system. */
fn update_target(time: Res<Time>, mut controllers: Query<&mut PidController>) {
    let t = time.elapsed_secs();
    for mut controller in controllers.iter_mut() {
        // The plugin drives the rigid-body toward this pose before each simulation step.
        controller.target = PidTarget::from_translation(Vec3::new(3.0 * t.cos(), 2.0, 0.0));
    }
}

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 stored in the PidController::lin_integral and PidController::ang_integral fields updated by the plugin, and have to be reset with PidController::reset_integrals whenever the controller is given a target it never had a chance to reach. The PdController component is the variant without that integral part, and its behavior is generally good enough for games. Use either one or the other on a given entity, but not both.