Script Functions

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.

MEL Script

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

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.

Functions

fxgetactorname

Returns the actor name.

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

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: FaceFXNewFXA "Slade"

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: FaceFXOpenFXA "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.

fxsaveactor

Saves the current actor file to disk.

Maya: fxsaveactor -file "C:\\Slade.facefx";
Max: obj.fxsaveactor "C:\Slade.facefx";
XSI: FaceFXSaveFXA "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.

fximportrefpose

Imports the reference pose to the specified frame.

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

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"

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

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"

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.

 

 

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.

 

 

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

• This function is turned off in Mod developer versions of 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();

 

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

 

fxgetanimgroups

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

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

 

fxgetanims

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

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

 

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

 

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

 

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

 

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

 

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

 

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

 

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

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

 

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

 

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

 

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

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

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;

 

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

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;