See the changelog here

Hello all! I hope your day or evening is well. Here is what I consider to be the final big update from me for Ragdoll Puppeteer: animation retargeting! This one was in the backburner for a long time, but I was able to accomplish this, 7 months of making and testing this out. There are also a couple of small features that I've added to this one. I will go down the list and get you all up to speed on the new changes.

I did not expect myself to accomplish this feature for Ragdoll Puppeteer. Regardless, I persevered, and here we are: a functional animation retargeting feature for Ragdoll Puppeteer.

Animation retargeting works in the same principle as Animated Props' remapping feature: roughly speaking, an animation from one entity (the puppeteer) can be played on another puppet. To give examples, an HL2 puppeteer (such as male_07.mdl or kleiner.mdl) can play its walk or run cycles on a TF2 puppet (such as Heavy), or the GMod playermodel, combined with Dynabase and its animations, can be played on a L4D character (such as Francis).

Despite these combinations, there are requirements for animation retargeting to work, to repeat from the video:

1. A bonemap must exist between a puppeteer's boneset and a puppet's boneset
   
2. The retargeting must happen in singleplayer.

I have yet to find a good way to do retargeting in multiplayer. This is a problem that I will address in the next version of Ragdoll Puppeteer.

From the first point, a bonemap is a text file that consists of a pair of bone names, separated line by line. They look like this:
Bonemaps are two-way, which means that "ValveBiped.Bip01_R_Thigh,bip_hip_R" is also a defined pair. Hence, a second bonemap going the other way around is redundant.

Bonemaps allow puppeteers to translate their animations from one boneset to the puppet's boneset and apply its pose on the correct limb. The right thigh of the puppeteer should drive the right thigh of the puppet. Bonemaps are key in successfully retargeting an animation.

You can make your own bonemaps by accessing the Utilities > Ragdoll Puppeteer > Bone Map Generator tool in the spawnmenu. This tool is self-explanatory, and the video goes over how to use it in more detail. Once you have a bonemap made, you can use the `ragdollpuppeteer_refreshbones` console command to allow Ragdoll Puppeteer to detect your newly made bone map.

Nonetheless, not all successful retargets look natural. As seen in the video, some animations require corrections with the Pose Offsetter. Most SMH animations between characters are not feasible at all. To ensure animation retargets look natural from a puppeteer to a puppet, follow these rules of thumb for natural retargets:

1. Retarget animations between characters in the same universe with almost the same number of physics bones.
   
2. Retarget animations between characters in the same universe. These tend to have the same reference (A or T) pose, and their bone orientations tend to be consistent
   
3. Retarget animations between characters with the same reference pose. I restate this because while their reference pose are the same, their bone orientations may not be consistent
   
4. Retarget animations between characters with Valve bonesets. Reference poses and bone orientations may not be consistent, but a remapping exists.

The points here are ordered by descending likelihood of achieving a natural animation retarget, with the first point being the highest likelihood. You can easily achieve this with a number of ways, such as using your own playermodel to retarget player animations, or using another model with the same reference pose.

The video and the explanation above may not cover everything about the feature. I leave this up to you to mess around with.

In addition to the updates above, I have also addressed some concerns with Ragdoll Puppeteer in the following bulletpoint list

• Locomotion animations (running, walking, etc.) now adjust pose parameters automatically. Previously, this was not the case, which was the main confusing point with this addon. This behavior can be changed with `ragdollpuppeteer_autopose_locomotion`.
  
• SMH animations can be played on any model, other than the puppet's model. Look for this checkbox in the Stop Motion Helper tab in the Ragdoll Puppeteer settings,
  
• When selecting an entity, sequence lists now load over time, instead of all at once. Loading sequences should not take up the time to get into posing, which was a blatant issue with the GMod playermodels and its increasing number of sequences.
  
• Disable sequence sounds with a custom `prop_puppeteer` entity.
  
• Optimizations and tool restructuring

I mentioned in the beginning that this will be the final big update for Ragdoll Puppeteer. Despite this, there are still some features that I have not addressed: to name a few, multiple puppeteers, multiplayer support, and an implementation to retarget SMH animations. I plan to make these a possibility in the future, though not as an update for Ragdoll Puppeteer, but as part of Ragdoll Puppeteer 2, a planned rewrite of this tool.

Why am I pushing back on these features? I think that the tool is at a good state where big updates would not be necessary. I added all the features that I wanted in this addon, and the need to develop this further will take up time for other projects that I want to do.

I will still answer questions and troubleshoot, adapt this addon to new GMod updates, fix bugs, and add small features. I will go no further as to maintain this addon, so if you happen to read this and wish for something big with this addon, I'll add it in the todo list of Ragdoll Puppeteer 2!

As always, let's try to report any potential bugs from these features, so we can continue to improve the tool further. Of course, you can view some of the other features here[github.com]. And if you do have a problem with using this tool, feel free to make a discussion post on here. That way, I will be able to help troubleshoot and find a solution for your problem.