changed behavior: chain of small bodies unstable when wrapped around a rotating kinematic

[stephengold]

I recently discovered an unexpected and undesirable change in behavior of JoltPhysics that occurred between 26 March and 20 April of this year (2026). I guess the change might be related to PR #1970.

My test case is written in Java, and it simulates a windlass. The barrel of the windlass is a kinematic rigid body with a compound shape. User input causes the barrel to rotate around a horizontal axis. The barrel is attached to one end of a long cable, simulated as a chain of 53 "segments" (small dynamic rigid bodies) joined by point constraints. Initially 90% of the cable is coiled around the barrel of the windlass:

When simulated using JoltPhysics as of 26 March, rotating the barrel causes the cable to smoothly coil or uncoil. When simulated using JoltPhysics as of 20 April, rotating the barrel causes the cable to briefly intersect with the barrel, become unstable, whip around, and partially explode:

The failure is actually more subtle than I've described it. If I allow the physics simulation to settle for 5 seconds before rotating the barrel, I get the explosion. If I start rotating the barrel soon after the simulation starts, there's no explosion.

Any theory why changes made in March-April might've led to instability? Does my guess that it's related to PR #1970 seem plausible? Any ideas how I could determine the cause of the instability or work around it?

[jrouwe]

I don't immediately see which change could have caused this (#1970 seems unlikely, although it would be possible). Can you maybe answer the following questions?

• What OS are you testing this on?
• What compiler are you using?
• What defines is Jolt compiled with?
• Is it a Debug/Release/Distribution build?
• Can you maybe provide the scene as a snapshot? (let me know the exact revision you made this snapshot with, the binary format changes every now and then)

[stephengold]

The OS is Linux Mint v22.3 . The compiler is Clang++ 14.

Here's the full configuration string:

Single precision x86 64-bit with instructions: SSE2 SSE4.1 SSE4.2 AVX AVX2 F16C LZCNT TZCNT FMADD (16-bit ObjectLayer) (ObjectStream)

Defines include JPH_NO_DEBUG and JPH_USE_VK.

Other compiler options include -fno-exceptions -fno-rtti -std=c++17 -Werror=return-type -msse4.1 -msse4.2 -mavx -mf16c -mavx2 -mbmi -mlzcnt -mfma -O3 -fPIC -fvisibility=hidden

Here's a zipped snapshot generated with PhysicsScene::SaveBinaryState(out, true, true) at JoltPhysics commit 3830e04 (20 April) just before rotating the barrel:

archive.zip

[stephengold]

I re-tested using a Debug build and got identical results.

[jrouwe]

I compiled the library with ./cmake_linux_clang_gcc.sh Distribution clang++-14 (which produces the same config string as you have) and adjusted LoadSnapshotTest to wait 5 seconds and then start rotating the barrel at 2 rad/s. I tried this on March 26th, April 20th and today's version and they all look fine. This is a recording of April 20th, I had to shorten it a bit to get github to accept it:

Jolt.Physics.Samples.Ubuntu-24.04.2026-06-05.14-16-47.mp4

I tried various other configurations and things like varying update frequencies, different gravity settings and different barrel rotation directions/speeds, but I could not get it to explode. The only thing that happens (on all versions when the rotation speed of the barrel is high enough) is that sometimes the tension becomes high enough for a link to tunnel through another, but that doesn't cause instabilities.

Is there anything else I need to do to get the same conditions as you? (e.g. what update frequency / barrel rotation speed are you using?)

[jrouwe]

Maybe you can post a video as well?

[stephengold]

A video might help clarify things. I'll work on that.

[stephengold]

My rotation rate is 4 radians/second around the X axis. I see issues both with +X and -X rotations.
My simulation timestep is 0.0015 seconds.
Gravity is (0, -981, 0), but I assume that's stored in the snapshot.

[stephengold]

Here's a video clip of the old/expected behavior:

• https://youtu.be/c684E07hv00

Here are 3 video clips of the new/undesirable behavior:

• https://youtu.be/EXrX4O3oeDE
• https://youtu.be/ZOvOGn6zihk
• https://youtu.be/VEwHjgf4Ovo

[jrouwe]

Gravity is (0, -981, 0), but I assume that's stored in the snapshot.

No, global settings are not stored in the snapshot. Only bodies and their constraints.

Here are 3 video clips of the new/undesirable behavior:

Those movies provide the final piece of the puzzle: You can see that the barrel is rotating in the first movie, but isn't in the other 3 movies.

What this tells me:

• You spawn the bodies (and probably activate all of them).
• Wait for 5 seconds. Because the barrel is not moving, it goes to sleep.
• You then set the angular velocity using Body::SetAngularVelocity instead of BodyInterface::SetAngularVelocity. The result is that the body remains sleeping but it has an angular velocity now.
• Before Performance improvement for kinematic bodies #1970 the cable would have formed an island together with the barrel and woken the barrel up, now it doesn't anymore.
• The result is that the barrel has a velocity, but isn't updating. The constraints follow the barrel velocity, but since the barrel isn't actually moving, the constraint gets violated. This happens every frame causing the error to get bigger and bigger.

If you immediately start rotating the barrel, it hasn't gone to sleep yet, so it will be active and it will work as before.

So TLDR: You need to ensure that you activate the body when you set a velocity on it. The best way is to use BodyInterface::SetAngularVelocity.

I will add an assert that detects this situation / add some additional notes to the documentation. Unfortunately I cannot do this in Body::SetAngularVelocity as it is valid to first set a velocity and then activate the body.

[jrouwe]

See #2043

[stephengold]

Thanks for solving the mystery!