a.k.a. Blender to Unity Asset Builder (Part 2)

I didn’t plan on writing a second part to the Blender to Unity Asset Builder post, but I found myself continuing work on my asset build scripts because for whatever reason, Unity does not recognize Blender’s pose markers during FBX import, so no animation events get loaded for all the animation clips. But for a full explanation, let me rewind a bit.

Some Background

Definitions

3D animation for games consists of short clips of animation made up of keyframes that define the motions of a skeleton or armature. Short clips can be defined as “walk” cycles or “idle” loops. Furthermore, for real-time animation used in video games, “event triggers” can be attached to specific frames of the animation to let other systems know about a key point in the animation to react to. For example, events can be added to footsteps in a walk cycle, so that the audio system can trigger a particular footfall sound.

For my purposes, I needed event triggers for “attack” animations, in which a character winds up for a punch or sword stroke, and subsequently lunges forward for the strike. That strike needs a trigger, so that the character on the receiving end of the attack can play the reaction animation.

Blender’s event triggers are called Pose Markers (in the Dope Sheet/Action Editor):

Whereas Unity’s event triggers are called AnimationEvents (as seen on the FBX asset’s Animation tab):

The Problem

When exporting a Blender file to the FBX format, the Pose Markers do not get saved out with the file. This means Unity will never know about these animation events. While Unity has a way of storing these events, it’s preferable that the data comes from Blender because this is where the animation is being authored. Adding the events on the Unity side means that every time a model is modified in Blender, the animation events must also be re-added back to Unity. That’s a lot of throw-away work:

Solution Hints

After a lot of researching online, I came across two good sources that were promising:

• Importing Animation Events from Blender into Unity3D by Jens Ch. Restemeier
• ADD ANIMATION EVENTS USING ASSETPOSTPROCESSOR IN UNITY

Both of these solutions are pretty much the same, but they’re just implemented slightly differently. I’m personally using Mr. Restemeier’s solution as the basis for my solution, since it uses XML as the intermediate data format, so I’ll use that as the basis of my explanation below.

Solution Overview

Here are the main steps that need to happen:

1. Blender constructs an XML structure of the animation events.
2. Blender exports the resulting XML file into the Unity Asset directory.
3. Blender exports the model as an FBX file into the Unity Asset directory. (See the previous blog post.)
4. Unity processes the XML file after processing the FBX model.

Starting with the XML-based solution, I mainly had to modify the Python and C# scripts to be usable with the latest versions of Blender and Unity. For the most part, I didn’t have to update any API calls, which surprised me. The majority of my changes had to deal more with getting those scripts to work with my own build system.

Integrating Into the Existing Asset Builder

Blender Scripts

There’s not that much that’s different from the Blender Operator script that I discussed in the previous blog post. The MyExportFBXOperator class would simply be adapted into something like a MyAnimEventOperator class. The obvious difference would be in the execute(self, context) function, of course, in that instead of exporting an FBX file, the operator would write out an XML file, and Mr. Restemeier’s solution in export_events.py provides a perfectly sound solution to this. What is of interest though, is how the Pose Markers are obtained. Here’s a Python snippet that will loop through all pose markers in each action clip in a Blender file.

for action in bpy.data.actions:
    print('action: ' + action.name)
    for marker in action.pose_markers:
        print('marker: ' + marker.name)
        print('frame: ' + (int)marker.frame)

Unity Scripts

The Unity scripts also did not require much editing. The file of interest is EventImporter.cs. The EventImporter class is derived from the AssetPostProcessor class, which is a class used by Unity’s build pipeline to allow any custom post processing. The function of interest is OnPostprocessModel() which reads the XML file generated by Blender and populates each animation clip’s AnimationEvents from that XML data.

The only part that gave me problems was the introduction of the EventReceiver class in that function. The EventReceiver is intended to receive the events (duh) from the AnimationEvents that fired. For instance, an AnimationEvent with the name “Stab”, will call the function

public void Stab() {}

in the EventReceiver class. Naturally, this class is very game-specific, and is only intended to serve as an example. I decided to comment out anything regarding the EventReceiver in the OnPostprocessModel() function, since the EventReceiver component is dynamically added in this function, it has a tendency to leak memory.

I also commented out this code block:

if (methodInfo != null){
...
} else {
...
}

This code populates the user-defined data for the AnimationEvent. It can be composed of a float, int, string, or object reference. It may be necessary for some projects, but I don’t have a particular need for it now. Additionally, it’s not absolutely necessary to use C# reflection (the only usage of the EventReceiver component in this function) to determine a match between the receiving function and the supplied data. Although it’s probably good programming practice, it unnecessarily ties a game-related class to a generic build pipeline solution.

After everything is working, the “Stab” event shows up in Unity’s Animation Window.

Unfortunately, I couldn’t get the event to show up when selecting the FBX asset in the Project window, but that’s okay. At least the Animation Window shows proof that it actually works.

Blender Export Dialog

To tie together all of the export functionality in Blender, I decided to write up a Dialog to invoke from a keyboard shortcut.

bl_info = {
    "name": "Export Master Menu",
    "author": "Under the Weather, LLC",
    "category": "Import-Export",
    "description": "Export Master Menu",
}

import bpy
from bpy.types import Menu, Panel, UIList
import MyExportFBXOperator
import MyExportAnimEventsOperator

# export flags
gModel = True
gTextures = True
gAnimEvents = True


class DialogOperator(bpy.types.Operator):
    bl_idname = "wm.exportmastermenu"
    bl_label = "Export Master"
     
    sTargetGameAssetPath = bpy.props.StringProperty(name="Target")
    
    bExportModel = bpy.props.BoolProperty(name="Model")
    bExportTextures = bpy.props.BoolProperty(name="Textures")
    bExportAnimEvents = bpy.props.BoolProperty(name="Anim Events")
    
 
    def invoke(self, context, event):
        global gModel, gTextures, gAnimEvents
        
        self.bExportModel = gModel
        self.bExportTextures = gTextures
        self.bExportAnimEvents = gAnimEvents
        return context.window_manager.invoke_props_dialog(self)
    
    def execute(self, context):
        print('Processing')
         if bpy.data.filepath == "":
            print('Blend file needs to be saved first.')
            return {'FINISHED'}
        
        if self.bExportModel:
            bpy.ops.wm.exportfbx('EXEC_DEFAULT', targetGameAssetPath=self.sTargetGameAssetPath, copyTextures=self.bExportTextures)
            
        if self.bExportAnimEvents:
            bpy.ops.wm.exportanimevents('EXEC_DEFAULT', targetGameAssetPath=self.sTargetGameAssetPath)
            
        print('Process complete!')
            
        return {'FINISHED'}    
    
def register():
    bpy.utils.register_class(DialogOperator)    
    

def unregister():
    bpy.utils.unregister_class(DialogOperator)

Which looks something like this:

Conclusion

I seriously thought I was done writing my custom asset builder the last time I wrote about it. As I was working more on my game, I was trying to avoid using Unity’s AnimationEvent system by simply capturing state changes in the Animator component’s AnimatorStateInfo. Soon enough, I found that I needed to capture events in the middle of animation clips rather than just at the end or beginning, so I dug around for solutions, and the ones I linked to above seemed to be the most promising ones. There were a few solutions in the Unity Asset store as well, but I wasn’t able to get the free one working out of the box, and the other solutions weren’t free. I think that’s about all I want to talk about in regards to the asset build pipeline for a while. It’s time to make a game!

• Blender: 2.74
• Unity 3D: 5.1.1f1

Over the past few days, I’ve been working on an asset builder to build my Blender models. Here’s the what, why, and how.

What is an Asset Builder?

An asset builder automatically processes content authored by artists, designers, etc. into data that can be readily used by a game engine. In the case below, I am specifically talking about 3D models, textures, and animations authored in Blender that are converted into a data format that is usable in Unity3D.

Why Do You Need an Asset Builder for Unity?

Generally, for Unity, you actually don’t need an asset builder. When you place an asset like a blend file or fbx file in the Assets folder in your Unity project, the file gets automatically processed into models, skeletons/armatures/avatars, and animation clips, ready to be used in your game. I really didn’t want to spend time on writing build tools. I was hoping Unity’s processors would be good enough. For my purposes though, I had a few problems getting my models from Blender to Unity.

1. Placing a .blend file directly into Unity doesn’t give you full control over how the models/skeleton/animations are processed. It’s possible that the results may not be fully optimized.
2. As a result of #1, manually exporting from Blender to Unity, although straightforward, is time consuming and repetitive. These qualities suggest that this task can be easily scripted and automated for efficiency. The manual process usually goes like this:
   1. Open the Export to FBX Menu in Blender.
   2. Select FBX export settings.
   3. Navigate to the destination Unity Asset directory and name the file. (I’m using Blender’s Rigify addon, so the RigifyToUnity asset requires that the file name have an identifier like “rigify” in it.)
   4. Click on Export.
   5. Repeat 10-100 times a day.
3. This last point is a result of a personal preference that I have in regards to source control. I prefer to keep my .blend file separate from the exported FBX file that resides in the Unity Asset directory. The reasons for this are as follows:
   1. FBX files are generally smaller than .blend files, due to some optimization options that the FBX format provides, like exporting only deformed bones. Enabling some of these options can significantly reduce the size of the data necessary for Unity.
   2. I keep my source assets (3d model .blend files, textures (PSDs, XCFs, SVGs, PDNs, etc.)) in an SVN repo, and my code in a Perforce depot. I do this because my Perforce depot is getting quite huge already, and adding source assets to the depot will just make it even larger. That said, I don’t want to keep large .blend files in my code depot.

As a side effect of this structure, I now have two files representative of the same asset; one in my working art directory and the other in my Unity asset directory. However, I plan on only keeping the source .blend file in source control, and the exported FBX file is considered part of my asset build, so it doesn’t have to be stored in source control. However, if later down the road, I absolutely need to keep the FBX files in source control, they will at least be the fraction of the size of the .blend files in my Perforce depot.

I admit this can sound confusing to those not familiar with all the systems that I mentioned. Luckily, item 3 above does not apply to everyone, and hopefully can just be ignored by a majority of those developers who have a slicker source control setup.

How Do You Implement an Asset Builder?

The general answer is, “It depends. Every project’s requirements are different, so the build system has to be custom built.” With that said, the best I can do is describe how I implemented my asset builder.

Python and batch files. That’s the quick answer.

Python is great. And especially with Blender’s support of Python, it makes the asset build solution even more feasible. (I know that Maya and 3ds max also support Python, but I’m not sure to what extent, though I wouldn’t doubt that it’s possible to use Python for an asset build solution in those 3d packages as well.)

Requirements

The first step, of course, is to define your requirements. I’m on a Win7 PC.

I want to:

1. Automate the conversion of a <name>.blend file from my working art directory to a <name>_rigify.fbx file in the Unity Asset directory, while preserving the subtree that the .blend file resides in (i.e. <art>/<game>/models/hero/hero.blend -> <Unity project>/Assets/models/hero/hero_rigify.fbx).
2. Be able to click on a batch file to launch the autobuild step in #1.
3. Be able to press a shortcut in Blender to launch the autobuild step in #1.
4. Be able to click on a batch file to run an autobuild on the entire models directory, which simply calls the autobuild step in #1 for each model in that directory.

Implementation

As you may guess, item 1 above is the bulk of the work. Items 2, 3, and 4 are just hooks into the work done in item 1.

Since there are so many facets to setting up build scripts, I’m just going to attack this explanation as best as I can. It’ll be all over the place, but I’ll try to be as complete as possible.

Command Line Scripts

Add a directory to your path that contains all your art tool scripts. For example, d:/art/_tools/. This way, your batch files can be accessible from anywhere in the system. It’s also probably a good idea to add an environment variable for your tools path, like ART_TOOLS_PATH = d:/art/_tools/.

The main key to getting this to all work is Blender’s command line mode:

blender.exe mymodel.blend -b --python pythonScript.py -- param1 param2 ...

This allows you to run Blender in background mode (-b) and execute a Python script that Blender can read, passing in any number of parameters to the script that you may require.

You can just wrap this up in a batch file (i.e. exportfbx.bat)  that contains something like this:

blender.exe %1 -b --python %ART_TOOLS_PATH%/myBuildScript.py -- %2

where %1 is the name of the .blend file passed to the batch file, and %2 can be the destination path.

This way, you always have the option to write a batch file for an individual model, call it say, build.bat that sits alongside your .blend file in say, <art>/<game>/models/hero/hero.blend, that does something like this:

exportfbx.bat hero.blend d:/myUnityGame/Assets/

And you may notice that this batch file satisfies our requirement #2! Yay!

But if you’ve also noticed, we have to step back to requirement #1. We need to implement something in myBuildScript.py for Blender to actually execute. My script basically looks like this:

import bpy
import sys

def main():
    argv = sys.argv
    argv = argv[argv.index('--') + 1:] # get all args after '--'
    if (len(argv) < 1):
        print('ERROR: Target game asset path not specified.')
        return

    bpy.ops.wm.exportfbx('EXEC_DEFAULT', targetGameAssetPath=argv[0], copyTextures=True)

if __name__ == "__main__":
    main()

As you can see, it looks like a basic Python script. The key thing to note is that we are importing the bpy module for Blender to use, and the key line is:

bpy.ops.wm.exportfbx('EXEC_DEFAULT', targetGameAssetPath=argv[0])

where:

• wm.exportfbx is the name of our Blender operator.
• targetGameAssetPath is the asset path passed in as a parameter.

So, wm.exportfbx needs some explanation, and for that, I have to switch to “Blender talk”.

The Blender Operator

Blender’s plugin system is basically in the form of Python scripts that get stored in an addons directory. This is usually stored in Blender’s appdata folder (on Win7, it’s in Users/<user>/AppData/Roaming/Blender Foundation/Blender/<ver>/scripts/addons/) or in a script folder that you can specify in Blender.

A very basic operator script that does nothing looks like:

import bpy
class MyExportFBXOperator(bpy.types.Operator):
    bl_idname = 'wm.exportfbx'
    bl_label = 'My Export FBX'

    targetGameAssetPath = bpy.props.StringProperty()

    def execute(self, context):
        # Do something here
        return {'FINISHED'}


def register():
    bpy.utils.register_class(MyExportFBXOperator)

def unregister():
    bpy.utils.unregister_class(MyExportFBXOperator)

if __name__ == "__main__":
    register()

It’s some boilerplate code for registering the operator with Blender. But here are the things to note:

• bl_idname = 'wm.exportfbx' This is the name of the command that is used by the call in myBuildScript.py above, so this must match.
• targetGameAssetPath is a string property that gets initialized from the passed parameter in myBuildScript.py.
• The execute() function is where the work is actually done.

So, at this point, we have access to the Blender file proper. We can access the scenes, objects, bones, textures, etc. I’m not going into the implementation of the execute() function, but ultimately, what you want to call is something like the following:

bpy.ops.export_scene.fbx(filepath=outFile, axis_forward='-Z', axis_up='Y', object_types={'ARMATURE','MESH'}, use_armature_deform_only=True)

There are many options to bpy.ops.export_scene.fbx, so it will depend on what you need for your project. outFile is simply the remapped filePath to the target Unity Asset directory. I like to export only the ‘MESH’ and ‘ARMATURE’ types, because that’s all you really need for character animations.

Well, this satisfies requirement #1!

Exporting Textures

But I do need to mention something else, which is a bonus of sorts. bpy.ops.export_scene.fbx will only export the model, armature, and animations, but you’ll most likely want to also export the textures associated with the file.

I found a great post on the Blender Stack Exchange that describes how you can get the list of linked textures. If that link ever goes down, here is the key piece of code that I used:

ob = bpy.context.object
if ob:
 for mat_slot in ob.material_slots:
     for mtex_slot in mat_slot.material.texture_slots:
         if mtex_slot:
                 if hasattr(mtex_slot.texture , 'image'):
                 print("\t\t%s" % mtex_slot.texture.image.filepath)

With that, you can simply copy the textures from your source art directory to the target Unity Asset directory as necessary.

Blender Shortcut

For requirement #3, the MyExportFBXOperator script above is almost set up for usage in the Blender UI. The only thing missing is the following header:

bl_info = {
    "name": "My Export FBX",
    "category": "Import-Export"
}

The “name” field will appear in the Blender UI, and it will be in the “Import-Export” category. In Blender, you can open up User Preferences > Add-ons > Categories:User, and you’ll see your operator script listed. Just check the box to enable it. Once it’s enabled, you can go to User Preferences > Input, and add wm.exportfbx to any shortcut that you want! The details on this are beyond the scope of this post, but there are plenty of articles and youtube videos describing how to do this.

Full AutoBuild

Lastly, requirement #4 is just another script that walks your models directory for each .blend file that you want to export, and calls exportfbx.bat. Truthfully, I haven’t implemented this part yet, but if anyone complains =), I may just write up another post on it.

EDIT: [2016.06.30] I’ve had a request for the script file that processes all models in a directory tree, and since I actually have it done, here it is!

#  build_all.py

# Copyright (c) 2016 Under the Weather, LLC
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of this software
# and associated documentation files (the "Software"), to deal in the Software without restriction,
# including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
# and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all copies
# or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
# PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
# FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

import sys
import os
import subprocess
    
def main():
    argv = sys.argv
    argv = argv[argv.index('--') + 1:] # get all args after '--'
    if (len(argv) < 2):
        print('ERROR: Source and Target game asset path not specified.')
        return

    sourceGamePath = argv[0]
    targetGamePath = argv[1]

    optionStr = ''
    options = argv[2:]
    for option in options:
        optionStr += option + ' '

    print('============================================================')
    print('BUILD ALL')
    print('SOURCE: ' + sourceGamePath)
    print('TARGET: ' + targetGamePath)
    print('OPTIONS: ' + optionStr)
    print('============================================================')    

    no_build_token = '_'    # If the .blend filename has this token (or even string), they will be excluded from the build

    for root, dirs, files in os.walk(sourceGamePath):
        for name in files:
            ext = os.path.splitext(name)
            if ext[1].lower() == '.blend':
                path = os.path.split(name)
                fname = path[1]
                if fname.find(no_build_token) == -1:
                    absPath = os.path.join(root, name)
                    print('Processing Blender file: ' + absPath)

                    command = 'exportfbx.bat ' + absPath + ' ' + targetGamePath + ' ' + optionStr
                    print('command: ' + command)
                    
                    subprocess.call(command, shell=True)

if __name__ == "__main__":
    main()

And now for a bit of explanation. The script accepts no less than 2 arguments; the source and the target paths. The script also supports a string of additional options/parameters, if necessary for whatever reason you may have. You'll also notice the no_build_token, which is essentially a character or string used to identify any blender files that are not intended to be exported. And that's it!

Conclusion

I seriously didn't think I was going to type that much. It was pretty frustrating for me to find a lot of fragmented information on the Blender and Unity pipeline, so I decided to put as much as I know all together here. There are definitely aspects of this system that need attention, such as custom material exports from Blender, and multiple armature and animation exports, but I think a lot of what I covered in this post can get some people started with more efficient game development.

Make it fun!

Info:

• Unity 5.0.1f1
• Blender 2.74
• Python 2.6.4