[Cocos Creator 3.8.5]Jittering When Two RigidBodies Snap Together

Cocos Creator
1

I’m working on a Cocos 3D project and have run into a physics issue with two rigid bodies:

When I click the upper body, it drops freely into the lower groove—but as soon as it contacts the groove, it jitters and eventually falls out of the screen. What I actually want is:

  • Once it settles in the groove, and no external forces are acting on it, it should remain perfectly still.
  • If an external force is later applied, it should respond normally to that force.

Here’s a short demo of the problem:

dropOut

Both nodes use the same BoxItem script. Relevant snippets follow:

// Called every frame
protected update(dt: number): void {
  const rigidBodies = this.node.getComponentsInChildren(RigidBody);
  for (const body of rigidBodies) {
    // Prevent any unwanted spin when fixed
    if (this.isFixed) {
      body.setAngularVelocity(v3(0, 0, 0));
    }
  }
}

// Initialization (e.g. onLoad)
const rigidBodies = this.node.getComponentsInChildren(RigidBody);
for (const body of rigidBodies) {
  body.type         = RigidBody.Type.DYNAMIC;
  body.useGravity   = true;
  body.angularFactor = v3(0, 0, 1);      // Only allow rotation around Z
  if (this._boxModel?.mass) {
    body.mass = this._boxModel.mass;
  }
}

What I’ve Tried So Far

  • Clamping angular velocity to zero when isFixed
  • Ensuring both bodies use the same mass and gravity settings

Desired Behavior

  • After the upper body falls into the groove, it should come to rest and stay exactly in place if no other forces act on it.
  • If another force (e.g. a collision or user interaction) is later applied, it should react normally.

Questions

  1. What’s causing that continuous jitter when it first contacts the groove?
  2. Which physics properties (e.g., linear/angular damping, friction, contact/collision margins) should I adjust to let it stabilize and lock in place?

Thanks in advance for any insights or recommendations!