From ETC Public Wiki
Jump to: navigation, search

Maya2EGG GUI quick start guide

Although the command line version of maya2egg (and the additional optimization utilities such as egg2bam, egg-optchar, work well when used correctly, typically problems arise from a poor understanding of the command line options and requirements. This standalone tools application attempts to demystify some of those options and present them in a way an artist (rather than a programmer) can better understand. However, the application still requires the command line programs to be present in order to actually export or process any eggs or Maya files. Simply put, the application builds the command line arguments for you and can process multiple files in a sequence (better known as batch processing). After all, in most game pipelines models and animations have to be exported multiple times with no changes to their settings after minor tweaks within the 3D package. It should also be noted this tool currently only supports the maya2egg exporter, but since the other optimization tools operate on egg files they can be used with any egg file that has been correctly exported from any 3D package.
NOTE: The application was developed to work on Windows, Linux, and Mac OS. There are certain differences between how each operating system installs Panda , and how directory paths are represented. For the rest of this document I am going to use Windows conventions because it is the operating system I am most familiar with. However, if there are significant differences between how you need to use the app in Linux of OSX I will be sure to provide the necessary steps to ensure the application working correctly.

Simple Mode

This application presents two modes for exporting a model or animation from Maya. Upon opening the application the simple mode is presented. The simple mode tab is intended to do “one-off” or single file exports. It would be the same thing as typing the exporter command and options each time you wanted to export a model. To use simple mode follow these few steps:
-Click the Save button next to the first text box labeled “Egg file to be written” and navigate to your intended export directory and name you r file. When you’ve finished this click OK.
-Click the Choose button next to the text box labeled “Maya file to be exported” and select the .mb file that you would like to export.
-Select the version of Maya you currently have on your system from the Maya Version drop-down box.
Now, before you click Run Export, you must decide if you want to export any animation from the file and if so what type. If you simply want a static model (usually used for props and game levels) select “none” in the Animation box. This will export only the geometry from your scene, excluding any joints or key frames. It should be noted that this type of model will not export any skinning data from Maya. However, it will still have a transform included which will allow it to be placed in a Panda3D world.
If you want to export a scene with joints and skinning data so that it can later accept any exported animation select “model “ from Animation box. This term can be slightly confusing initially, but once you realize we’re talking about what type of animation (if any) to export the distinction between “none” and “model” is slightly more clear. Remember, model doesn’t just mean polygon geometry, it implies that the model has joints and possibly a skin cluster in the scene file. It is meant to accept animation data from a separate file or to be animated by the programmer through code.
If you only want to export the animation data from a scene select “chan”. This will simply write out the key frames of your scene and what joints those key frames apply to into the egg file. This file is almost always used with a separate egg file that was egged out with the “model” option.
Lastly, if you want all the geometry, joints, and skinning data exported to your egg in one file select “both” from the Animation box. This file type is rarely used, but special cases exist. Most of the time you would want to keep the animation and geometry data in separate files. This allows you to load animations on the fly inside the engine without having to load the geometry data twice. Thus making your game load (and possibly run) faster.
Once you’ve figured out which type of animation you need to export in your egg file. Click Run Export. A pop-up window will show up and it will start writing the output from the command line tool that the application launched in the background. If your scene file does not export correctly, this text will let you know in most cases. It can be helpful in tracking down problems and be sure to copy and paste it to text file if things don’t work out so you can show your programmer or a member of the Panda community where things are going haywire. Also, since computers in general have not learned to interpret the intentions of a human without explicit instructions the egg file may not show up in the game correctly. In short the exporter may write a perfectly good egg file, but since something wasn’t quite right in your scene file in Maya, things may not turn out correctly when you Pview or import the egg into your game. This almost always has to do with the Maya file itself, NOT the exporter, so be sure to try and diagnose problems inside Maya first. A good place to start is the Common Problems section of this document. If there’s no answer there, post on the Panda3D forums. There are a number of experts and seasoned artists who have probably come across the same problems you have and can quickly get you back on track.

Advanced Mode

In the beginning Simple Mode should cover the basics of single file exporting. However, once you’ve had to load the application a few times and enter the same settings over and over again, it’s probably time to move on to using the Advanced Mode Tab.
Aside from allowing you to have greater control over what specifically gets exported out of a particular Maya scene, this tab allows you to save these options and settings for later use. Also, since everyone has a different set of default exporter options and locations the application allows you to save and load a preferences XML file to load each time the application is launched.
The process for exporting from the Advanced Mode tab is largely the same as Simple Mode, but with a few wrinkles. First you should choose your Panda installation directory and Maya version from the Environment Options section. This location is the directory where you told Panda3D to install when running the installer. It is NOT the \bin directory where the maya2egg executable resides. This little wrinkle was necessary to allow multiple operating systems to use the application.
The last difference between Simple and Advanced mode for exporting a single file, is that it must be put into the batch list before it can be exported. The Batch List represents the order of the files that are about to be exported. To Add a Maya scene file with its export options to this list simply click Add To Batch (The other utilities in the Extra Utilities section have this same button for simplicity’s sake, but the main Add To Batch button deals solely with the maya2egg tool). After you’ve added any number of scene files with any of the available options to the Batch List you can then click Run Batch and the application will launch the exporter or utility command one by one until it has finished the entire list of items.
Another useful feature of the application is that it checks the modified date of every file used as an input for the given utility (ie the .mb file for an exporter batch command, and an egg file for egg2bam). This is handy if you have saved out an entire batch list of 20 files but only need to export the three files you actually changed. The exporter skips any unchanged files by default, but this behavior can be overridden by checking the “Override export changed files” checkbox next to the Run Batch button.
TODO: Explain how the app can pipe an mb file through all the other utilities. I haven’t written this yet because I haven’t implemented the feature for any sort of release yet. It’s in the works essentially.

Common Problems

-The exporter fails to launch the application.
->open up the Windows command line and type maya2egg[version number].exe –h. If you get a weird error about an ordinal not being located in a dynamic link library. Navigate to the \bin directory where you installed Maya (ex. C:\Program Files\Autodesk\Maya 2010\bin) and copy the file libguide40.dll to the bin directory underneath your Panda3D installation directory (by default it’s Panda[version number]\bin. Make sure to Copy and Replace (overwrite) the older .dll in the Panda directory with the one from the Maya directory. This issue is always present on Windows and is a necessary step to get the maya2egg tool running. It arises from Maya including its own copy of Python, which has some different libraries than Panda’s.
->Double check that you’ve correctly chosen your Panda3D install directory in the application. Being careful NOT to select the \bin directory
-Maya 2 egg can’t find a valid copy of Maya.
->Since maya2egg actually launches an instance of Maya in the background (you never actually see it), it has to be licensed in order to run properly. If you don’t have a licensed copy of Maya on your machine then the exporter will not work at all. Whether Maya PLE (Personal Learning Edition) can allow you to use the exporter is largely unknown, but it will probably fail given that it currently saves .mb files slightly differently than a full fledged copy of Maya.
-None of my textures are showing up in Pview?
->This usually has to do with bad/dead file links inside the maya scene file itself. Or the egg file is looking for textures in a location that does not actually have the textures present. Double check your file links inside Maya. If that appears correct, inspect the <Texture> tags inside the egg file itself by loading it into a text editor (such as Notepad). Make sure these path’s and files exist (making sure to note whether they are absolute paths or relative paths to the egg file).
-I rigged my character. Exported it using model. Then imported that character.mb file into a new maya scene and then animated it. Saved it as character_anim.mb and then exported it with the “chan” option. My animations aren’t showing up in the game or in Pview. What’s going on?
->When this happens the animation egg usually reference a “character name” that doesn’t exist. However, when you exported character.mb as a model egg. It created a character name appropriately named character. Next when you exported character_anim.mb it probably tried to target the animation for a character named character_anim. To remedy this re-export the animation file and make sure to check the “Character Name (-cn)” option box in the application and enter the correct character name (in this case it’s character)

New Features in the Maya exporter (egger)

-legacy-shader (legacy shader generation (T/F)
This command line option exists simply as a failsafe for Phong materials erasing flat color on export. Since around 2005 the preferred Maya material has been Phong. However, until very recently, a model with Phong materials would have its flat (poly) color information erased when exported without a texture map. Although a fix has been committed that now corrects this behavior automatically. We felt that leaving the option to export an entire scene using the much older method for exporting materials was necessary as a fallback option if any new bugs relating to Phong(ed) models arise down the road. However, it' is important to note that since Lambert materials inside Maya will never support specularity by definition, specularity/glossiness will have to be applied outside of the 3D modeling package somehow if this option is used.
-copytex "dir" (copy textures (T/F) + path (relative or absolute))
This feature is designed to improve some of the path preservation and redirection utilities already built into the exporter. It specifically applies to the textures referenced by the Maya scene file you are exporting. In short it takes all the textures in the Maya scene and copies them to the specified directory, updating the egg file as necessary. This can be handy if you have all your textures in remote location (on a network drive for example) and need to move them to a local directory for your project's build system.
The "dir" after the copytex flag denotes the destination of the copied textures. This path can be absolute or relative to the output directory of the egg file. For example you could specify "C:\textures\" or \textures. The first would use the C: drive exclusively, and the second would create a subdirectory underneath the output directory of the egg file. So, if I exported my egg file to C:\models\ and specified \textures in the copytex sequence then my texures would end up in C:\models\textures. The egg file would reference the absolute or relative path as well.

Using the Egg-Palletize Tool

Egg-palettize is an optimization tool in Panda for you to group your textures. You can have your textures placed in a single palette. In the advance mode of the GUI, choose the egg-palettize panel. This is the egg-palettize Tool.
For using Egg pallettize for a single egg file select that option in the drop down list. First, specify the input egg file, the output texture file and the output egg file. The output texture file is where the palette will be put in. And the output egg file is the new egg with the new palette as the texture.
Before generating the egg palette, a .txa file should be generated with some attributes listed in the attribute panel.
Set palette size: Specify the size of the palette.
Imagetype: Image type of the palette.
Powertwo flag: Specifies whether textures should be forced to a power of two size when they are notplaced within a palette. The default is false.
Set background color: Specifies the background color of the generated palette images. The background color is the color of the palette images where nothing is used. The number r, g, b, a channels are range from 0 to 255. The default color is black.
Margin: This specifies the amount of default margin to apply to all textures that are placed within a palette image. The margin is a number of additional pixels that are written around the texture image to help prevent color bleeding between neighboring images within the same palette. The default is 2.
Coverage: The 'coverage' of a texture refers to the fraction of the area in the texture image that is actually used, according to the UV's that appear in the various egg files. If a texture's coverage is less than 1, only some of the texture image is used (and only this part will be written to the palette). If the coverage is greater than 1, the texture repeats that number of times. A repeating texture may still be palettized by writing the required number of copies into the palette image, according to the coverage area. This attribute specifies the maximum coverage to allow for any texture before rejecting it from the palette. It may be any floating-point number greater than zero. Set this to 1 to avoid palettizing repeating textures altogether.
After setting all the attribute, click on Save Attributes button to save all the attributes to a .txa file. Last, add this to batch list, after clicking run batch, the palette will be generated.

Egg-palettize for multiple eggs

Egg-palettize can also generate a palette image for multiple egg files to share. This palette image has all the textures of multiple egg files to be placed on it.
This panel is almost the same as the single egg one. Only for the input egg file can have multiple egg files put into it. Select a added egg file and click Remove button can remove that egg file. Click Remove All button can remove all the added egg files
The output is a folder to put all the new eggs.
Attributes Panel is the same as the single egg one.