Porting humanoids to Portal 2

The G-Man in Portal 2, complete with working eyes and flex animations.

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 these models using 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.

Decompiling

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.
   Note:If you are porting humanoids from Half-Life 2 you will need to also extract the male_gestures.mdl, male_postures.mdl, male_shared.mdl and male_ss.mdl models for the male npcs and female_gestures.mdl, female_postures.mdl, female_shared.mdl and female_ss.mdl models for the female npcs otherwise the game will crash. These just have to be recompiled and the $attachment step can be skipped.
2. Download Crowbar, if you haven't already, download it 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 the files to. It is recommended to use the Full Path option, but it's completely up to the user. Under Options, make sure your options are the same as shown in the image below:

Crowbar decompilation options as of version 0.74.

Recompiling

1. Find the .QC file and open it in a text editor and look for the line beginning with $attachment. It should look something like this:

   $Attachment "eyes" "ValveBiped.Bip01_Head1" 3.23 -3.49 0.12 rotate 0 -80.1 -90
   $Attachment "mouth" "ValveBiped.Bip01_Head1" 0.6 -5.5 0 rotate 0 -80 -90
   $Attachment "chest" "ValveBiped.Bip01_Spine2" 5 4 0 rotate 0 90 90
   $Attachment "forward" "ValveBiped.forward" 0 0 0 rotate 0 0 0
   $Attachment "anim_attachment_RH" "ValveBiped.Anim_Attachment_RH" 0 0 0 rotate -90 -90 0
   $Attachment "anim_attachment_LH" "ValveBiped.Anim_Attachment_LH" 0 0 0 rotate -90 -90 0
   $Attachment "anim_attachment_head" "ValveBiped.Bip01_Head1" 0 0 0 rotate -90 -90 0
   

   Note: If you see attachments named "EyeRightAttach" and "EyeLeftAttach", proceed to Step 4.
2. Copy and paste the line that contains "eyes" in this section twice. Change "eyes" to "EyeRightAttach" in the first copy, and to "EyeLeftAttach" in the second. The section should now look something like this.

   $Attachment "EyeRightAttach" "ValveBiped.Bip01_Head1" 3.23 -3.49 0.12 rotate 0 -80.1 -90
   $Attachment "EyeLeftAttach" "ValveBiped.Bip01_Head1" 3.23 -3.49 0.12 rotate 0 -80.1 -90
   $Attachment "eyes" "ValveBiped.Bip01_Head1" 3.23 -3.49 0.12 rotate 0 -80.1 -90
   $Attachment "mouth" "ValveBiped.Bip01_Head1" 0.6 -5.5 0 rotate 0 -80 -90
   $Attachment "chest" "ValveBiped.Bip01_Spine2" 5 4 0 rotate 0 90 90
   $Attachment "forward" "ValveBiped.forward" 0 0 0 rotate 0 0 0
   $Attachment "anim_attachment_RH" "ValveBiped.Anim_Attachment_RH" 0 0 0 rotate -90 -90 0
   $Attachment "anim_attachment_LH" "ValveBiped.Anim_Attachment_LH" 0 0 0 rotate -90 -90 0
   $Attachment "anim_attachment_head" "ValveBiped.Bip01_Head1" 0 0 0 rotate -90 -90 0
   

3. Save and close the QC.
4. Open Crowbar and switch to the Compile tab. Under QC input, browse to the QC file you just opened and select it.
5. For Output Folder, switch to Game's "models" folder
   Note:For this to work you have to have your games set up properly by going into the Set Up Games tab
6. Under the Options section, make sure that Game that has the model compiler: is set to Portal 2.
7. Hit Compile!

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 with a purple and black missing texture. Navigate to the Model tab and look at the VMTs Loaded section. The VMT files listed here are the ones you will need to port alongside their corresponding VTF files. Extract them from the original VPK and move them to the corresponding location in Portal 2's directory -- for example, you would place \materials\models\gman\gman_sheet.vmt in C:\Program Files (x86)\Steam\SteamApps\common\Portal 2\portal2\materials\models\gman\gman_sheet.vmt. once again correcting for your Steam install directory.
3. Hit F5 to refresh HLMV. The model should now be perfectly textured.

Fixing the eye material

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

1. Find the VMT files 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.
2. Replace the contents of the file with this:

EyeRefract
{
$Iris "iris_texture_goes_here"
$AmbientOcclTexture "models/player/chell/gambler_eye_ao"
$Envmap "Engine/eye-reflection-cubemap-"
$CorneaTexture "Engine/eye-cornea"
$EyeballRadius "0.5"
$AmbientOcclColor "[.6 .4 .3]"
$Dilation ".6"
$ParallaxStrength "0.25"
$CorneaBumpStrength ".5"
$halflambert 1
$nodecal 1
$ambientocclusion 1

$RaytraceSphere 1
$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!

Fixing the eye texture

How it should look at this point as described in step 5

To have the eye texture appear properly both the iris textures and eyeball textures have to be combined into one single texture. To do this an image editing program like GIMP or Adobe Photoshop is needed.

1. Export the eyeball and iris texture from their respective VTF files
2. Next, export gambler_eyes.vtf found under \materials\models\player\chell in the Portal 2 .VPK
3. Import the images into your image editing program of choice
   Note:In this tutorial GIMP is used but the process should be similar to your setup
4. Copy the Half-Life 2 eyeball texture over to the gambler_eyes texture and scale it to fit the gambler_eyes image size as shown in the image
5. Copy and paste the iris texture onto the eyeball texture and merge the two together
6. Next copy the alpha channel of gambler_eyes to the Half-Life 2 eyeball texture. Tutorial for GIMP
7. Now with that done export the image (without the gambler_eyes texture of course) and it's ready to be reimplemented and be used as the eyeball texture within the new shader
   Note:Remember to name it the same as the original eyeball texture.
   The texture has to be imported into VTFEdit in RGBA8888 formatting

Tip:To create the right version of the texture simply take the left one and flip it horizontally.

How it should look in the end

Important Notes

• Everything works except automatic lipsync and walking. Lipsyncing will have to be done manually. And by "manual" it means adding your own flexes -- the phoneme system is broken entirely in Portal 2. (But of course, why would Portal 2 need something so unutilized?) However, everything else works, including skeletal animation, facial expression animation, gestures, and eye tracking.
• Walking animations are very buggy. A generic actor when walking will glitch, visually teleporting around and will appear to "lag".
• Ported human models' eyes will just follow the player around no matter their location UNLESS the prop type is set to generic_actor. At first glance, this appears to remove some features like the SetAnimation input. However, generic_actor grants access to using scripted_sequence and 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.
• To adjust the pupil size of a ported model, it has to be manually resized in the Fixing the eye texture step of the porting process. This is due to the limitations of the EyeRefract shader.

See also

• Choreography creation: For animating the humans
• Portal 2 Level Design: P2 level creation home page
• weapon_portal_base: For creating custom weapons in the Portal franchise