Difference between revisions of "Prop data"

From Valve Developer Community
Jump to: navigation, search
(Created.)
 
m
 
(92 intermediate revisions by 18 users not shown)
Line 1: Line 1:
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.
+
{{otherlang2
 +
|title=prop_data
 +
| jp = Prop data:jp
 +
|ru=Prop data:ru
 +
}}
  
==Core Data File==
+
{{toc-right}}
The Prop Data system stores data in a hierarchy. The base prop data classes are laid out inside the <code>mod\scripts\propdata.txt</code> 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 <code>propdata.txt</code> format is a KeyValue formatted data file, where each entry matches the following format:
+
'''<code>prop_data</code>''' can be used to make a model:
  "prop data class name"
+
 
 +
* [[#Options|Physical]] (by default models with <code>prop_data</code> cannot be [[prop_static|static]])
 +
* [[#Damage modifiers|Breakable]] (with [[#Gibs|gibs]])
 +
* [[#Flammable props|Flammable]]
 +
* [[#Exploding props|Explosive]]
 +
 
 +
It is a [[KeyValues]] block embedded with the QC command <code>[[$keyvalues]]</code>.
 +
 
 +
{{note|The properties of a model's ''surface'' are defined by <code>[[$surfaceprop]]</code>.}}
 +
{{note|Models for use with [[prop_physics]] will also need <code>[[$staticprop]]</code>.}}
 +
 
 +
== Example ==
 +
 
 +
  [[$keyvalues]]
 
  {
 
  {
    "key"              "value"
+
prop_data
    ...
+
{
 +
base Wooden.Small
 +
dmg.bullets 0
 +
explosive_damage 100
 +
explosive_radius 50
 +
}
 
  }
 
  }
  
The keys & their appropriate values are as follows:
+
Here we derive prop_data from the generic base_type "Wooden.Small". Then we use additional keyvalues to give the model three special characteristics: it will be bulletproof, but when it breaks it will explode and cause up to 100 damage to entities within a 50 unit radius.
* '''"base"'''
 
: <string> Should be the name of another prop data class defined in the <code>propdata.txt</code> 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".
 
* '''"dmg.club"'''
 
: <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 <code>propdata.txt</code> 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==
+
==Tips==
  
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_Commands|.QC]] file. First, you need to decide how the prop should be simulated. In HL2, we tried to follow these general rules:
+
;You don't need to override anything at all if you don't want to
* If it's going to attach to, or act as a support for a non moving thing, it should be static.
+
:Just set a <code>base</code> and you've got a working physics prop.
* If it generates light, it should be static.
+
;Don't override health levels in all your props
* If it's really big and the player can't possibly move it, it should be static.
+
:Instead, let the base types set the health. This way you won't have one chair that takes twice as much damage as every other chair.
* Otherwise, it should be physically simulated.
+
;Whenever possible, avoid mixing material types inside the same prop
'''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.
+
:Don't make half-metal, half-wood props.
 +
;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 put water in a physical fish tank.
  
'''If you want your prop to be physically simulated''', then you need to add the $keyvalues section to the model's [[.QC_Commands|.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:
+
=== Should my model be physical? ===
$keyvalues
+
 
{
+
In Half-Life 2, Valve tried to follow these general rules:
    "prop_data"
+
 
    {
+
;If it's going to attach to or act as a support for a non-moving thing...
        "base"              "Wooden.Small"
+
:It should be static.
        "dmg.bullets"       "0"
+
;If it generates static light...
        "explosive_damage"  "100"
+
:It should be static.
        "explosive_radius"  "100"
+
;If it's really big and the player couldn't possibly move it...
    }
+
:It should be static.
}
+
;Otherwise...
This example prop data entry tells the prop to derive all of its data from the base "Wooden.Small" entry in the <code>propdata.txt</code> 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 <code>mod/scripts/propdata.txt</code> 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.  
+
:It should be physical.
 +
 
 +
Additionally, Valve consider metal and plastic invulnerable but everything else breakable.
 +
 
 +
== Options ==
 +
 
 +
=== Base type ===
 +
 
 +
; <code>base <[[string]]></code>
 +
: Gives the model a [[prop_data base types|predefined prop_data type]], providing in one motion all the data the engine needs to make the model both physical and breakable. Most other commands in a prop_data block are overrides of values inherited from here.
 +
 
 +
===General===
 +
 
 +
; <code>health <[[int]]></code>
 +
: The amount of damage this prop should take before breaking. 0 means don't break.
 +
; <code>allowstatic <[[bool]]></code>
 +
: Allows the model to be used with [[prop_static]]. To enforce consistency, avoid if possible.
 +
; <code>physicsmode <choices></code>
 +
: Sets the physics mode used by [[prop_physics_multiplayer]]. Can be overridden by the entity in the Orange Box.
 +
{{physicsmode choices}}
 +
; <code>blockLOS <bool></code>
 +
: Overrides whether the prop should block NPC [[line of sight]]. If unspecified, the game engine will decide based on the model's dimensions.  
 +
; <code>AIWalkable <bool></code>
 +
: Should NPCs try walking over this prop? {{todo|Does 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.)''
 +
 
 +
; <code>dmg.bullets</code> <float> : Modifies damage done by bullets.
 +
:* Paper, Cloth and Glass = 0.5
 +
:* Wood = 0.75
 +
:* Flesh = 1.25.
 +
; <code>dmg.club</code> <float> : Modifies damage done by blunt impacts.
 +
:* Cloth = 0.75
 +
:* Paper and Pottery = 1.25
 +
:* Wood = 2.0
 +
; <code>dmg.explosive</code> <float> : Modifies damage done by explosions.
 +
:* Paper, Cloth, Pottery, Flesh and Wood = 1.5
 +
; <code>damage_table</code> <choices>
 +
: [[Impact Damage Table]]s are defined in C++ code (in physics_impact_damage.cpp), and contain very detailed information about what damage a prop should take from different directions and forces. Only Glass and Pottery base_types inherit one. {{tip|Use <code> damage_table "" </code> to ignore an inherited table.}}
 +
:; <code>glass</code>
 +
:: Extremely fragile, will break just by being dropped.
 +
:; <code>player</code>
 +
:: {{todo}}
 +
:; <code>player_vehicle</code>
 +
:: {{todo}}
 +
:; <code>npc</code>
 +
:: {{todo}}
 +
 
 +
=== Flammable props ===
 +
 
 +
See [[Prop interactions#Fire interactions|fire_interactions]]
 +
 
 +
=== Exploding props ===
 +
 
 +
''If these two fields are specified for a prop, and it is given health so that it can be damaged, then it will explode when it breaks.''
 +
 
 +
; <code>explosive_damage <float></code>
 +
: The amount of explosive damage.
 +
; <code>explosive_radius <float></code>
 +
: The radius of the explosion. Damage falls off as distance from the origin increases.
 +
 
 +
''See the "explode_fire" [[Prop interactions|prop interaction]] for explosions that only ignite entities''
 +
 
 +
=== Interactions ===
 +
 
 +
Prop interactions are technically part of prop_data and can be used in base types and even within prop_data's $keyvalues section, but they are usually used separately and can be embedded in a model as independent blocks without the direct use of prop_data at all. They are used to serve specific functions like sticking to a wall when launched by the gravity gun or igniting when at half-health.
 +
 
 +
Read more about them [[Prop interactions|here]].
 +
 
 +
=== Gibs ===
 +
 
 +
''The prop_data system handles generic [[Wikipedia:Gibs|gibs]]. Generic gibs are used for any breakable object that doesn't have [[Creating Custom Breakable Gibs|custom gibs]].''
 +
 
 +
; <code>breakable_model <choices></code>
 +
: Defines the set of generic gibs (as defined in <code>scripts\propdata.txt</code>) this prop should break into. Props with a wooden base type gib in this manner already. See also [[Creating Custom Breakable Gibs|creating custom gibs]].
 +
:* <code>WoodChunks</code>
 +
:* <code>GlassChunks</code>
 +
:* <code>ConcreteChunks</code>
 +
:* <code>MetalChunks</code>
 +
; <code>breakable_count <int></code>
 +
: The number of generic breakable gibs to break into. If this is not specified, the engine will generate a sensible number based on the gibs' and model's sizes.  
 +
; <code>breakable_skin <int></code>
 +
: Allows you to specify a skin to use on the gib models, which is useful for matching the original prop's skin.
 +
: Only props with Wooden base_types inherit a gib skin (skin 0).
 +
; <code>multiplayer_break <choices></code>
 +
: {{confirm|Determines where the gibs from a [[prop_physics_multiplayer]] are simulated.}}
 +
:* <code>both</code>
 +
:* <code>server</code>
 +
:* <code>client</code> (default)
 +
 
 +
* {{todo|Confirm whether breakable_count, breakable_skin and multiplayer_break do not affect custom gibs.}}
 +
* {{todo|Confirm whether multiplayer_break is set for the breakable model rather than each individual gib itself.}}
 +
 
 +
== Creating new base types ==
 +
 
 +
All base types are defined in <code>scripts\propdata.txt</code>. If you edit a base type in this file, you will affect the behaviour of all models using it (that do not have their own overrides).
 +
 
 +
The format of the file is:
 +
 
 +
<source lang=cpp>
 +
PropData.txt
 +
{
 +
<base type name>
 +
{
 +
<any number of the prop_data KVs listed above>
 +
}
 +
}
 +
</source>
 +
 
 +
Valve generally only use their base types to set health and damage modifiers.
 +
 
 +
=== Creating generic gibs ===
 +
 
 +
Generic gibsets are also defined in propdata.txt. Valve have only four, and only one (<code>WoodChunks</code>) is assigned to a base type - most models instead specify theirs directly, with <code>breakable_model</code>.
 +
 
 +
Defining a new gibset is easy as most of the work is done by the engine:
 +
 
 +
<source lang=cpp>
 +
PropData.txt
 +
{
 +
BreakableModels
 +
{
 +
WoodChunks
 +
{
 +
// 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
 +
}
 +
}
 +
}
 +
</source>
 +
 
 +
== Prototyping models ==
  
'''When building props''', you can help your game / mod to be consistent by following these tips:
+
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 <code>$keyvalues</code> .[[qc|QC]] section). It will also allow the level designer to set its "health".
* 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.
 
  
==Prototyping==
+
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 [[Hammer Entity Report Dialog|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).
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 [[func_physbox]] for brush-based physics objects.
  
==See Also==
+
== See also ==
  
* [[prop_static]], [[prop_dynamic]], [[prop_physics]]
+
* [[prop_data base types]]
* [[Overview of Prop Types - Description of the various model prop entities.|Overview of Prop Types]]
+
* [[prop_static]], [[prop_dynamic]], [[prop_physics]] - common prop entities.
 +
* [[Prop Types Overview]] - an article describing various prop types.
 +
* [[Prop interactions]] - a group of QC $keyvalues blocks that handles some interactions with outside forces and defines other properties
  
[[Category:Entities]]
+
[[Category:Modeling]]
 +
[[Category:QC Keyvalues]]

Latest revision as of 22:23, 22 February 2018

Русский 日本語

prop_data can be used to make a model:

It is a KeyValues block embedded with the QC command $keyvalues.

Note:The properties of a model's surface are defined by $surfaceprop.
Note:Models for use with prop_physics will also need $staticprop.

Example

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

Here we derive prop_data from the generic base_type "Wooden.Small". Then we use additional keyvalues to give the model three special characteristics: it will be bulletproof, but when it breaks it will explode and cause 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, let the base types 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.
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 put water in a physical fish tank.

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

Additionally, Valve consider metal and plastic invulnerable but everything else breakable.

Options

Base type

base <string>
Gives the model a predefined prop_data type, providing in one motion all the data the engine needs to make the model both physical and breakable. Most other commands in a prop_data block are overrides of values inherited from here.

General

health <int>
The amount of damage this prop should take before breaking. 0 means don't break.
allowstatic <bool>
Allows the model to be used with prop_static. To enforce consistency, avoid if possible.
physicsmode <choices>
Sets the physics mode used by prop_physics_multiplayer. Can be overridden by the entity in the Orange Box.
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.
blockLOS <bool>
Overrides whether the prop should block NPC line of sight. If unspecified, the game engine will decide based on the model's dimensions.
AIWalkable <bool>
Should NPCs try walking over this prop? To do: Does 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.
  • Paper, Cloth and Glass = 0.5
  • Wood = 0.75
  • Flesh = 1.25.
dmg.club <float> 
Modifies damage done by blunt impacts.
  • Cloth = 0.75
  • Paper and Pottery = 1.25
  • Wood = 2.0
dmg.explosive <float> 
Modifies damage done by explosions.
  • Paper, Cloth, Pottery, Flesh and Wood = 1.5
damage_table <choices>
Impact Damage Tables are defined in C++ code (in physics_impact_damage.cpp), and contain very detailed information about what damage a prop should take from different directions and forces. Only Glass and Pottery base_types inherit one.
Tip:Use damage_table "" to ignore an inherited table.
glass
Extremely fragile, will break just by being dropped.
player
To do
player_vehicle
To do
npc
To do

Flammable props

See fire_interactions

Exploding props

If these two fields are specified for a prop, and it is given health so that it can be damaged, then it will explode when it breaks.

explosive_damage <float>
The amount of explosive damage.
explosive_radius <float>
The radius of the explosion. Damage falls off as distance from the origin increases.

See the "explode_fire" prop interaction for explosions that only ignite entities

Interactions

Prop interactions are technically part of prop_data and can be used in base types and even within prop_data's $keyvalues section, but they are usually used separately and can be embedded in a model as independent blocks without the direct use of prop_data at all. They are used to serve specific functions like sticking to a wall when launched by the gravity gun or igniting when at half-health.

Read more about them here.

Gibs

The prop_data system handles generic gibs. Generic gibs are used for any breakable object that doesn't have custom gibs.

breakable_model <choices>
Defines the set of generic gibs (as defined in scripts\propdata.txt) this prop should break into. Props with a wooden base type gib in this manner already. See also creating custom gibs.
  • WoodChunks
  • GlassChunks
  • ConcreteChunks
  • MetalChunks
breakable_count <int>
The number of generic breakable gibs to break into. If this is not specified, the engine will generate a sensible number based on the gibs' and model's sizes.
breakable_skin <int>
Allows you to specify a skin to use on the gib models, which is useful for matching the original prop's skin.
Only props with Wooden base_types inherit a gib skin (skin 0).
multiplayer_break <choices>
Confirm:Determines where the gibs from a prop_physics_multiplayer are simulated.
  • both
  • server
  • client (default)
  • To do: Confirm whether breakable_count, breakable_skin and multiplayer_break do not affect custom gibs.
  • To do: Confirm whether multiplayer_break is set for the breakable model rather than each individual gib itself.

Creating new base types

All base types are defined in scripts\propdata.txt. If you edit a base type in this file, you will affect the behaviour of all models using it (that do not have their own overrides).

The format of the file is:

PropData.txt
{
	<base type name>
	{
		<any number of the prop_data KVs listed above>
	}
}

Valve generally only use their base types to set health and damage modifiers.

Creating generic gibs

Generic gibsets are also defined in propdata.txt. Valve have only four, and only one (WoodChunks) is assigned to a base type - most models instead specify theirs directly, with breakable_model.

Defining a new gibset is easy as most of the work is done by the engine:

PropData.txt
{
	BreakableModels
	{
		WoodChunks
		{
			// 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 func_physbox for brush-based physics objects.

See also