Porting humanoids to Portal 2

From Valve Developer Community
Jump to: navigation, search
The G-Man in Portal 2, complete with working eyes and skeletal and flex animation.

Portal 2, due to numerous and sometimes unknown bugs, will not support the direct (i.e. "drag'n'drop") porting of humans and humanoids, such as those from Half-Life 2. By porting models in this method, the humanoids will crash Hammer, HLMV, and Portal 2 itself. By following this guide, you will be able to successfully port humanoid models to Portal 2. To do: Do humanoids from other games, such as CS:GO, possess these same issues?

Note.png Note: I am not sure if all of the steps detailed underneath are required. Decompiling, Recompiling, and Porting the materials certainly are, as well as the shader change in Fixing the eyes.


  1. Extract the .mdl, .dx90.vtx, .dx80.vtx (if applicable), and .phy files from the VPK you are porting from, and place them in a handy directory.
  2. Download Crowbar, if you haven't already, by following the links here.
  3. Open Crowbar's exe file (you may have to extract the archive first). Open the Decompile tab and under MDL file or folder browse to the .mdl of the model you are converting. Under Output Folder, choose a nice clean directory to extract your files to. I recommend using the Full Path option, but it's completely up to you. Under Options, make sure your options are the same as mine:
Options for Crowbar decompile.


  1. Find the QC and open it in a text editor. Look for the line beginning with "$ModelName" and remember the string in quotes. Next, scroll down to the area where every line begins with $Attachment -- it should look something like this.
    $Attachment section
  2. If you see attachments named "EyeAttachRight" and "EyeAttachLeft", proceed to **Step 4**.
  3. Copy and paste the line that contains "eyes" in this section twice. Change "eyes" to "EyeAttachRight" in the first copy, and to "EyeAttachLeft" in the second. The section should now look something like this.
    $Attachment section after editing
    Save and close the QC. Don't worry about what this is doing -- it will come in handy later.
  4. Open Crowbar and switch to the **Compile** tab. Under **QC file or folder**, browse to the QC file you just opened.
  5. For Output Folder, switch to Full Path and type in C:\Program Files (x86)\Steam\SteamApps\common\Portal 2\portal2\models\[x], substituting [x] for the string you noted earlier, but with the file removed. Essentially, if the QC read "$ModelName" "props_test\testanim\deyork.mdl", you would enter C:\Program Files (x86)\Steam\SteamApps\common\Portal 2\portal2\models\props_test\testanim\ in the Full Path dialog, correcting for your Steam install directory.
  6. Under the Options section, make sure that Game that has the model compiler is set to Portal 2. Hit Compile!
    Note.png Note: Depending on your Steam library setup, you may have to run Set Up Games first.

Porting the materials

  1. After compiling your model, hit Use in View on the bottom bar of Crowbar. Then click on View. This will open HLMV straight to the model.
  2. If you have not already ported the materials, your model will appear black. Navigate to the Model tab and look at the VMTs Loaded section. The VMTs listed here are the ones you will need to port. Extract them from the original VPK and move them to the corresponding location in Portal 2's directory -- for example, you would place models/test/bestmap.vmt in C:\Program Files (x86)\Steam\SteamApps\common\Portal 2\portal2\materials\models\test\bestmap.vmt. once again correcting for your Steam install directory.
  3. Open all of the just-ported VMTs and find the VTFs they reference, and repeat the same process for them as well.
  4. Hit F5 to refresh HLMV. The model should now be perfectly textured.

Fixing the eyes

This is the step of the porting process that has stayed elusive to most modders.

  1. In HLMV, navigate to the Attachments tab. In the left column, select "eyes", and mess with the translation values so it is level with the eyes and about far away from them as in this picture on the right.
    Your model's "eyes" attachment should be in this position.
    Make sure that the blue arrow is pointing up, the red arrow is pointing away from the eyes, and the green arrow is perpendicular to them! Copy the QC String and replace the original $Attachment string for "eyes" in the QC with that.
  2. In the left column, select "EyeRightAttach" and mess with the Translation settings to get it centered on all axices in the model's right eye. Once again, make sure the blue arrow is pointing up, the red arrow is pointing away from the eyes, and the green arrow is perpendicular to them. Copy the QC String and replace the original $Attachment string for "EyeAttachRight" in the QC with that.
  3. Repeat the last step. except instead selecting, modifying, and replacing "EyeLeftAttach".
  4. Repeat the earlier process for compiling the model and hit F5 to refresh it in HLMV.
  5. Find the VMTs for the eyes by looking at the VMTs Loaded section of HLMV again. They will most likely be named eyeball_r.vmt and eyeball_l.vmt. Find them on-disk in your Portal 2 directory and open them.
  6. Replace the contents of the file with this:
$Iris "iris_texture_goes_here" 
$AmbientOcclTexture "models/player/eyeball_r_ambient" 
$Envmap "Engine/eye-reflection-cubemap-" 
$CorneaTexture "Engine/eye-cornea" 
$EyeballRadius "0.6" 
$AmbientOcclColor "[0.13 0.13 0.13]" 
$Dilation "0.4" 
$ParallaxStrength "0.25" 
$CorneaBumpStrength "1.0" 
$halflambert 1
$nodecal 1

$RaytraceSphere 0 
$SphereTexkillCombo 0 


Be sure to replace iris_texture_goes_here with the name of the original texture for $iris. Hit F5 to reload the model -- you're done!

Important Notes

  • Everything works except automatic lipsync. You'll have to do it manually. And be "manual" I mean adding your own flexes -- the phoneme system is broken entirely in Portal 2. (After all, why would they need it? The only human in the game doesnt even talk!) However, everything else works, including skeletal animation, facial expression animation, gestures, and eye tracking.
  • Ported human models' eyes will completely bug out UNLESS you set their prop type as "generic_actor" (or maybe another NPC). At first glance, this appears to remove some features like the "SetAnimation" input. However, generic_actor grants to access to using Faceposer to animate and choreograph scenes. It can accomplish everything that can be accomplished with prop_dynamic and more, but takes a bit more effort and work, and requires scenes/scenes.image to be distributed along with your BSP.
  • If you want to adjust the pupil size of a ported model, you have to manually resize the pupil on the texture in an image-editing program. This is due to the limitations of the EyeRefract shader.

See Also