vlazed Group Body Modifiers

Grouped Body Modifiers

Warning

Due to the volatile nature of the beta, the following content is subject to deprecation.

This version contains modifiers for animating a group of physical bones (grouped bone timelines or GBTs). The list is as follows

• Lower Body: Animate lower body parts, including the root bone
• Upper Body: Animate upper body parts, excluding the root bone
• Root Physics: Animate root bones only.
• Child Physics: Animate child bones of root bones only, excluding the root bone
• (Body Template): A modifier meant to be implemented by another modifier. The custom modifiers above all derive this modifier)

These differ from the Physical Bones modifier in that it does not record the transforms of all physics bones. Instead, it records the transforms of a group of physics bones, and stores their keyframes within that group.

This feature achieves separation of an animation between different parts of a character's body. For example, the lower body can be responsible for moving a character in a walk cycle, while the upper body could be used for other actions.

Usage

Animation

To animate with these modifiers, do the following:

1. Open the properties menu
2. Add new timelines for the modifiers that you want to work with
3. Check the specified modifier for each timeline (for instance, Timeline 2 will contain Lower Body, and TImeline 3 will contain Upper Body)
4. Optionally, disable the Physical Bone modifier in any timeline
5. Optionally, make a new timeline preset for convenience

To "export" your animation onto the original Physical Bone modifier for others to use, open the properties menu again, and then:

1. Add a timeline and check the Physical Bone modifier, along with other modifiers that you've worked with
2. Set smh_enablephysbake 1
3. Record at each keyframe on the timeline (using a macro can make this easy). Alternatively, you can use the Physics Recorder.
4. Set smh_enablephysbake 0

To clean up your keyframes from the custom modifiers after baking,

1. Add a timeline and set it to all the body modifiers you've used
2. Remove each keyframe

Physics Bones

Animating with these modifiers comes with some inconsistencies with physical bones, which make it difficult to select bones using tools like Ragdoll Mover. To overcome this, you can do one of the following:

• Use Ragdoll Unstretch on the ragdoll
• Use Ragdoll Mover's Reset +Children Position option
• Set smh_unstretch_sync 1. See this page for more info.

Model compatibility

Unlike the Physical Bone modifier, the custom modifiers need explicit support for different models.

The custom modifiers search the following directories in your garrysmod/data folder:

• Lower Body: smh_lowerbodies
• Upper Body: smh_upperbodies
• Root Physics: smh_rootphysics
• Child Physics: smh_childphysics

These directories contain text files with a list of physical bone names. These bone names may be leaf bones: that is, bones without child bone. For example, read a snippet of the smh_upperbodies/valve.txt file:

bip_head
bip_hand_L
bip_hand_R

Note

It is fine to specify a non-leaf bone. For instance, you can use bip_foot_L in addition to bip_toe_L for compatibility with different physics models

Warning

You may specify every bone in the text file. A custom modifier that reads all physical bones in the text file essentially mimics the original Physical Bone modifier

You can then specify the bones of your model to allow these modifiers to work on them.

The custom modifiers record the transforms starting from the leaf bone, and moves up to its parent bone (e.g. bip_head to bip_neck to bip_spine_2) until it reaches its root bone or the bone nearest to the root bone (depending on the modifier used).

Authoring your own modifiers

This repo comes with the bodytemplate.lua modifier. This is what all physical bone custom modifiers must use. You can make your own by doing the following:

1. Copy one of the custom modifiers (e.g. copy lowerbody.lua) and rename it to the name of your modifier
2. Open your modifier in a text editor, and change the modName = ... variable to the filename of your modifier
3. Go to the bottom of the modifier file, and change MOD.Name to a short, fancier name of your filename
4. Modify MOD.SetRoot if you want your modifier to move bones like pelvis bones
5. Reload your modifiers by reloading the GMod session (map change, running reload) (alternatively, if you are using my fork, run smh_refreshmodifiers)

Tip

If you know your modifier moves the root, you should indicate it in MOD.Name e.g. Lower Body (moves root)

Warning

When animating, you should have only one modifier checked that moves the root. Attempting to use multiple modifiers that move root bones will result in one modifier overpowering another

Remarks

• You should use these modifiers for ragdolls. Prefer using the original Physical Bone modifier for physics props, effect props, camera props, or similar.

Rational

Individual bone timelines (IBTs) enables an animator to manipulate one or a set of bones independently from each frame. It allows for animations such as gestures layered on walk or run cycles. Current versions of Stop Motion Helper as of April 11, 2026 lack this feature. Hence, animators must refer to multiple workarounds to achieve this level of complexity. For instance, one would need to use another animation tool (such as Henry's Aniamtion Tool or Ragdoll Puppeteer) to allow for root motion animations. These methods has its own constraints and does not significantly increase animation flexibility.

To overcome this limitation, this solution instead exploits the knowledge that Physical Bones record all physical bone transforms and provides modifiers that only record a subset of all physical bones. The Root Physics and Child Physics modifier pair allows the animation to occur wholly in Stop Motion Helper, without reliance on external tools. The Lower Body and Upper Body modifier pair is based on a heuristic which assumes that actions on the lower body (e.g. walking) and actions on the upper body (head movements, arm poses, etc.) differ.

These lack the features of true IBTs, where one can manipulate a single bone at a time. This can be achievable theoretically, but it is intractable to achieve this in SMH 4.0's UI without sacrificing ease of use.