Updated: 8/31/04

I : Understanding MasctorX

MasctorX's sole function is to make the task of exporting animation ;& meshes from Maya to Unreal effecient and straight forward. The job of exporting 80 or so animations by hand is highly tedious and a poor way to end an energized session of animating, so I devised this solution to automate the task. Besides mass exporting your animations ;& meshes, the script will automatically determine your animation length, if the animation loops to prevent stutters, as well as whether your mesh is static or skinned.

II : Requirements

- Maya 6.0
- ActorX Plugin 2.34 for Maya 6.0 is installed & loaded

(If someone could test this with Maya 5 or PLE, let me know the results)

In order for MasctorX to work with your project, you have to use the following organization system:

- Folder with all your animations/meshes you want to export in it
- One animation per scene file, with the animation name in the filename (example: necros-runf23.mb, necros-walklrevised.mb, necros-crouch.mb, etc)

III : Using MasctorX

A. Exporting Animations
1. Browse to your animation folder containing all the animations you wish to export. Note that all scene files in this folder will be exported.

2. Browse to where you want the PSA file (and log file if you enable it) to be placed.

3. The range finder is used to determine the animation length & whether the animation loops. You will want to put the names of a couple animated controllers on your character in here, each seperated by a comma, no spaces. You can put as many object names there as you want, the more, the more accurate the detection will be; I recommend 3-5 controllers. (example: HipController,L_FootController,HeadController,R_HandController)

4. Specify the starting frame for all the animations. This is so if you keyframed the character in bindpose at 0 or -1, it won't export those frames. If you uncheck start frame, it will use the range finder to determine the start of the animation, unless you've disabled range detection.

5. Enable 'Save PSA upon completion', if you want it to write the PSA once it collects all the animations.

6. Log results is recommended when you do your first export of all your animations as it will tell you both the results from MasctorX and ActorX, such as what the ranges exported for each animation was, whether a loop was detected, etc. Go over this atleast once to make sure it is properly detecting your looped animations.

7. Hit the export animations button which will proceed to open each of your maya scene files in your animation folder, determine range, etc as specified by the user and export each animation into ActorX. If you do not enable 'Save PSA', the animations will appear in ActorX's animation manager. If you enabled 'Save PSA' the animations will not appear in the animation manager as it seems ActorX purges the animations after they are written to file, so you will have to import the PSA file into ActorX if you wish to adjust anything afterwards.

B. Exporting Meshes
1. Browse to your meshes folder containing all the meshes you wish to export. Note that all scene files in this folder will be exported.

2. Browse to where you want the resulting PSK files (and log file if you enable it) to be placed.

NOTE: If you are exporting static meshes, you will need to goto the file menu in MasctorX, ActorX > Static Mesh Export. You have to adjust all the variables there for the export, including the path, then close the window and go back to MasctorX. Static meshes will not use the path in MasctorX, only the one in the static mesh export panel & any options you have set. This is since the static mesh export does not have any programmable extensions, and in fact only through analyzing the plugin in detail that this even works. In addition, MasctorX's prefix/suffix remover does not work with this either, and meshes will use their object names in Maya as they normally do. I am petitioning Epic to add commands for all this, but in the meantime this will have to due.

3. Auto-Triangulate uses the triangulate function built into Maya so the results are better than the one built into ActorX. Recommended however that you triangulated your static meshes beforehand to ensure the end result.

4. Log results is recommended when you do your first export of all your animations as it will tell you both the results from MasctorX and ActorX, such as what the ranges exported for each animation was, whether a loop was detected, etc. Go over this atleast once to make sure it is properly detecting your looped animations.

5. Adjust the reference frame if you are exporting skin meshes so it exports the reference pose and nothing else.

6. The type specifies what type of meshes you want to export, it is recommended you leave it set to automatic.

7. Hit the export meshes button which will proceed to open each of your maya scene files in your meshes folder, and write each file to an ASE or PSK file in the directory you specified.

IV : Advanced Options

Import/Export MasctorX Config : Available in the file menu, File > Import/Export MasctorX Config, this lets you export & import the configuration you have set for MasctorX for future exports. Will save out both animation & mesh export options.

Method : This specifies the method used to load the animation scene files. Import is the recommended method as it is slightly faster & prevents Maya from loading the workspace saved in the file (if you have that option enabled). If you disable both auto-range finder and loop detection, you will have to use the open method as it then reads the animation ranges from the timerange slider in Maya's min & max playback values. Has little bearing on mesh exports.

Auto-Range Finder : Using the list of animated objects in the Range Finder, this will automatically determine the animation time range for export into ActorX. Unless you have all your scene files timesliders set to the exact length of each animation and are using the open method, do not disable this.

Loop Detection : This differentiates between looped animations and non-looped, so that looped animation do not stutter when exported. Again, do not disable unless you're using the open method and have all timesliders set to the exact animation length.

Remove Prefix : A regex based prefix remover for the animation scene file names. My animation scene filename look something like "sturm-runf2.mb" or "sturm-walkb4t.mb". To ensure each animation is labeled correctly, I would use "sturm-" as the removal prefix, and "t|[0-9]" as the removal suffix. Expressions are evaluated left to right, so work from the suffix inwards as is demonstrated with the "t|[0-9]". Note: Use "|" to seperate queries for individual processing since this is not a true regexp processor.

Remove Suffix : Same as remove prefix. Note that the file extension is removed automatically so is not part of the suffix.

Rate : Set the FPS rate at which animations are exported to unreal format. Default is 24 FPS.

MEL Injector : Any MEL commands entered in the textbox will run right before the animation is exported on each scene file. The following variables are available for low-level API: (r = readonly, rw = readwrite)

- (rw) INT $unreal_rangemin = animation start frame
- (rw) INT $unreal_endkey = animation end frame
- (rw) INT $unreal_rate = animation export FPS rate
- (rw) STRING $unreal_animationname = self explanitory
- (r) STRING $unreal_file = animation file name (no path)
- (r) STRING $unreal_animfolder = animation folder with animation scene files

Note: This function is still buggy with certain symbols, so use with care. Email me with any errors that occur.

IV : Concluding Notes

This is a first release so there are almost certainly bugs but has worked for me fine thus so far. Make sure you read the entire readme (Help > Masctor Help) if you have any issues. I haven't included a ton of error checking so entering random data could crash Maya or break something. In the extremely unlikely event that this script somehow corrupts a file or whatnot, I highly recommend you backup all your animations before exporting them (which you should already be doing as its a good practice to avoid mistakes/disasters). If you encounter any issues, found this tool useful, have recommendations, or anything else, email me at quantax<at>innoscience.net.

I also hangout on IRC:

network: irc.ugc.net
chan: #ug
My nickname is usually quantax

Updates will be posted to www.innoscience.net

Thanks to SuperMatt for testing.

- Brandon

Disclaimer: I am not responsible if this script destroys your data, makes your computer spontaniously combust or anything else.

Usage: You are free to run this script for non-commercial purposes. Changes can be made (for public release) by permission of the author so long as the author recieves proper credit.

IV : Version Notes

v1.1 : 8/31/04
- Added mass mesh export for both static & skin meshes
- Tabbed layout for mesh & animation exporting
- Fixed incorrect animation name export error
- Minor adjustments to UI
- Quick access to ActorX tools
- Triangulation now uses Maya's triangulation for better results

v1.0 : 8/29/04 - First release
- Import/export MassActor config
- Save PSA upon completion
- Prefix/suffix deletion
- MEL Injector
- Open/Import method option
- Range Detection
- Loop Detection
- Logging of results
- FPS Speed
- Start detection