Creating a new Puppetshop Limb

From Tech Artists Wiki

Jump to: navigation, search

With the plethora of rigging options in Puppetshop, it is not often you will have a rig you need a custom bodypart for. The one exception I found was Puppetshop's Dog Leg, though I am sure there are other areas you and your animators will find. Here I will walk you through creating a new Puppetshop limb (a Dog Leg) on the high level- I won't include actual code because, as you will find out, it is pretty irrelevant to what is discussed here (which is a good thing!).

I hope, after reading this tutorial, you will have the courage to embark on modifying and expanding Puppetshop for yourself. It is a truly remarkable piece of software that makes animating in Max bearable and 'rigging' in Max (if you can call building puppets rigging) almost painless.


Design and Prototype

What can't the existing limbs do?

Puppetshop's only significant drawback, I've found, is that all rigs are IK, FK, or IK/FK blend. There is not the option to do both at the same time. For an example, create a Puppetshop Dog Leg (a 3-bone leg with the Dog Leg option checked), and create a Biped and give it a third leg bone to create a dog leg. You will see that the results are hugely different. The main difference is that the Biped leg is IK with the handle in the Ankle, and the lower calf is an FK bone. The Puppetshop version is IK with the handle in the Ankle, but the Hip is an FK bone.

This seemingly small difference is actually a huge one. With PS's dog leg, we have essentially an arm- there is IK on the lower bones and FK on the Hip/Clavicle. These are two almost independent systems. With the Biped dog leg, we have essentially an FK bone thrown into the middle of an IK system. This is incompatible with Puppetshop's IK/FK/Blend setup, which means we'll need some significant changes.

What does the new limb need to do?

Using Biped as an example gave me a functional version of what I needed to achieve. This was valuable because it allowed the animators to say 'yes I want something like that.' However, now came the fun part, to figure out how to build the rig by hand. I used Max Bones and helpers and created a Bone version that worked just like the Biped version (including the lack of a swivel object). At this point, I also created a script to build it automatically, but this was unnecessary, it was mainly for my own rigging experience (I was and am not experienced in Max custom rigging). I now had a working prototype and could start thinking about getting it into Puppetshop.

Where does the limb fit into PuppetShop?

You have a couple options when creating a new limb/rig in Puppetshop, ranging from completely integrated to overwriting. For the dog leg, I just chose to overwrite Puppetshop's dog leg. However, if you were making something like a Wing, you'd either want to add a checkbox/more options to an existing bodypart (such as an Arm), or add an entirely new bodypart (Kees has some docs about doing this included with PS). I won't go into this, because I haven't done it- I will keep with what I did for the Dog Leg.

Creating the Rig

Understand how Rigging in Puppetshop works

Rigging in PS works almost exactly like rigging with some rigging scripts you wrote. The only differences are:

  • Using PS functions you use to create things (Nulls instead of Helpers, etc).
  • Using PS functions to turn your rig into one that supports PS features, such as layers.

To understand best how a rig works, you will need to read through the code yourself. I started with the bigger concepts and worked my way down: ignore anything with Toes, for example, and isolate what does what to what bones and what controllers. Generally things are well ordered and the script doesn't jump around, just like a good custom rigging script- you should be able to follow it, if you ignore things such as the complex animated pivot, toe functions, and swivel options. Just get the bare bones, that is all you will need, because most of the script will be your own (it won't be a copy and paste job).

Useful Functions

I originally intended to put commonly used functions here, but I didn't. They are pretty easy to discern how to use from the existing PS code and their names. They are also documented in the PuppetShop API. Finally, if you don't understand what one does, just ask Kees. There are less than a dozen you will need to actively use to rig (such as setting names, creating nulls, and creating controls), most of the rest can just be copied and pasted to work with your new rig part after you are about done rigging (such as 'setStoreNode', 'addAnimLayers', etc.).

Writing the Rigging Script

I can't help you here with writing the rigging script. It will really be, at this step, a standard rigging script, converted to use some PS functions. The difficulty of this step has little to do with PS and more to do with how good you are at rigging- in fact, given the existing PS code and samples, this may be easier than normally writing a rigging script.

I could go through some example code here to explain my rigging, but I think it'd be pretty unnecessary, and only applicable to my dog rig. Once you get into the code, you will see that creating your custom rig in PS is little different from creating a custom rig outside of it.

IK and FK

As mentioned before, PS's bodyparts are built between IK, FK, and Blending between them. The Dog Leg, however, does not behave like that. I only created FK controls for the bones I needed to be FK (the ankle and lower calf). The hip and upper calf are IK-only. It is important to keep this in mind when rigging, because PS's existing rigs don't work this way. In my case I add FK controls only to the bones that need it.


Testing the script can be a pain. To test, I would exit Max and restart. I don't suggest doing this, since you cannot undo things this way, and it takes a while. You are better off modifying the Puppetshop startup script so that you can run it and Puppetshop will reload (in order to not screw stuff up, if PS is already loaded it won't load again). I would suggest asking Kees Rijnen on the Lumonix Forum about it.

Finalizing the Rigging Script

Improvements and Refinements

At this point, you should have a basic bodypart. In the case of the Dog Leg, it was a 3-bone leg, with a foot, that behaved like Biped's. I also used a controller for the swivel (that 4-arrow shape) instead of a swivel target. Now, you should go back in and add in things you may have taken out, like Toe/Reverse Heel/Heel controls, Toes, etc. You can do this by copying PuppetShop code and slightly modifying it to work with the new Bodypart. For my Toes, I barely needed to modify any of it to get them working. Also, make sure to keep testing it as you add in stuff. The code can be very long and you don't want to break stuff.

Unifying it with PuppetShop

Once your rig is done, you need to do two things for each controller- 'register' it with the Puppet, and assign it layers. There are some neat functions for this that make this step painless and very simple (I mention these above). Kees goes over what these functions do in the Puppetshop API, and they are easy enough to identify from the code. For example, use the function "ps_rig.addAnimLayers" to add all the list and animation controllers to a node. This is something I do at the end of the rigging process, since the controller should not transform at all after the addAnimLayers is run (or it will throw off your BasePose).

More Testing

I don't tend to test out my tools as much as I should, but I was sure to test the dog leg as much as possible. Remember, this will be part of a rig that needs to work, that once animation starts will be a big pain to fix. Make sure it works, make sure the animators spend enough time testing it for bugs and improvements.

Expanding your Bodypart

A new bodypart, especially one that doesn't conform to Puppetshop's way of doing things, will require some extra things to augment some PS features.


Tragically, custom bodyparts will take substantial work to integrate with Motion Capture. The BVH will export fine, but since we do not use just IK or just FK controllers, but both, the Constraint system will not work correctly. I had to build a custom mirroring function that doesn't use BVH at all (it does a much more traditional, but very robust, animation mirroring, and to be quite honest I like it better than the BVH constraining and hope to replace the BVH mirroring). It is probably possible to adjust the constraint system to work with your bodypart, but I haven't done that. Rig mirroring will be another tutorial, since it is quite separate from Puppetshop bodyparts.

Personal tools