Difference between revisions of "Blender Source Tools Help"

From Valve Developer Community
Jump to: navigation, search
(doesn't seem like a good choice of package to me, but hey...)
 
(Armature properties)
 
(28 intermediate revisions by 3 users not shown)
Line 1: Line 1:
This tutorial will show you how to export a simple model from [[Blender]] for compiling with [[studiomdl]].
+
{{toc-right}}
  
'''To learn about the general usage of Blender, see [[Is Blender 3D Good for Source/How to Start]].'''
+
{{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]].
  
{{todo|Is it not possible to export collision meshes? That's crap!}}
+
== Importing ==
  
== The export process ==
+
The "'''Import SMD/VTA, DMX, QC'''" operator is used to import models. You can find it:
  
[[Image:Model_blender_export.png|right|150px|Menu location of Blender's SMD export command.]]
+
* By searching the {{key|Space}} menu (try "SMD")
 +
* Under File > Import
  
#Create your model and texture it via UV mapping. The result should be a .blend file and all the [[TGA]] files you used as textures. The example used here is the PC Gamer UK mag secreted all around de_dust_pcg (blender file for the model <code>pcgmag.blend</code> and texture file <code>pcgmag.tga</code>)
+
You can import a whole QC at once to save time.
#Having installed the [[Blender#Plugins | SMD exporter plugin]], export your model to a Half-Life 2 [[SMD]] file, in this case <code>pcgmag.smd</code>.
 
#Copy the SMD file into <code><game>/modelsrc</code> and the TGA file(s) into <code><game>/materialsrc/models</code>
 
#The SMD you have already is '''just the reference model'''. We will also need an additional SMD to declare the 'idle' animation. So, in a text-editor, create a file called <code>pcgmag_idle.smd</code> (or some other name ending in SMD) and enter this as its contents:
 
  
version 1
+
=== Options ===
nodes
 
0 "joint0" -1
 
end
 
skeleton
 
time 0
 
0 0.000000 0.000000 0.000000 0 0.000000 0.000000
 
end
 
  
You are now ready to [[Compiling Models|compile the model]].
+
''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 {{IconLabel|File:BlenderObEmpty.png|Empty}} is created instead.
 +
; Rotation mode
 +
: How keyframes are created. Euler is human-readable, Quaternion avoids [[W:Gimbal lock#Gimbal lock in applied mathematics|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 {{key|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 {{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.
 +
 
 +
=== Source Engine Export ===
 +
 
 +
This panel contains scene options, export buttons, and utilities.
 +
 
 +
[[File:Blender smd export.png|right|link=]]
 +
 
 +
; Export
 +
: Pops up a menu presenting export options based on the {{IconLabel|File:BlenderObject.png|Objects}} you currently have selected. {{note|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|Use the [[#Source Engine Exportables|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 {{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.
 +
; Export Path
 +
: 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.}}
 +
; 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 <code>\bin</code> folder of 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.
 +
; 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 http://steamcommunity.com/groups/BlenderSourceTools].
 +
; 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.
 +
 
 +
=== Source Engine Exportables ===
 +
 
 +
[[File:Blender smd objects.png|right|link=]]
 +
 
 +
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:
 +
 
 +
; {{IconLabel|File:BlenderGroup.png|Groups}}
 +
: Objects which have been grouped together in Blender are merged and exported to the same file.
 +
; {{IconLabel|File:BlenderObject.png|Objects}}
 +
: Objects not in a valid Group are listed here. They will be exported individually.
 +
; {{IconLabel|File:BlenderAction.png|Actions}}
 +
: Actions are the source of [[skeletal animation]]s. Only Actions from {{IconLabel|File:BlenderObArmature.png|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 ====
 +
 
 +
[[File:Blender smd props group.png|right|link=]]
 +
 
 +
This panel lists all of the Group's exportable members. You can disable each one individually.
 +
 
 +
{{note|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.
 +
<div style="clear:right"></div>
 +
 
 +
==== Flex properties ====
 +
 
 +
[[File:Blender smd dmx flex.png|right|link=]]
 +
 
 +
If you are exporting [[DMX model|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 {{IconLabel|File:BlenderText.png|Text}}. {{tip|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|To enable [[wrinkle maps|wrinkle map]] generation, set a non-zero <code>wrinkleScales</code> 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 {{IconLabel|File:BlenderText.png|Text}}.
 +
; Flex Controller Help
 +
: Opens this web page.
 +
; Generate Corrective Shape Key Drivers
 +
: Creates [http://wiki.blender.org/index.php/Doc:2.6/Manual/Animation/Editors/Graph/Drivers animation drivers] for all [[Flex animation#Corrective shapes|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|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 {{IconLabel|File:BlenderMesh.png|Mesh}} you can chose a {{IconLabel|File:BlenderVertexGroup.png|Vertex Group}}.
 +
: This property can appear multiple times if a {{IconLabel|File:BlenderGroup.png|Group}} is being exported.
 +
 
 +
==== 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 ===
 +
 
 +
[[File:Blender smd qc compile.png|right|link=]]
 +
 
 +
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 <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.
 +
; [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 {{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!
 +
: Only armature bone animation created in {{IconLabel|File:BlenderPoseMode.png|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 {{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"!
 +
: 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 <code>.</code> (which means "current directory") to prevent <code>anims</code> from being inserted.
 +
 
 +
== I found a bug ==
 +
 
 +
[http://steamcommunity.com/groups/blendersourcetools/discussions/0/ Please report it.]
 +
 
 +
[[Category:Blender]]
 +
[[Category:Modeling]]

Latest revision as of 15:58, 17 April 2016

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