Troubleshooting

Step 1. Verify your license

Each time you create an HIKCharacter, you must supply a runtime license key that is verified internally before HumanIK returns to you a pointer to the newly created HIKCharacter object. If this license key is not set up correctly, or if the key provided to you has expired (typically, when you exceed the limit of your pre-determined evaluation period), the HumanIK inverse kinematics and retargeting solvers will generate random, impossible positions for your characters.

An expired license may be the cause if your problem with HumanIK occurs suddenly in a situation where the HumanIK solvers previously gave good results, and if similar results occur every time you call the HumanIK solvers.

You must ensure that you have correctly followed the instructions under Setting Up the HumanIK License Key. If your runtime license key has expired, contact Autodesk Support, and request a new license key for your project. See Support.

Step 2. Use the Verbose library

On Windows platforms, the HumanIK library is available in a Verbose configuration that offers you the possibility of logging errors and warnings encountered during the characterization and solving processes, as well as access to the HumanIK callstack if desired.

Linking to this version of the library during your development process and monitoring the output periodically for warnings and errors can help to diagnose problems that may manifest themselves in the poses generated by the HumanIK solvers. For details, see Logging Debug Messages.

Step 3. Troubleshooting failed character creation

If a call to HIKCharacterCreate() or HIKCharacterCreateInPlace() returns a null pointer, you most likely have a problem with either your runtime license key or with the Nodes you have set up in your character definition.

To determine the cause of the problem, you can pass your HIKCharacterDefinition to the validation functions defined in hikvalidation.h: HIKValidateRequiredBone(), HIKValidateSpine() and HIKValidateNeck(). If any of these functions return false, check the error string they generate to determine the cause of the problem.

Alternatively, if you use the verbose build of the HumanIK library, you can call HIKValidateHierarchy(), which calls the above functions in sequence and writes any errors they generate to the log.

If the validation functions described above indicate that no problems could be found with your character definition, your runtime license key may have expired. If so, contact Autodesk Support, and request a new license key for your project. See Support.

Step 4. Troubleshooting failed characterization

If a call to HIKCharacterizeGeometry() returns false, you most likely have a problem with the T-stance that you have set up for your character.

To determine the cause of the problem, you can pass your HIKCharacter to the validation functions defined in hikvalidation.h: HIKValidateHipsXAxis(), HIKValidateArmsXAxis(), HIKValidateSpineYAxis() and HIKValidateBonePosition(). If any of these functions return false, check the error string they generate to determine the cause of the problem.

Alternatively, if you use the verbose build of the HumanIK library, you can call HIKValidateGeometry(), which calls the above functions in sequence and writes any errors they generate to the log.

Step 5. Verify your data flow

Using HumanIK necessarily involves a bi-directional flow of animation data between your game engine and HumanIK. Each time you call a HumanIK solver to create a new pose for a character, you typically must retrieve the positions and orientations of the joints in your character’s skeleton from your game engine, and store that information in an HIKCharacterState in a format understood by HumanIK. Similarly, you must retrieve the pose generated by the HumanIK solver from an HIKCharacterState, and transfer that information back into your game engine.

Once put into place, this bi-directional data flow becomes transparent to the process of using HumanIK, but it can be challenging to set up for the first time. For details on the various different functions available in HumanIK for setting and retrieving animation data in HIKCharacterStates and HIKEffectorSetStates, see Setting and Retrieving Animation Data.

Verify to the best of your ability that your game engine is translating data correctly as it exchanges character poses with HumanIK. One possible approach to check for problems:

1. Set up the Nodes of an HIKCharacterState with the translations and orientations of one of your characters.
2. Before calling one of the HumanIK solvers, immediately retrieve the Node data and re-apply it to the character in your game engine.

You should see exactly the same pose that you sent in. If you do not see exactly the same pose you began with from your game engine, you have a problem with either the way you set data in your HIKCharacterState, the way you retrieve data from the HIKCharacterState, or both.

Step 6. Verify your character properties

If your character’s default stance is good, and if your data flow transfers all animation data reliably between your game engine and HumanIK, your problem may be due to unexpected values set for one or more character properties in your character’s HIKPropertySetState.

Try repeating your problematic operation with a newly created HIKPropertySetState that contains default values for all properties. If this resolves the issues you are having, try adding back any property values you had previously set one-by-one, until you find the property settings that are causing the unexpected behavior.

Step 7. Contact Autodesk Support

If all of the above steps have failed to correct your problem, and your characters still exhibit unexpected behavior, Autodesk Support engineers are standing by to assist you.

For rapid resolution, you are encouraged to provide as much information as you can about your problem and its context as soon as possible, to help the assigned engineer understand your situation and identify possible avenues for addressing the problem. For example, the following items of information can be invaluable:

• Descriptions of the context in which the problem occurs, including what you are trying to accomplish.
• Images or screen captures that illustrate the problem you are having and the desired results.
• Disk files containing your HIKCharacter, HIKCharacterState, HIKEffectorSetState and HIKPropertySetState, both before and after the problematic call to the HumanIK solver. Your assigned engineer may be able to use these files to reproduce your issue.
• Where possible, the segments of your code in which you initialize your HumanIK objects and call the HumanIK solvers.

For contact information, see Support.