Add joint motors for revolute and prismatic joints

[pierre-l]

Objective

Supports velocity and position control with optional timestep-independent spring-damper parameters (frequency, damping_ratio). Includes warm starting and motor force feedback via JointForces.

Partially fixes #465
This implementation only works for joints with a single axis (PrismaticJoint, RevoluteJoint).
Additional work is needed to support multiple axes (SphericalJoint).

Solution

Add three MotorModel: ForceBased and AccelerationBased are directly inspired from the Rapier eponymous models, the SpringDamper model doesn't exists in Rapier but seems much easier to use to me. The latter is the default.

The motors are solved through XPBD like any other joint constraint.

Relevant Rapier sources:

• src/dynamics/joint/motor_model.rs
• src/dynamics/joint/generic_joint.rs
• dynamics/solver/joint_constraint/joint_constraint_builder.rs
• src/dynamics/joint/revolute_joint.rs
• src/dynamics/joint/prismatic_joint.rs

Breaking change

(first commit only, outdated by the second one)

The current implementation minimizes breaking changes, however, users who directly add the XPBD solver systems instead of using the plugin will have to make changes for motors to work:

Similarly, users who manually implemented XpbdConstraint for custom joints may need to implement XpbdMotorConstraint instead if they want motors to work.

Users who manually implemented XpbdConstraint for custom joints may need to write a custom implementation for the new XpbdConstraint::warm_start_motors method as its default implementation does nothing.

Users who manually add the solve_xpbd_joint systems instead of using the plugins may need to also add warm_start_xpbd_motors. (why would anyone do that though?)

Testing

• A reasonable series of unit tests is included in the PR,
• The joint_motors_2d and joint_motors_3d examples provide an interactive way to test these,
• I used these examples to manually perform a brief test of motors+limits, no surprises there,
• I couldn't find proper test vectors so there currently is no test scenario where it is verified that a specific motor configuration reaches a specific state in a precise time interval.

---

Showcase

Concise showcase

// Position-controlled motor (e.g., servo arm)
RevoluteJoint::new(anchor, arm)
    .with_motor(AngularMotor {
        enabled: true,
        target_position: PI / 4.0,  // 45 degrees
        max_torque: 100.0,
        motor_model: MotorModel::SpringDamper {
            frequency: 2.0,
            damping_ratio: 1.0,  // critically damped
        },
        ..default()
    })

// Velocity or position can then be set on demand
fn set_motor_position(mut joints: Query<&mut RevoluteJoint>) {
      for mut joint in &mut joints {
          if let Some(motor) = joint.motor.as_mut() {
              motor.target_position = PI / 2.0; // 90 degrees
          }
      }
  }

See the examples included in this PR for more detailed examples.

Screencast.from.2026-01-11.14-55-37.webm

[Jondolf]

Thanks for the PR! This looks very nice and impressive already, based on a quick look :)

Just as a heads-up: we have some plans to potentially replace the joint XPBD solver with something else, most likely a more traditional impulse-based solver like the one used by most other engines and our contacts, or mayybe AVBD if we can get it working well enough. That's one of the main reasons why I haven't personally prioritized implementing joint motors yet.

Still, that may take a while, and this work is very useful regardless; motors are something that a lot of people have been asking for, and the API should remain mostly the same even if the solver implementation were to change in the future.

---

Now, some general comments based on a first glance at the implementation.

I like having LinearJointMotor and AngularJointMotor as components from an API perspective. However, it does have a few problems:

• some joints don't support motors at all (ex: fixed joints)
• some joints only support linear motors (ex: prismatic joint) or angular motors (ex: revolute joint), but not both
• some joints can have multiple linear and/or angular motors, and need to support multiple axes, as you pointed out

Ultimately, it seems to me like we need some joint-specific motor APIs, both for correctness and flexibility. There's roughly two approaches I can think of:

1. Similar to Box2D and Jolt: Store motor settings on the joints themselves, in a JointMotor or MotorSettings property.

// Example: revolute joint motor
#[derive(Component)]
pub struct RevoluteJoint {
    pub body1: Entity,
    pub body2: Entity,
    pub frame1: JointFrame,
    pub frame2: JointFrame,
    #[cfg(feature = "3d")]
    pub hinge_axis: Vector,
    pub angle_limit: Option<AngleLimit>,
    // `MotorSettings` is like this PR's `LinearJointMotor`
    // or `AngularJointMotor`, but as just a single type;
    // in this case, it's used as an angular motor
    pub motor: MotorSettings,
    pub point_compliance: Scalar,
    pub align_compliance: Scalar,
    pub limit_compliance: Scalar,
}

2. Similar to Bepu: Have many different motor types, like RevoluteMotor, SphericalMotor, PrismaticMotor, and so on.

// Example: revolute joint motor
#[derive(Component, Deref, DerefMut)]
pub struct RevoluteMotor(MotorSettings);

// Example: spherical joint motor
// Alternatively, we could have a separate `SwingMotor` and `TwistMotor`
#[cfg(feature = "3d")]
#[derive(Component)]
pub struct SphericalMotor {
    pub swing: MotorSettings,
    pub twist: MotorSettings,
}

With either approach, each joint can store only the motors that are relevant for it, and can even support multiple axes. For example, Jolt's SwingTwistConstraint has separate mSwingMotorSettings and mTwistMotorSettings.

Option 2 looks interesting and does maybe feel more natural from a composition and ECS standpoint. I've been thinking that joint limits are optional in a similar way as motors, so we could even land on a design where the base joint type, its limit(s), and its motor(s) are all separate components:

commands.spawn((
    // The base joint type
    RevoluteJoint::new(entity1, entity2),
    // Optional limit
    RevoluteLimit::new(-FRAC_PI_2, FRAC_PI_2),
    // Optional motor
    RevoluteMotor::from_target_velocity(1.0),
));

This would lead to a rather nice conceptual split:

• Joint: locks some degrees of freedom, leaving others free
• Limit: limits relative movement along the remaining free degrees of freedom
• Motor: provides position and/or velocity actuation for the remaining free degrees of freedom

However I think the gains are still somewhat dubious, and it does add some complexity, since you need to query for multiple different components, and users could technically create invalid or unsupported configurations, like a spherical joint motor on a prismatic joint.

So for now, I think I would just go with Option 1, since it's more common and probably the most straightforward to implement. I also do kinda like that e.g. all revolute joint configuration and features are on the actual RevoluteJoint type and not scattered across many components.

Curious if you have ideas or thoughts here though :)

[pierre-l]

@Jondolf I greatly appreciate your words, thoughts, and the attention you already put into this.

This PR's API is an aspect I'm particularly not satisfied with yet. There is too much freedom to shoot oneself in the foot in the constructor variants, and then there's the syntax point you mentioned. I am fine with both options. I agree with the nice conceptual separation from option 2, but joint limits and motors make no sense without a joint to attach to, so it's more natural to me to have these as attributes rather than components. We agree on which is the best option then. Worst case scenario: we're both wrong on this and adjust. No big deal, the adjustment effort looks similar either way.

I should be able to bring this ready for a proper review in the next few days.

[pierre-l]

I've tinkered with this for a long time and I do believe option 1 is the way to go.
It also seems to make it easier to implement joints with multiple motors like the SphericalJoint, however I have not been able to properly implement that yet and have very limited visibility about how much time I can spend on it.

I'm wondering if SphericalJoint couldn't be implemented as a composition of a PrismaticJoint and a RevoluteJoint. It seems a lot simpler to me, but maybe I'm being naive.

I updated the PR description and will mark it as ready for review.

[Jondolf]

Thanks, sounds good! It's fine to leave SphericalJoint motors to a future follow-up PR, the motors for revolute and prismatic joints are highly valuable by themselves and can be added first. I'll try to do a proper review on this later this week, but based on a quick look through the code, it looks great!

I'm wondering if SphericalJoint couldn't be implemented as a composition of a PrismaticJoint and a RevoluteJoint. It seems a lot simpler to me, but maybe I'm being naive.

I think the interface would ideally let you set a target relative orientation and angular velocity. In PhysX, the D6 (aka 6DOF) joint supports this with two different angular drive models, twist & swing, and SLERP (link). In other engines like Jolt and Bepu, it's a bit less clear how they determine the rotation "path" for angular motors/servos, but they still also allow setting a target orientation as a quaternion. I haven't yet looked into how exactly it should be implemented though

[Jondolf]

Hi! I finally did a pass on this PR, and made some changes:

• Motors are no longer Options, and instead store an enabled property. This allows users to enable/disable motors without clearing the existing motor properties, and overall seems like a nicer API.
• Motors are now solved directly in solve instead of a separate solve_motors method. We need to solve motors before limits, otherwise the motors can overpower the limit and cause visible stretching/error, especially at low substep counts.
• Cleaned up the examples and docs a bit. The examples let you properly toggle the motors, and have gravity enabled, which showcases e.g. the prismatic joint dropping down when the position motor is disabled. (I added a limit so it doesn't fall indefinitely)
• Rename examples from motor_joints_nd to joint_motors_nd.

I also updated the PR description to match the changes. I'll probably do a bit more polish work over the next day or two, and add a brief migration guide, after which I'll merge, unless you have something to add 🙂

[pierre-l]

Hello,

Thanks for these changes, the API is indeed a lot nicer now and I'm much more satisfied with the state of this PR. Good point on the motors vs limits solving order too.
I made another doc adjustment as my point about timeless-independence was confusing if not plain false.

I don't see your changes in the PR description, maybe you kept these as a draft?

CI failed. It looks like an infra issue. I added another commit in an attempt to fix this. I'll check this out again later today.