Script Functions



Contents
  1. MEL Script
  2. MAXScript
  3. XSI Scripting
  4. Functions
    1. fxbatchexportboneposes
    2. fxbatchimportboneposes
    3. fxchangeanalysisactor
    4. fxclean
    5. fxcreateactor
    6. fxcreatenode
    7. fxdeleteallkeys
    8. fxexportbonepose
    9. fxexportrefpose
    10. fxgenerateanim
    11. fxgetactorname
    12. fxgetanimgroups
    13. fxgetanimduration
    14. fxgetanims
    15. fxgetbakedcurvekeyslopein
    16. fxgetbakedcurvekeyslopeout
    17. fxgetbakedcurvekeytimes
    18. fxgetbakedcurvekeyvalues
    19. fxgetbones
    20. fxgetcurves
    21. fxgetnodes
    22. fxgetrawcurvekeyslopein
    23. fxgetrawcurvekeyslopeout
    24. fxgetrawcurvekeytimes
    25. fxgetrawcurvekeyvalues
    26. fxgetrefbones
    27. fximportanim
    28. fximportbonepose
    29. fximportrefpose
    30. fxinsertanimationgroup
    31. fxinsertkey
    32. fxisanalysistool
    33. fxisnosave
    34. fxismoddeveloper
    35. fxlinknodes
    36. fxloadactor
    37. fxnewtake
    38. fxoutputwindowlog
    39. fxsaveactor
    40. fxsetdisplaywarningdialogs
    41. fxsetnormalizescale
    42. fxsetbipedheadrotation
  5. 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.

XSI Scripting

Instead of prefixing function names with "fx", in XSI they are prefixed with "FaceFX".  Also the function names have capitalized words ("FaceFXImportBonePose" instead of "fximportbonepose") and the function names can differ slightly from their Max/Maya counterparts. 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";
XSI: FaceFXBatchExportBonePoses "C:\batch-file.txt"

  • Notice that the when specifying a file from MEL Script, you must use two backslash characters as the folder deliminator. This is optional in 3D Studio Max.

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";
XSI: FaceFXBatchImportBonePoses "C:\batch-file.txt"

  • Notice that the when specifying a file from MEL Script, you must use two backslash characters as the folder deliminator. This is optional in 3D Studio Max.

fxchangeanalysisactor

Changes the analysis actor to use during analysis.  Only available in analysis-enabled plugins.  By default, the default.facefx analysis actor is searched for in the FaceFX folder of the plugin

Maya: fxchangeanalysisactor -file "C:\\myAnalysisActor.facefx"
Max: fxchangeanalysisactor "C:\myAnalysisActor.facefx"
XSI: FaceFXChangeAnalysisActor "C:\myAnalysisActor.facefx"

fxclean

Imports the reference pose to frame 0 and deletes all other animation data on the bones specified in the Reference 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();
XSI: FaceFXClean

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";
XSI: FaceFXNewActor "Slade"

fxcreatenode

Creates a Face Graph node of the specified type with the specified node minimum and maximum values.

Maya: fxcreatenode -nodename "newNode" -nodetype "FxCombinerNode" -nodemin 0 -nodemax 1
Max: obj.fxcreatenode "newNode" "FxCombinerNode" 0 1;
XSI: FaceFXCreateNode "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";
XSI: FaceFXDeleteAllKeys "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 reference pose are pruned out from the exported pose.

Maya: fxexportbonepose -frame 10 -name "open";
Max: obj.fxexportbonepose 10 "open";
XSI: FaceFXExportBonePose 10, "open"

fxexportrefpose

Exports the reference pose for the actor. The bones contained in the reference 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 reference pose. If the actor already has a reference pose, the existing pose is overwritten.

The reference pose is important for the following reasons:
  • To save memory, FaceFX only stores the difference between a bone pose and the reference pose. Any bones that do not move in the pose are pruned. For this reason, you may want to re-export your existing bone poses if you change the reference pose.
  • The reference pose determines what bones are included in the FaceFX system. If the bone isn't in the reference pose, FaceFX will not influence it.

Maya: fxexportrefpose -frame 0 -bones "BN_Root BN_Head";
Max: obj.fxexportrefpose 0 #("BN_Root", "BN_Head");
XSI: FaceFXExportRefBonePose 0, "BN_Root, BN_Head"

fxgenerateanim

Generates an animation by opening a browse dialog for the audio.  Only available in analysis-enabled plugins.  Evaluation versions are phrase-locked.

Maya:  fxgenerateanim;
Max: obj.fxgenerateanim();
XSI: FaceFXGenerateAnim

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();
XSI: FaceFXListAnimationGroups

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";
XSI: FaceFXGetAnimDuration "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";
XSI: FaceFXListAnimationsFromGroup "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";
XSI: FaceFXGetBakedCurveKeySlopeIn "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";
XSI: FaceFXGetBakedCurveKeySlopeOut "Default", "welcome", "open"

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";
XSI: FaceFXGetBakedCurveKeyTimes "Default", "welcome", "open"

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";
XSI: FaceFXGetBakedCurveKeyValues "Default", "welcome", "open"

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 reference 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";
XSI: FaceFXGetNodes "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";
XSI: FaceFXGetRawCurveKeySlopeIn "Default", "welcome", "open"

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";
XSI: FaceFXGetRawCurveKeySlopeOut "Default", "welcome", "open"

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";
XSI: FaceFXGetRawCurveKeyTimes "Default", "welcome", "open"

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";
XSI: FaceFXGetRawCurveKeyValues "Default", "welcome", "open"

fxgetrefbones

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

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

fximportanim

Imports the specified animation into the timeline starting at frame 0. All bones in the reference 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
XSI: FaceFXImportAnimation "Default", "welcome", 30, 0

  • This function is turned off in Mod developer versions of FaceFX.

fximportbonepose

Imports the specified bone pose to the specified frame, inserting keys for all bones in the reference pose at that frame.

Maya: fximportbonepose -frame 10 -name "open";
Max: obj.fximportbonepose 10 "open";
XSI: FaceFXImportBonePose "open", 10

fximportrefpose

Imports the reference pose to the specified frame.

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

fxinsertanimationgroup

Inserts a new animation group.

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


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;
XSI: FaceFXInsertKey "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;
XSI: FaceFXIsAnalysisTool

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;
XSI: FaceFXIsNoSave

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;
XSI: FaceFXIsModDeveloper

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);
XSI: FaceFXLinkNodes "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";
XSI: FaceFXOpenActor"C:\Slade-Maya.facefx"

  • Notice that the when specifying a file from MEL Script, you must use two backslash characters as the folder deliminator. This is optional in 3D Studio Max.

fxnewtake

Performs a new analysis take on the specified animation using the analysis actor specified with fxchangeanalysisactor.  If valid "start" and "end" times are passed in (with start < end), the analysis take is limited to the specified time range.  Otherwise, a new analysis take is generated for the entire animation.  Only available from analysis-enabled plugins.  Evaluation versions may only perform a new take on phrase-locked animations.

Maya: fxnewtake -group "Default" -anim "welcome" -start 0 -end 0
Max: obj.fxnewtake "Default" "welcome" 0 0
XSI: FaceFXNewTake "Default", "welcome", 0, 0


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";
XSI: FaceFXSaveActor "C:\Slade.facefx";

  • Notice that the when specifying a file from MEL Script, you must use two backslash characters as the folder deliminator. This is optional in 3D Studio Max.

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


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;
XSI: FaceFXGetBoolUserProperty "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;
XSI: FaceFXGetChoiceUserProperty "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";
XSI: FaceFXGetNumUserProperties "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;
XSI: FaceFXGetRealUserProperty "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;
XSI: FaceFXGetStringUserProperty "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;
XSI: FaceFXGetUserPropertyName "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;
XSI: FaceFXGetUserPropertyType "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";
XSI: FaceFXSetBoolUserProperty "node1", 0

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";
XSI: FaceFXSetChoiceUserProperty "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;
XSI: FaceFXSetRealUserProperty "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";
XSI: FaceFXSetStringUserProperty "node1", 0, "newString"

 


 


 


 


 


 



 




 




Version Number: 
2010