FaceGen Pipeline

(Redirected from FaceGen)
Jump to: navigation, search

Please note: FaceGen licensing is now provided free of cost to HeroCloud Licensees. Once you've looked over this page and are ready to see how deep the rabbit hole goes, please see the FaceGen Customizer page to obtain the Customizer Executable.

FaceGen technology is the key ingredient in the entire character system, and impacts both face and body. HeroEngine uses a blend of it, along with our own modifications, to do body morphing, facial expressions, and head customization. Not all characters need to use FaceGen technology -- sometimes the Parts system is more appropriate.

This document covers setting up your own data.



The key to FaceGen is its statistical model. You can create a base line definition of the shape of a character (such as the nude form) and then create any number of morph targets from that. Then, the statistical methods will ensure that every alternate part (clothing, hair, helms, everything) will morph correctly without having to create any morph targets for them. The artist time, computer memory and disk space savings of this over traditional methods cannot be overstated!

It's important to know when exactly you need this system. There is overhead associated with using FaceGen statistics (namely the statistical information that must be generated and loaded) so it is best to utilize this for limited parts of your game design (such as just player characters and NPCs). The hard and fast line is that the FaceGen pipeline is used when a character requires some sort of morphing. Typically this means it's used for player characters, but not for creatures. And always keep in mind that you can have characters that take advantage of the Parts system without using any FaceGen data.


Morph Type Memory Requirements Per Morph (bytes) Performance Considerations Per Vertex
Diff 10 * numVerticesInMesh 3 multiplies and 3 additions
Stat (16 * numStatMorphVerts) + 4 3 subtractions, 3 additions, 3 multiplies, plus 3 multiplies and 3 additions per base statistic control
(Typically, numStatMorphVerts will be less than numVerticesInMesh, but as you can see, the cost per-vertex for a stat morph is quite a bit higher than that of a diff morph.)

For more information on terms and concepts, read readme.pdf in the FaceGen SDK and also this page.

Note: template_directory will be used throughout this tutorial to refer to a base statistic's root directory


The bulk of the pipeline is cascading, so that performing one step requires you to perform all subsequent steps down the pipe.

Integration and generating cache files each take an amount of time proportional to the number of controls in the base statistic:

The majority of the FaceGen process is spent integrating meshes and adding the statistics, as this happens every time you add a new character part that needs to be affected by FaceGen.

Base Statistic Initial Setup

This section covers creating your own custom full-body statistic that can be used for body morphing. The same steps apply to creating a custom statistic for any section of your character (for example, a custom head statistic for applying morphs that aren't covered by the default FaceGen statistics, like nonhuman racial morphs).

If you're just looking to take advantage of the extensive head statistics provided by FaceGen for your own head mesh, skip down to generating cache files.

Creating Your Source Meshes

The first step is to create your "mean mesh." This is the base-line character from which all control meshes (aka, morph targets) are derived from. For a human-like character, this would be a character in a root pose with no geometric clothing details. We are just looking for a good volume that represents your character.

Mean mesh morph.jpg

Remember that this is simply the statistical model, not the actual render model. Therefore this mean mesh and its accompanied extreme targets do not need materials or skinning data. Your render model will made up of any number of parts and sub-parts and they can have any sort of topology you like (each different from the next). What the mean model is used for is defining the statistical information for how this model will change as morphs are applied and it can then use this information to correctly morph every other renderable mesh regardless of its topology.

Once you have a mean mesh created, you can move on to create an extreme mesh for each control you need in this statistic. Every extreme mesh must have the same vertex count. You can only edit these targets by translating vertices in 3D space; in all other ways, it must be identical to the mean mesh. This means that you cannot change the topology (meaning you cannot add or remove vertices or change the triangle layout in any way). This is the same requirement you'll find in doing morph targets in any other 3D app.

Tip: When you're designing what controls to create in the statistic, keep in mind that each one must be as orthogonal as possible. For example, if one control increases the size of the eyes, then no other control should do that (however another control may increase the slantiness of the eyes, for example).

Here are some sample full-body extreme meshes:

The dwarf and Lanky controls would also require skeletal morphing to look right--since it changes proportions and size--while the body gut, bulk, and bobblehead controls would not, since it keeps the same general proportion of the mean mesh.)


  1. First we'll deal with getting the OBJs out of Max and into the proper directory. It's easiest to author all of your statistical targets in the same scene as your mean mesh. Make sure your mean mesh is at 0,0,0 and its Xforms have been reset so your scale is at a uniform 100. Off to the side I have all of my target meshes, which are simply deformed duplicates of the mean mesh.
    Targets morph.jpg
    Morpher max.jpg
    Some benefits of using the morpher and keeping all of these in 1 max file are:
    • Scene management: less files equals less mess
    • The ability to preview the combinations that your targets will make
    • Ensuring that the vert counts and mapping stay consistent
  2. Select your mean mesh and from the modifier dropdown select Morpher. Then add your targets to the available empty slots in the Morpher panel.
    • After you've added your targets to the mean mesh, hide your target meshes. You do not want to look at these again unless you need to do some edits.
  3. Now Export the controls one at a time. First, with all the Morphs turned to 0, do file\export selected\OBJ. This first one will be your base mean mesh. Make sure to follow the settings in the following OBJ image. If you modeled in tris, simply change the faces box to tris.

Alternately, you can export your controls as static asset GR2s and change them to OBJ format with the GR2toOBJ.exe converter available on the Account Management System downlod page

    • Name them all with a common prefix that describes your base statistic (e.g. a common prefix of morphman_ might result in meshes named morphman_base.obj, morphman_bobblehead.obj, and morphman_bulky.obj)
    • Type: Static Asset (because this isn't skinned to anything and only serves as a volume)
    • When Exporting, make sure that Move to origin is unchecked
    • Export the OBJs to your facegen directory \template_directory\egm\objs
      OBJ settings.jpg
  1. Export the mesh again with with your first Morph Target on the Morpher set to 100. Name this appropriately.
  2. Repeat the last step until all morphs are exported. Remember, only one can have influence at a time.
  3. Source Code Devs: Get //depot/vendor/singular_inversions/template_directory/... from Perforce.
    Contact the support list to request access to this directory, if it is not already available to your perforce user account.
  4. HeroCloud Devs: Get ...\ArtPipeline\Templates\...
  5. Rename template_directory to the name of the base statistic you're creating, like "Full Body" or "Torso."
  6. Edit the batch file template_directory\process.bat
    • Change the variables logFile, ctlFName, defaultFGName, and gr2toobjdir as needed.
      • You probably want to set logFile to be the same as the path to template_directory, so you have the generated log file of process.bat in the same place as process.bat.
      • Make ctlFName and defaultFGName similar to the name of your base statistic.
      • Example: For a statistic named Torso, make ctlFName torso.ctl and defaultFGName defaultTorso.fg
  7. Edit the batch file template_directory\egm\add_morphs.bat
    1. Replace the string "baseTriMesh" with the name of your mean mesh (without the extension, so "bob.gr2" is just "bob").
    2. Replace "meshNamePrefix" with the common prefix you put on all of your source mesh names.
  8. Add the controls to complete the base statistic.

Adding Controls

For each control you want to add, you must have already created an extreme mesh. When you have done so, do the following to add the controls to the base statistic:

  1. Bring the extreme meshes for the new controls into template_directory\egm\gr2s. Make sure they've been fixseamed if need be.
  2. For each control, add a line to template_directory\egm\add_morphs.bat using the following pattern (change the things in red):
    addanimatemorph diff InternalMeanFace.tri extremeMeshName.tri "Display Name of This Control" InternalMeanFace.tri
    • If this control changes the proportions of the mean mesh (making it a skeletal morph), the display name of the new control must be the name of the morph (i.e. MorphName, see here for where MorphName comes from).
    • If you're specifying the first control, you must also replace the first InternalMeanFace.tri on the line with the name of the mean mesh (with a .tri extension), like so:
      addanimatemorph diff meanMeshName.tri firstControlExtremeMeshName.tri "Display Name of The First Control" InternalMeanFace.tri
    • There are by default 3 example lines in add_morphs.bat; overwrite those before adding new lines.
      Note: FaceGen requires at least 3 shape controls per base statistic. If you don't have 3 controls, fill the remaining ones with "dummy" controls by using the mean mesh as an extreme mesh.
  3. Run template_directory\process.bat.
  4. Check the end of the log file (it's wherever you set the logFile variable in process.bat to) for a line that says
    xxx diff morphs converted to EGM modes
    (where xxx is the number of controls you have created for the statistic)
    • If xxx is 0 or some other number not equal to how many controls should be in the statistic, check for other errors in the log file.
  5. If this was the first time generating this base statistic, do the following:
    1. Create a facegen.dat if it doesn't already exist for this character specification.
    2. Create a subdirectory in the FaceGen subdirectory named after the statistic (see the EGM property here if you don't know what kind of statistic you're using). This will be referred to as the statistic subdirectory.
      • For example, the Head statistic subdirectory for an orc might be Character\Orc\FaceGen\Head\
    3. Upload the generated .ctl and .fg files in template_directory\ctl\ and template_directory\fg\, respectively, to the statistic subdirectory you created in the previous step.
    4. Add the new base statistic to facegen.dat in the [Controls] section:
      1. Add the appropriate statistic name (Head, CustomHead, or Body) in {} to begin the control's definition (this will be the same name as the statistic subdirectory).
      2. Add paths to the .ctl and the corresponding .fg files in the statistic subdirectory using the File and DefaultCoord properties, respectively.
  6. In facegen.dat, add any control keywords for the new control(s) as appropriate.
    • If this control is for a skeletal morph, the keyword must be named a certain way (see the last step here for details).
  7. If the control changes the model's proportions, add a skeletal morph for this new control.
  8. (Re)Generate the cache files for this base statistic.

Here's what you should have after you've created the statistic:

  1. A .ctl file in template_directory\ctl. This tells how controls are laid out in egms. It also holds the strings for the control names.
  2. An InternalMeanFace.tri and InternalMeanFace.egm in template_directory\egm. They tell how each control modifies the mean mesh to get its extreme mesh as a result.
  3. A .fg file in template_directory\fg. This is a saved version of the statistic that represents having all of the controls set to 0. In other words, applying this coordinate file to a character would give you the mean mesh.

If you're missing any of the above files after completing these steps, check the log file that was output from process.bat to see what went wrong. Start with the first error you find from the top of the log file and work down from there.

Generate Cache Files

You've created a base statistic (or are using the default FaceGen head statistics), but before you can integrate your part meshes, FaceGen needs to run some heavy calculations to figure out how your mean mesh relates to the extreme meshes. This makes integration much quicker, which is important since that's the step that you run most often.

If you're regenerating cache files because you changed a base statistic in some way, copy the [Integrate] section from the old Customizer project, delete that old project, complete these steps again starting at step 2, and paste the [Integrate] section into the new Customizer project before you move on to the integration step. That way you won't have to set up every mesh for integration all over again.

  1. If you're using the default FaceGen statistics for the first time, do the following to produce a reference head mesh:
    1. Open up the highest resolution version of your head mesh that will actually be used in the game.
    2. Since this version of your head mesh is for reference, remap the entire thing to use a single material to eliminate seams and vertex duplication due to material intersections.
    3. Import the super-high-poly-reference-mean-face-mesh (the FaceGen mean face) into your modeller (for Max, see these instructions). It is available on the Account Management System download page.
    4. Translate, rotate, and/or scale the FaceGen mean face as a whole to align it to your head mesh. The goal is to have it overlap the skinned head mesh of your character. It should fit as closely as possible to the character head; the character should actually poke through a bit in places. Don't alter the individual vertices of the FaceGen mean face in any way!
    5. Skin the FaceGen mean face to the same rig as the head mesh.
    6. Export the repositioned FaceGen mean face and your head mesh separately using the same settings as for any other dynamic character part.
    7. Run both of the exported meshes through GR2ToObj (you can drag-and-drop them, one at a time, onto GR2ToObj.exe).
  2. Run FaceGen Customizer.
Note: If this is your first time running Customizer on your machine, you'll need to get a site key for the machine. To do this, send the displayed site code to support@facegen.com (use copy and paste to avoid transcription errors). You have to repeat this site code/key procedure for each machine you want to use Customizer on.
  1. Create a new project.
    • The project name determines what folder will hold the project data (it'll be projWhateverProjectNameYouEntered), and the model set name is for your own personal reference.
    • If you're doing these steps because you changed the base statistic, make sure you delete your old version of the project or else you'll quickly run out of disk space (the cache files are ~98MB per control, so you don't want outdated ones accumulating on your hard drive).
  2. Import the mean face and registered models.
    • If you're using the default FaceGen base statistic, use the resulting obj for the FaceGen mean face that you exported above as the "Re-scaled/Re-oriented mean face" and the obj of your head mesh (also exported earlier) as the "Imported registered models".
    • If you're using a custom base statistic, use template_directory\customizer_1_1\data\InternalMeanFace.tri for both "Re-scaled/Re-oriented mean face" and "Imported registered models" (you'll probably have to change the file filter in the open dialogs to display .tri files)
  3. Follow the instructions in the Integration Setup section of this page. Skip the "Obtain neck seam vertices" section if you're not working with the default FaceGen head statistic.
    Note: Creating cache files is dependent on the number of controls in the base statistic. There's one cache file generated per control, each one taking 5-10 minutes to calculate and ~100MB of disk space. So the default FaceGen statistics--with 80 controls--take ~7-14 hours and ~9GB. Custom base statistics, however, tend to be much more lightweight as they have fewer controls. Note that these files, while very large, are not distributed to the end user and are only used by FaceGen for doing its internal analysis during part integration.
  4. Integrate any meshes you have that are affected by this statistic.

Integrate Meshes

As its name implies, a base statistic is just the "base"--or springboard--to actually generating the statistics for individual meshes: it tells a mesh what it has to conform to. For each mesh that can be deformed by the base statistic, you need to generate statistics and feed those results into the engine. Generating these mesh statistics is called integration. For example, if we had a base body statistic, integrating a gauntlet mesh would result in a set of statistics that allow the gauntlet to automatically scale properly when you make your character bulkier. This is the most-travelled section of the FaceGen pipeline.

Note: If you're just integrating because of regenerating cache files, make sure you've copied the [Integrate] section from your old Customizer project file into this new one and then skip to step 4.
  1. Fixseam the meshes to be integrated.
  2. Using GR2ToObj, convert all of the meshes to be integrated into obj files, and put them somewhere.
    1. If you haven't already done so, create a master directory for gr2 -> obj conversion of parts:
      1. Create a directory with GR2ToObj.exe and granny2.dll in it.
      2. Grab \\depot\HeroEngine\MAIN\GR2ToObj\GR2ToObj\Release\runOnAllGR2.bat from Perforce and put it in the same directory.
      3. Make a subdirectory named gr2s.
    2. Put all of your gr2s for integration into whatever directory structure you want within the gr2s folder.
      • If you're going to use the FaceGen layout helper (it's recommended if you're integrating several meshes at a time), make the subdirectories of the gr2s folder identical in structure to the layout of your meshes in the repository (see the layout helper prerequisites section for an example).
    3. Execute runOnAllGR2.bat and you'll have the obj equivalents in an objs subdirectory, with the directory structure of your gr2s folder maintained within that.
  3. Use HeroBlade to automatically generate a layout file for your Customizer project.
  4. Use the generated Customizer layout file to modify the Customizer project file.
    Note: Make sure Customizer is closed before modifying the project file.
    1. Open the file generated in the last step in OutputDirectory\customizerLayouts\. It'll have the same name as the character specification you're working on (i.e. Human_Male.layout if the character specification is Human_Male.dat).
    2. Open the corresponding Customizer project file in CustomizerDirectory\projYourProjectName.
      • It should be named like your project directory, but without the proj, i.e. YourProjectName.fgprj
    3. Copy and paste the generated layout file contents into the [Integration] section of the Customizer project file. You'll have to hand-merge the ModelMorph lines of existing meshes that have morphs, as the layout helper isn't able to generate those lines.
      • If the Customizer project file doesn't have an [Integration] section, add a line with the text [Integration] on it and then paste the entire contents of the layout file starting on the next line.
      • If you do any hand editing of the file, pay attention to the model numbers; if you have duplicates, Customizer will get confused and some meshes will be skipped.
  5. Run FaceGen Customizer.
    • Read the instructions for model integration here for some background.
    1. Open the project in Customizer.
    2. Click the Geometry Integration button.
    3. Make sure that none of the models you just added have a "skip" in the Skip column.
    4. To assign neck seam vertices (only when integrating with the default FaceGen head statistic) or diff or stat morphs to a model, select the model and click the Change button (see Assign Neck Seam Vertices and Animation Morphs under the Geometry Integration section here for details).
    5. Click the Start Integration button to generate the statistics for the meshes.
  6. Add the resulting statistics to HeroEngine.

Add Statistics to HeroEngine

After you've integrated meshes, you actually need to tell the engine to use the resulting statistics with their corresponding .GR2 files (the exported assets from Max/Maya). To do this, you'll need a dynamic character and a primed facegen.dat file. Once you have those, do the following steps to hook up your statistics from integration:

  1. Copy all of the .egm files (and .tri files for those meshes that have diff or stat morphs) in the csamYourProjectName subdirectory of your Customizer project folder (projYourProjectName) into the appropriate statistic subdirectories of your FaceGen subdirectory.
  2. Use HeroBlade to automatically generate a [SAMs] section for your facegen.dat.
  3. Open one of the generated layout files in OutputDirectory\facegenDatLayouts\ in your favorite text editor.
  4. Do the following for the newly integrated meshes that have the combination of statistics specified by the layout file you just opened:
    1. Find them in the generated layout file (the SAM name will be in the form slotName.partName).
    2. Copy them into the [SAMs] section of facegen.dat.
    3. Add any TRI (if the part includes a diff or stat morph) or RecalculateNormals properties, since the layout helper doesn't take care of those.
  5. Repeat steps 3 and 4 for each layout file you exported.
  6. Make sure everything looks okay in HeroBlade.


Once you finish adding the most recent batch of statistics to HeroEngine, you should run HeroBlade to ensure things are working properly. Check for the following:


Automatically Generating SAM and Customizer Layouts With HeroBlade

HeroBlade has the ability to automatically export both a project file for FaceGen Customizer and a prefilled [SAMs] section of facegen.dat so that hand-editing of those text files is kept to a minimum. This is extremely time-saving when your artists start cranking out content, requiring you to add several parts at once. It also cuts down on all sorts of errors associated with tedious editing of text, including copy-and-paste errors.

The helper works by looking at the location of each mesh in the repository (based on the paths provided in the .par file and then generates the following:


There are a couple of requirements to meet before you can take advantage of HeroBlade's automatic generation of FaceGen layouts:


  1. Create an NPC (or go to an area that has an existing one) of the same type that you're looking to generate layout information for. The NPC doesn't have to be visible, but it does have to be created on the client.
    Tip: It can be helpful to have an area in which there exists one NPC of each type of creature in your game. That makes it easier to use the layout helper next time, as well as check at a glance that all characters are functioning/rendering properly.
  2. On the Render panel, find the FaceGen layout helper (see image to the right).
  3. Check the statistics (coordinates) you wish to have included in the export data.
    • This determines which EGM(coordinateName)= lines each SAM has.
  4. Enter an OutputDirectory.
  5. Enter the location of the base obj directory where the obj file hierarchy is.
  6. Hit Save to generate the files into OutputDirectory.
  7. Repeat steps 3 and 4 for as many combinations of coordinates as you need for the parts you're adding to the character.
    • For example, if you're adding a leg part and a hat part and are utilizing body morphing, the leg will need just the Body coordinate, while the hat will need at least the Head and Body coordinates. Do one export with just Body checked, and one export with both Head and Body checked.
FG Layout Helper.png

Create a Minimal Facegen.dat

  1. Create a directory somewhere on the repository to hold your FaceGen-related data for this character specification, referred to from this point on as the FaceGen subdirectory. It makes sense to make a subdirectory under your character specification folder and name it FaceGen, i.e. Character\Orc\FaceGen\.
    1. Create a subdirectory in the FaceGen subdirectory named after the statistic (see the EGM property here if you don't know what kind of statistic you're using). This will be referred to as the statistic subdirectory.
      • For example, the Head statistic subdirectory for an orc might be Character\Orc\FaceGen\Head\
    2. If you're using the default FaceGen statistics (the Head statistic), copy the controls file and default face coordinate into the statistic subdirectory:
        1. Copy si.ctl from FaceGen Modeller into the statistic subdirectory. Feel free to rename si.ctl as you see fit.
        2. Generate a default face coordinate from si.ctl using BlankFgCoord.exe and upload this .fg file to the statistic subdirectory.
      • (For a custom base statistic, this will be done later when you add your controls.)
  2. Create a text file named Facegen.dat in the FaceGen subdirectory.
  3. Add a line like the following to your dynamic character specification (.dyc) file that tells it where to find the file you just made in the last step:
  4. Fill the Facegen.dat you just made with the minimal amount of information necessary.
    1. Add the [Settings] section with the version number as the only property in it.
    2. Add the [Controls] section.
      • If using the default FaceGen statistic, do the following (otherwise, this information will be covered when you add controls for your custom base statistics here and so right now your [Controls] section will just have the header):
        1. Add a {Head} line to begin the control's definition.
        2. Add paths to the .ctl and the corresponding .fg files in the statistic subdirectory using the File and DefaultCoord properties, respectively.
        3. Add any control keywords as appropriate (see Default FaceGen Head Statistic Control Name Reference for the control names to choose from).
    3. Add the header to the [SAMs] section, but leave the rest of the section blank.

See also

Personal tools