ModelDoc FAQ & best practices

<cat>Model.Intro</cat>
<title>ModelDoc FAQ & best practices</title>

# Frequently asked questions

## > Can you import MDL/FBX/SMD...

ModelDoc supports:
* Valve's own formats: DMX (should be version 22?), and SMD (technically deprecated, but usable)
* Typical 3D formats: FBX, OBJ, VOX
* Multiple animations per FBX file (also known as "takes" in the FBX format)

What's NOT supported:

* Source 1 and GoldSrc MDL (support was removed)
* Vertices with more than 4 weight influences. *Weights will automatically get culled and normalized, which is far from ideal; best to plan your skinning with this in mind from the start!*

## > How do I import several animations at once?

Use the *"Add Simple Animations"* feature. The simplest way to access it is by right-clicking *AnimationList*.

<upload src="a50a1/8d972b21c553879.png" size="32842" name="sbox_2021-09-08_12-18-38.png" />

## > How do I create a player model for s&box?

You need to create a character model, with its own animgraph that will respond properly to the inputs of the Animation Controller. This involves all steps of model creation, along with animating and creating the graph yourself.

If you can't or don't want to do all this for your new character, you can work "on top of" the Citizen, or extend it. [See this section of the Citizen page for more info.](https://wiki.facepunch.com/sbox/Citizen_Model#creatinganewplayermodel)

## > How do I decompile a compiled model (VMDL_C)?

Ideally, you shouldn't decompile a model. You're likely to get something that's not usable without some (if not lots of) work. If you want to modify something someone else made, you should ask them first!

The cleanest way to generate source files back out of an existing VMDL is to open it in ModelDoc, and use the *Export As...* function. It can export any meshes (including skinned ones) as FBX or OBJ. It will also attempt to export the maps used by the model's materials.

You may also try to use the [Valve Resource Format](https://github.com/SteamDatabase/ValveResourceFormat/releases) explorer to attempt to export individual animations, though they will need some clean-up.

## > How do I move/scale a model in ModelDoc?

It is recommended you modify location and rotation manually in a separate modelling program. Alternatively, for scale you can use the **ScaleAndMirror** node for scaling your model. If your mesh is static (not skinned to any bones), you can change its position, orientation, and, scale in the same **RenderMeshFile** node you used to import the model:

<upload src="a4aaf/8d9989cc0f1d3ae.png" size="7247" name="image.png" />

<warning>Because animation nodes don't have individual scaling settings, scaling a mesh without its animations would effectively break the animations. Therefore, for animated models, using the ScaleAndMirror global modifier node is preferred.</warning>

## > I have missing bones!

By default, bones that are not skinning anything will be transparently discarded. You can prevent this behaviour in two ways:

1) Create a BoneMarkup node for your bone, and tick "Do Not Discard"
2) Set "Bone Cull Type" to "Leaf Only" or "None" on the root "BoneMarkupList" container.

Keep in mind that fewer bones are best for performance.

You can check the compiled hierarchy in the "Compiled Preview Outliner", under "Skeleton"; this lets you know what may have been discarded, changed, or otherwise modified.

## > My morph target (blend shape) isn't importing properly!

* Make sure the material used by your mesh has morph enabled in its material properties!

* There must not be any underscores in the names of your shapes. In the DMX specification, underscores are specifically for corrective shapes. See [this page](https://developer.valvesoftware.com/wiki/Flex_animation#Corrective_shapes) on the Valve Developer Community wiki for more information.

# What's "Base Model"?

Think of it as an equivalent of [Source 1's $includemodel .QC command](https://developer.valvesoftware.com/wiki/$includemodel), which was used by your "main" model to reference animation-only models.

However, in s&box, it works the other way around! For example, if you want to extend the Citizen character with new animations, your new VMDL (e.g. "citizen_my_custom_version.vmdl") would be referencing "citizen.vmdl" as its "Base Model".

<warning>**Your new VMDL should only hold new animations and nothing else.**</warning>

# Best practices

* Unless your model is meant to be a fully static thing, it should have at least one animation sequence. Just bindPose should be enough. Otherwise, for optimization purposes, some things may invisibly break (morph targets won't work, IK data will mysteriously go missing, etc.)

* Do not create bones in ModelDoc unless you absolutely have to do it that way — this feature should be seen as a "last resort", when you absolutely can't go into 3D software to create the bone in the source file. You should only rely on that feature if you have a completely rigid prop (no articulations, no "jiggle bones", no cloth, etc.) and you need to define ONE attachment (or attachment bone) for it. 

* When working with others, or when distributing your source files, your FBX files should be binary, and not ASCII. This is because Blender users can only import binary FBX files.

* Keep the download size of your addon in mind. Compress your files and masks up to the point that's needed. Your character model shouldn't be 300 MiB on its own. See the Material Editor category on this wiki for more information.

* If your model has multiple materials, name them accordingly. If a material has a period in its name everything after it will get omitted, resulting in multiple materials of the same name, which gets collapsed into only one when imported *(example: Blender naming materials .001, .002, etc. when using the same names)*

ModelDoc FAQ & best practices

Account Management

Special Pages

Wiki List

S&box Wiki