Multiple bones

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## v3.1.0 - 2026-05-13
+
+### Changed
+
+- Allow setting multiple bones for `DMWBWigglePositionModifier3D` and `DMWBWiggleRotationModifier3D` instead of just one
+	- **Note:** The previous property `bone_name` is migrated to `bones` when opening scenes which used an older addon version. After saving, these scenes will require the new version to work properly.
+- Fix typos and update class documentation
+
+## v3.0.1 - 2026-01-30
+
+### Fixed
+
+- Separate gizmo functions (#18)
+
 ## v3.0.0 - 2025-11-11
 
 ### Changed
@@ -10,9 +24,3 @@
 ### Deprecated
 
 - `WiggleBone` and `WiggleProperties` should not be used anymore and will be removed in a later version
-
-## v3.0.1 - 2026-01-30
-
-### Fixed
-
-- Separate gizmo functions (#18)

README.md

@@ -14,7 +14,7 @@ Adds jiggle physics to a `Skeleton3D` bone using `SkeletonModifier3D` nodes.
 
 ---
 
-![Palm](images/palm.gif)
+![A palm swaying in the wind](images/palm.gif)
 
 ## Installation
 
@@ -30,24 +30,29 @@ or...
 
 ## Usage
 
-You can now add `DMWBWiggleRotationModifier3D` or `DMWBWigglePositionModifier3D` nodes to a `Skeleton3D`. See the example scenes in [examples](https://github.com/detomon/wigglebone/tree/master/examples/wigglebone).
+- Add `DMWBWiggleRotationModifier3D` or `DMWBWigglePositionModifier3D` nodes to a `Skeleton3D`.
+- Define the `bones` which should be modified.
+- Add a property resource (`DMWBWiggleRotationProperties3D` or `DMWBWigglePositionProperties3D`) to define how the bones should behave.
+
+See the [example scenes](https://github.com/detomon/wigglebone/tree/master/examples/wigglebone) for some examples.
 
 **Note:** Poses modified in `SkeletonModifier3D` nodes are only temporary for the current frame. Modifiers for parent bones should come first (above) in the scene tree, otherwise it may have not the desired effect.
 
 > [!WARNING]
-> The `WiggleBone` node is deprecated and should be replaced with either `DMWBWiggleRotationModifier3D` or `DMWBWigglePositionModifier3D`.
+> The `WiggleBone` node is deprecated and will be removed in a future release. It should be replaced with either `DMWBWiggleRotationModifier3D` or `DMWBWigglePositionModifier3D`.
 
 ## Wiggle rotation
 
-**DMWBWiggleRotationModifier3D**
+![Icon of the rotation modifier node](addons/wigglebone/icons/wiggle_rotation_modifier_3d.svg) **DMWBWiggleRotationModifier3D**
 
-Rotates the bone around the current bone pose. The current pose direction acts as the spring's rest position.
+Behaves like a spring attached to the bone's current pose and rotates it around its origin. It reacts to global movement, rotation, or applied forces. The current pose direction acts as the spring's rest position.
 
 ### Modifier properties
 
 | Property | Description |
 |---|---|
-| `properties` | Properties used to move the bone. (`DMWBWiggleRotationProperties3D`) |
+| `bones` | A list of bone names to modify with the defined properties. |
+| `properties` | Properties which define the spring behaviour. (`DMWBWiggleRotationProperties3D`) |
 | `force_global ` | Applies a constant global force. |
 | `force_local ` | Applies a constant force relative to the bone's pose. |
 | `handle_distance ` | Sets the distance of the editor handle on the bone's Y axis. |
@@ -56,16 +61,16 @@ Rotates the bone around the current bone pose. The current pose direction acts a
 
 **DMWBWiggleRotationProperties3D**
 
-Used to set the modifier properties. Can be shared by multiple modifiers.
+Sets the modifier properties. Can be shared by multiple modifiers.
 
 | Property | Description |
 |---|---|
-| `spring_freq ` | The spring's oscillation frequency. *Note: Adding forces may change the frequency.* |
+| `spring_freq ` | The spring's oscillation frequency in `Hz`. *Note: Adding forces may change the frequency.* |
 | `angular_damp` | Damping factor of the angular velocity. |
-| `force_scale` | Defines how much the rotation is influenced by forces. |
-| `linear_scale` | Defines how much the rotation is influenced by global movement. |
-| `swing_span` | Maximum angle the bone can rotate around its pose. |
-| `gravity` | Applies a constant global force. |
+| `force_scale` | Defines how much the rotation is influenced by forces (`°/m`). |
+| `linear_scale` | Defines how much the rotation is influenced by global movement (`°/m`). |
+| `swing_span` |  Maximum angle in radians the bone can rotate around its pose. |
+| `gravity` | Applies a constant global force (`m/s²`). |
 
 ### Methods
 
@@ -77,7 +82,7 @@ Used to set the modifier properties. Can be shared by multiple modifiers.
 
 ### Free rotation
 
-To allow the bone to rotate freely, the spring frequency (`spring_freq`) can  be set to `0.0` or a very low value.
+To allow the bone to rotate freely, the spring frequency (`spring_freq`) can be set to `0.0` or a very low value.
 
 ### Limitations
 
@@ -89,32 +94,33 @@ To allow the bone to rotate freely, the spring frequency (`spring_freq`) can  be
 
 ## Wiggle position
 
-**DMWBWigglePositionModifier3D**
+![Icon of the position modifier node](addons/wigglebone/icons/wiggle_position_modifier_3d.svg) **DMWBWigglePositionModifier3D**
 
-Moves the bone around the current bone pose without rotating. The current pose position acts as the spring's rest position.
+Behaves like a spring attached to the bone's current pose and moves its origin without rotating. It reacts to global movement or applied forces. The current pose position acts as the spring's rest position.
 
 ### Modifier properties
 
 | Property | Description |
 |---|---|
-| `properties` | Properties used to move the bone. (`DMWBWigglePositionProperties3D`) |
+| `bones` | A list of bone names to modify with the defined properties. |
+| `properties` | Properties which define the spring behaviour. (`DMWBWigglePositionProperties3D`) |
 | `force_global ` | Applies a constant global force. |
 | `force_local ` | Applies a constant local force relative to the bone's pose. |
 
 ### Property resource
 
 **DMWBWigglePositionProperties3D**
 
-Used to set the modifier properties. Can be shared by multiple modifiers.
+Sets the modifier properties. Can be shared by multiple modifiers.
 
 | Property | Description |
 |---|---|
-| `spring_freq ` | The spring's oscillation frequency. *Note: Adding forces may change the frequency.* |
+| `spring_freq ` | The spring's oscillation frequency in `Hz`. *Note: Adding forces may change the frequency.* |
 | `linear_damp` | Damping factor of the velocity. |
-| `force_scale` | Defines how much the position is influenced by forces. |
-| `linear_scale` | Defines how much the position is influenced by global movement. |
-| `max_distance` | Maximum distance the bone can move around its pose position. |
-| `gravity` | Applies a constant global force. |
+| `force_scale` | A factor which defines how much the position is influenced by forces. |
+| `linear_scale` | A factor which defines how much the position is influenced by global movement. |
+| `max_distance` | Maximum distance in meters the bone can move around its pose position. |
+| `gravity` | Applies a constant global force (`m/s²`). |
 
 ### Methods
 
@@ -123,11 +129,15 @@ Used to set the modifier properties. Can be shared by multiple modifiers.
 | `void reset()` | Reset position and velocity. |
 | `void add_force_impulse(force: Vector3)` | Add a global force impulse. |
 
-## Testing in Editor
+### Free movement
+
+To allow the bone to move freely, the spring frequency (`spring_freq`) can be set to `0.0` or a very low value.
+
+## Testing in editor
 
 When a `DMWBWiggleRotationModifier3D` or `DMWBWigglePositionModifier3D` node is selected in the scene tree, a force can be applied to it by dragging its handle. Another way is to drag or rotate the `Skeleton3D` or one of its parents.
 
-### Disabling Editor Gizmo
+### Disabling editor gizmos
 
 The editor gizmo (cone/sphere) can be hidden in the 3D viewport by disabling it in `View > Gizmos > DMWBWiggleRotationModifier3D` or `View > Gizmos > DMWBWigglePositionModifier3D`, respectively.
 

addons/wigglebone/functions.gd

@@ -6,7 +6,7 @@ static func get_sorted_skeleton_bones(skeleton: Skeleton3D) -> PackedStringArray
 	if not skeleton:
 		return []
 
-	var bone_names: Array = []
+	var bone_names: Array[String] = []
 	var bone_count := skeleton.get_bone_count()
 
 	bone_names.resize(bone_count)

addons/wigglebone/icons/wiggle_bone.svg.import

@@ -35,4 +35,4 @@ process/size_limit=0
 detect_3d/compress_to=1
 svg/scale=1.0
 editor/scale_with_editor_scale=true
-editor/convert_colors_with_editor_theme=false
+editor/convert_colors_with_editor_theme=true

addons/wigglebone/wiggle_bone.gd

@@ -76,7 +76,9 @@ func _get_configuration_warnings() -> PackedStringArray:
 	var warnings := PackedStringArray()
 
 	if not properties:
-		warnings.append("WiggleProperties resource is required")
+		warnings.append("WiggleProperties resource is required.")
+
+	warnings.append("This node is deprecated. Use WiggleRotationModifier3D or WiggleDislocationModifier3D instead.")
 
 	return warnings
 
@@ -138,13 +140,17 @@ func set_properties(value: WiggleProperties) -> void:
 	update_gizmos()
 
 
+## Applies a force impulse.
+## If [param global] is [code]false[/code], the impulse is relative to the bone pose.
+## If [param global] is [code]true[/code], the impulse is global.
 func apply_impulse(impulse: Vector3, global := false) -> void:
 	if global:
 		impulse = _global_to_pose * impulse
 
 	_point_mass.apply_force(impulse)
 
 
+## Resets the pose and movement.
 func reset() -> void:
 	if _skeleton:
 		_skeleton.set_bone_global_pose_override(_bone_idx, Transform3D(), 0.0)

addons/wigglebone/wiggle_position_gizmo_plugin.gd

@@ -68,7 +68,7 @@ func _redraw(gizmo: EditorNode3DGizmo) -> void:
 	var node: DMWBWigglePositionModifier3D = gizmo.get_node_3d()
 	var properties: DMWBWigglePositionProperties3D = node.properties
 
-	if not properties:
+	if not properties or not node.bones:
 		return
 
 	var handle_position := _get_handle_position(properties)