The LFA Scene Manager for Maya/Ogre3D

Video Tutorials:
1) Exporting to Ogre3D with the LFA Tools

2) Using the LFA Tools' material system

3) The theory and basics of the .scene file

4) Using the .scene in practice with the LFA Tools

5) Customizing the .scene with the LFA Tools

6) Characters and Animation Part 1: Basics

7) Characters and Animation Part 2: Workarounds

8) Customizing the LFA Toolset for your pipeline



Q & A:

• What is the LFA Scene Manager?
• How do I install the Scene Manager?
• What are 'export parameters'?
• How do I use the .scene (dotScene) format?
• How does the material system work?
• How do I create my own material definitions?
• Why does the scene manager display an 'ATTR ERROR' message when i click on a material?
• What are environment settings?
• How can I change the default export path?
• What are the 'node ID' and 'entity ID' for?
• How do I add my own scripts to the 'Custom Game Actions' buttons?
• Why do the positions of objects look different in Maya than in my .scene?
• I set up lights and turned their intensity WAY up, and they still don't light anything!
• Why does my spot light in maya look so different from the one I export?
• How do I use 'Shared Geometry'?
• When I export, the normals on my model are reversed, (model looks inside out) wtf?
• How do I export animation?
• Locators are special?
• How do I add a sprite(billboard) to the scene?
• How do I add a particle emitter to the scene?
• How do I make 2 objects use the same .mesh file?
• How do I incorporate a terrain file into the scene?
• How do I add ambient light to the scene?
• How do I add userDataReference (custom user data) to a node?
• My question is not listed here, how can I contact you.

 

What is the LFA Scene Manager?

The LFA Scene Manager for Maya is a set of MEL scripts that is my attempt at making a professional and practical tool for Maya artists using the OGRE 3D graphics engine. Basically to create a part of an art pipeline through which one could quickly and easily test , view and use art content in OGRE.

Its basic functions are to:

- export chosen scene geometries via .mesh files from Maya
- export their materials via .material files from Maya
- export arbitrary combinations of skeletal and pose animations from Maya
- export mesh and node postions from Maya into Ogre via the .scene file.

I tried to make it as easy and straighforward to use as possible.

But keeping in mind that neither OGRE or Maya are for the faint of heart, I hope i succeded =P

The manager is free and can be obtained here:

How do I Install the Scene Manager?

IMPORTANT: Before installing/using the scene manager, be sure to have the regular Ogre exporter for Maya installed as the scene manager relies on it to work properly.

 

STEP 1 Unzip LFA_sceneManager.zip contents into:

C:\Documents and Settings\username\My Documents\maya\x.x\scripts\

STEP 2 Upon restarting Maya make a button or run the script:

lfa;

STEP 3 For BASIC HELP on usage go to the LFA window and choose:

Help > Instructions

What are 'export parameters'?

Export parameters are hidden attributes added to a Maya node by the tools that tell the exporter *how* to export the object. For example: Does it have vertex colors? Should we export UVs? Does it have animation? etc. etc. (however, this is all under-the-hood stuff)
You can add export parameters to nodes by selecting the object and then clicking 'Tag for Export' in the LFA Scene Manager window. Whenever you select an object and the 'Tag for Export' button doesn't exist it is either because it already has export parameters, or it will tell you why it can't be given export parameters.
Objects not tagged for export are ignored by the sceneManger and will not export (with 2 exceptions: shared geometry and skeletally bound meshes which can export without being tagged themselves, and instead use the parameters of the associated mesh or joint that has been tagged).

NOTE: When you 'Remove Tag' it actually keeps the parameters but deactivates them (in case you want them back, your original settings will be preserved). When you 'hard delete' parameters the attributes added to the nodes are actually deleted and all information added by LFA tools is lost.

How do I use the .scene (dotScene) format?

There are some C++ classes on the Ogre Wiki that you can use as a starting point to load them for you.
I personally use a modified version of THIS ONE. Here is ANOTHER.
Neither is comprehensive. Neither takes advantage of all the information that the scene manager exports. But thats up to you to customize your own software for your needs!

There are also many topics in the OGRE Forums concerning this.

One might start their learning here then here.

How does the material system work?

The material system is a based on presets(material definitions). Each material is assigned one preset, or chosen not to export at all (the 'NONE' preset). Most presets have configurable settings, and you can also make your own preset (see below). When you select a material, the lfa window will update to display the current settings for the current preset on the current material. You can see all available presets by browsing the 'Type' drop down menu. If the material is applied to an object with export parameters, it will automatically export if you click 'Export ALL' or if you click 'export materials only'. Alternatively, if you want to create some materials by hand, you can keep them from getting overwritten or conflicted by using the 'NONE' preset, in which case the material will be totally ignored by LFA, but your mesh will still have the material name applied to the appropriate faces so Ogre will still hook up its material automatically.

NOTE: Materials not assigned anything will default to 'simpleTexture' if a fileTextureNode is connected, otherwise will default to 'noTexture' when exported.

How do I create my own material definitions?

Included with the scene manager in your scripts/lfa_sceneManager/materialDefinitions/ is a file with instructions. Its easy! The short version is that after you create your new super duper material definition just drop it into the directory and it will be dynamically loaded as an option with the rest! ^_^

simply close and open your lfa window to have it show up.

Why does the scene manager display an 'ATTR ERROR' message when I click on a material?

Most material templates try to hook into some existing real-time attributes of the Maya material so that you can have some interactivity while tweaking its properties. This 'error' simply means that the attribute requested for realtime control doesn't exist on the currently selected Maya material. Simply choose a different Maya material type or a different Ogre material template. Otherwise, the pre-defined defaults in the material definition will be filled in for those attributes that display ATTR ERROR when its time to export the material file.

What are environment settings?

Environment settings are attributes that can be added to your .scene if you choose.

When you click on Tools > Environment Settings inside the Scene Manager window, a special curve object is created called OGRE_ENVIRONMENT that looks like an "E". All the environment settings of your scene are stored in that object.

If you want to share environment properties across different Maya files, you can export and import this object into them. The E will be recognized when you run the Scene Manager again.

You can do anything you want to the E (scale, rotate, translate, hide) and your scene will not be affected, but only delete or rename the E if you want to reset your environment properties to defaults or not include them at all.

NOTE: Materials you list inside the Environment Settings are automatically exported on scene export and/or material export (if they exist).

How can I change the default export path?

Included in the LFA_sceneManager.zip you downloaded is a file named:

\lfa_sceneManager\lfa_settings.mel

You can directly change the directory there.... however, a better idea is to copy the settings from that file that you would like to change and copy the changed lines into a sister file named lfa_userSettings.mel

lfa_userSettings.mel is called immediately after lfa_settings.mel and overwrites anything that was declared there. The advantage is that you wont have your customizations nuked each time you update your LFA tools (as lfa_userSettings is not included in updates).

What are the 'node ID' and 'entity ID' for?

These are strings that you can use to attach data to a node in your .scene file.

The .scene will export them like this:

<node name="myObjNode" id="nodeID">
<position x="-6" y="0" z="0" />
<rotation qx="0" qy="0" qz="0" qw="1" />
<scale x="1" y="1" z="1" />
<entity name="myObj" id="entID" meshFile="myObj.mesh" static="false" castShadows="false" />
</node>

An alternative to this feature, for exporting node data into the .scene is the userDataReference feature.

How do I add my own scripts to the 'Custom' menu?

Simply drop your .mel scripts into the folder named:

\lfa_sceneManager\customScripts_menu\

(or one of its subfolders) and your scripts will dynamically appear as menu items as soon as you close and re-open the scene manager window.

You can also add custom buttons inside the main window by placing your .mel files inside here:

\lfa_sceneManager\customScripts_button\

Although subfolders are not recognized in this directory.

Why do the positions of objects look different in Maya than in my .scene?

You need to reset your transforms. Maya tries to keep things user friendly for us, so can hide true transforms under certain circumstances.

step 1. make sure no rotations , translations, or scales are locked

step 2. scene manager > tools > reset tranformations

your object should now have true transforms.

TIP: ALWAYS run "Reset Transformations" after moving a pivot.

TIP: Always parent your object BEFORE locking any transforms.

 

I set up lights and turned their intensity WAY up, and they still don't light crap!

1. Have you tagged them as exportable?

2. If so, make sure that the object you are trying to light is inside the 'range' of the light. You can test the range of the light in Maya by checking on 'display range'.

3. re-export the .scene file

POSSIBLE SOLUTION #2: if it still doesnt work make sure that your light is not parented to something that has had its scale modified... as this will make the 'range sphere' of the light inaccurate.

Why does my spot light in maya look so different from the one I export?

Keep in mind that the maya spot light value of Dropoff is totally ignored by the scene manager... and probably best to keep it at 0.

The values that define a spot lights' "spot" are your cone angle and your penumbra angle.

The falloff field in the scene manager window (not to be confused with the maya dropoff value) is the interpolation of those 2 angles... 0 being none/ very hard... 1 being linear and so forth.

How do I use "Shared Geometry"?

You can use shared geometry by parenting a mesh with no export parameters to a mesh that does have parameters. The first mesh will export as a submesh of the second.

Example: mesh_A (no parameters), mesh_B (given export parameters)

If mesh_A is parented to mesh_B, it will export as part of mesh_B

When I export, the normals on my model are reversed, (model looks inside out) wtf?

The first thing to try is to 'fix reverse normal objects':

-LFA Scene Manager > Custom > Metaldev's favs > fix reverse normal objects

(this script turns off 'double sided' and then checks the 'opposite' flag enabled on selected objects, if it is enabled, it turns it off and flips your normals for you) basically a quick way to ensure true normals are showing.

 

If that didn't work, try reversing your normals:

- Edit Polygons > Normals > reverse

 

If that didn't work, the next thing to try is this:

-select the offending object and open the attribute edtor (ctrl + A)

-under Render Stats, make sure both 'Double Sided' and 'Opposite' are checked OFF

 

If your normals in maya are still the opposite of what they are when you export, the last thing to try:

Finally, try attaching it with another mesh...

for example:

- create a poly primitive
- select the cube, then your object
- LFA Scene Manager > Tools > 'Attach' your 'inverted' model and the primitive.
- delete the faces of the primitive from the new object
- delete history

by now you should see your faces inverted in maya (like they are when exported)... so reverse normals with editPolygons>normals>reverse

and export again... you should be set.

(also, one time that this happened to me i had to do these steps twice for some reason, so if it didnt work the first time try again)

 

How do I export animation?

As of v3.0 the scene manager supports animation export. This is how it works:

- Only meshes or joints can have animations saved to them using the animation manager. NOTE: Applying animations to objects does NOT mean that it's animations will be exported, nor does it give the object export parameters.

- Animations only get exported when they:

- are applied on a mesh or joint that has been given export parameters
OR
- are applied on meshes that are bound to a joint with export parameters
OR
- are applied on a mesh that is parented to another mesh with export parameters.

- To export Skeletal Animation give the root joint of bound geometry export parameters and animation parameters. Even if the bound geometry is made up of several meshes, they will export as one skeletal mesh. Unless you want the bound meshes themselves to also export as static meshes in addition to being part of the skeletal mesh, do not give them export parameters.

- To export Blend Shapes or Blend Shape Animation (pose animation) give a mesh export parameters and animations (and of course Maya blend shape animations!)... If you only want to export blend shapes and not any blend shape animations, you can simply give the mesh a bogus animation of 1 frame etc.

- To export both Blend Shape AND Skeletal animation:

1. give the root joint export parameters.
2. apply the intended skeletal animations to the root joint.
3. apply blend shape animations to any of the bound meshes, but DO NOT give them export parameters. The joint with the export parameters will automatically detect blend shape animations on any meshes bound to it and include them.

NOTE: due to deformation order it is recommended to apply blend shapes first, then bind to joints.

- To export Blend Shape animation on Shared Geo, any animations saved to any of the included meshes will get exported. However, the parent with export parameters must have a Maya blendshape. (Otherwise, the animations will be ignored.) NOTE: combining blend shapes with shared geo sometimes yields unexpected results (multiple identical poses exporting, and even geometric oddities when using 'grouped' blendshapes).

- If you are using animation with instanced meshes, only animations applied to the instance original will be considered by the exporter.

- Give all your animations unique names or they will clobber each other. This includes blendshape animations and skeletal animations on the same object. This may be desirable in some cases (animations that include both skeletal and blend shape deformation can be exported as 1 animation for example.) but this has not been fully tested and is not officially supported.

- The LFA tools do not support Morph animation you will have to use the regular exporter if you want this.

*REMEMBER

: animations on MESHES export as BLEND SHAPE/ POSE. Animations on JOINTS export as SKELETAL.

Locators are special?

Yes!

I have chosen the object type of locator to be the way through which we can implement several things in the .scene file. By choosing its "Mode" we can specify its behavior as follows:

simpleNode -
The locator will act as an empty group... in other words, simply an empty node or bone in a heirarchy.

particleSystem -
Incorporate the particle file in the text field into the scene at the position of the locator.

trackTarget -
Will point the locator (and any of its children) at the entity annotated in the field.

lookTarget -
Will point the locator (and any of its children) at the entity annotated in the field.

spriteCloud -
The locator will act as a sprite (billboard) or cloud of sprites.
Read the following question for more info...

entity -
The locator will act as a mesh entity. This is useful for incorporating .mesh files exported from other Maya scenes. Simply annotate the appropriate .mesh in the file field.
NOTE: .mesh files incorporated in this way are automatically non-static and shadow casting.

textFile -
The contents of the file in the 'File' path are copied into the .scene file where the locator is defined. (this path is relative to the export path)
This can be used to customize the .scene with non-standard content.

text -
This will paste the text in the notes attribute of the locator into the .scene file in the section where the locator is defined.
This can be used to customize the .scene with non-standard content.
To add notes to an object in Maya press ctrl+A to open the attribute editor and select the object. The notes section is at the bottom of the attribute editor.

How do I add a sprite(billboard) to the scene?

Create a locator, make it exportable, and choose MODE: "spriteCloud".

The default parameters are to have a single sprite at the position of the locator. The size of the sprite will be that of the locator. Simply specify the material you want the locator to use.

If you want to make a group of sprites you can specify how many in the 'sprite count' field. You can specify the density of the cloud (billboardSet) by choosing a radius. All the sprites will appear within that distance from the locator.

Using "size variance" is not recommended as it runs slower in real-time, but what it does is randomly vary the size of each sprite by the amount you specify if you wish to use it. The size of the sprites is taken from the size of the locator (scale X and Y only), so keep in mind that the size variance value is a random offset from that.

One can also vary the color of the sprite(s) using the controls listed under "Sprite Color Offset:"
The color values supplied perform a modulate(multiply) over the color of the material you list in the "mat" field. Therefore a value of 1 (white) for the color and aplha fields will have no effect.

If you wish for each sprite in the cloud to be individually different colors, you can randomize each channel by inputting 0-255 in the "Rand" fields. The fields correspond to R G B A respectively. 0 being no randomization (simply use the color you specified above) 255 being a fully random color. However, keep in mind that the rand values are relative to the colors above... so for example, if you specify a color of 1 (white) with rand 255 the randomization range will be from 0 to 510 therefore half the values will be above 255 and will be clamped to white.

NOTE: when using spriteCloud, the exporter will automatically export the material in the text field if it exists

How do I add a particle emitter to the scene?

Create a locator, make it exportable, and choose MODE: particleSystem.

Specify the file that defines your particle system in the field... it should appear at the position of the locator.

How do I make 2 objects use the same .mesh file?

The LFA Scene Manager recognizes instances. So simply instance (as opposed to duplicate) whatever objects you want to share .mesh files.

Instanced objects share Shape Nodes in maya... and the scene manager translates that properly for you into the .scene file.

Example:
If you were to export 10 instanced objects... there will only be 1 .mesh exported, but 10 nodes and entities inside the .scene that point to the same .mesh file.

NOTE: Maya allows you to have different material assignments between instances. As an optimization, the tools do not support this and only the materials of the instance original are considered. (I don't believe Ogre supports this either without modification)

How do I incorporate a terrain file into the scene?

In the Scene Manager, Tools > Environment Settings.

There is a slot in there for including its file. Depending on what you are using to load your .scene, you may need to include the relative file path (from your application) for it in the text field.

How do I add ambient light to the scene?

Add an ambient light and make it exportable.

Keep in mind that multiple exportable ambient lights will have their effects combined / added in the .scene file. Although the placement node for each ambient light will be editable in the game, ambient lighting is actually a single attribute in the environment element of the .scene so their light values are combined before being sent to ogre... therefore, multiple ambient light values are not individually editable after export.

How do I add userDataReference (custom user data) to a node?

Params > Add User Data

"Add User Data to Node" and "Add User Data to Entity" will generally export as follows:

<node name="objNode" id="0">
    <position x="-48" y="0" z="-70" />
    <rotation qx="0" qy="0" qz="0" qw="1" />
    <scale x="15.78941125" y="15.78941125" z="15.78941125" />
    <userDataReference id="userData in Node" />
    <entity name="obj" id="0" meshFile="obj.mesh" static="false" castShadows="false">
        <userDataReference id="userData in Entity" />
    </entity>
</node>

- User Data is ignored on objects without export parameters.
- You may add as many userDataReferences to supported nodes or entities as you want.
- You can delete user data in 3 ways: removing all user data with the X buttons, copying empty user data onto an object, or HARD deleting parameters.
- User Data can only be edited and copied from 1 object at a time.
- User Data can be pasted or appended onto multiple objects at a time.
- Some object types such as ambientLight and emptyGroup do not support userData on Entity
- Some locator types such as "simpleNode" will ignore userData on Entity
- when you put userData on the OGRE_ENVIRONMENT node, any data in the node section is applied to the <scene> and any data in entity section is applied to <environment>

NOTE: don't use the characters ^ or % in userDataReference fields, they are used for internal parsing and will not behave as you expect (sorry, i originally used more exotic characters but that seemed to break some incarnations of Maya)

For more ways to customize your .scene, read about locators.

My question is not listed here, how can I contact you?

You can post questions related to using the Scene Manager with Ogre on the OGRE Forums or the LFA Forums.

enjoy!

-metaldev