StudioMDL (Source): Difference between revisions

Latest revision as of 07:12, 20 May 2025

For a guide to studiomdl's usage, see Compiling a model.

StudioMDL is the command-line tool used to compile models from intermediate formats exported from modeling packages to the binary .mdl format that is read by the Source engine.

It can be found at common\<gamename>\<gamefolder>\bin\studiomdl.exe.

Tip:The name "studio" is a throwback to the development of

Half-Life, during which Valve used 3D Studio Max to create their models.

Bug:Attempting to use Studiomdl or a shortcut of it pinned to the taskbar in Windows 8 will result in an invalid target path, even when -game and an associated path are specified. Using a shortcut on the desktop, however, still works. This is an issue on Microsoft's end, unfortunately.

Bug:64-bit version of StudioMDL from the Team Fortress 2 branch is currently broken.

Code:Source code for an older version is available in the 2006 SDK.

Parameters

The only parameter required is a QC file. Any others must come before it.

studiomdl [options] <path\QC>

General

-game <gamedir>: Override the VProject game path.
-quiet: Suppresses some console output, such as spewing the searchpaths.
-x360: Enable Xbox 360 output, overriding the Gameinfo.txt.
-nox360: Disable Xbox 360 output, overriding the Gameinfo.txt. Implied by default in non--based branches of Source.
-nowarnings: Disable warnings.
-maxwarnings <int>: Print no more than the specified number of warnings.

Animation

-definebones: See $definebone.
-printbones: Writes extra bone info to the console.
-printgraph: Todo: Appears to dump xnode data for each node?
-overridedefinebones: Equivalent to specifying $unlockdefinebones in QC.
-checklengths: Prints engine-ready keyframe data for each animation.

Performance

-fastbuild

Skip processing .sw.vtx (DX6/DX7), .dx80.vtx, and .360.vtx variants (use .dx90.vtx only). This speeds up compiling.

Important:In games before

, if the .dx80.vtx is absent for a static prop, VRAD will fail to generate lighting for that prop!

-preview

Skip splitting quads into tris and building tristrips. This changes the rendering flags for the model, most likely resulting in slower performance or buggier rendering in-engine.

-fullcollide (only in )

Don't truncate really big collision meshes

Note:(in all games since

) use $maxconvexpieces, as -fullcollide does nothing.

-striplods

Ignore all $lod commands.

-minlod <lod>

Throw away data from LODs above the given one (see $minlod).

-mdlreport <path\model.mdl>

-perf <path\model.mdl>

Report performance info for an already-compiled model. A QC file is not needed when using this command.

-mdlreportspreadsheet

Report performance info, per-LOD, as a comma-delimited spreadsheet. It will appear in the form:

Path to VTX, VTX file extension, LOD number (1 is the root lod), tri count, number of batches rendered, number of materials used

Must be used with -mdlreport or -perf!

Note:It doesn't actually write a spreadsheet to disk; use > to

pipe output to a CSV file.

Debug

-d: Dumps various glview files (10 per LOD per VTX file),
-h: Dump hitboxes to console.
-n: Tag bad normals.
-dumpmaterials: Dump names of used materials to the console.
-i: Ignore warnings.
-t <material>: Replaces all materials with the specified material.
-parsecompletion: Prints an easily parseable message indicating whether the compile was successful or a failure.
-collapsereport: Prints info on which bones are being retained and which bones are being collapsed.

Other

-nop4: Disables Valve's Perforce integration. Unless you actually have Perforce set up for your game/mod (a highly unlikely scenario), you should use this.
-verify: Compile the model, but don't actually write the results to disk.
-a <normal_blend_angle>: Auto-smooth faces equal to or below specified angle in degrees. By default, Studiomdl blends normals that are 2 degrees or less apart. Will override normal data for all meshes.
-f (removed since ): Flip all triangles.; Bug:Does not work in Orange Box and later builds of Studiomdl. You can achieve the same behavior with $body, however.
-vsi <path\[QC|MDL]>: Generates a VSI file from a QC or MDL.
-stripmodel <path\model.mdl>: Strips down a model, removing its LOD info.
-stripvhv <path\sp_hdr_x.vhv>: Strips down hardware verts (VHV) of their LOD info.
-makefile: Generates a simple makefile for later compiling. It also parses the QC for any errors, and runs in -quiet mode.
-basedir <path>: Runs studiomdl in the context of the provided path.
-tempcontent <path>: Adds the provided path as a content search path.

Nonfunctional

-r: In , tagged reversed normals in compile output console; example: triangle reversed (0.748195 0.949818 0.839380)
-ihvtest: Probably meant to test the model collision for any physics errors. Skips whatever argument is provided after it.

Input Files

StudioMDL supports a range of input formats. These include SMD, DMX, OBJ, and VRM for reference meshes, SMD and DMX for skeletal animation, and VTA and DMX files for vertex and flex animation. Counter-Strike: Global Offensive also supports FBX, but with limited functionality. Flexes are not directly supported, nor are FBX sequences, however an SMD/DMX sequence can be used on an FBX model.

Note:While FBX does technically support flex animations, an SMD file is required to generate the VTA file, making the use of an FBX file for flexes redundant.

Format	File Extensions	Mesh	Skeletal animation	Vertex/flex animation
SMD	SMD SMA (in all games since ) PHYS (in all games since )	Yes	Yes	Yes
DMX	DMX (in all games since ) XML (in all games since ) MPP (in all games since )^[confirm]	Yes	Yes	Yes
OBJ	OBJ	Yes	No	No
FBX	FBX (in all games since )	Yes	(only in NekoMDL)	(only in NekoMDL)
VRM	VRM	Yes	Yes	No
VTA	VTA	No	No	Yes

Output files

mymodel.mdl: Skeleton, animations, bounding/hit boxes, surface materials, LOD indices, contents and MDL flags, etc.
mymodel.sw.vtx
mymodel.360.vtx
mymodel.dx80.vtx
mymodel.dx90.vtx: Vertex data optimized for DirectX 6/7, Xbox 360, DirectX 8, and DirectX 9 respectively.
Note:.360.vtx files are just byteswapped .dx90.vtx files.
mymodel.vvd: Remaining hardware-agnostic vertex data, including the UV map
mymodel.phy: Collision mesh data. Omitted if no $collisionmodel is defined.
mymodel.ani: Animations, if $animblocksize is used.

@@ Line 1: / Line 1: @@
-{{otherlang2|ru=Studiomdl:ru|es=Studiomdl:es}}
+{{LanguageBar}}
-{{bug| Attempting to use Studiomdl or a shortcut of it pinned to the taskbar in Windows 8 will result in an invalid target path even when -game and an associated path is specified. However using a shortcut on the desktop still works. This is an issue on microsoft's end unfortunately.}}
+{{src topicon}}
+{{tabs|StudioMDL|goldsrc=1|source=1}}
-:''For a guide to studiomdl's usage, see [[Compiling a model]].''
+{{for|a guide to studiomdl's usage|[[Compiling a model]]}}
 {{toc-right}}
+{{sm|4}} is the [[command-line]] tool used to compile [[model]]s from intermediate formats exported from modeling packages to the binary .mdl format that is read by the Source engine.
-'''Studiomdl''' is the [[command-line]] tool used to compile [[model]]s from the intermediate [[Studio Model Data]] format exported from modeling packages to the binary .mdl format that is read by the Source engine.
+It can be found at {{file|<nowiki>common\<gamename>\<gamefolder>\bin\studiomdl</nowiki>|exe}}.
-It can be found at <code>steam/steamapps/<account>/sourcesdk/bin/[orangebox|ep1]/bin/studiomdl.exe</code>.
-{{tip|The name "studio" is a throwback to the development of [[Half-Life 1]], during which Valve used [[3D Studio Max]] to create their models.}}
+{{tip|The name "studio" is a throwback to the development of {{hl|2}}, during which Valve used [[3D Studio Max]] to create their models.}}
+{{bug|hidetested=1|Attempting to use Studiomdl or a shortcut of it pinned to the taskbar in Windows 8 will result in an invalid target path, even when {{mono|-game}} and an associated path are specified. Using a shortcut on the desktop, however, still works. This is an issue on Microsoft's end, unfortunately.}}
+{{Bug|hidetested=1|64-bit version of StudioMDL from the {{tf2branch|1}} is currently broken.}}
+{{codenote|Source code for an older version is available in the [https://github.com/Source-SDK-Archives/source-sdk-2006-ep1/tree/master/utils/studiomdl 2006 SDK].}}
 == Parameters ==
+The only parameter required is a [[QC|QC file]]. Any others must come ''before'' it.
-The only parameter required is a [[Qc|QC file]]. Any others must come ''before'' it.
   studiomdl [options] <path\QC>
 === General ===
+;{{mono|-game <gamedir>}}
-; <code>-game <gamedir></code>
+:Override the VProject game path.
-: Override system-wide game path.
+;{{mono|-quiet}}
-;<code>-quiet</code>
+:Suppresses ''some'' console output, such as spewing the searchpaths.
-:Theoretically suppresses console output. In practice does nothing.
+;{{mono|-x360}}
-;<code>-x360</code>
+:Enable Xbox 360 output, overriding the {{ent|Gameinfo.txt}}.
-:Enable Xbox 360 output (OB).
+;{{mono|-nox360}}
-;<code>-nox360</code>
+:Disable Xbox 360 output, overriding the {{mono|Gameinfo.txt}}. Implied by default in non-{{l4d}}-based branches of Source.
-:Disable Xbox 360 output (Ep1).
+;{{mono|-nowarnings}}
-;<code>-nowarnings</code>
 :Disable warnings.
+;{{mono|-maxwarnings <[[int]]>}}
+:Print no more than the specified number of warnings.
 === Animation ===
+; {{mono|-definebones}}
-; <code>-definebones</code>
+: See {{ent|$definebone}}.
-: See [[$definebone]].
+; {{mono|-printbones}}
-; <code>-printbones</code>
 : Writes extra bone info to the console.
-; <code>-printgraph</code>
+; {{mono|-printgraph}}
-: Writes some kind of animation weight graph to the console.
+: {{Todo|Appears to dump xnode data for each node?}}
-; <code>-overridedefinebones</code>
+; {{mono|-overridedefinebones}}
-: Equivalent to specifying [[$unlockdefinebones]] in QC.
+: Equivalent to specifying {{ent|$unlockdefinebones}} in QC.
+; {{mono|-checklengths}}
+: Prints engine-ready keyframe data for each animation.
 === Performance ===
+; {{mono|-fastbuild}}
-; <code>-fullcollide</code>
+: Skip processing {{mono|.sw.vtx}} (DX6/DX7), {{mono|.dx80.vtx}}, and {{mono|.360.vtx}} variants (use {{mono|.dx90.vtx}} only). This speeds up compiling.
-: Don't truncate really big [[collision mesh]]es (Ep1 only; OB uses [[$maxconvexpieces]]).
+: {{important|In games before {{l4d}}, if the {{mono|.dx80.vtx}} is absent for a [[static prop]], [[VRAD]] will fail to generate lighting for that prop!}}
-; <code>-striplods</code>
+; {{mono|-preview}}
-: Ignore all [[$lod]] commands.
+: Skip splitting quads into tris and building tristrips. This changes the rendering flags for the model, most likely resulting in slower performance or buggier rendering in-engine.
-;<code>-minlod <lod></code>
+; {{mono|-fullcollide}} {{src06|only}}
-:Throw away data from LODs above the given one (see [[$minlod]]).
+: Don't truncate really big [[collision mesh]]es
-;<code>-perf</code>
+:{{note|{{src07|since}} use {{ent|$maxconvexpieces}}, as -fullcollide does nothing.}}
-:Report performance info in console.
+; {{mono|-striplods}}
-;<code>-mdlreport <path\model.mdl></code>
+: Ignore all {{ent|$lod}} commands.
+;{{mono|-minlod <lod>}}
+:Throw away data from LODs above the given one (see {{ent|$minlod}}).
+;{{mono|-mdlreport <path\model.mdl>}}
+;{{mono|-perf <path\model.mdl>}}
 :Report performance info for an already-compiled model. A QC file is not needed when using this command.
-;<code>-mdlreportspreadsheet</code>
+;{{mono|-mdlreportspreadsheet}}
-:Report performance info as a comma-delimited spreadsheet. {{TODO|Usage}}
+:Report performance info, per-LOD, as a comma-delimited spreadsheet. It will appear in the form:
+:<source>Path to VTX, VTX file extension, LOD number (1 is the root lod), tri count, number of batches rendered, number of materials used </source>
+:'''Must be used with -mdlreport or -perf!'''
+:{{Note|It doesn't actually ''write'' a spreadsheet to disk; use {{code|>}} to {{w|Redirection_(computing)#Basic|pipe output}} to a CSV file.}}
 === Debug ===
+;{{mono|-d}}
-;<code>-d</code>
 :Dumps various [[glview]] files (10 per LOD per VTX file),
-;<code>-h</code>
+;{{mono|-h}}
-:Dump [[hitbox]]es to console,
+:Dump [[hitbox]]es to console.
-;<code>-n</code>
+;{{mono|-n}}
 :Tag bad normals.
-;<code>-dumpmaterials</code>
+;{{mono|-dumpmaterials}}
 :Dump names of used materials to the console.
-;<code>-i</code>
+;{{mono|-i}}
 :Ignore warnings.
-;<code>-t</code>
+;{{mono|-t <[[material]]>}}
-: Replaces all materials with the default pink check pattern
+:Replaces all materials with the specified material.
+;{{mono|-parsecompletion}}
+:Prints an easily parseable message indicating whether the compile was successful or a failure.
+;{{mono|-collapsereport}}
+:Prints info on which bones are being retained and which bones are being collapsed.
-=== Unknown ===
+=== Other ===
+;{{mono|-nop4}}
+:Disables Valve's Perforce integration. Unless you actually have Perforce set up for your game/mod (a highly unlikely scenario), you should use this.
+;{{mono|-verify}}
+:Compile the model, but don't actually write the results to disk.
+;{{mono|-a <normal_blend_angle>}}
+:Auto-smooth faces equal to or below specified angle in degrees. By default, Studiomdl blends normals that are 2 degrees or less apart. Will override normal data for all meshes.
+;{{mono|-f}} {{src07|removed}}
+:Flip all triangles.
+:{{bug|hidetested=1|Does not work in Orange Box and later builds of Studiomdl. You can achieve the same behavior with {{ent|$body}}, however.}}
+;<tt>-vsi <path\[QC|MDL]></tt>
+:Generates a [[VSI]] file from a [[QC]] or [[MDL]].
+;{{mono|-stripmodel <path\model.mdl>}}
+:Strips down a model, removing its LOD info.
+;{{mono|-stripvhv <path\sp_hdr_x.vhv>}}
+:Strips down hardware verts ([[VHV]]) of their LOD info.
+;{{mono|-makefile}}
+:Generates a simple makefile for later compiling. It also parses the QC for any errors, and runs in {{mono|-quiet}} mode.
+;{{mono|-basedir <path>}}
+:Runs studiomdl in the context of the provided path.
+;{{mono|-tempcontent <path>}}
+:Adds the provided path as a content search path.
-;<code>-a <normal_blend_angle></code>
+=== Nonfunctional ===
-:?
+;{{mono|-r}}
-;<code>-checklengths</code>
+:In {{goldsrc}}, tagged reversed normals in compile output console; example: triangle reversed (0.748195 0.949818 0.839380)
-:?
+;{{mono|-ihvtest}}
-;<code>-f</code>
+:Probably meant to test the model collision for any physics errors. Skips whatever argument is provided after it.
-:Flip all triangles.
-;<code>-r</code>
+== Input Files ==
-:"Tag reversed"..?
+StudioMDL supports a range of input formats. These include [[SMD]], [[DMX]], [[OBJ]], and [[VRM]] for reference meshes, [[SMD]] and [[DMX]] for skeletal animation, and [[VTA]] and [[DMX]] files for vertex and flex animation. {{csgo|2}} also supports [[FBX]], but with limited functionality. [[Flex_animation|Flexes]] are not directly supported, nor are FBX sequences, however an SMD/DMX sequence can be used on an FBX model.
-;<code>-vsi <path\[QC|MDL]></code>
-:Generate stripping information .vsi file. Works with QC and MDL. (Some sort of memory optimisation function? Possibly related to Xbox 360.)
+{{note|While FBX does technically support flex animations, an SMD file is required to generate the VTA file, making the use of an FBX file for flexes redundant.}}
-;<code>-stripmodel</code>
-:Process binary model files (VSI?) and strip extra lod data.
+{| class="wikitable"
-;<code>-stripvhv</code>
+|-
-: Strip hardware verts to match the stripped model.
+! Format !! File Extensions !! Mesh !! Skeletal animation !! Vertex/flex animation
+|-
+| [[SMD]]
+| SMD<br>SMA {{src06|since}}<br>PHYS {{src06|since}}
+| Yes || Yes || Yes
+|-
+| [[DMX]]
+| DMX {{src07|since}}<br>XML {{src07|since}}<br>MPP {{csgobranch|since}}{{confirm}}
+| Yes || Yes || Yes
+|-
+| [[OBJ]]
+| OBJ || Yes || No || No
+|-
+| [[FBX]]
+| FBX {{csgobranch|since}}|| Yes || {{only|[[NekoMDL]]}} || {{only|[[NekoMDL]]}}
+|-
+| [[VRM]]
+| VRM || Yes || Yes || No
+|-
+| [[VTA]]
+| VTA || No || No || Yes
+|}
 == Output files ==
+;{{mono|mymodel.[[MDL (Source)|mdl]]}}
-;<code>mymodel.mdl</code>
+:[[Skeleton]], animations, bounding/hit boxes, surface materials, [[LOD]] indices, [[contents flags|contents]] and [[MDL flags]], etc.
-:[[Skeleton]], animations, bounding/hit boxes, surface materials, [[lod]] index...
+;{{mono|mymodel.sw.[[vtx]]}}
-;<code>mymodel.sw.vtx</code>
+;{{mono|mymodel.360.[[vtx]]}}
-;<code>mymodel.dx80.vtx</code>
+;{{mono|mymodel.dx80.[[vtx]]}}
-;<code>mymodel.dx90.vtx</code>
+;{{mono|mymodel.dx90.[[vtx]]}}
-:Vertex data optimised for DirectX 7, 8 and 9 respectively
+:Vertex data optimized for DirectX 6/7, Xbox 360, DirectX 8, and DirectX 9 respectively. {{Note|{{mono|.360.vtx}} files are just byteswapped {{mono|.dx90.vtx}} files.}}
-;<code>mymodel.vvd</code>
+;{{mono|mymodel.[[vvd]]}}
 :Remaining hardware-agnostic vertex data, including the [[UV map]]
-;<code>mymodel.phy</code>
+;{{mono|mymodel.[[phy]]}}
-:Collision mesh data
+:Collision mesh data. Omitted if no [[$collisionmodel]] is defined.
+;{{mono|mymodel.[[ani]]}}
+: Animations, if {{ent|$animblocksize}} is used.
 == See also ==
+* [[Compiling a model#Common errors|Common Studiomdl errors]]
-* [[Compiling a model#Common_errors|Common Studiomdl errors]]
+* [[Crowbar]], a popular graphical frontend for studiomdl which also supports model decompiling and other advanced features.
-* [[Studiocompiler]], a graphical interface for studiomdl
+* [[Studiocompiler]], a graphical frontend for studiomdl
-* [[GUIStudioMDL]], another graphical interface
+* [[GUIStudioMDL]], another graphical frontend
 * [[Source Model Compiler]], a web based model compiler and QC generator.
+* [[NekoMDL]], a modified fork of StudioMDL with additional features and increased limits
+* [https://gamebanana.com/tuts/12511 Fixing the 5% Weight Bone Link Cull], for SFM
+{{gldsrc sdktools}}
 {{SDKTools}}
 [[Category:Modeling]]

StudioMDL (Source): Difference between revisions

Latest revision as of 07:12, 20 May 2025

Contents