refactor(joint): derive motor engagement from maxMotorForce

Remove the redundant enableMotor boolean. A motor with a zero force
budget does nothing, so a positive maxMotorForce is the natural "motor
active" signal - mirroring how a spring acts when its stiffness is
positive. This drops another boolean from the public surface and removes
a redundant state without losing expressiveness: free (zero force),
drive (positive force, non-zero speed) and brake/hold (positive force,
zero speed) all remain reachable.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: willeastcott

examples/src/examples/physics/joints.example.mjs

@@ -177,7 +177,6 @@ createJoint('windmill-hinge', new pc.Vec3(-5.5, 4, 0.3), new pc.Vec3(0, -90, 0),
     type: pc.JOINTTYPE_HINGE,
     entityA: rotor,
     entityB: pole,
-    enableMotor: true,
     motorSpeed: 90,
     maxMotorForce: 100
 });
@@ -221,13 +220,12 @@ app.root.addChild(rail);
 const platform = createBox('platform', new pc.Vec3(0.8, 0.25, 0.6), new pc.Vec3(1.5, 0.85, 0), green, 'dynamic', 10);
 
 // the slider is pinned to the world (entityB is null) - the platform can only translate along
-// the joint's X axis, driven back and forth by the motor
+// the joint's X axis, driven back and forth by the motor (active because maxMotorForce > 0)
 const sliderJoint = createJoint('slider', new pc.Vec3(1.5, 0.85, 0), new pc.Vec3(0, 0, 0), {
     type: pc.JOINTTYPE_SLIDER,
     entityA: platform,
     enableLimits: true,
     limits: new pc.Vec2(-2, 2),
-    enableMotor: true,
     motorSpeed: 1.5,
     maxMotorForce: 400
 });

src/framework/components/joint/component.js

@@ -128,7 +128,7 @@ const hingeJoint = {
         // bullet's hinge motor clamp is an impulse per simulation step, so scale the torque by
         // the fixed timestep
         const maxImpulse = joint.maxMotorForce * joint.system.app.systems.rigidbody.fixedTimeStep;
-        joint._constraint.enableAngularMotor(joint.enableMotor, joint.motorSpeed * math.DEG_TO_RAD, maxImpulse);
+        joint._constraint.enableAngularMotor(joint.maxMotorForce > 0, joint.motorSpeed * math.DEG_TO_RAD, maxImpulse);
     }
 };
 
@@ -157,7 +157,7 @@ const sliderJoint = {
 
     updateMotor(joint) {
         const constraint = joint._constraint;
-        constraint.setPoweredLinMotor(joint.enableMotor);
+        constraint.setPoweredLinMotor(joint.maxMotorForce > 0);
         constraint.setTargetLinMotorVelocity(joint.motorSpeed);
         constraint.setMaxLinMotorForce(joint.maxMotorForce);
     }
@@ -352,9 +352,6 @@ class JointComponent extends Component {
     /** @private */
     _limits = new Vec2(-45, 45);
 
-    /** @private */
-    _enableMotor = false;
-
     /** @private */
     _motorSpeed = 0;
 
@@ -680,32 +677,11 @@ class JointComponent extends Component {
     }
 
     /**
-     * Sets whether the joint's motor is enabled. The motor drives a hinge joint's rotation or a
-     * slider joint's translation towards {@link motorSpeed}, applying up to
-     * {@link maxMotorForce}. Not used by other joint types. Defaults to false.
-     *
-     * @type {boolean}
-     */
-    set enableMotor(arg) {
-        if (this._enableMotor !== arg) {
-            this._enableMotor = arg;
-            this._updateMotor();
-        }
-    }
-
-    /**
-     * Gets whether the joint's motor is enabled.
-     *
-     * @type {boolean}
-     */
-    get enableMotor() {
-        return this._enableMotor;
-    }
-
-    /**
-     * Sets the target speed of the joint's motor. For hinge joints, this is an angular speed in
-     * degrees per second. For slider joints, this is a linear speed in meters per second. Only
-     * used when {@link enableMotor} is true. Defaults to 0.
+     * Sets the target speed the motor drives towards. For hinge joints, this is an angular speed
+     * in degrees per second; for slider joints, a linear speed in meters per second. The motor is
+     * active only while {@link maxMotorForce} is greater than 0; with a target speed of 0 and a
+     * positive force the motor acts as a brake, holding the joint at rest. Only used by hinge and
+     * slider joints. Defaults to 0.
      *
      * @type {number}
      */
@@ -717,7 +693,7 @@ class JointComponent extends Component {
     }
 
     /**
-     * Gets the target speed of the joint's motor.
+     * Gets the target speed the motor drives towards.
      *
      * @type {number}
      */
@@ -726,9 +702,10 @@ class JointComponent extends Component {
     }
 
     /**
-     * Sets the maximum force the joint's motor can apply to reach {@link motorSpeed}. For hinge
-     * joints, this is a torque in Newton meters. For slider joints, this is a force in Newtons.
-     * Only used when {@link enableMotor} is true. Defaults to 0.
+     * Sets the maximum force the motor can apply to reach {@link motorSpeed}. For hinge joints,
+     * this is a torque in Newton meters; for slider joints, a force in Newtons. The motor is
+     * disabled while this is 0, so set it greater than 0 to engage the motor. Only used by hinge
+     * and slider joints. Defaults to 0.
      *
      * @type {number}
      */

src/framework/components/joint/system.js

@@ -8,7 +8,7 @@ import { JointComponent } from './component.js';
 const _properties = [
     'type',
     'enableCollision', 'breakImpulse',
-    'enableLimits', 'limits', 'enableMotor', 'motorSpeed', 'maxMotorForce',
+    'enableLimits', 'limits', 'motorSpeed', 'maxMotorForce',
     'swingLimitY', 'swingLimitZ', 'twistLimit',
     'linearMotionX', 'linearMotionY', 'linearMotionZ',
     'linearLimitsX', 'linearLimitsY', 'linearLimitsZ',

test/framework/components/joint/component.test.mjs

@@ -39,7 +39,6 @@ describe('JointComponent', function () {
             breakImpulse: 500,
             enableLimits: true,
             limits: new Vec2(-10, 80),
-            enableMotor: true,
             motorSpeed: 90,
             maxMotorForce: 12,
             swingLimitY: 30,
@@ -75,7 +74,6 @@ describe('JointComponent', function () {
         expect(c.breakImpulse).to.equal(500);
         expect(c.enableLimits).to.equal(true);
         expect(c.limits.equals(new Vec2(-10, 80))).to.equal(true);
-        expect(c.enableMotor).to.equal(true);
         expect(c.motorSpeed).to.equal(90);
         expect(c.maxMotorForce).to.equal(12);
         expect(c.swingLimitY).to.equal(30);
@@ -119,7 +117,6 @@ describe('JointComponent', function () {
             expect(c.isBroken).to.equal(false);
             expect(c.enableLimits).to.equal(false);
             expect(c.limits.equals(new Vec2(-45, 45))).to.equal(true);
-            expect(c.enableMotor).to.equal(false);
             expect(c.motorSpeed).to.equal(0);
             expect(c.maxMotorForce).to.equal(0);
             expect(c.swingLimitY).to.equal(45);