Call of Duty 2: Maya Plugins Documentation

Models and Animations in the CoD2 Engine

Setting up the maya.env and usersetup.mel files on your computer

• To start off, you need to set up the usersetup.mel and maya.env files so Maya can find our tools.
  The files included have already been set up to work with our pipeline.
  The maya.env file creates the environment variables to point to the locations of plugins and scripts located in the tree, and should be put in ' My Documents\maya\6.0 '.
  Example paths are
  ' MAYA_SCRIPT_PATH = C:/Program Files/Activision/Call of Duty 2/bin/maya ' and
  ' MAYA_PLUG_IN_PATH = C:/Program Files/Activision/Call of Duty 2/bin/maya '.
  These will tell Maya to look here for our plugins and scripts.

• The usersetup.mel file will tell Maya what to add on startup of Maya.
  This invokes the startup of our 'COD Tools' menu.

Setting up, skinning and exporting a character model

• The first stage of getting a character into the game is to bind the character’s body to the DefMesh skeleton.
  The DefMesh skeleton is the basic rig that will be ultimately exported into the game, and is included within the Josh_DefMesh character.
  The Josh character is a good example of how one should bind the model to the skeleton.

Our conventions

• Our character models are usually rigged on the DefMesh skeleton in 3 different parts: the body, head, and helmet.
  This is done so that characters parts may be interchangeable.
  This usually means that you want to rig the character or characters bodies LOD's into one Maya file, and the heads into a separate Maya file.
  You can also export the model as one full mesh if you’d like, but you will not be able to make unique characters out of any part of your model that was exported as one full mesh.

• We generally make 4 levels of detail for each character, at 8,000, 4,000, 1,000 and 300 triangles.
  We name the parts for each LoD, _8k, _4k, _1k and _300.

• In all our Maya scenes, Z is up.

Rigging

• You may decide to position the joints to fit the character’s mouth, eyes, and other areas.
  If you decide to move the joints in the face, or any other part of the body, you must animate with the provided Josh_DefMesh characters skeleton positions.
  The reason being is that the provided base_character.XMODEL uses the Josh character.

• After positioning the joints into the correct places, bind all of the facial joints, J_Head, J_Neck, and J_Spine4 joints to the facial geometry.

• Skinning the body uses pretty much the same procedures as the head, except there are no adjustments to joint positions per character on the body.
  Therefore, you are able to put multiple unique bodies and their LOD's into the same Maya file, which can work well for editing and copying weights.

• To export the model, go to 'COD Tools->Model Exporter' in the menu.
  Click 'Add New Entry' to create a new list to add to for each LOD.
  Here is where you can designate where the .xmodel_export files will be exported to.
  You should export all of your models to subdirectories in 'C:/Program Files/Activision/Call of Duty 2/xmodel_export/*.
  Force Export Selected Joints must be checked if you are exporting animatable models (like a character’s head).
  You also must set the meshes and joints that will be exported.
  To do this, you can either manually select the joints that are used in the skinClusters of the head or full charater, or you can use a script called 'selectBound' that is included.
  To use the script, first select all of the pieces of the highest LOD, and type selectBound in the command line.
  This will remove any unused influences from the skinClusters, and will then return and select all of the joints that are used within the selected objects.
  The script will also add extra joints like TAG_ joints where needed.
  After you have the highest LOD's bones selected, Shift select the highest LOD's top group and then set exports.
  After that, you can deselect the 8k group, and shift select the 4k group and set exports.
  Do this for the rest of the LOD's.
  In our engine, even if the lowest LOD is only using 4 joints (which we do when skinning to save in calculation), you must still include all of the joints of the highest LOD in the Exports.

Materials

• By default, the game engine uses the material name you use in Maya.
  It does not use the actual image file you use in Maya, just the name of the material.
  Give your material a good name - we use the prefix ‘mtl_’, followed by the model name for almost all materials on our models, which makes our lives much easier.
  Once you’ve exported your model, you’ll need to create a material with that name in Asset Manager (covered later).

Creating a Rig

• To start off, our main character that we do all animation exports from is the Josh_DefMesh_Rig.
  The reason we must use Josh_DefMesh_Rig to export all animations is because the 'base_character' that we assign for almost all animations is using his character as a reference.
  Often though, we create other animatable _Rig characters that can be used to animate with until export time.

• To create a new Rig character for animating with, start by creating a new Maya file.
  Next, create a reference using namespaces and set the type to ‘this string:’.
  Make a new prefix name (i.e. “rig”) and reference in the Josh_DefMesh character.
  From here you can build animation controls onto the character to animated with.
  You may also decide to just build the animation controls onto the Josh_DefMesh.mb file, but you still MUST create a new reference file before you are to export any animations.

Working with and exporting animations

• Depending on the animation, you may need to add a 'Notetrack' to specify when certain actions occur that have to be noted for scripting purposes.
  Notetracks associate a word or phrase with a frame of the animation, and can be detected by the game script at run time.
  An example of this would be to specify when the sound file for dialog should be played.
  To do this, you can create a notetrack using the tool located under 'COD Tools->Notetrack Window'.
  You would then 'Create Note Track node' on the frame at the beginning of the dialog.

• Once all of your animation is complete and you are ready to export your animation, go to 'COD Tools->Animation Exporter' in the menu.
  Here is where you can designate where the .xanim_export file will be exported to.
  You should export all of your animations to subdirectories of 'C:/Program Files/Activision/Call of Duty 2/xanim_export/*', or where the game has been installed.

• You need to set the start and end frames of the animation, and the joints that are used in the animation.
  If you click on the 'Export Nodes' button, you will notice it will bring up a window that will ask you which character (designated by its prefix) you would like to set for exports.
  This button will then set the full set of joints for exporting for the particular character.
  Sometimes you may want to only select the head joints or the upper torso joints for export.
  In this case, you must select them manually and set those for export.

• If your animation uses a note track, you’ll need to tell the exporter.
  Click on the ‘notetrack’ button in the animation exporter window, and a dialog will pop up asking you which notetrack the animation uses.

Asset Manager

• Asset Manager (AssMan for short) is a little program that helps us edit all our game data files (.gdt’s).
  GDT’s control how Maya models become game models, how materials and animations associate with models and how normal maps are associated with color maps.
  They also control a whole host of other, less-art-specific things, like how weapons behave and what guns each AI uses.

Models

• Click on “xmodel” and
  click on the “New Entry” button and specify a unique name for your model that is less than 40 characters.
  You’ll now see a list that appears on the right hand side.
  For static models, you set the type to ‘rigid’.
  For animated models, you use ‘animated’.
  In the filename box below is where you specify the xmodel_export filename for the highest LOD of your model.
  In the highLodDist selection box, specify the distance that the game should use for the highest LOD.
  From here, specify the mediumLod, lowLod, and lowestLod xmodel_exports and their corresponding LOD distances.

• On character models, you’ll want to specify the hitBoxModel, which is included in the bin/maya directory.

• In AssMan, you have the ability to make a group of models to be randomly selected within the game by giving that group a name of it’s own.
  Groups of model types to be interchanged between characters.
  For instance, you could create an xmodelalias for a handful of head models.
  To do this, you would create a unique name for the xmodelalias, and then assign head models you made as xmodels and put their names in these fields.

Materials

• Click on “material” and click on the “New Entry” button and specify a unique name for your model that is less than 40 characters.
  You can see they are all the materials associated with the models in the GDT.
  The main ones to edit here are first the materialType and surfaceType, where you set these to the corresponding types.
  The other ones to be concerned with is the Color Map, Normal

Map, Specular color map, and Cosine power map fields.
Here you put the path of where these files are located, which should be 'C:\Program Files\Activision\Call of Duty 2\xmodel_export\*’ for materials associated with a model, and in ‘C:\Program Files\Activision\Call of Duty 2\texture_source\*’ for world textures.
The rest of the entries can usually be left as default, but can aid in the look of how the materials are displayed.

Animations

• Click on “xanim” and click on the “New Entry” button and specify a unique name for your model that is less than 40 characters.
  Animation GDT’s should be saved
  in 'C:\Program Files\Activision\Call of Duty 2\xanim_export\*’.

• The first option in the right is “filename”, which is the xanim_export file for the animation.

• The second option is “model”, which can be confusing at first.
  We associate every animation with a model, which establishes the base pose and proportions that the animation is diverging from.
  We also get all hierarchy information from the model.
  Also, any joints that are in the animation but not in the model will be stripped from the animation.
  We made a special model file called “Base_character” for our full-body character animations.
  It’s basically just a copy of our Josh model, but we called it base_character to make it easy to find.

• The third option is “looping” – whether or not the animation is looping.
  When you set this, the last frame of the animation is assumed to be the same as the first, and is deleted by converter.

• “Type” is generally set to “delta” for full-body character animations.
  Delta uses the root joint of the model to determine how far the model moves each frame.
  In “delta” animations, it’s essential that the root bone always remain upright (the Z axis of the bone faces along Maya’s Z axis, or the Z axis of the “node” if a node is specified in the next point).
  Type “relative” treats the root joint of the model (or the joint in the animation that is highest in the model’s hierarchy) as the origin, and animates the other joints relative to that.
  Type “absolute” treats the origin of your Maya scene as the origin and moves all the joints relative to that.
  The “mp_” types are used only for MP animations.

• “Node” is only used with “type”=”delta” animations.
  The node is a very powerful feature that enables us to line up scripted animations perfectly.
  Export a joint or object with your animation from Maya, and enter its name here.
  When the designer plays your animation in script, he or she can specify a node for the animation to be based off, and the engine will move the animation so that the node in your Maya file lines up with the node in the game.
  Thus you could create a complex animation of several people interacting, based around some point on the floor, and you don’t have to worry about compounding errors making your characters drift apart or through each other.

• “angleError” and “translationError” are the maximum errors allowed when compressing the animation.
  Larger numbers make smaller files, smaller numbers make perfect animation.
  The defaults (0.05 and 0.025) result in no noticeable compression artifacts that we’ve noticed.

• “boneStabilizers” is old, and something to do with multiplayer.
  I doubt you’ll need it.

Converting models and animations

• After exporting your models or animations and adding them to AssMan, you need to convert the text files into files the game engine reads.
  To do this, execute converter, located at ‘C:\Program Files\Activision\Call of Duty 2\bin\converter.exe’.
  This will convert all files that have been changed.
  Converter endeavors to find every possible error in your models, materials and animations so that we don’t have any surprises in the game, so you may have to go back and fix problems in Maya or AssMan in order to get converter to finish with no errors.

In-game – the console and DevGUI

• To enable cheat codes, the console and the DevGUI, you need to run the game in developer mode.
  The most common way to do this is to run the game from a shortcut, and add switches to the shortcut as follows: C:\Program Files\Activision\Call of Duty 2\CoD2SP.exe +set developer 2 +set logfile 2 +seta thereisacow 1337.

• +set developer 2 enables the DevGUI and several other development options.

• +set logfile 2 makes the game print the contents of the console to console.log, which can be useful for tracking down missing assets or other errors.

• +seta thereisacow 1337 enables cheat codes.
  Seta archives the variable, so that if you run the game from a different shortcut later, cheat codes should still be enabled.

The Console

• By default, you can bring up the console by holding down Backspace and hitting Home.
  By setting the variable “monkeytoy 0”, the console defaults to the more familiar tilde (~) key.

• The CoD2 console shows only one line by default.
  By hitting shift-~, you can see a larger console.
  In many cases you don’t need it because of the auto-complete features of the CoD2 console.

The DevGUI

• The DevGUI is an in-game tool that we are developing to replace the console for systems without keyboards, and for people who don’t want to learn all the console commands.

• Generally, we show the DevGUI in the PC game by hitting the F1 key.

• Try hitting F1.
  If the console doesn’t appear, it’s probably because F1 isn’t bound to the devgui command.
  Bring up the full console (hold down shift and hit ~, assuming that you’ve set the monkeytoy variable to 0) and type “bind f1”.
  The console will probably tell you ‘”f1” is not bound’.
  (If it tells you ‘”f1” = “devgui”’ then you have different problems, probably in your shortcut.
  You need to activate cheats and developer commands.)
  Next, type “bind f1 devgui”.
  Now type “bind f1” again, and the console should tell you ‘”f1” = “devgui”’.
  Get rid of the console (hit ~) and hit F1 again.
  This time the DevGUI should appear at the top of the screen.

• The DevGUI options vary depending on whether you’re in a map or not.
  In theory, you can use the DevGUI for anything you might want to do, although in practice binding keys to common commands is much faster.
  Navigate through the DevGUI using the arrow keys, Enter and Esc.
  Some options bring up sliders, which you alter using the arrow keys or by holding down the mouse and dragging left and right.

Testing models and animation in the game environment

• Load a map and hit the F1 key to open the DevGUI, and navigate to Model Previewer using the arrow keys and the Enter key.

• The first option you’ll need to use is “Load Model”.
  Select this menu option and hit enter.
  A scroll bar appears at the bottom of the screen.
  Scroll through entries using the arrow keys, or by holding down the mouse button and dragging left and right.
  Once you have selected the model you want to load, hit enter.

• The controls to maneuver around are similar to Maya’s navigational tools.
  Use W and E to switch to move or rotate mode.
  Hold down Alt and use different mouse buttons to move the camera.
  Note that in rotate mode, holding down the right mouse button will rotate the model on its vertical axis.

• A very useful feature of the DevGUI (for artists) is the ability to turn various textures on and off.
  If you go to Renderer -> Texture Override, you can mess with the light map, normal map, color map and spec map.
  If you’re technical, you can also glean some information from the debug shaders, which might help debug lighting anomalies due to messed up normals.

• You can also apply animations to the model, using the animation previewer.
  To be frank though, the animation previewer isn’t done, and it’s not easy to use.
  It can be useful if an animation doesn’t work, and you want to debug it, but for general testing you’re much better off scripting the animation to play in a level.

Sources: Infinity Ward Docs