Prop data

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. For HL2, 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 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 level designer places it as a prop_physics entity, it will be removed during BSP compile and a warning will be displayed in the compiler log.

If you want your prop to be physically simulated, then you need to add a prop_data block into $keyvalues section to the model's .QC file, unless it's there already. An example $keyvalues entry would look something like this:

$keyvalues
{
	prop_data
	{
		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 class "Wooden.Small" entry in the propdata.txt file. It then goes on to override several values, making the model immune to bullet damage but creating an explosion when the model breaks.

To find the best prop_data base class for your model, see prop_data base material guidelines. If you are modelling for a mod that doesn't use the default propdata.txt, 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.

Tip:When compiling your model's prop_data, you can help your game / mod to be consistent by following these tips:

• You don't need to override anything at all if you don't want to. Just use base and you've got a working physics prop.
• 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 individually simulate identical looking objects elsewhere.
• Avoid moving parts & materials we don't simulate, i.e. don't hang coats from a coat rack.

prop_data keyvalues

base <choices>

Defines the main breakable properties of the prop according to the material from which it is made.

• The parameter must be the name of a prop_data base class.
• For your convenience, here is a list of the Source SDK Base prop_data base classes for use with models.
• If specified, this prop will inherit its prop_data from the base class. Further prop_data key/values will override any "base class" values.
• Your mod's quirky prop_data "base classes" will be defined in game_dir/scripts/propdata.txt.

allowstatic <boolean>

An override to allow this prop to be a prop_static as well as a prop_physics.

• In general, this should not be used.

physicsmode <choices>

Sets the physics mode used by the 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>

Used to override whether this prop should block NPC's Line of Sight.

• If unspecified, the game engine will decide whether it blocks NPC LOS based on the model size.
• Use this to enforce a desired sight blocking behaviour.

AIWalkable <boolean>

Used to set whether AI should consider this prop as a floor candidate.

breakable props

Primarily, the health of the model determines if and when the model will break into gibs and/or explode.

• If model's health is set to "0" or "" (null), it will not take damage and is not breakable and cannot explode.
• All prop_data "base classes" define the health of models based on them and, by default, only models based on Metal, Plastic or Item "base classes" are unbreakable.

health <integer>

The amount of damage this prop should take before breaking.

• If set to "0" or "", this prop will not take damage and is not breakable.
• This value is inherited from all "base classes". Specify only to override.

damage modifiers

damage_table <choices>

The name of the Damage Table to use for this prop.

• Only props with the Glass and Pottery "base class" inherit a damage_table ("glass").
• Use damage_table "" to ignore a damage_table inherited from "base" class
• Damage tables are defined in code (physics_impact_damage.cpp). Only the stock tables are mentioned here.

dmg.bullets <float>

Modifies damage done by bullets to this prop.

• For most "base classes" this is set to "1.0" but Paper, Cloth & Glass Window = "0.5", Wood = "0.75", and Flesh = "1.25".

dmg.club <float>

Modifies damage done by clubs to this prop.

• For most "base classes" this is set to "1.0" but Cloth = "0.75", Paper & Pottery = "1.25", Wood = "2.0".

dmg.explosive <float>

Modified damage done by explosives to this prop.

• 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.
• For most "base classes" this is set to "1.0" but Paper, Cloth, Pottery, Flesh & Wood = "1.5".

flammable props

fire_interactions is a sub-set of the prop_data $keyvalues that defines flammability. There are currently only 3 known parameters.

• Todo: confirm : conceivably unbreakable props might still be flammable ...
• QC syntax example :

$keyvalues {
   prop_data {
      fire_interactions {
         ignite "halfhealth"	// This prop will ignite itself when its health falls below half its starting health.
         explosive_resist "yes" // This reduces blast damage to the prop so it ignites instead of breaking.
         flammable "yes"	// This prop can be ignited by nearby fires & "explode_fire" physgun missiles.
      }
   }
}

ignite <choices>

Literal Value	Description
halfhealth	This prop will ignite itself when its health falls below half its starting health.

explosive_resist <choices>

Literal Value	Description
yes	This sets a special behavior on the prop that reduces blast damage it takes. If the prop is about to take blast damage that would kill it, it will reduce the damage enough to not die, and then ignite itself instead.

flammable <choices>

Literal Value	Description
yes	This prop can be ignited by ignition damage (such as nearby fires & props marked with the "explode_fire" physcannon interaction. This was unused in HL2, and hence unsupported as this time.

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 Wood "base class" 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 Wood "base class" 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 the Wood "base class" 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 multiplayer_break is set for the breakable model rather than each individual gib itself.

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. 
   }
}

physgun_interactions

The physgun_interactions $keyvalues set affects how props are handled, etc by the physcannon. Note that they are not part of the prop_data block : example QC syntax:

$keyvalues {
   physgun_interactions {
      preferred_carryangles 	"0 0 0" 	
      onworldimpact 		"stick"		
      onfirstimpact 		"break" 		
      onfirstimpact 		"paintsplat" 	
   // onfirstimpact 		"impale" 		
   // onlaunch 			"spin_none" 		
      onlaunch 			"spin_zaxis" 		
      onbreak 			"explode_fire" 		
      damage 			"none" 			
   }
}

preferred_carryangles <angles>

Sets the angles, relative to the player's orientation, at which the prop will be held when carried.

• This is used, for example, with the sawblades and propellers in Ravenholm, as well as the turret NPCs in Nova Prospekt.

onworldimpact <choices>

Literal Value	Description
stick	Prop will embed itself into the world if it hits it after being launched.

onfirstimpact <choices>

Literal Value	Description
break	Prop should always break on colliding with anything after being launched.
paintsplat	Prop applies paint decals to the first thing it hits after being launched.
impale	Prop impales whatever it first collides with after being launched. Not used in HL2, and hence unsupported at this time.

onlaunch <choices>

Literal Value	Description
spin_none	Prop does not spin when launched. By default, the physgun applies random angular velocity to objects it launches.
spin_zaxis	Prop should spin around the Z axis when launched by the physcannon.

onbreak <choices>

Literal Value	Description
explode_fire	Prop ignites nearby enemies when it explodes on breaking.

damage <choices>

Literal Value	Description
none	Prop does not move when 'attacked' with the physgun. It may still take damage, but it won't move due to the impact.

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).

propdata.txt

The purpose of the Prop Data system is to ensure that the interactive behavior 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 section will explain how you can edit it in your mod.

The Prop Data system stores data hierarchically. The prop_data base classes are defined inside the mod\scripts\propdata.txt file. Wherever possible, models use one of these classes instead of defining their own class. This ensures a reasonable level of consistency in physics with models, and makes it easier to apply tweaks to the entire set of prop models without having to recompile each mdl. For example, in response to Half-Life 2 playtests, Valve 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:

<material_type>.<size_description> // Suggested format; you can actually call it anything you like (but avoid spaces)
{
	key	"value x or y" // If there is a space or tab character within a key or value, you need quote marks around it
	(...)
}

See also

• prop_static, prop_dynamic, prop_physics - common prop entities.
• Prop Types Overview - an article describing various prop types.