Prop data

Every model that is to be used by prop_physics (and some that are to be used by prop_dynamic) must have a prop_data block. The block is embedded with the QC command $keyvalues.

prop_data co-exists with, but is distinct from, $surfaceprop.

Note:By default, models with prop_data cannot be prop_static.

Should my model be physical?

In Half-Life 2, Valve tried to follow these general rules:

If it's going to attach to or act as a support for a non-moving thing...

It should be static.

If it generates light...

It should be static.

If it's really big and the player couldn't possibly move it...

It should be static.

Otherwise...

It should be physical.

QC syntax example

$keyvalues
{
	prop_data
	{
		base			Wooden.Small 
		dmg.bullets		0 
		explosive_damage	100
		explosive_radius	50 
	}
}

• This example derives all its prop_data from the generic base_type "Wooden.Small".
• It then uses additional keyvalues to modify 3 special characteristics only for this model.
• So this particular small, wooden model will be bulletproof, but when it breaks it will explode, causing up to 100 damage to entities within a 50 unit radius.

Tips

You don't need to override anything at all if you don't want to

Just set a base and you've got a working physics prop.

Don't override health levels in all your props

Instead, use the base_types and let them set the health. This way you won't have one chair that takes twice as much damage as every other chair.

Whenever possible, avoid mixing material types inside the same prop

Don't make half-metal, half-wood props.

Follow Valve's rules above unless you have good reason to change them

In addition: Valve consider metal and plastic invulnerable, but everything else breakable.

Avoid collecting multiple objects into the same prop

Especially if you or Valve individually simulate identical-looking objects elsewhere.

Avoid moving parts and materials Source doesn't simulate

Don't hang coats from a coat rack or put water in a physical fish tank.

Options

General

base <base_type>

Defines the physical properties of the prop, according to the material from which it is made. All other keyvalues override those inherited from this!

See prop_data base material guidelines for a list of the stock prop_data base_types from Source SDK Base.

health <integer>

The amount of damage this prop should take before breaking.

Note:It is the model's health attribute that determines whether or not it is breakable. If health is "0" or "" (null), the model does not take damage and is not breakable.

allowstatic <boolean>

Allow this model to be prop_static as well as prop_physics. For consistency, avoid using this.

physicsmode <choices>

Sets the physics mode used by prop_physics_multiplayer.

Number	Name	Description
1	Solid, Server-side	Solid, pushes the player away.
2	Non-Solid, Server-side	Non-solid, but gets pushed away by the player.
3	Non-Solid, Client-side	Non-solid, clientside simulated only.

Template:Ep2 add

blockLOS <boolean>

Overrides whether the prop should block NPC Line of Sight. If unspecified, the game engine will decide based on the model's dimensions.

AIWalkable <boolean>

Set whether AI should try walking over this prop.

Todo: Does the prop type matter?

Damage modifiers

Use damage modifiers to reflect differences between the amount of damage that an object takes from different attacks. Don't use them to reflect overall damage strength. (e.g. Stone is resilient to everything. To reflect this, increase the health of all stone objects, don't set the damage modifiers lower.)

dmg.bullets <float>

Modifies damage done by bullets. Default is 1.0

• Paper, Cloth and Glass Window = 0.5
• Wooden = 0.75
• Flesh = 1.25.

dmg.club <float>

Modifies damage done by blunt impacts. Default is 1.0

• Cloth = 0.75
• Paper and Pottery = 1.25
• Wooden = 2.0

dmg.explosive <float>

Modifies damage done by explosions. Default is 1.0

• Paper, Cloth, Pottery, Flesh and Wooden = 1.5

damage_table <choices>

A Damage Table is defined by a programmer (in physics_impact_damage.cpp), and contains very detailed information about what damage a prop should take from different directions and forces. Only Glass and Pottery props inherit one; the others are used per-entity in C++ code.

Tip:Use damage_table "" to ignore an inherited table.

Flammable props

fire_interactions is a sub-set of the prop_data $keyvalues that defines flammability. There are only three known parameters, each with only one known value:

$keyvalues
{
   prop_data
   {
      fire_interactions
      {
         ignite      "halfhealth" 	// Will ignite on reaching 50% health.
         explosive_resist   "yes" 	// Clamp blast damage so that the prop ignites instead of breaking.
         flammable          "yes" 	// Can be ignited by fire and explosions.
      }
    }
}

Todo: confirm that fire_interactions are not used for flammable NPC models.

Todo: confirm that unbreakable (health 0) models can be flammable.

Exploding props

If these two fields are specified for a prop, then the prop will create an explosion with the specified values when it breaks.

$keyvalues
{
	prop_data
	{
		health 1 			// health must be >0 for the prop to be breakable. 
		explosive_damage <float> 	// The amount of explosive damage done by this prop when it breaks. 
		explosive_radius <float> 	// The radius of the explosion caused by this prop when it breaks. 
	}
}

Gibs

The prop_data system handles generic gibs. Generic gibs are used for any breakable object that doesn't have custom gibs. Custom gibs are assigned to a model using the $collisiontext QC command.

breakable_model <choices>

Defines the set of generic gibs this prop should break into.

• WoodChunks
• GlassChunks
• ConcreteChunks
• MetalChunks

Only props with the Wooden base_type inherit a gibset (WoodChunks).

This is only necessary if the prop doesn't have custom gibs. In general custom gibs are far superior to generic ones, but of course, there's a limit to how many custom gibs you can fit into memory.

Generic Gibsets are defined at the bottom of mod/scripts/propdata.txt.

breakable_count <integer>

The number of generic breakable gibs to break into. Required for gibs to appear.

This allows you to hard-code the number gibs yourself. By default the game engine will attempt to attribute a sensible number of generic gib models within the volume of the breaking object, based upon their (and its) size.

Only props with the Wooden base_type inherit a gib count - ranging from Wood.Tiny = 0 through to Wood.Huge =10.

breakable_skin <integer>

The skin to use on the generic breakable models.

Allows you to specify a skin to use on the gib models, which is useful for matching the original prop's material.

Only props with Wooden base_types inherit a gib skin (skin 0).

multiplayer_break <choices>

Determines whether the gibs from a prop_physics_multiplayer are simulated on the Client or Server or both.

Literal Value	Description
both	Creates gibs on both the server and the client.
server	Only creates gibs on the server.
client	Only creates gibs on the client. This is the default behavior.

Usually small gibs have no significant collision effect that might influence in-game events, so these are handled clientside rather than using up client-server connection bandwidth.

Todo: confirm that breakable_count, breakable_skin and multiplayer_break do not affect custom gibs.

Todo: confirm that multiplayer_break is set for the breakable model rather than each individual gib itself.

Generic prop_data

base_types

The purpose of the prop_data base_type is to apply generic, preset prop_data values to physics models. This ensures that in-game physics interactions are reasonably consistent for similar types of objects.

• Wherever possible, models should use one of these base_types instead of defining their own prop_data values. Once you have set a base_type for your model, it is not necessary to specify any other prop_data keyvalues - you have a working physics model.

• This table shows a list of the prop_data base_type names (and some guidance notes) available for Source SDK Base games. (A mod could conceivably use a different or modified list of prop_data base_type names, but this is unlikely.)

These are the prop_data base types available in Source SDK Base, as of April 2008:

Cardboard.Small

Cardboard / Paper blocks, less than 1ft³

Cardboard.Medium

Cardboard / Paper blocks, less than 3ft³

Cardboard.Large

Large Cardboard / Paper blocks (boxes, paper stacks...)

Cloth.Small

Small / thin cloth objects

Cloth.Medium

Heavier cloth / leather objects

Cloth.Large

Large / thick cloth objects (upholstery)

Wooden.Tiny

Tiny Wooden pieces that should die in one hit

Wooden.Small

Wooden blocks, less than 1ft³

Wooden.Medium

Wooden blocks, less than 3ft³

Wooden.Large

Large wooden blocks, less than 5ft³

Wooden.ExtraLarge

Extra large wooden objects

Wooden.Huge

Huge wooden objects (bookcases, wardrobes...)

Stone.Small

Stone blocks, less than 1ft³

Stone.Medium

Medium stone blocks, less than 3ft³

Stone.Large

Large stone blocks, less than 5ft³

Stone.Huge

Huge stone blocks, greater than 5ft³

Glass.Small

Glass blocks, less than 1ft³

Glass.Window

Window panes

Metal.Small

Small metal blocks, less than 1ft³

Metal.Medium

Medium metal objects

Metal.Large

Large metal objects (cars, fridges...)

Plastic.Small

Item.Small

Plastic blocks, less than 2ft³

Plastic.Medium

Item.Medium

Plastic blocks, less than 4ft³

Plastic.Large

Item.Large

Large Plastic objects, or medium objects with mixes of plastic & metal that you still want destructible (computers etc.)

Pottery.Small

Pottery blocks, less than 2ft³

Pottery.Medium

Medium pottery objects (flowerpots, plates...)

Pottery.Large

Large pottery objects

Pottery.Huge

Huge pottery objects (big ornate vessels)

Flesh.Tiny

Flesh/fruit that should die in a single hit

Flesh.Small

Flesh/fruit less than 1ft³

• Before 'overriding', say, the health of just one specific "Wooden.Small" model, consider whether it would in fact be more appropriate to change the health of all "Wooden.Small" models in your mod. If so, you will want to edit the "Wooden.Small" values in propdata.txt rather than the QC of your model.

editing propdata.txt

The purpose of game_dir/scripts/propdata.txt is to define generic, preset prop_data for physics models. This ensures that in-game physics interactions are reasonably consistent for similar types of objects.

Editing propdata.txt is an easy way to apply tweaks to the entire set of prop models without having to recompile each mdl. For example, in response to HL2 playtesting, Valve tweaked the overall amount of health for all wooden objects in the game several times.

Whilst it is possible to define new prop_data base_types, or rename existing ones, this would undermine the whole purpose of the propdata.txt file (vis to preserve consistency between physics models) and may render the vast majority of models available for Source games incompatible with your mod. It is therefore recommended that whenever possible, you should only edit the keyvalues of the existing base_types, not their names. Example (section from Source SDK Base/scripts/propdata.txt):

//=================================================================================
//		PAPER
//=================================================================================
// Base damage modifiers for paper objects
	
"Cardboard.Base"	 // DON'T USE THIS FOR A PROP. USE THE NON.BASE ONES.
	{
	"dmg.bullets"		"0.5"
	"dmg.club"		"1.25"
	"dmg.explosive" 	"1.5"
	} 

"Cardboard.Small" 	// Cardboard or Paper blocks, less than 1 foot cubed. eg small cardboard boxes, notepads, newspapers, thin books.
	{
	"base"			"Cardboard.Base"
	"health"		"10"
	}

"Cardboard.Medium" 	// Cardboard or Paper blocks, less than 3 foot cubed. eg cardboard boxes. thick books
	{
	"base"			"Cardboard.Base"
	"health"		"20"
	}

"Cardboard.Large" 	// Large Cardboard or Paper blocks. i.e. solid cardboard boxes
	{
	"base"			"Cardboard.Base"
	"health"		"40"
	}

Note:The Source SDK Base/scripts/propdata.txt only specifies only damage modifier and health prop_data keyvalues for each base_type. The exception is Wooden base_types which also have gib keyvalues specified.

Generic gibsets

Generic gibsets are also defined at the foot of propdata.txt. There are only four of them : "WoodChunks", "GlassChunks", "ConcreteChunks" and "MetalChunks". Only "WoodChunks" are assigned to a base_type (namely the "Wooden" base_types). However many models will make direct use of these generic gibsets via the prop_data "breakable_model" key.

• Example (section from Source SDK Base/scripts/propdata.txt):

"WoodChunks"      // Sorted in order of smallest to largest
{
  "models\Gibs\wood_gib01e.mdl"	"1"
  "models\Gibs\wood_gib01d.mdl"	"1"
  "models\Gibs\wood_gib01c.mdl"	"1"
  "models\Gibs\wood_gib01b.mdl"	"1"
  "models\Gibs\wood_gib01a.mdl"	"1"
}

Prototyping models

When working on prototypes, or when you don't have modellers handy, it's useful to be able to work around the prop data system's enforcement. To do this, use the prop_physics_override and prop_dynamic_override entities instead of prop_physics and prop_dynamic. A prop_physics_override entity will not remove itself if it is assigned a model that wants to be static (i.e. has no "prop_data" entry in its $keyvalues .QC section). It will also allow the level designer to set its "health".

The override entities allow you to temporarily use models incorrectly while prototyping, or waiting for a modeller to finish up a new model that has the properties you desire. It is highly recommended that you use Hammer's Entity Report feature to check each of your maps to ensure you have no override entities left when you ship them. Otherwise you may be shipping physics inconsistencies, and players are extremely quick to notice them (the orange bucket won't move when I shoot it on this level, but it did on the previous one).

See also

• prop_static, prop_dynamic, prop_physics - common prop entities.
• Prop Types Overview - an article describing various prop types.
• physgun interactions - another QC $keyvalues block that defines some special interactions between prop_physics models and the physcannon.