WiggleBone: jiggle physics for Skeleton3D bones in Godot

Two modifier nodes replaced a deprecated one

WiggleBone adds jiggle physics to a Skeleton3D bone using SkeletonModifier3D nodes, and the current version of the project is built around two nodes rather than one.

You can add either DMWBWiggleRotationModifier3D or DMWBWigglePositionModifier3D to a Skeleton3D. There is an examples directory with the sample scenes.

The older approach is still in the tree but is marked deprecated. The WiggleBone node is deprecated and should be replaced with either of the two modifier nodes, and the warning about it sits in the usage section rather than being buried, which is the right place for something that will change how existing scenes behave.

Two properties of the modifier approach catch people out and both are stated plainly in the usage notes.

First, poses modified in SkeletonModifier3D nodes are only temporary for the current frame. A modifier computes a pose for the frame it is processing and the result does not persist, which is a different model from a node that writes into a bone transform and leaves it there.

Second, the order in the scene tree matters. Modifiers for parent bones should come first, above, in the tree, otherwise it may not have the desired effect. Since each modifier operates on a pose and a child bone's rest orientation depends on its parent's, the modifier chain has to run from the root down for the poses to compose correctly.

The project is written in GDScript, it is MIT licensed, and the only tagged release is v3.0.0 from November 2024, with the last push on 2026-05-14.

Rotation uses the current pose as the spring's rest position

The rotation modifier rotates the bone around the current bone pose, and the current pose direction acts as the spring's rest position.

That single design decision explains most of the behaviour people notice. The spring does not pull the bone toward some absolute orientation, it pulls it back toward wherever the bone is already pointing. That is what makes a jiggle effect work on a character whose arms hang down in one pose and are raised in another, without the effect needing to know anything about the animation.

The modifier holds a properties resource, of type DMWBWiggleRotationProperties3D, and that resource can be shared by multiple modifiers. Four properties sit directly on the modifier. The properties resource holds the ones used to move the bone. force_global applies a constant global force. force_local applies a constant force relative to the bone's pose. And handle_distance sets the distance of the editor handle on the bone's Y axis.

The separation between the two is worth pausing on. The modifier holds the wiring, the resource holds the physical parameters. A character with ten jiggle bones can share one properties resource across all of them, and tuning the feel of the whole character is a single slider rather than ten. It also means the same physical settings can be shared between a rotation modifier and a position modifier without pretending they are the same physics.

The properties resource itself has six settings. spring_freq is the spring's oscillation frequency, with the note that adding forces may change the frequency. angular_damp is the damping factor of the angular velocity. force_scale defines how much the rotation is influenced by forces, and linear_scale defines how much the rotation is influenced by global movement, which is a separate quantity from the force itself. swing_span is the maximum angle the bone can rotate around its pose, and gravity applies a constant global force.

The distinction between force_scale and linear_scale is the one to understand. A force is a push, and force_scale decides how strongly it moves the bone. linear_scale decides how much of the bone's own movement carries into the rotation, so a character walking and a character standing still can jiggle differently under the same settings.

There are three methods on the modifier. reset resets rotation and angular velocity. add_torque_impulse takes a torque vector and adds a global torque impulse. And add_force_impulse takes a force vector and adds a global force impulse.

Free rotation is available too. To allow the bone to rotate freely, the spring frequency can be set to 0.0 or a very low value, which removes the restoring force and leaves only the damping and the applied forces.

The 180 degree pole is a real limit, and the documentation admits it

The rotation modifier has three documented limitations, and they are all about the same thing, which is what happens when a bone rotates close to half a turn from its rest position.

Rotations near 180 degrees have a pole, which means that the bone spins around its forward axis near that limit. Rotation with exactly 180 degrees has no unique solution, and the bone's forward axis rotation snaps to a fallback axis. And when the rotation approaches 180 degrees while using a low spring frequency, the angular rotation may change its direction in certain cases.

The pole is a consequence of how a bone's rotation is represented. A bone points along a forward axis, and at exactly half a turn there is no longer a unique axis to rotate around, so the simulation has to pick one and the result is a snap. The three bullets describe that at three different levels of severity, from a visible spin, to a snap at the exact limit, to a direction flip that can happen slightly before it.

There is a workaround, and it is a good one. Some of these problems can be avoided by setting the bone pose rotation already to the desired rest position, and the example given is that if a bone is hanging down, the bone pose should already be pointing down.

That advice makes sense given the rest-position design. If the spring's rest position is the current pose, then choosing a pose that is close to the intended motion range means the spring never has to pull the bone a long way, and the pole sits far outside the range the effect ever reaches.

The third limitation only appears when you combine the pole with a low spring frequency, and the two are the same underlying problem seen at different settings. A stiff spring snaps back before it gets near the limit, and a loose spring drifts into it. The pole is therefore a problem for the specific combination of a slack spring and a bone whose rest position is far from where it moves, which is exactly the combination the workaround removes.

Position moves the bone without touching its orientation

The position modifier moves the bone around the current bone pose without rotating, and the current pose position acts as the spring's rest position.

Everything else mirrors the rotation modifier with the rotation-specific parts removed, and that symmetry is the clearest sign that the two were designed as a pair rather than as separate features.

The modifier has four properties of its own. The properties resource, of type DMWBWigglePositionProperties3D, holds the ones used to move the bone and can be shared by multiple modifiers. force_global applies a constant global force and force_local applies a constant local force relative to the bone's pose.

The properties resource has seven settings, and comparing them to the rotation list shows the differences at a glance. spring_freq is the oscillation frequency, with the same note that adding forces may change the frequency. linear_damp is the damping factor of the velocity, where the rotation modifier had angular_damp for the angular velocity. force_scale defines how much the position is influenced by forces, and linear_scale defines how much the position is influenced by global movement. max_distance is the maximum distance the bone can move around its pose position, which is the position counterpart of the rotation modifier's swing_span. And gravity applies a constant global force.

So the rotation modifier is bounded by an angle and the position modifier by a distance, and both have a scale for how strongly forces act and a scale for how much of the global movement carries in.

The methods are two rather than three. reset resets position and velocity, and add_force_impulse takes a force vector and adds a global force impulse. There is no torque impulse, because the position modifier does not rotate the bone, so there is nothing for a torque to act on.

The practical difference between the two nodes is worth stating plainly. Rotation gives you a character whose hair, ears or accessories swing around their attachment point, which is the classic jiggle. Position gives you a bone that slides relative to its rest location, which is what you want for something like a collar or a strap that should hang and shift rather than swing.

The editor handle lets you test the force without playing the animation

When a rotation or position modifier node is selected in the scene tree, a force can be applied to it by dragging its handle. The other way to apply a force is to drag or rotate the Skeleton3D itself, or one of its parents.

That second option is the one that makes the tool usable while building a scene. Dragging the skeleton moves the whole character, and the modifiers respond, so you can see how the effect behaves while the character is moving rather than only at rest. It is a direct manipulation workflow rather than a preview one.

The handle itself is positioned with the handle_distance property, which sets its distance on the bone's Y axis. The Y axis is the bone's local up, so the handle sits above the bone by default, and moving it further away gives you more travel to drag through. This is the same property that appears on both modifier types, so the handle behaves consistently whether you are testing rotation or position.

There is also a way to turn the handle off. The editor gizmo, the cone or sphere shape, can be hidden in the 3D viewport by disabling it in the View menu, then Gizmos, then the entry for the modifier you are using. The two modifiers have separate entries in that menu, so you can hide one and keep the other.

That is a small feature with a real use. The gizmo sits in the viewport on every frame while the node is selected, and for a character with many jiggle bones, or for a modifier that is easy to select by accident, a way to remove the visual noise is worth having.

The repository layout is small and follows the Godot addon convention. There is an addons/ directory holding the plugin itself, an examples/ directory with the wigglebone example scenes, an images/ directory with the preview animation, an icon.svg with its import file, a project.godot file for the editor project, a CHANGELOG.md, a LICENSE, a README.md, a .editorconfig, a .gitattributes and a .github/ directory.

Testing in the editor rather than only in a running game is the loop the whole tool is designed around, and the two ways of applying a force are the two ends of it, a deliberate push from the handle and an incidental one from moving the character.

Godot 4.3 is required, and 4.2 has a separate branch

The plugin targets Godot 4.3, and the reason is a specific engine feature rather than a preference.

As Godot 4.2 and lower does not support SkeletonModifier3D nodes, there is a branch named godot-4.2 with an alternative implementation using Node3D, and it can be used as a fallback for existing projects.

That is a well handled version story. The engine change is the constraint, the workaround targets the older engine with a different node type, and the fallback lives on its own branch so the main branch can use the modern API cleanly. A project that has to stay on 4.2 does not have to abandon the effect or backport it by hand.

The two installation routes are equally short. In the AssetLib editor tab you search for wigglebone, download and install the plugin, and enable it in the project settings via the Plugins tab.

Or you clone the repository or download the archive, copy the addons/wigglebone folder to the project's addons folder, creating it if needed, and enable the plugin in the project settings via the Plugins tab. The plugin is not automatically enabled either way, which is the usual Godot convention for addons.

The documentation closes with its references, and they are worth noting because they explain the choices in the physics. The spring behaviour is based on a video titled Springs: From Hooke's law to a time based equation by EgoMooses. And the time-independent lerp is based on a talk titled Lerp smoothing is broken by Freya Holmér.

The second reference is the more interesting one for a position modifier. Lerp smoothing is the most common approach to making a value follow a target smoothly, and the claim that it is broken is a claim that linear interpolation smoothing does not behave the way people expect when the frame rate varies or when the target changes quickly. The reference sits in the documentation because the position modifier does not use the naive approach, and knowing which failure it avoids tells you what the implementation is doing differently.

Two video references and a spring formula is a small bibliography for a plugin of this size, but it is the right kind of small. The project is not a physics library and does not present itself as one; it points at the specific pieces of theory it relies on.

Editorial conclusion

WiggleBone suits a Godot developer giving a character secondary motion, whether hair, ears, a collar or an accessory, since the spring rest position being the current bone pose means one setup works across every animation you have. It does not suit you if you need the bone's motion to persist rather than being recomputed each frame, because modifier poses are temporary for the current frame, and it does not suit you on Godot 4.2 unless you switch to the fallback branch. Before you build on it, set the bone pose rotation to the direction you want the effect to hang in, because that is what keeps the 180 degree pole out of the range the effect ever reaches.

Frequently asked questions

Official sources

1. detomon/wigglebone on GitHub
2. Issues
3. License: MIT
4. README
5. Releases