From Valve Developer Community
Jump to: navigation, search

PHY is the extension for Source's proprietary collision model data format. It stores data for the rigid or jointed (ragdoll) collision model used by the MDL. In addition, it stores some $keyvalues about a model such as which gib-models to use if destroyed.

Note:The PHY file is completely independent from the rest of the models binaries. As long as the filename and skeleton structure matches the data within the MDL file the collision data can be changed without any adverse affects. A collision mesh could be added to a model without one initially but a recompile would be needed to set the correct flags within the MDL file and to add $keyvalues data.

Also if you're optimizing your map because you have too many edicts it's useful to know that the .phy file counts as +1 edict (Adds to Entity_limit) to the for unknown reasons. You can delete the .phy file to over come this problem if the custom model doesn't really need the collision data.

File Format

In brief, a PHY file is formed by:

  • A main header, which specifies the number of solids
  • A series of VPHY/collision data sections, one per solid
  • A single text data section, variously-ordered block elements that specify which solid they apply to

Main header

The first bytes of the file form the main header:

// this structure can be found in <mod folder>/src/public/phyfile.h
struct phyheader_t
	int		size;           // Size of this header section (generally 16)
	int		id;             // Often zero, unknown purpose.
	int		solidCount;     // Number of solids in file
	long	        checkSum;	// checksum of source .mdl file (4-bytes)

Collision data sections

There will be a series of these sections, back-to-back, numbering the same as the header's solidCount.

// new phy format
struct compactsurfaceheader_t
	int	size;			// Size of the content after this byte
	int	vphysicsID;		// Generally the ASCII for "VPHY" in newer files
	short	version;
	short	modelType;
	int	surfaceSize;
	Vector	dragAxisAreas;
	int	axisMapSize;
// old style phy format
struct legacysurfaceheader_t
	int	size;
	float	mass_center[3];
	float	rotation_inertia[3];
	float	upper_limit_radius;
	int	max_deviation : 8;
	int	byte_size : 24;
	int	offset_ledgetree_root;
	int	dummy[3]; 		// dummy[2] is "IVPS" or 0

To do: Document details of each collision section

Text section

The text section occurs near the end of the file, and is one single string with no size header. Among the text blocks it may contain:

  • solid blocks define solids, using an index value to distinguish which set of collision data they refer to.
  • ragdollconstraint blocks define relationships between parent and child solids.
  • An editparams block with general information about the entire object.
  • Various break blocks with information about rigid or jointed gibs created when the model is destroyed.

Here is an incomplete sample from the Combine Strider, formatted for readability.

	"index" "8"
	"name" "Combine_Strider.Leg_Hind_Bone1"
	"parent" "Combine_Strider.Leg_Hind_Bone"
	"mass" "137.739014"
	"surfaceprop" "strider"
	"damping" "0.000000"
	"rotdamping" "1.000000"
	"inertia" "1.000000"
	"volume" "109397.476563"
	"parent" "7"
	"child" "8"
	"xmin" "0.000000"
	"xmax" "0.000000"
	"xfriction" "2.000000"
	"ymin" "0.000000"
	"ymax" "0.000000"
	"yfriction" "2.000000"
	"zmin" "-32.000000"
	"zmax" "138.000000"
	"zfriction" "0.200000"
	"rootname" "combine_strider.body_bone"
	"totalmass" "2000.000000"
	"model" "Gibs/Strider_Gib1" 
	"health" "0" 
	"fadetime" "0" 
	"placementbone" "Combine_strider.body_bone"
	"ragdoll" "Gibs/Strider_Head" 
	"health" "0" 
	"fadetime" "0"  

See also