Blender Source Tools Help

From Valve Developer Community
Jump to: navigation, search
Warning.pngWarning:This page was written for an outdated version of Blender and Blender export plug-in, as well as duplicates advice found in more general articles.
While it is still of some use, visit Blender, Blender Modeling Walkthrough (3.6.1) or Category:Modeling for more up-to-date documentation.
Icon-broom.png
This article or section needs to be cleaned up to conform to a higher standard of quality because:
This article needs to be rewritten for the newer version of Blender and the add-on export.
For help, see the VDC Editing Help and Wikipedia cleanup process. Also, remember to check for any notes left by the tagger at this article's talk page.

Blender Models are imported and exported from Blender with the Blender Source Tools. Any type of object with 2D surfaces can be exported. For details on creating animations for export, see Animation in Blender.

Importing

The "Import SMD/VTA, DMX, QC" operator is used to import models. You can find it:

  • By searching the Space menu (try "SMD")
  • Under File > Import

You can import a whole QC at once to save time.

Options

These can be set in the lower-left area when selecting a file.

Extend any existing model
Adds meshes and animations to the armature of the active object, or of the first object found in the scene if none are active. Otherwise a brand new armature is created. Ignored during QC import.
Import animations
SMD animations are very large. They take a lot of time to import and take up a lot of disc space. You can skip them when importing a QC by unchecking this box. Ignored during SMD import.
Up axis
Rotates everything so that it points upward in Blender if it didn't originally, and configures the Target Up Axis property of the current scene. Automatically set during QC import.
Make camera at $origin
Helpful when importing viewmodel QCs. If this is not set, an (Icon) Empty is created instead.
Rotation mode
How keyframes are created. Euler is human-readable, Quaternion avoids gimbal lock.

Exporting

The "Export SMD/VTA/DMX" operator is used to export models, animation and shape keys. You can find it:

  • By searching the Space menu (try "SMD")
  • Under File > Export
  • On the export configuration panel seen below

The Source Tools are designed to make repeat exports as painless as possible. To that end, once you have set up an Export Folder (see below) objects/groups are exported there using their Blender names.

The Source Tools' three export panels can be found under (Icon)+(Icon) Scene Properties. Due to the way Blender's addon system works they will start off at the bottom of the area, but you can drag them higher with the grips in the top right corners.

Source Engine Export

This panel contains scene options, export buttons, and utilities.

Blender smd export.png
Export
Pops up a menu presenting export options based on the (Icon) Objects you currently have selected.
Note.pngNote:You won't be prompted for a filename. Exports are made to the folder given in Export Path, using the exportable item's Blender name as a filename.
Tip.pngTip:Use the Source Engine Exportables panel to configure the Scene Export option.
Visible layer(s) only
Restrict scene exports and the UI to objects in the scene's active layers.
Ignore Blender materials
The Source Tools will usually export the name of the (Icon) Material assigned to each face, or a face-assigned (Icon) Texture if none is found. Checking this box makes the Tools skip straight to the texture name at all times.
Export Path
The root folder into which objects will be exported.
Tip.pngTip:If you start the path with // it will be relative to the location of the .blend file.
Export Format
Whether to output Studiomdl Data or DMX model files. DMX has more features than SMD but older engine branches and tools don't support it.
Export Up Axis
Use for compatibility with existing models. You will want to set this if the QC you are compiling with uses $upaxis (e.g. the TF2 player models are all Y-up).
SDK Path
The path to the \bin folder of the engine branch for which you are making a model. This determines DMX version and is used to select the correct version of studiomdl when compiling QCs.
DMX Version
Don't panic! These options are only displayed if SDK Path is blank or the SDK version it points to isn't recognised by the tools. They allow you to manually specify versions of DMX binary encoding and DMX model format to export.
Material Path
DMX only; the equivalent of the QC command $cdmaterials.
Help
Opens this web page.
Steam Community
Opens http://steamcommunity.com/groups/BlenderSourceTools.
Check for updates
Connects to the Tools' Google Code website and downloads any updates, as long as they are compatible with your version of Blender.

Source Engine Exportables

Blender smd objects.png

This panel contains settings for each of the exportable items in the scene. The checkboxes determine what is exported when you select the Export Scene export mode (filtering the list UI does not do this). There are three types of exportable item:

(Icon) Groups
Objects which have been grouped together in Blender are merged and exported to the same file.
(Icon) Objects
Objects not in a valid Group are listed here. They will be exported individually.
(Icon) Actions
Actions are the source of skeletal animations. Only Actions from (Icon) Armatures are listed.

The "Subfolder" option can be used to change the folder to which an item is written.

There may also be some of the following sub-panels:

Group properties

Blender smd props group.png

This panel lists all of the Group's exportable members. You can disable each one individually.

Note.pngNote:Filtering the list UI doesn't affect which items are exported.

There are two advanced options:

Suppress
Makes the Source Tools ignore the Group, returning its members to the list of exportable items (unless they are in other unsuppressed Groups).
Merge mechanical parts
This option only appears when exporting DMX. When enabled, the exporter will run the Join operator on objects which share the same bone parent, reducing the number of individual items written to the output file. This is useful when you are exporting complicated mechanical objects consisting of many bone-parented objects.

Flex properties

Blender smd dmx flex.png

If you are exporting DMX, flex animation controllers are defined in the model file (if you're exporting SMD they are defined in the QC and this panel won't appear).

The Source Tools don't provide any UI for defining flex controllers. Instead there are two options:

Simple
Generate simple flex controllers every time you export
Advanced
Insert the flex controllers of another DMX file
Advanced mode

Advanced mode has the following settings:

Controller source
An existing DMX, the flex controllers of which will inserted into your DMX. This can be an on-disc file or a (Icon) Text.
Tip.pngTip:See Flex animation#DMX format for details on writing your own flex controllers. Use the Text Editor's Edit > Insert UUID operator to generate unique IDs.
Tip.pngTip:To enable wrinkle map generation, set a non-zero wrinkleScales value in the relevant flex controller definition.
Generate controllers
Generates a KeyValues2 DMX file containing a simple set of flex controllers for your model. The file is written to a (Icon) Text.
Flex Controller Help
Opens this web page.
Generate Corrective Shape Key Drivers
Creates animation drivers for all corrective shapes on the active object. This means that you can play around with shapes without having to worry about manually activating the relevant corrective shapes.
Note.pngNote:The algorithm for applying corrective shapes is not guaranteed to match Source's, so always check your work in HLMV!
Stereo sharpness
Defines the transition from left to right for flex controllers flagged as "stereo". You can have the tools generate a transition across an axis (X by default), or if the item is a (Icon) Mesh you can chose a (Icon) Vertex Group.
This property can appear multiple times if a (Icon) Group is being exported.

Armature properties

Blender smd props armature.png

There are no special Action properties; instead, this panel displays the properties of the relevant Armature.

Note.pngNote:Only armature bone animation created in (Icon) Pose Mode can be exported. See Animation in Blender.
Action selection
You can choose how to select Actions for export: either the active Action or NLA track, or a filtered list of all Actions in the .blend. This is fiddly, but unfortunately Blender does not currently provide a good way of associating multiple Actions with any one Object.
Implicit motionless bone
Creates a dummy bone for vertices which don't move. Otherwise Studiomdl will attach them to the root bone.
Enabling this option emulates Blender's behaviour with regard to unweighted verts, but may break compatibility with existing exports.
Action selector
Changes the Armature's current Action. This is a built-in Blender setting that has been placed here simply for convenience.

Curve properties

Blender smd props curve.png

Determines which side of an extruded Curve to generate polygons on.

Source Engine QC Compiles

Blender smd qc compile.png

The Source Tools can automatically run studiomdl on demand or after an export. They will not actually generate a QC for you!

QC file path
This is where the Tools should look for QCs to run. You can use the // syntax to make the path relative to the .blend file, and you can also use * and ? to perform a wildcard search for multiple files.
[QC List]
This is where any QCs found at the QC path are displayed. You can compile one at any time by clicking its button.
Compile all on export
Automatically compiles all QCs when anything is exported.
Compile all now
Does exactly what it says.
Launch HLMV
Launches HLMV from your SDK folder. If Game Path has been defined, it will override the system VPROJECT value.

Troubleshooting

Animation

My animations are messed up!
Version 1.1 of the Tools changed the way bones are exported. You can fix the problem by re-exporting everything, but if that isn't an option see the (Icon)+(Icon) Armature Properties panel and enable "Legacy rotation" (only available when exporting SMD).
My animation won't export!
Only armature bone animation created in (Icon) Pose Mode can be exported. See Animation in Blender.

Meshes

My mesh is in the wrong place!
The Source Tools export each object relative to its own origin, not the scene's, unless it is parented to another object. If you need to align meshes with each other (e.g. Groups, collisions, gibs) then make sure that they are all parented. Create an (Icon) Empty if need be; the parent itself doesn't have to be part of the export.
Studiomdl always says my collision mesh has "2-dimensional geometry"!
The edges of collision geometry must be smooth. Use the "Shade Smooth" operator on your object. Also, there cannot be any holes in the mesh. See Collision mesh#Caveats.

Export filename

My stuff is exporting with the wrong name!
Names of Blender objects/data used have an annoying 29-character limitation, which the Source Tools overcame by using a Custom Property called "smd_name". Remove the property (via the "Custom Properties" panel) and the Blender name will be used again.
I don't want my animations in a subfolder!
You can use a subfolder of . (which means "current directory") to prevent anims from being inserted.

I found a bug

Please report it.