FaceFX Documentation and support
##
Table of Contents
To use the MEL commands, simply make sure the FaceFX.mll plug-in is loaded and call the functions as described below.
To use the MAXScript commands, you need to create a FaceFX object. This can be done as follows from a Max Script window:
obj = FaceFX();
Once created, all of the MAXScript functions described can be called by referencing the FaceFX object. The order of the parameters matches the order provided in the Maya function example.
Exports all of the poses in the batch export text file to the actor
Maya: fxbatchexportboneposes -file "C:\\batch-file.txt";
Max: obj.fxbatchexportboneposes "C:\batch-file.txt";
Imports all of the poses in the batch export text file from the .facefx file into Max or Maya.
Maya: fxbatchimportboneposes -file "C:\\batch-file.txt";
Max: obj.fxbatchimportboneposes "C:\batch-file.txt";
Imports the rest pose to frame 0 and deletes all other animation data on the bones specified in the rest Pose. This function also sets a key with time=0 and value=0 for all morph targets that have the same name as a node in the face graph.
Maya: fxclean;
Max: obj.fxclean();
Creates an actor. This is the first step to getting your character talking in FaceFX. The name is not the name of the file, but rather the name that is used internally by FaceFX.
Maya: fxcreateactor -name "Slade";
Max: obj.fxcreateactor "Slade";
Creates a Face Graph node of the specified type with the specified node minimum and maximum values. FxMorphTargetNodes created with this function will automatically have the “Morph Target Name” user property set to the name of the node so that it can drive Ogre morph targets inside of FaceFX Studio.
Maya: fxcreatenode -nodename "newNode" -nodetype "FxCombinerNode" -nodemin 0 -nodemax 1;
Max: obj.fxcreatenode "newNode" "FxCombinerNode" 0 1;
Deletes all keys in the specified curve.
Please be aware that any changes made to curves that are owned by analysis will be lost if the .facefx file is loaded back up into FaceFX Studio.
Maya: fxdeleteallkeys -group "Default" -anim "welcome" -curve "Eat";
Max: obj.fxdeleteallkeys "Default" "welcome" "Eat";
Exports the specified bone pose from the specified frame. Any bones that have identical position, rotation, and scale values with respect to the rest pose are pruned out from the exported pose.
Maya: fxexportbonepose -frame 10 -name "open";
Max: obj.fxexportbonepose 10 "open";
Exports the rest pose for the actor. The bones contained in the rest pose are specified along with the frame to export from. The positions, rotations, and scales of these bones are recorded at the specified frame and used to create the rest pose. If the actor already has a rest pose, the existing pose is overwritten.
The rest pose is important for the following reasons:
Maya: fxexportrefpose -frame 0 -bones "BN_Root BN_Head";
Max: obj.fxexportrefpose 0 #("BN_Root", "BN_Head");
Returns the actor name.
Maya: fxgetactorname;
Max: obj.fxgetactorname();
Returns an array of strings representing the animation groups present in the actor.
Maya: fxgetanimgroups;
Max: obj.fxgetanimgroups();
Returns the duration in seconds of the specified animation in the specified group.
Maya: fxgetanimduration -group "Default" -anim "welcome";
Max: obj.fxgetanimduration "Default" "welcome";
Returns an array of strings representing the animations present in the specified animation group.
Maya: fxgetanims -group "Default";
Max: obj.fxgetanims "Default";
Returns an array of input slopes for the specified curve in the specified group and animation. The returned curve is baked. The function returns an empty array if the curve can’t be found.
Maya: fxgetbakedcurvekeyslopein -group "Default" -anim "welcome" -curve "open";
Max: obj.fxgetbakedcurvekeyslopein "Default" "welcome" "open";
Returns an array of output slopes for the specified curve in the specified group and animation. The returned curve is baked. The function returns an empty array if the curve can’t be found.
Maya: fxgetbakedcurvekeyslopeout -group "Default" -anim "welcome" -curve "Eat";
Max: obj.fxgetbakedcurvekeyslopeout "Default" "welcome" "Eat";
Returns an array of key times (in seconds) for the specified node in the specified group and animation. The returned curve is baked. The function returns an empty array if the node or animation can’t be found.
Maya: fxgetbakedcurvekeytimes -group "Default" -anim "welcome" -curve "Eat";
Max: obj.fxgetbakedcurvekeytimes "Default" "welcome" "Eat";
Returns an array of key values for the specified node in the specified group and animation. The returned curve is baked. The function returns an empty array if the node or animation can’t be found.
Maya: fxgetbakedcurvekeyvalues -group "Default" -anim "welcome" -curve "Eat";
Max: obj.fxgetbakedcurvekeyvalues "Default" "welcome" "Eat";
Returns an array of strings representing the names of all the bones contained in a given pose. If a bone is present in a pose, it means that there is a difference between the bone’s translation in the rest pose and the bone’s translation in the specified pose.
Maya: fxgetbones -name "open";
Max: obj.fxgetbones "open";
Returns an array of strings representing the curves present in the specified animation.
Maya: fxgetcurves -group "Default" -anim "welcome";
Max: obj.fxgetcurves "Default" "welcome";
Returns an array of strings representing the names of all the nodes of the specified type in the actor.
Maya: fxgetnodes -type "FxBonePoseNode";
Max: obj.fxgetnodes "FxBonePoseNode";
Returns an array of input slopes for the specified curve in the specified group and animation. The returned curve is raw. The function returns an empty array if the curve can’t be found.
Maya: fxgetrawcurvekeyslopein -group "Default" -anim "welcome" -curve "Eat";
Max: obj.fxgetrawcurvekeyslopein "Default" "welcome" "Eat";
Returns an array of output slopes for the specified curve in the specified group and animation. The returned curve is raw. The function returns an empty array if the curve can’t be found.
Maya: fxgetrawcurvekeyslopeout -group "Default" -anim "welcome" -curve "Eat";
Max: obj.fxgetrawcurvekeyslopeout "Default" "welcome" "Eat";
Returns an array of key times for the specified curve in the specified group and animation. The returned curve is raw. The function returns an empty array if the curve can’t be found.
Maya: fxgetrawcurvekeytimes -group "Default" -anim "welcome" -curve "Eat"
Max: obj.fxgetrawcurvekeytimes "Default" "welcome" "Eat";
Returns an array of key values for the specified curve in the specified group and animation. The returned curve is raw. The function returns an empty array if the curve can’t be found.
Maya: fxgetrawcurvekeyvalues -group "Default" -anim "welcome" -curve "Eat"
Max: obj.fxgetrawcurvekeyvalues "Default" "welcome" "Eat";
Returns an array of strings representing the names of all bones in the rest pose in the current actor.
Maya: fxgetrefbones;
Max: obj.fxgetrefbones();
Imports the specified animation into the timeline starting at frame 0. All bones in the rest pose will get position, rotation, and scale keys at every frame (similar to raw motion capture data). Any morph targets in the scene that that have the same name as a node in the face graph will be driven by a curve that represents that node’s value over time.
Maya: fximportanim -group "Default" -anim "welcome" -framerate 30 -audioStartTime 0
Max: obj.fximportanim "Default" "welcome" 30 0
Imports the specified bone pose to the specified frame, inserting keys for all bones in the rest pose at that frame.
Maya: fximportbonepose -frame 10 -name "open";
Max: obj.fximportbonepose 10 "open";
Imports the rest pose to the specified frame.
Maya: fximportrefpose -frame 0;
Max: obj.fximportrefpose 0;
Inserts a new animation group.
Maya: fxinsertanimationgroup -group "NewGroup";
Max: obj.fxinsertanimationgroup "NewGroup";
Inserts a new animation.
Maya: fxinsertanim -group "Default" -anim "welcome"
Max: obj.fxinsertanim "Default" "welcome";
Inserts a key into the specified curve at the specified frame. The function will create the curve if it doesn’t exist, but the group and animation must be present or the function will fail. On success, the index of inserted key is returned. On failure, -1 is returned.
Please be aware that any changes made to curves that are owned by analysis will be lost if the FaceFX is loaded back up into FaceFX Studio.
Maya: fxinsertkey -group "Default" -anim "welcome" -curve "Eat" -frame 10 -value 0.82 -inslope 0.0 -outslope 0.0;
Max: obj.fxinsertkey "Default" "welcome" "Eat" 10 0.82 0.0 0.0;
Returns true if the plugin can support analyzing audio and generating new animations.
Maya: fxisanalysistool;
Max: obj.fxisanalysistool;
Returns true if the plugin has been built with saving capabilities turned off. No-save versions of FaceFX Studio and the tools allow OC3 Entertainment to distribute free trials of the software.
Maya: fxisnosave;
Max: obj.fxisnosave;
Returns true if the plugin has been built for mod developers. Mod developer plugins can not import animation data using the tools. They can only be used to define now bone poses.
Maya: fxismoddeveloper;
Max: obj.fxismoddeveloper;
Creates a link between two nodes in the face graph. The link function parameters is an array of floats. In Maya, this is specified using a space-seperated array of strings. The order of the parameters is the same as used in FaceFX Studio’s link function editor dialog.
Maya: fxlinknodes -fromnode "node1" -tonode "node2" -linkfntype "linear" -linkfnparams "1.0, 0";
Max: obj.fxlinknodes "node1" "node2" "linear" #(1.0, 0);
Loads an existing actor file (*.facefx) from disk. Only one actor can be loaded at a time.
Maya: fxloadactor -file "C:\\Slade.facefx";
Max: obj.fxloadactor "C:\Slade.facefx";
Toggles if FaceFX logs to the Output Window. To turn it on, set the toggle flag to “on”. To turn it off, set the toggle flag to anything else. Output always goes to the FaceFX_Log.txt file in the main Maya install directory.
Maya: fxoutputwindowlog -toggle "on";
Saves the current actor file to disk.
Maya: fxsaveactor -file "C:\\Slade.facefx";
Max: obj.fxsaveactor "C:\Slade.facefx";
Toggles if warning dialog boxes are displayed. If you want to perform an operation from script, this function can be useful to make sure that the script does not require user intervention. Warning dialog boxes are on by default because they alert the user of common problems and mistakes. To turn it on, set the toggle flag to “on”. To turn it off, set the toggle flag to anything else.
Maya: fxsetdisplaywarningdialogs -toggle "on";
Max: obj.fxsetdisplaywarningdialogs "on";
Sets the normalize scale option. When Normalize scale is on, all scale values will be neutralized when exporting the rest pose or bone poses. To turn it on, set the toggle flag to “on”. To turn it off, set the toggle flag to anything else.
Max: obj.fxsetnormalizescale "on";
Sets the biped head rotation option, which is on by default. When Biped head rotation is on, FaceFX will attempt to key the biped head bone if it is included with the rest pose. Keying the Biped head bone involves automatically removing any selected biped mode (like figure mode, footsteps, etc). If you don’t want this to occur, turn this option off and FaceFX will not attempt to key any biped bones.
Max: obj.fxsetbipedheadrotation "on";
Returns an array of floats representing baked animation data keys for the given nodes, animation, and animation group. The first returned float represents the number of curves returned (always the same as the number of node names passed in). The next returned float represents the number of keys in the first curve, followed by 4x that number of floats with each group of 4 floats representing the time, value, inslope, and outslope values for a single key. The data for subsequent curves follows in a similar fashion.
Maya: fxgetbakedanimdata -group "Default" -anim "welcome" -nodes "node1|node2";
Max: obj.fxgetbakedanimdata "Default" "welcome" #("node1", "node2");
Returns an array of floats representing raw animation data keys for all curves in the given animation. The first returned float represents the number of curves returned. The next returned float represents the number of keys in the first curve, followed by 4x that number of floats with each group of 4 floats representing the time, value, inslope, and outslope values for a single key. The data for subsequent curves follows in a similar fashion.
Maya: fxgetrawanimdata -group "Default" -anim "welcome";
Max: obj.fxgetrawanimdata "Default" "welcome";
Face Graph user properties are not used extensively. FxMorphTargetNodes have a string user property called “Morph Target Name” that is used in FaceFX Studio to match up the node name with the morph target in Ogre. FxMaterialParameterNodes have 3 string user properties with the following names “Material Name”, “Pass Name” and “Parameter Name”. Unreal-specific material and morph nodes also use face graph node user properties to specify Unreal-specific information.
Although this system is not extensively used in FaceFX, full access to the user property system is provided in Max, Maya and XSI via the below functions.
Accepts the node name and user property index as input. Returns false if the node doesn’t exist, the user property doesn’t exist, or the user property is not of the correct type.
Maya: fxgetbooluserproperty -node "node1" -index 0;
Max: obj.fxgetbooluserproperty "node1" 0;
Accepts the node name and user property index as input. Returns an empty string if the node doesn’t exist, the user property doesn’t exist, or the user property is not of the correct type.
Maya: fxgetchoiceuserproperty -node "node1" -index 0;
Max: obj.fxgetchoiceuserproperty "node1" 0;
Accepts the node name as input. Returns an 0 if the node doesn’t exist. Otherwise returns the number of user properties that the node has.
Maya: fxgetnumuserproperties -node "node1";
Max: obj.fxgetnumuserproperties "node1";
Accepts the node name and user property index as input. Returns an 0 if the node doesn’t exist, the user property doesn’t exist, or the user property is not of the correct type.
Maya: fxgetrealuserproperty -node "node1" -index 0;
Max: obj.fxgetrealuserproperty "node1" 0;
Accepts the node name and user property index as input. Returns an empty string if the node doesn’t exist, the user property doesn’t exist, or the user property is not of the correct type.
Maya: fxgetstringuserproperty -node "node1" -index 0;
Max: obj.fxgetstringuserproperty "node1" 0;
Accepts the node name and user property index as input. Returns the name of the userproperty at index.
Maya: fxgetuserpropertyname -node "node1" -index 0;
Max: obj.fxgetuserpropertyname "node1" 0;
Accepts the node name and user property index as input. Returns “Integer”, “Bool”, “Real”, “String”, “Choice”. If the node or user property doesn’t exist, “Invalid” is returned.
Maya: fxgetuserpropertytype -node "node1" -index 0;
Max: obj.fxgetuserpropertytype "node1" 0;
Accepts the node name, user property index, and value as input. Set the value to “on” for true, anything else for false.
Maya: fxsetbooluserproperty -node "node1" -index 0 -value "on";
Max: obj.fxsetbooluserproperty "node1" 0 "on";
Accepts the node name, user property index, and value as input.
Maya: fxsetchoiceuserproperty -node "node1" -index 0 -value "choice1"
Max: obj.fxsetchoiceuserproperty "node1" 0 "choice1";
Accepts the node name, user property index, and value as input.
Maya: fxsetrealuserproperty -node "node1" -index 0 -value 2.7
Max: obj.fxsetrealuserproperty "node1" 0 2.7;
Accepts the node name, user property index, and value as input.
Maya: fxsetstringuserproperty -node "node1" -index 0 -value "newString"
Max: obj.fxsetstringuserproperty "node1" 0 "newString";