Blender Source Tools Help: Difference between revisions

From Valve Developer Community
Jump to navigation Jump to search
No edit summary
No edit summary
Line 1: Line 1:
:''This article documents the new UI released in Blender SMD Tools 1.5. If you are using an older version, [{{fullurl:Blender SMD Tools Help|oldid=170906}} click here].''
{{toc-right}}
{{toc-right}}


Line 23: Line 25:
: 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.''
: 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]]
; Make camera at [[$origin]]
: Helpful when importing [[viewmodel]]s. If this is not set, an {{IconLabel|File:BlenderObEmpty.png|Empty}} is created instead.
: Helpful when importing [[viewmodel]] QCs. If this is not set, an {{IconLabel|File:BlenderObEmpty.png|Empty}} is created instead.
; Rotation mode
; Rotation mode
: How keyframes are created. Euler is human-readable, Quaternion avoids [[W:Gimbal lock#Gimbal lock in applied mathematics|Gimbal lock]].
: How keyframes are created. Euler is human-readable, Quaternion avoids [[W:Gimbal lock#Gimbal lock in applied mathematics|gimbal lock]].


== Exporting ==
== Exporting ==
Line 37: Line 39:
The SMD 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 SMD 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 export panel ===
The SMD Tools' three export panels can be found under {{IconLabel|File:BlenderProperties.png|plus=File:BlenderScene.png|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.
 
[[File:Blender smd export prefs.png|right]]


The '''export configuration panel''' can be found under {{IconLabel|File:BlenderProperties.png|plus=File:BlenderScene.png|Scene Properties}}. Due to the way Blender's addon system works it will start off at the bottom of the area, but you can drag it higher with the grip in the top right.
=== Source Engine Export ===


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


''This area applies to all exports.''
[[File:Blender smd export.png|right|link=]]


; pyroMeshShape.smd (Export Current)
; Export Current (displays output filename)
: Exports the active object to <code><Output Folder>/<Object Subfolder>/<Object Name></code>. You will be prompted for an Output Folder if there isn't already one. This button's name and icon changes to reflect the current object.
: Exports the active object to <code><Output Folder>/<Object Subfolder>/<Object Name></code>. You will be prompted for an Output Folder if there isn't already one. This button's name and icon changes to reflect the current object.
; Scene as configured
; Scene as configured
: Exports everything selected for export in the big list further down the panel.
: Exports everything selected for export in the Source Engine Exports list.
; Output Folder
; Output Folder
: The root folder into which objects will be exported. {{tip|If you start the path with <code>//</code>, it will be relative to the location of the .blend file.}}
: The root folder into which objects will be exported. {{tip|If you start the path with <code>//</code>, it will be relative to the location of the .blend file.}}
; Target Engine
; Target Engine
: The [[:Category:Engine branches|engine branch]] for which you are making a model. This will be used to select the correct version of [[studiomdl]] when compiling QCs.
: The [[:Category:Engine branches|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.
; Output Format
: Whether to output [[Studiomdl Data]] or [[DMX model]] files. DMX isn't available for older engine versions.
; Target Up Axis
; Target 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).
: 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).
; Material Path (DMX only)
: The equivalent of the QC command [[$cdmaterials]].
; Visible layer(s) only
: Restrict scene exports and the UI to objects in the scene's active layers.
; Ignore Blender materials
: The SMD Tools will usually export the name of the {{IconLabel|File:BlenderMaterial.png|Material}} assigned to each face, or a face-assigned {{IconLabel|File:BlenderTexture.png|Texture}} if none is found. Checking this box makes the Tools skip straight to the texture name at all times.
; Help
: Opens this web page.
; Check for updates
: Connects to the Tools' [http://code.google.com/p/blender-smd/ Google Code website] and downloads any updates, as long as they are compatible with your version of Blender.


==== Scene Exports ====
=== Source Engine Objects ===


''This is where batch exports are configured.''
[[File:Blender smd objects.png|right|link=]]


* ''All items in the list can be excluded from batch exports by clicking their names.''
This panel contains settings for each of the exportable items in the scene. The checkboxes determine what is exported in Scene mode. There are three types of item:
* ''Export subfolders can be entered in the right-hand column.''


; {{IconLabel|File:BlenderGroup.png|Groups}}
; {{IconLabel|File:BlenderGroup.png|Groups}}
: Objects which have been grouped together in Blender are merged into the same SMD file. You can expand the list of objects in the Group for inspection, and exclude certain ones by clicking on them. {{tip|To have the SMD Tools ignore a Group entirely and return its contents to the Objects section, use the new options found on the Groups panel under {{IconLabel|File:BlenderProperties.png|plus=File:BlenderObject.png|Object Properties}}.}}
: Objects which have been grouped together in Blender are merged and exported to the same file.
; {{IconLabel|File:BlenderObject.png|Objects}}
; {{IconLabel|File:BlenderObject.png|Objects}}
: Objects not in a Group are listed here. They will all be exported to their own SMDs.
: Objects not in a valid Group are listed here. They will be exported individually.
; {{IconLabel|File:BlenderAction.png|Actions}}
; {{IconLabel|File:BlenderAction.png|Actions}}
: Actions are the source of [[skeletal animation]]s. This section lists all the {{IconLabel|File:BlenderObArmature.png|Armatures}} in the scene and exposes their Actions. You can either export the current Action, a filtered list of all Actions in the .blend, or the Actions used in the Armature's NLA tracks. (There is currently no good way of associating multiple Actions with any one Object.) {{note|Only armature bone animation created in {{IconLabel|File:BlenderPoseMode.png|Pose Mode}} can be exported. See [[Animation in Blender]].}}
: Actions are the source of [[skeletal animation]]s. Only Actions from {{IconLabel|File:BlenderObArmature.png|Armatures}} are listed.
; Ignore materials
 
: The SMD Tools will usually export the name of the {{IconLabel|File:BlenderMaterial.png|Material}} assigned to each face, or a face-assigned {{IconLabel|File:BlenderTexture.png|Texture}} if none is found. Checking this box makes the Tools ignore materials at all times.
The "Subfolder" option can be used to change the folder to which an item is written.
; Visible layer(s) only
 
: Restricts the Scene Exports list to objects in the 3D View's active layers.
There may also be some of the following sub-panels:
 
==== Group properties ====
 
[[File:Blender smd props group.png|right|link=]]
 
This panel lists all of the Group's exportable members. You can disable each one individually.
 
You can also "suppress" the Group. This returns its members to the list of exportable items.
<div style="clear:right"></div>
==== Flex properties ====
 
[[File:Blender smd dmx flex.png|right|link=]]
 
If you're exporting [[DMX model|DMX]], flex 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 SMD 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 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 {{IconLabel|File:BlenderText.png|Text}}. {{tip|See [[Flex animation#DMX format]] for details on writing your own flex controllers. Remember to make all your element IDs unique!}}
; Generate controllers
: Generates a [[KeyValues2]] DMX file containing a simple set of flex controllers for your model. The file is written to a {{IconLabel|File:BlenderText.png|Text}}.
; Flex Controller Help
: Opens this web page.
; Stereo sharpness
: Defines how sharp the transition from left to right is for flex controllers flagged as "stereo". This property can appear multiple times if a {{IconLabel|File:BlenderGroup.png|Group}} is being exported.
 
The number of [[wrinkle map]]s is also displayed. Wrinkle maps are {{IconLabel|File:BlenderVertexGroup.png|Vertex Groups}} with names matching {{IconLabel|File:BlenderShapeKey.png|Shape Keys}}.
 
==== Armature properties ====
 
[[File:Blender smd props armature.png|right|link=]]
 
There are no special Action properties; instead this panel displays the properties of the relevant Armature.
 
{{note|Only armature bone animation created in {{IconLabel|File:BlenderPoseMode.png|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 ====
 
[[File:Blender smd props curve.png|right|link=]]
 
Determines which side of an extruded Curve to generate polygons on.
<div style="clear:right"></div>
=== Source Engine QC Compiles ===


==== QC Compiles ====
[[File:Blender smd qc compile.png|right|link=]]


''The SMD Tools can automatically run [[studiomdl]] on demand or after an export. They will not actually generate a QC for you, however!''
The SMD Tools can automatically run [[studiomdl]] on demand or after an export. ''They will not actually generate a QC for you!''


; QC file path
; QC file path
: This is where the Tools should look for QCs to run. You can use the <code>//</code> syntax to make the path relative to the .blend file, and you can also use the <code>*</code> and <code>?</code> to perform a wildcard search for multiple files.
: This is where the Tools should look for QCs to run. You can use the <code>//</code> syntax to make the path relative to the .blend file, and you can also use <code>*</code> and <code>?</code> to perform a wildcard search for multiple files.
; pyro, pyro legacy (QC List)
; [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.
: 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
; Compile all on export
Line 88: Line 155:
; Compile all now
; Compile all now
: Does exactly what it says.
: Does exactly what it says.
==== Utility ====
''Operators that aren't directly related to exporting.''
; Clean all SMD data
: The SMD Tools will store data on each object for use when exporting. Some of these, like name overrides, don't have their own section in the UI. You can remove all of these properties at once with this button.
; Help
: Open this web page.
; Check for updates
: Connects to the Tool's [http://code.google.com/p/blender-smd/ Google Code website] and downloads any updates, as long as they are compatible with your version of Blender.


== Troubleshooting ==
== Troubleshooting ==
Line 105: Line 161:


; My animations are messed up!
; 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 {{IconLabel|File:BlenderProperties.png|plus=File:BlenderArmature.png|Armature Properties}} panel and enable "Legacy rotation".
: 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 {{IconLabel|File:BlenderProperties.png|plus=File:BlenderArmature.png|Armature Properties}} panel and enable "Legacy rotation" (only available when exporting SMD).
; My animation won't export!
; My animation won't export!
: Only armature bone animation created in {{IconLabel|File:BlenderPoseMode.png|Pose Mode}} can be exported. See [[Animation in Blender]].
: Only armature bone animation created in {{IconLabel|File:BlenderPoseMode.png|Pose Mode}} can be exported. See [[Animation in Blender]].
Line 112: Line 168:


; My mesh is in the wrong place!
; My mesh is in the wrong place!
: The SMD 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. collisions, gibs) then make sure that they are all parented. Create an {{IconLabel|File:BlenderObEmpty.png|Empty}} if need be; the parent itself doesn't have to be exported.
: The SMD 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 {{IconLabel|File:BlenderObEmpty.png|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"!
; 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]].
: 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]].
Line 118: Line 174:
=== Export filename ===
=== Export filename ===


; My object/bone is exporting with the wrong filename!
; My stuff is exporting with the wrong name!
; The filename I want is too long for Blender!
: Names of Blender objects/data used have an annoying 29-character limitation, which the SMD 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.
: Names of Blender datablocks have an annoying 32-character limitation. You can get around this by going to {{IconLabel|File:BlenderProperties.png|plus=File:BlenderObject.png|Object Properties}} or {{IconLabel|File:BlenderProperties.png|plus=File:BlenderBone.png|Bone Properties}} and adding a Custom Property called <code>smd_name</code>, which the tools will then use instead of the actual datablock name.
: Likewise, removing that property will cause the Tools to start using the actual datablock name again. <code>smd_name</code> will often be set by the Tools during import.
; I don't want my animations in a subfolder!
; I don't want my animations in a subfolder!
: You can use a subfolder of <code>.</code> (which means "current directory") to prevent <code>anims</code> from being inserted.
: You can use a subfolder of <code>.</code> (which means "current directory") to prevent <code>anims</code> from being inserted.
Line 134: Line 188:
== I found a bug ==
== I found a bug ==


Super! [http://code.google.com/p/blender-smd/issues/list Please report it on Google Code.]
[http://code.google.com/p/blender-smd/issues/list Please report it on Google Code.]


[[Category:Blender]]
[[Category:Blender]]
[[Category:Modeling]]
[[Category:Modeling]]

Revision as of 12:46, 3 September 2012

This article documents the new UI released in Blender SMD Tools 1.5. If you are using an older version, click here.

Blender Models are imported and exported from Blender with the Blender SMD 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 SMD 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 SMD 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 Current (displays output filename)
Exports the active object to <Output Folder>/<Object Subfolder>/<Object Name>. You will be prompted for an Output Folder if there isn't already one. This button's name and icon changes to reflect the current object.
Scene as configured
Exports everything selected for export in the Source Engine Exports list.
Output Folder
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.
Target Engine
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.
Output Format
Whether to output Studiomdl Data or DMX model files. DMX isn't available for older engine versions.
Target 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).
Material Path (DMX only)
The equivalent of the QC command $cdmaterials.
Visible layer(s) only
Restrict scene exports and the UI to objects in the scene's active layers.
Ignore Blender materials
The SMD 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.
Help
Opens this web page.
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 Objects

Blender smd objects.png

This panel contains settings for each of the exportable items in the scene. The checkboxes determine what is exported in Scene mode. There are three types of 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.

You can also "suppress" the Group. This returns its members to the list of exportable items.

Flex properties

Blender smd dmx flex.png

If you're exporting DMX, flex 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 SMD 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 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. Remember to make all your element IDs unique!
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.
Stereo sharpness
Defines how sharp the transition from left to right is for flex controllers flagged as "stereo". This property can appear multiple times if a (Icon) Group is being exported.

The number of wrinkle maps is also displayed. Wrinkle maps are (Icon) Vertex Groups with names matching (Icon) Shape Keys.

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 SMD 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.

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 SMD 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 SMD 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.

DMX

I get a runtime error when I export DMX!
Ignore it.
How can I import DMX models?
Download DMX-Model and put it in your root Blender folder, alongside blender.exe.

I found a bug

Please report it on Google Code.

Retrieved from "https://developer.valvesoftware.com/w/index.php?title=Blender_Source_Tools_Help&oldid=171545"