maya2q3 GPL source release ================================== HermitWorks Entertainment Corporation Email: phill@hermitworksentertainment.com This file contains the following sections: LICENSE GENERAL NOTES COMPILING ON WIN32 COMPILING ON GNU/LINUX USAGE LICENSE ======= See COPYING.txt for the GNU GENERAL PUBLIC LICENSE ----------------------------------------------------------------------------- Some source code in this release is not covered by the GPL: NVMeshMender.cpp NVMeshMender.h NvTriStrip.cpp NvTriStrip.h NvTriStripObjects.cpp NvTriStripObjects.h VertexCache.h Copyright NVIDIA Corporation 2003 TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THIS SOFTWARE IS PROVIDED *AS IS* AND NVIDIA AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL NVIDIA OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF NVIDIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. DXVec.h is also not covered under the GPL as it is copied from the DirectX SDK. ----------------------------------------------------------------------------- GENERAL NOTES ============= A short summary of the file layout: maya2q3 maya2q3 source code glew GL Extension Wrangler library http://glew.sourceforge.net physfs-1.1.0 PhysicsFS file system library http://icculus.org/physfs/ These folders will be created by the Win32 build process: maya2q3/win32/bin/CONFIG exporter executable binary (and debug symbols) maya2q3/win32/obj/CONFIG intermediate files (.obj, etc) Release builds also generate .pdb debugging databases, however due to compiler optimizations these are not sufficient for debugging - they will not allow you to properly step through the code. If you're trying to debug, use a debug build. COMPILING ON WIN32 ================== DEPENDENCIES: The plugin depends on the GLEW library for access to OpenGL and OpenGL extensions, and on the PhysicsFS library for access to assets in a Quake 3 style game directory. The source for both libraries is included in the repository to make building the plugin easier. You will need to build these libraries before you can build the plugin. To do this open and build libs.sln. The project files it references have already been set up with the correct compiler and linker settings, and will put the .lib files where the maya2q3 project expects to find them. You only have to do this once. Note that neither I nor anyone else at Hermitworks Entertainment are responsible for the development or maintenance of either project. You can find the people that *are* responsible for them here: GLEW: http://glew.sourceforge.net/ PhysicsFS: http://icculus.org/physfs/ THE PLUGIN: Note: You MUST have Maya (or at least the SDK components) installed on your system. Open maya2q3.sln. There are 4 configurations in the solution: debug for Maya 6.0, debug for Maya 7.0, release for Maya 6.0, and release for Maya 7.0 (note that only the Maya 7.0 configurations are being actively developed or supported). You must match the configuration to the version of Maya you are building against. The solution is already configured to build the exporter and copy it to the appropriate directory, along with its supporting script(s). Note that building a debug will overwrite an existing release build. Modify the Custom Build Step project property's command line of you want to change this but we find it makes it easier to debug the plugin if only one copy ever exists: going back to a release plugin is as easy as rebuilding. IF MAYA IS INSTALLED TO A NON-DEFAULT DIRECTORY: If Maya is not installed in the default folder $(Program Files)\Alias\Maya\VERSION then you will have to edit the project's properties to get it to reference the correct header and library files. Open up the project properties and change C/C++ -> General -> Additional Include Directories Linker ->General -> Additional Library Directories Build Events -> Post-Build Event -> Command Line SUPPORTING OTHER MAYA VERSIONS: If you're adding code to support another version of Maya, create new solution configurations and update the above properties. The code automatically retargets itself to the current Maya version based on the value of the MAYA_API_VERSION macro, so it is imperative that the compiler is directed to the correct version of the headers. COMPILING ON GNU/LINUX ================== Download the tar.gz, and extract with tar -zxf maya2q3-VERSION.tar.gz then run make from inside of the mata2q3-1.0/maya2q3 folder. Once it is done there should be a maya2q3.so in the linux/bin directory. Copy that to your maya plug-ins folder. On my system it's in /usr/aw/maya7.0/bin/plug-ins/ You can also use maya to browse for the plugin if you do not have rights to copy it into the plug-ins folder. $ tar -zxf maya2q3-VERSION.tar.gz $ cd maya2q3-VERSION/maya2q3 $ make $ sudo cp linux/bin/maya2q3.so /usr/aw/maya7.0/bin/plug-ins/ The Makefile assumes that the environment variable MAYA_LOCATION is properly defined in your environment, on my system is is set to /usr/aw/maya7.0/ If you have any problems with the linux build, contact scott@hermitworksentertainment.com USAGE ===== MODELLING GUIDE: The exporter only outputs geometry from meshes. That said, it can handle ANY mesh geometry. It supports parenting, instancing, N-sided polygons, and isn't even picky about non-manifold geometry. If you create more than one UV mapping for an object, the exporter will use the first one Maya gives it, whichever that may be. The MD3 format includes a surface name and a default shader name. These are derived from Maya as follows: A surface is basically a set of polygons that share the same material. It is named after the shading group that it belongs to. To access this, select the material and press Go to Output Connection in the attribute editor (this will take you to the shading group). NEW (version 2) WAY: Each surface is connected to a default Q3 shader. The shader is specified by applying a Q3Shader material to the object and setting the shaderName attribute. If a non-Q3Shader material is assigned to an object, it will export using the old rules (below). NOTE: the Q3Shader material understands Quake 3 shader rules and can accept the name of a shader or the path of a texture, in game notation. In order for it to be able to load the shader, you must configure your Maya project to include your game data search paths. To create the appropriate entry execute this MEL script at the command line (after that the entry will appear in the project settings GUI and you can modify it from there). workspace -rt "Q3GameData" "GAME_DATA_PATHS" ; The GAME_DATA_PATHS may be absolute or relative to the project folder. To maintain a cross-platform project, use forward slashes (/) and let the plugin convert them. Multiple paths must be seperated by semicolons. PK3 files in these folders are automatically added to the search as well, in Q3 order. If you are using Maya 6.x you must do this before creating the first Q3Shader node in your scene, and you must restart Maya if you change this variable. The Maya 7.0 build automatically refreshes the nodes when the path changes. This is due to a limitation in the Maya 6.x API. When editing a Q3Shader-bound object's UVs in the UV Texture Editor, use the Image -> Selected Images -> SHADER_IMAGE_NAME to display any texture referenced by the shader in the UV Texture Editor window. Bear in mind that as this is an early release, the plugin only supports DDS and TGA images. BMP and PCX support may be added later. There are no plans to add JPG. For more info on MEL or Maya's project system, check your Maya documentation. OLD WAY: Each surface is connected to a default Q3 shader. The shader is named after the material assigned to the object. In order to maintain compatibility with Q3, this name is mangled (a little bit). The default shader is the material name, with all underscores converted to forward slashes, except if a pair of underscores is found near the end of a name it will be converted to a period. So: sample_shader_name becomes sample/shader/name sample_shader_name__tga becomes sample/shader/name.tga BOTH CASES: NOTE: polygons assigned to the default shader "lambert1" will never be exported. You can use this to your advantage: if you need reference geometry that you don't want to export, simply stick lambert1 on it and leave it in your scene. This is handled on a per-face basis, so you can also use it to create holes in the exported object, while keeping the geometry solid in Maya (which helps with certain tools). Any shape who's name starts with "tag_" (case insensitive) will have its world transform exported as a tag of the same name. If you use polygon shapes for your tags, keep in mind that they will also be exported as geometry, unless you leave lambert1 on them. WIN32 INSTALLATION: 1. Copy maya2q3.mll into MAYA_INSTALL_DIR\bin\plug-ins NOTE: if you are building from Visual Studio and already have your project set up with Maya's installation directory you should skip this step. 2. Copy AEQ3ShaderTemplate.mel into MAYA_INSTALL_DIR\scripts\AETemplates Note: if you are buliding from Visual Studio and already have your project set up with Maya's installation directory you should skip this step. 3. Start up Maya, go to Window -> Settings/Preferences -> Plug-in Manager. 4. Check "loaded" and "auto-load" next to the maya2q3 entry. Note: if checking loaded makes Maya pause briefly but not load the plugin, make sure you have the new version of the MS CRT libraries installed (see step 2). EXPORTING: 1. Set your project and point it to your game data (see modelling guide notes). 2. Model your object. Make sure you give it a Q3Shader material with a meaningful name (see modelling guide). 3. Animate it (if you want). 4. Set the range slider to include the exact frames you want to export (this is important!). 5. Go File -> Export All or File -> Export Selected. NOTE: When exporting a selection, you must select all instances of the geometry you want to expect (even though Maya makes it look like they're all selected when you click on one, you still need to SHIFT-click on the others) AS WELL AS all tags you want to export. Otherwise the exporter won't export everything you intended. 6. Select Export MD3 from the file types list. 7. Type in a file name. 8. Hit Export.