Using the Blue Mars COLLADA asset importer
From Blue Mars Developer Guidebook
 |
|
|
Introduction
Note: This documentation assumes familiarity with the general Blue Mars asset creation process, including the use of the Sandbox2 editor for the CryEngine2 game engine.
COLLADA .dae files are exported from the Autodesk Maya and 3ds Max 3D content creation applications by the ColladaMaya and ColladaMax plug-ins, originally developed by Feeling Software. COLLADA .dae files exported from other third-party software packages may (or may not) be compatible with bmImport and bmImportCmd. Please refer to the Blue Mars COLLADA compatibility guide for more information.
bmImport is a Windows program which converts COLLADA .dae files to the Blue Mars asset files - .cgf (geometry), .chr (character), and .caf (character animation) - used by the Sandbox2 editor and the CryEngine2 game engine.
bmImportCmd is the command line version of bmImport, suitable for use in production pipeline and batch command scripts; or by the ancients who prefer a command line interface to a GUI.
Blue Mars asset files created by bmImport and bmImportCmd can be post-processed and optimized by the Resource Compiler and/or directly read into the Sandbox2 editor. bmImport and bmImportCmd have an option to create basic material (.mtl) files for use with the material editor in the Sandbox2 editor.
Supported Features
- Geometry
- Physics proxies
- Occlusion objects
- Level-of-Detail (LOD) objects
- Material file (.mtl) generation
- Object instancing
- Character
- Biped and non-biped skeletons
- Skin geometry
- Hit detection objects
- Morph targets
- Character Animation
- Bone animation
Unsupported Features
- Geometry
- Geometry animation, eg. Blue Mars .cga and .anm files
- Breakable objects
- Character
- Phys skeletons and IK parameters
Requirements
bmImport and bmImportCmd are compatible with COLLADA .dae documents created by the ColladaMaya and ColladaMax plug-ins, developed by Feeling Software. COLLADA document versions 1.4.0 and 1.4.1 are currently supported.
bmImport and bmImportCmd should be compatible with any version of Maya or 3ds Max which is compatible with version 3.05B of the ColladaMaya or ColladaMax plug-in.
bmImport and bmImportCmd have been tested with 3DS Max 2008 (32-bit and 64-bit) and Maya 2008 (32-bit and 64-bit).
Installation
bmImport and bmImportCmd are included with the developer build of the Blue Mars client software.
The ColladaMaya and ColladaMax plug-ins may be downloaded, free of charge, from the Feeling Software website (www.feelingsoftware.com).
Maya Setup
After the plug-in has been installed, run Maya and confirm that the COLLADA.mll plug-in has been loaded (Window -> Settings/Preferences -> Plug-in Manager):
Up axis and working units
The Sandbox2 editor uses Z-up axis, so geometry which is constructed using Maya's default Y-up axis will need to be rotated 90 degrees about the X-axis when imported into the Sandbox2 editor. To avoid this problem, Maya can be configured to use Z-up axis, before constructing geometry.
Open the Preferences panel (Window -> Settings/Preferences -> Preferences) and choose the Settings category. Set Up axis under the World Coordinate System subpanel to "Z".
The Sandbox2 editor uses the centimeter at its basic working unit, so confirm that Linear under the Working Units subpanel is set to "centimeter".
3ds Max Setup
After the plug-in has been installed, run 3ds Max and confirm that the COLLADAMAX.DLE plug-in has been loaded (Customize -> Plug-in Manager...):
Up axis and working units
By default, 3ds Max and the Sandbox2 editor are configured to use Z-up axis, so no change should be required in 3ds Max.
The Sandbox2 editor used the centimeter at its basic working unit, so select Customize -> Units Setup... and confirm that Metric has been selected under the Display Unit Scale subpanel and the units are set to "Centimeters".
Using with Autodesk Maya and 3D Studio Max
- Creating Blue Mars .cgf (geometry) files
- Creating Blue Mars .chr (character) files
- Creating Blue Mars .caf (character animation) files
Object Naming Conventions and Restrictions
When creating objects, in Maya or 3ds Max, the following naming conventions must be followed:
- All names are limited to a maximum of 63 characters.
- All names are case-insensitive. For example, "testPIVOT", "testPivot", "testpivot", and "testPiVoT" refer to the same object.
- The postfix Proxy is reserved for identifying physics proxy materials only. For example, "proxy" and "physics_Proxy" are reserved names.
- The names $occlusion and _occlusion are reserved for occlusion objects only.
- The names $lod1, $lod2, et cetera; and _lod1, _lod2, et cetera; are reserved for LOD objects only.
- The prefix Bip01 is reserved for skeleton nodes and objects only. For example, "Bip01 Pelvis" and "Bip01" are reserved names.
- The postfix Footsteps is reserved for skeleton nodes and objects only. For example, "Bip01 Footsteps" and "Footsteps" are reserved names.
- The postfix Phys is reserved for IK nodes and objects only. For example, "Bip01_Spine1_Phys" and "Phys" are reserved names.
- The postfix HitMesh is reserved for character hit detection objects only. For example, "Bip01_Head_HitMesh" and "HitMesh" are reserved names.
- The postfix Helper is reserved for creating 3ds Max-type dummy "helpers" in Maya only. For example, "grab_onehanded_01Helper" and "grab_twohanded_01helper" are reserved names.
- The postfixes PIVOT and ParentFrame are automatically-generated by the various software packages and should not be used to name any objects. For example, "Bip01 Arm PIVOT", "Bip01_LegParentFrame", "PIVOT", and "ParentFrame" are restricted names.
- The postfix Shape is automatically-generated by Maya and should not be used to name any objects. For example, "TeapotShape", "Bip01_L_ArmShape", and "Shape" are restricted names.
Running bmImport
bmImport is a Windows program, which may be launched by clicking the desktop shortcut for bmImport, or by selecting Start -> All Programs -> Avatar Reality -> Blue Mars -> Tools -> bmImport.
Select File -> Open File(s).... This will launch a standard Windows file selector dialog box, which can be used to select one or more COLLADA .dae files for import.
The names of the selected file(s) will be displayed in the Source COLLADA file(s): list box.
Next, select the appropriate Output type:
- CGF : Static geometry
- CHR : Character geometry with a skeleton or morph targets
- CAF : Animation for a character skeleton or morph
Note that only a single output type may be set, which will be applied to all of the source file(s).
By default, bmImport will save the Blue Mars asset files to the same folder as the source file(s). If you wish to save the files to a different folder, use the Save to folder: edit box to provide the desired output folder location.
Select and/or set the desired options on the right side of the panel. Refer to the Options section for an explanation of each available option.
Select Start to begin converting the source file(s).
The Cancel button may be used to interrupt the file conversion. Please note that there might be a delay before the cancellation occurs, if the program is currently executing a process which cannot be immediately interrupted.
The status of the file conversion process will be displayed in the status line at the bottom of the panel. Also, as each file is processed, the display of the name of the processed source file in the Source COLLADA file(s) list box will be updated. The result for each file can be either ok or failed. If a particular file fails to convert, running the command line version, bmImportCmd, on the file may provide additional information on the reason for the conversion failure.
After the conversion is complete, the Start button can be use to re-run the conversion process on the currently selected files, or another set of source files may be selected and converted, or you may choose to exit the program.
Running bmImportCmd
bmImportCmd is a Windows command line program, which converts a single COLLADA .dae file to a Blue Mars asset file. To run the program, open a Windows cmd window by selecting Start -> Run..., typing in "cmd" into the Open: text entry field, and clicking the OK button.
Running bmImportCmd with no arguments will bring up the command and options usage information.
Usage: bmImportCmd [options] in_file out_file
where
in_file = Filename of input COLLADA document (.dae) file.
out_file = Filename of output Blue Mars (.cgf, .chr, or .caf) file.
Example:
bmImportCmd -mtl -texturePath Objects/dae/ myModel.dae myModel.cgf
Refer to the Options section for the list and explanation of available options.
Note that the filename extension of out_file determines the type - .cgf (geometry), .chr (character), or .caf (character animation) - of the Blue Mars asset file which will be created by bmImportCmd.
Options
Options for bmImport are selected and set via standard user interface widgets: check boxes and edit fields. Options for bmImportCmd are selected and set via the use of command line arguments, prefixed by a '-' (hyphen).
The available options for bmImport and bmImportCmd are identical, with the exception of the option to run the Resource Compiler automatically, as a post-process, which is only in bmImport, and the option to generate an intermediate .dae file for debugging purposes, which is only in bmImportCmd.
Generate a Blue Mars material (.mtl) file
-
- bmImport:
This option will create a basic material file, which can be opened in the Sandbox2 editor. Due to the CryEngine2-specific behavior of many shader parameters, only a few basic parameters are currently imported from the COLLADA document. These parameters include diffuse, specular and normal/bump UV texture maps, and basic color settings.
Prepend relative subpath to texture image filenames in .mtl file
-
- bmImport:
In Blue Mars, all texture images must be located under the Game/ subfolder. The subpath, relative to the Game/ subfolder, must be prepended to the filename of the texture image in the material (.mtl) file, in order for the Sandbox2 editor and/or the CryEngine2 game engine, to locate and load the texture images.
Add a default material to geometry which does not have a material
-
- bmImport:
This option will assign a default "placeholder" material to any non-skeleton geometry, which does not already have a material. This is intended to be used only when importing legacy models, which were originally created without materials. The placeholder material should be replaced using the Sandbox2 editor.
Enable creation of faux UV coordinates and diffuse map
-
- bmImport:
All Blue Mars rendered geometry must have: (a) UV mapping coordinates, applied to each vertex in the geometry; and (b) a diffuse texture map. This is required even for geometry which is a single, solid color.
This option will create a faux (fake) set of UV coordinates and add a diffuse texture map to all geometry in the object which does not already them.
Note that this option does not attempt to unwrap the object in order to create a real set of UV coordinates; it merely assigns the UV mapping values of (0,0), (0,1), and (1,0) to the vertices of every triangle in the geometry.
Filepath to the faux diffuse texture map image file.
-
- bmImport:
This option is used in conjunction with the -useFauxMap option, in order to specify the diffuse texture map which will be applied to all geometry which has been assigned faux UV coordinates.
By default, this filepath value should be set to textures/ar/Common/ar_solid_255_255_255_diffuse.dds, which defines a 1x1 pixel 100% white diffuse texture map.
Enable alpha test mode for opacity values of 1.0 in .mtl file
-
- bmImport:
This flag enables a shading option to switch to stencil maps for opacity calculations, when the normalized value in an opacity map is set to 1.0. A stencil map is much faster to calculate, but does not allow for gradual transitions in the blending between the foreground object and the background objects.
Merge all nodes (MaxExporter option)
-
- bmImport:
This flag replicates an option from the original 3DS Max CryEngine2 Exporter plug-in.
Set offset used to identify morphed vertices (MaxExporter option)
-
- bmImport:
This flag replicates an option from the original 3DS Max CryEngine2 Exporter plug-in.
Set number of time divisions per second
-
- bmImport:
This value is a 3DS Max system variable, possibly required by some downstream code in the Blue Mars game engine. Unless you are doing something really unusual, this value should be left unchanged, at the default value of 4800 ticks per second.
Set number of frames per second
-
- bmImport:
This value affects certain animation timing. Blue Mars uses the 30 frames per second standard, so, in most cases, the default value of 30 fps should be left unchanged.
Set name of the skeleton root node
-
- bmImport:
In general, COLLADA .dae files of character models should be exported with a single skeleton, with a single root node. The root node should be a skeleton bone/joint node, at the top of the bone/joint hierarchy, and/or be specifically named Bip01. Assuming this is the case, by default, this option is not necessary and the edit field should be left blank, for bmImport.
However, in the case where multiple skeletons exist in the COLLADA .dae file, or in the case where the actual skeleton root node is not the topmost node, this option may be used to identify the name of the skeleton root node which should be used to create the Blue Mars .chr asset file.
Automatically generate proxy objects
-
- bmImport:
This flag enables the automatic generation of simple bounding box physics proxy objects (for .cgf files), or a hit detection object (for .chr files). A proxy material is assigned to the generated object and saved in the corresponding .mtl, if the option to generate the .mtl file has been enabled.
In .cgf files, a bounding box physics proxy object is calculated for each geometry linked to a specific node, unless the node already has a link to a physics proxy or hit detection object.
In .chr files, a single bounding box hit detection object is calculated for the skin geometry object, in a skeleton with skin .chr file, or for the base geometry object, in a morph targets .chr file.
For a skeleton with skin .chr file, the bounding box will be calculated using the posed position of the skin geometry object. Warning: The posed geometry calculation can be very slow for models with a large number of vertices and/or bones. The bounding box hit detection object will be linked to the root skeleton node. Important note: Any and all transforms on the skeleton root node will be reset when using -autoProxy, ie. translation will be set to 0, 0, 0; rotation will be set to 0, 0, 0; and scale will be set to 1, 1, 1.
Run the Resource Compiler as a post-process
-
- bmImport:
If this flag is set, the Resource Compiler will be run as a post-process on the Blue Mars asset files, created from the source file(s).
Save conformed COLLADA instance document
-
bmImport: Not available
bmImportCmd: -dae filename
Note: This feature is intended for debugging purposes only.
Running the Resource Compiler
After using bmImportCmd to generate the Blue Mars asset file, the Resource Compiler will need to process the file to optimize the data and to enable certain features such as occlusion or LODs.
Unlike bmImportCmd, which accepts a source file and generates a separate target file, the Resource Compiler modifies the source file, in place, overwriting the original data.
The Resource Compiler is a Windows command line program, called rc.exe. To run the program, open a Windows CMD window by selecting Start -> Run..., typing in "cmd" into the Open: text entry field, and clicking the OK button.
Running the Resource Compiler with no arguments will bring up the command and options usage information.
Usage: rc [options] file
where
file = Filename of the Blue Mars (.cgf, .chr, or .caf) asset file.
Example:
rc myModel.cgf
In bmImport, the Run Resource Compiler option may be set to run the Resource Compiler as a post-process on each generated Blue Mars asset file.
Acknowledgments
bmImport and bmImportCmd were developed using COLLADA-DOM, from Sony Computer Entertainment of America (SCEA). The ColladaMaya and ColladaMax plug-ins were developed by Feeling Software, under contract to Autodesk.
Revision History
- Version 3.5
- Added compatibility support for ColladaMax/Maya NextGen plug-ins.
- Version 3.4
- Code refactoring and bug fixes.
- Version 3.3
- Option to apply a default material to any geometry without a material was added.
- Option to create faux UV mapping coordinates and diffuse texture map for unmapped geometry was added.
- Version 3.2
- Option to auto-generate physics proxy objects and hit detection objects was added.
- Version 3.1
- bmImport, the GUI version of bmImportCmd, introduced.
- Version 3.0
- Renamed from ColladaBM to bmImportCmd.
- Updated to support CryEngine 2.3.
- Implemented automated triangulization of polygons.
- Improved general COLLADA compatibility.
- Improved support for transparency/opacity.
- Code refactoring and bug fixes.
- Version 2.1.1
- Created Blue Mars version.
- Bug fixes.
- Version 2.1
- Updated documentation.
- Bug fixes.
- Version 2.0.2
- Added support for non-biped skeletons.
- Added support for object instances.
- Bug fixes.
- Version 2.0.1
- Added check pass to detect basic .dae export problems.
- Added support for pickable objects.
- Bug fixes.
- Version 2.0
- Added support for .chr and .caf files.
- Added installer.
- Added documentation.
- Version 1.0
- Only supported .cgf files.
Copyright © 2008-2009 Avatar Reality, Inc.
Return to Blue Mars Asset Creation
Blue Mars Guidebook Privacy Policy
Blue Mars Guidebook Community Guidelines
