Prop data

From Valve Developer Community
Revision as of 01:40, 15 July 2005 by Robin Walker (talk | contribs) (Created.)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

The purpose of the Prop Data system is to ensure that the interactive behaviour of prop models stays consistent across all the levels in your game / mod. The three core prop entities (prop_static, prop_dynamic, and prop_physics) all use the prop data system to load game-related data from the model they're set to use. This article will explain the data stored inside the Prop Data section of models, and how you can edit it in your mod.

Core Data File

The Prop Data system stores data in a hierarchy. The base prop data classes are laid out inside the mod\scripts\propdata.txt file. Wherever possible, models use one of these classes instead of defining their own class. This way, large tweaks can be applied to the entire set of prop models without having to rebuild any content (for instance, in response to HL2 playtests, we tweaked the overall amount of health for all wooden objects in the game several times).

The propdata.txt format is a KeyValue formatted data file, where each entry matches the following format:

"prop data class name"
    "key"              "value"

The keys & their appropriate values are as follows:

  • "base"
<string> Should be the name of another prop data class defined in the propdata.txt file. If specified, this prop data class will derive all of its data from the base class. Further keys in this class will override the base class keys.
  • "blockLOS"
<integer> Used to override whether this prop should block NPC's Line-Of-Sight. If unspecified, the prop will decide whether it blocks NPC sight based on its size. Set it "0" or "1" to enforce a desired sight blocking behavior.
  • "AIWalkable"
<integer> Used to set whether AI should consider this prop as walkable on. Set to "0" or "1".
  • "health"
<integer> The amount of damage this prop should take before breaking. If left out, or set to "0", this prop will not take damage and never break.
  • "damage_table"
<string> The name of a custom physics damage table to use for this prop. The mod must define the damage table in its code. HL2 only provides one custom damage table for props, named "glass". Use it for extremely fragile objects that could break just from being dropped.
  • "dmg.bullets"
<float> Modifies damage done by bullets to this prop. By default, this is set to "1.0".
  • ""
<float> Modifies damage done by clubs to this prop. By default, this is set to "1.0".
  • "dmg.explosive"
<float> Modified damage done by explosives to this prop. By default, this is set to "1.0".
Use damage modifiers to reflect differences between the amount of damage that an object takes from different damage types. Don't use them to reflect overall damage strength. i.e. Stone is resilient to everything. To reflect this, increase the health of all stone objects, don't set the damage modifiers lower.
  • "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.
If these two fields are specified for a prop, then the prop will create an explosion with the specified values when it breaks.
  • "breakable_model"
<string> The type of breakable gibs this prop should break into. Only necessary if the prop doesn't have custom gibs. The string should be the name of an entry in the generic breakable section, which is also defined in the propdata.txt file. See below.
  • "breakable_count"
<integer> The number of generic breakable gibs to break into.
  • "allowstatic"
<integer> An override to allow this prop to be static as well as physically simulated. In general, this should not be used.

Setting Up a Prop Model

Once you've built your prop model, you need to setup the prop data that should be enforced. Prop data is embedded into the $keyvalues section of the model's .QC file. First, you need to decide how the prop should be simulated. In HL2, we 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 can't possibly move it, it should be static.
  • Otherwise, it should be physically simulated.

If you want your prop to be static, then you're done. Any model without a prop data section in its $keyvalues section will be forced to be static. If a mapmaker places it as a prop_physics entity, it will be removed and a warning will be displayed.

If you want your prop to be physically simulated, then you need to add the $keyvalues section to the model's .QC file. If there is no existing $keyvalues section in the .qc, add the whole chunk. Otherwise just add the "prop_data" section at the end of the existing $keyvalues section. An example $keyvalues entry would be something like this:

       "base"              "Wooden.Small"
       "dmg.bullets"       "0"
       "explosive_damage"  "100"
       "explosive_radius"  "100"

This example prop data entry tells the prop to derive all of its data from the base "Wooden.Small" entry in the propdata.txt file. It then overrides several variables, which make the prop immune to bullet damage and creates an explosion when it breaks. To find the base prop class to derive from for your prop, open up the mod/scripts/propdata.txt file and find the entry that best matches the prop you've built. Make sure you choose a "<material>.<size>" entry, not the "<material>.Base" entry that simply sets damage modifiers for the material type.

When building props, you can help your game / mod to be consistent by following these tips:

  • Don't override health levels in all your props. Instead, use the base prop classes and let them set the health. This way you won't have one chair that takes twice as much health as every other chair.
  • Whenever possible, avoid mixing material types inside the same prop. i.e. don't make half metal, half wood props.
  • Follow the HL2 rules unless you have good reason to change them: metal & plastic are invulnerable. Everything else breaks.
  • Avoid collecting multiple objects into the same prop, especially if we invidividually simulate identical looking objects elsewhere.
  • Avoid moving parts & materials we don't simulate. i.e. don't hang coats from a coat rack.


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 "propdata" entry in its $keyvalues .QC section). It will also let the level designer to set a "health" on it.

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