Animated props with Blender

xzzy

aa
Jan 30, 2010
815
531
I spent a good chunk of my tf2 mapping time in the last two months trying to get an animated prop into TF2 using only free software. The Blender SMD exporter you can find in the Valve developer wiki comes close to allowing this, but it's currently geared more towards animating character models.

So I was forced to write my own exporter. Not entirely, I copied and pasted most of the code from the existing SMD exporter, but it still needed a bunch of massaging. I've submitted the changes to the guy who maintains the exporter, but am not sure if they will ever make it into the official version.

I sat down and started writing notes on how to prepare props for export (so I don't forget how to do it in the future), and once I was halfway done decided it would probably be more useful to make a tutorial and post it for other people to use. So here we are now.

Nerd details: the existing exporter requires the use of armatures and bones to create an animation. This is not really useful to a mapper. As an example, making a finale explosion on a map may involve hundreds of little pieces of debris. With the existing exporter, you are obligated to set up a bone (and animate that bone) for every single piece of debris. This is pretty ridiculous, so I redid the exporter pieces to export the rotation and location of an object as if it were a bone. This means a mapper can keyframe a piece of debris however he wants (even using the bullet physics engine) and with a button press, generate an SMD that can be imported into Hammer.

Prerequisites

I'm going to assume you know how to use Blender to create a model. If you don't, there are books and faqs and video tutorials all over the internet on how to model. Specifically, look up tutorials on making "keyframe animations". I will be covering some details of the process here, but not every single keypress. If you get lost, google is your friend.

You also need to be able to create UV maps, group objects together, edit materials, and if you want physics based animations, you'll need some skills with using the Blender game engine and bullet physics.

On the Source SDK side, you'll need to be able to create QC files and use studiomdl.exe to compile the SMD export into a MDL file you can use in Hammer.

You also need some software:

  1. Blender 2.6 - http://blender.org
  2. My exporter script (plus demo .blend) - http://xzzy.org/files/blender/smd_exporter.zip

And that's it!

Things to keep in mind

In the course of getting this to work, I came across a few quirks that I had to deal with. This is a listing of them:

  1. SMD models can only have 32 materials. 32 materials is a lot and most props will only have 1 texture. You'd think this means you will never get a SMD compile error, but you can. If you've been importing models exported from TF2, there may be some "wacky" UV maps with texture coordinates spread over a huge area. When this happens, you can get the 32 materials error. The only resolution is to review the UV maps of all your meshes and make sure there isn't a face off over the horizon somewhere.
  2. If you get purple checker boards when viewing your model in the Source SDK, it's probably a problem with the $cdmaterials variable in your QC file (I screw this up all the time, no matter how many times I make a prop).
  3. Certain material types (like blend textures) will not work on props. You'll get purple checkerboards.
  4. This exporter does NOT currently do vphysics models. This is a work in progress.

Set Up

There are a handful of manual tasks you have to do to get the prop ready for export.

  1. You have to paste the exporter script into Blender. Bring up Blender's text editor by clicking the menu in the lower left of one of Blender's panes. About midway through the list will be 'Text Editor'. Select that, and in the window that draws, press the 'New' button. Open up the smd_exporter.py you downloaded, copy all the text, and paste it into Blender's text window. On line 62 is a directory you have to edit.. pick wherever you want the SMD files to end up and type that path name there.
  2. Modeling with quads is fine. The export script will subdivide into triangles for you. Smoothing and modifiers probably won't work (I could not figure them out).
  3. You have to assemble your prop into a group to indicate to the exporter which pieces to put into the SMD. This may not make much sense when you're making a simple prop, but complicated animations may have several pieces, and Blender's Groups allow you to divide your objects into separate props. The group name will be used to name the SMD file on export.
  4. Objects are required to have UV maps specified. The exporter will crash if it encounters a face that does not have a UV map. Assigning a material with a projected UV map isn't good enough, you actually have to use the UV Image editor and unwrap all your meshes.
  5. The blender material name is the name of the texture that Hammer and TF2 uses. So if you choose the material Metal/wall028.vtf for your prop, you should set the Blender material name to "wall028".
  6. Animate. If the object does not have an action applied, the exporter will not create an animation SMD. You create an action by using keyframe animation to move your objects around. If an animation is exported, it will be saved as Group_anim (with Group changed to whatever the name of the object's group is).
  7. Write the QC file and store it wherever your SMD files were exported to. A sample QC file:

    Code:
    $modelname props_test/mymodel.mdl
    $cdmaterials "models/props_test/"
    $scale 100
    $surfaceprop metal
    $body mybody "Group.smd"
    
    $sequence idle "Group"
    $sequence anim "Group_anim"

Exporting

Once all that is done, select one of your objects, bring up the Blender Text Editor, and hit the 'Run Script' button. After a moment of churning, the model SMD and animation SMD should appear on your hard drive.

Drag and drop your QC file onto studiomdl.exe, and you should now have a usable model in your tf/models directory. Bring up the Source SDK model viewer and load it up to check for issues.

Export Demo

In the zip file you downloaded, there is a "smdphysicstest.blend" file. You can open this in Blender to get a feel for how your animations should be set up. The scene is ready for export.. you can load it up and press the "Run Script" button to generate the Prop.smd and Prop_anim.smd in the same directory that the blend file exists. You can then use the Prop.qc file to compile the model so it can be viewed in the SDK Model Viewer.
 

omegasupreme

L1: Registered
Nov 10, 2011
19
4
Which version of blender 2.6 are you using? I have tried this with 2.60 to 2.64 and it does not work. Either I get an error at the beginning of the script about importing stuff, or the script goes through but nothing exports. I have edited the file path to the correct directory. The blend file you included also will not work
 

xzzy

aa
Jan 30, 2010
815
531
I used both 2.63 and 2.64.

I just download the zip I gave in the OP and ran the export and it worked for me with 2.64, so the script should be okay.

Without more detail it's hard for me to offer suggestions on what's wrong, but if the script is crashing importing python modules my suspicion is the problem is coming from python.. either you're trying to use the OS installed python and it can't find the Blender libraries or python isn't installed.
 

xzzy

aa
Jan 30, 2010
815
531
I use the zip release.. had no idea there was a functional difference from the installer version.
 

omegasupreme

L1: Registered
Nov 10, 2011
19
4
It works now! :D For some reason it refused to export to my C drive but it would export to E. I can't compile at the moment but thanks for the awesome article and script.
 

xzzy

aa
Jan 30, 2010
815
531
It works now! :D For some reason it refused to export to my C drive but it would export to E. I can't compile at the moment but thanks for the awesome article and script.

Cool.. glad it's not useful to only me.

I actually have slightly updated version of the script and one that also does vphysics but I haven't quite gotten around to uploading them. I should do that someday!


As for choice of software, I like Blender because it's open source. I prefer to use free software whenever possible. It also helps that I've been using it for many years now and am pretty comfortable working with it.
 
Jul 26, 2015
693
817
This isn't working for me. I'm trying to create a simple spinning box, and I'm following every step as explained, and it just doesn't work. It creates the smds fine, I can compile the model with Crowbar, and when I open it up in hlmv it has the animation selectable, but it doesn't animate. What am I doing wrong?