FaceFX Support

FaceFX Documentation and support

Script Functions

##

Table of Contents

  1. MEL Script
  2. MAXScript
  3. Functions
    1. fxbatchexportboneposes
    2. fxbatchimportboneposes
    3. fxclean
    4. fxcreateactor
    5. fxcreatenode
    6. fxdeleteallkeys
    7. fxexportbonepose
    8. fxexportrefpose
    9. fxgetactorname
    10. fxgetanimgroups
    11. fxgetanimduration
    12. fxgetanims
    13. fxgetbakedcurvekeyslopein
    14. fxgetbakedcurvekeyslopeout
    15. fxgetbakedcurvekeytimes
    16. fxgetbakedcurvekeyvalues
    17. fxgetbones
    18. fxgetcurves
    19. fxgetnodes
    20. fxgetrawcurvekeyslopein
    21. fxgetrawcurvekeyslopeout
    22. fxgetrawcurvekeytimes
    23. fxgetrawcurvekeyvalues
    24. fxgetrefbones
    25. fximportanim
    26. fximportbonepose
    27. fximportrefpose
    28. fxinsertanimationgroup
    29. fxinsertanim
    30. fxinsertkey
    31. fxisanalysistool
    32. fxisnosave
    33. fxismoddeveloper
    34. fxlinknodes
    35. fxloadactor
    36. fxoutputwindowlog
    37. fxsaveactor
    38. fxsetdisplaywarningdialogs
    39. fxsetnormalizescale
    40. fxsetbipedheadrotation
    41. fxgetbakedanimdata
    42. fxgetrawanimdata
  4. Advanced User Property Functions
    1. fxgetbooluserproperty
    2. fxgetchoiceuserproperty
    3. fxgetnumuserproperties
    4. fxgetrealuserproperty
    5. fxgetstringuserproperty
    6. fxgetuserpropertyname
    7. fxgetuserpropertytype
    8. fxsetbooluserproperty
    9. fxsetchoiceuserproperty
    10. fxsetrealuserproperty
    11. fxsetstringuserproperty

MEL Script

To use the MEL commands, simply make sure the FaceFX.mll plug-in is loaded and call the functions as described below. 

MAXScript

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.

Functions

fxbatchexportboneposes

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";

fxbatchimportboneposes

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";

fxclean

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();

fxcreateactor

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";

fxcreatenode

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;

fxdeleteallkeys

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";

fxexportbonepose

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";

fxexportrefpose

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");

fxgetactorname

Returns the actor name.

Maya:  fxgetactorname;
Max: obj.fxgetactorname();

fxgetanimgroups

Returns an array of strings representing the animation groups present in the actor.

Maya: fxgetanimgroups;
Max: obj.fxgetanimgroups();

fxgetanimduration

Returns the duration in seconds of the specified animation in the specified group.

Maya: fxgetanimduration -group "Default" -anim "welcome";
Max: obj.fxgetanimduration "Default" "welcome";

fxgetanims

Returns an array of strings representing the animations present in the specified animation group.

Maya: fxgetanims -group "Default";
Max: obj.fxgetanims "Default";

fxgetbakedcurvekeyslopein

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";

fxgetbakedcurvekeyslopeout

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";

fxgetbakedcurvekeytimes

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";

fxgetbakedcurvekeyvalues

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";

fxgetbones

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";

fxgetcurves

Returns an array of strings representing the curves present in the specified animation.

Maya: fxgetcurves -group "Default" -anim "welcome";
Max: obj.fxgetcurves "Default" "welcome";

fxgetnodes

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";

fxgetrawcurvekeyslopein

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";

fxgetrawcurvekeyslopeout

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";

fxgetrawcurvekeytimes

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";

fxgetrawcurvekeyvalues

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";

fxgetrefbones

Returns an array of strings representing the names of all bones in the rest pose in the current actor.

Maya: fxgetrefbones;
Max: obj.fxgetrefbones();

fximportanim

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

fximportbonepose

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";

fximportrefpose

Imports the rest pose to the specified frame.

Maya: fximportrefpose -frame 0;
Max: obj.fximportrefpose 0;

fxinsertanimationgroup

Inserts a new animation group.

Maya: fxinsertanimationgroup -group "NewGroup";
Max: obj.fxinsertanimationgroup "NewGroup";

fxinsertanim

Inserts a new animation.

Maya: fxinsertanim -group "Default" -anim "welcome"
Max: obj.fxinsertanim "Default" "welcome";

fxinsertkey

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;

fxisanalysistool

Returns true if the plugin can support analyzing audio and generating new animations.

Maya: fxisanalysistool;
Max: obj.fxisanalysistool;

fxisnosave

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;

fxismoddeveloper

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;

fxlinknodes

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);

fxloadactor

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";

fxoutputwindowlog

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";

fxsaveactor

Saves the current actor file to disk.

Maya: fxsaveactor -file "C:\\Slade.facefx";
Max: obj.fxsaveactor "C:\Slade.facefx";

fxsetdisplaywarningdialogs

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";

fxsetnormalizescale

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";

fxsetbipedheadrotation

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";

fxgetbakedanimdata

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");

fxgetrawanimdata

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";

Advanced User Property Functions

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.

fxgetbooluserproperty

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;

fxgetchoiceuserproperty

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;

fxgetnumuserproperties

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";

fxgetrealuserproperty

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;

fxgetstringuserproperty

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;

fxgetuserpropertyname

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;

fxgetuserpropertytype

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;

fxsetbooluserproperty

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";

fxsetchoiceuserproperty

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";

fxsetrealuserproperty

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;

fxsetstringuserproperty

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";