Moderator elections are being held. See Valve Developer Community:Moderator elections for more details.
Users who would like to run for moderator must be autoconfirmed and have at least 100 edits. Users can check their own edit count at Special:Preferences.
This article's documentation is for anything that uses the Source engine. Click here for more information.

prop_static

From Valve Developer Community
Jump to: navigation, search
Not to be confused with the $staticprop and allowstatic (prop_data) QC commands.

prop_static is a internal point entity available in all Source Source games.

English (en)Русский (ru)中文 (zh)
Edit

It is used to cheaply add a model to the world. It cannot move, animate, or accept input (with the limited exception of $treesway). In fact, it doesn't exist as an entity after the map has been compiled. The vast majority of models in a typical map are prop_static entities.

A prop_static will collide with other objects assuming it has a collision mesh, and, unlike all other model entities, can be lit per-vertex and cast shadows onto lightmaps.

AltNames.pngAltNames: This entity is also tied to static_prop.

Bugs and Limitations

Demonstration of static prop lighting with and without $bumpmap in Source 2013 Source 2013, on a vanilla jeep model from Day of Defeat: Source Day of Defeat: Source. Note the differences in lighting accuracy on the jeep which is partially underneath the bridge.
Icon-Important.pngImportant:Models using bump maps or $phong cannot be lit per-vertex, except in the CS:GO engine branch CS:GO engine branch and Strata Source Strata Source, and will be lit based upon the model's origin instead!
Tip.pngTip:(in all games since Source 2007) As lighting is done per-vertex, higher-poly models will be lit more accurately than low-poly models. Use LoD models to simplify lighting (and GPU load) as the camera gets further from props.
Note.pngNote:In Source 2013 Multiplayer Source 2013 Multiplayer and Garry's Mod Garry's Mod, static props can use lightmaps using the static prop's UVs. They come with the same limitations as per-vertex lit props, and cannot be used on models with bump maps.
Warning.pngWarning:
Addtional caveats
Warning.pngWarning:Models use the same UVs for lightmaps as $basetexture, and the model's lightmap is affected by $basetexturetransform; as such, lightmapping on models with overlapping or tiling UVs may not appear as intended!
VRAD cannot create lightmaps for UVs outside of the 0-1 UV space.
Additionally, shadows may appear on UV seams; this is more noticeable on lower-resolution lightmaps.
Icon-Bug.pngBug:Lightmaps for models with multiple materials do not compile properly in VRAD! A lightmap will only be compiled for the first material on the model, that is a combined version of all the UV's used by all materials.
PlacementTip.pngWorkaround: Define a pre-baked $lightmap in the VMT of the VertexLitGeneric material (can be obtained using -dumppropmaps in VRAD).
Warning.pngWarning:Model lightmaps generated with VRAD are compiled as RGB888 (24-bit SDR) PPL files which can result in noticeable color banding when brightly lit in HDR mode.
PlacementTip.pngWorkaround:
  • Define a pre-baked RGBA16161616f $lightmap in the VMT of the VertexLitGeneric material. A custom-coded compiler would be required to this accurately.
  • Increase lightmap resolution (results may vary).
  • Move light source further away from the lit surface.
Warning.pngWarning:Models using $bumpmap cannot receive lightmaps, they will fall back to vertex-lighting based upon the models' origin.
Note.pngNote:There is an in-engine check that confirms whether or not the $bumpmap parameter is defined for a material, a custom shader cannot simply use both as there are a dozen technicalities that have to be overcome.
Technical

If $bumpmap, $normalmap, or $phong is defined, the engine will not send the lightmap data to the shader.
For $bumpmap, a workaround for this is to use a differently named parameter. ($NormalTexture) to get the normal map and undefining $bumpmap.
However no static lighting data can be received by the shader, if the $bumpmap parameter is not set to anything. This refers to lights that are not named and are not inherently dynamic.
This may be prefered as the static light information is already prebaked in the lightmap, however it means you cannot receive direction information from the lights.
No light direction means no bumped lighting from the lightmap. Aka no specular highlights.
A fix for this would be modifying VRAD to spit out a lightmap that is *2 the size on the U axis and then storing an average light direction there or doing some other smart technique to 'memorize' light directions.

This in-engine check also exists for $phong, however getting around the issue is more tricky. The default value of the integer parameter will be 0 even if not set in the vmt. Thus making $phong always be defined in a way.

Warning.pngWarning:VBSP enforces a soft limit on how many entities, including prop_statics, can be compiled into a map. If the limit is reached, VBSP will fail to compile the map. The default limits are as such:
  • Source 2007Source 2013Left 4 Dead engine branch 8192 MAX_MAP_ENTITIES
  • Alien Swarm engine branchPortal 2 engine branch 16384 MAX_MAP_ENTITIES
  • CS:GO engine branch 20480 MAX_MAP_ENTITIES
  • Mapbase 65536 MAX_MAP_ENTITIES (supports all Source 2013 Singleplayer games)

In practice, the maximum number of prop_statics will be less than this, due to the limit being shared between all entities in the map.

Tip.pngTip:This is a soft limit, and can be circumvented with a modified VBSP by editing 🖿public/bspfile.h. A BSP file can theoretically contain over 4 billion static props.
Icon-Bug.pngBug:prop_static does not support selectable $bodygroup submodels (although it does support selectable $texturegroup skins); only the first one will be used. Despite this, VRAD will generate lightmap shadows from all submodels present in the MDL! (tested in Day of Defeat: Source)
PlacementTip.pngWorkaround: Do one of the following:
  • Compile a separate model for each desired variation (doesn't use up an edict, better lighting)
  • Use prop_dynamic (easier, less file duplication)

Consistency

In order to enforce consistency of behavior, models with embedded physics data cannot be prop_static. Use the Hammer Model Browser's info tab to check for support.

PlacementTip.pngWorkaround: This is not an engine limitation, but rather an arbitrary restriction imposed by the compile tools, and can be bypassed with a modified VBSP; see below.

Keyvalues

Collisions (solid) <choices>
How the prop should interact with other objects.
  • 0 - Not solid
  • 2 - Use bounding box
  • 6 - Use VPhysics (default)
    Note.pngNote:Using this setting on models without a collision mesh will cause the engine to throw a warning upon loading the map. If you see such a warning, reset the collision of all props using the noted model to one of the other two choices.
Screen Space Fade (screenspacefade) <boolean>
If enabled, the prop will fade out based on how many screen pixels it covers. The start and end fade distances come to represent the pixels that the prop covers at the start and end of its fade when this is enabled.
Lighting Origin (lightingorigin) <targetname>
An info_lighting from which to sample lighting (instead of the model's origin). Disables per-vertex lighting.
Disable Vertex lighting (disablevertexlighting) <boolean>
Prop will be vertex lit more similarly to dynamic props, being lit based upon its origin instead of per-vertex. Set this to "Yes" to significantly reduce VRAD compile times if the prop does not benefit from complex lighting.
Warning.pngRisk of Confusion:This doesn't actually disable vertex lighting, but rather uses a simpler form of it that calculates vertex colors based upon the color, brightness, and direction of the origin (or $illumposition) at runtime instead of prebaking the them per-vertex into a VHV file (which is packed into the compiled BSP).
Icon-Important.pngImportant:Enabling this overrides generatelightmaps!
Icon-Bug.pngBug:Cascade shadows from Black Mesa Black Mesa doesn't work properly with prop_static if vertex lighting is enabled. Use this property if cascade lighting hits a static prop.
Bug example.


Disable Self-Shadowing with vertex lighting (disableselfshadowing) <boolean>
When vertex lighting is enabled, prevent the geometry from self-shadowing (casting shadows onto itself).
Ignore surface normal for computing vertex lighting (ignorenormals) <boolean>
When vertex lighting is enabled, ignore the surface normal of faces when calculating the vertex lighting, resulting in more uniform shading.
Tip.pngTip:Useful for thin, translucent objects such as leaves on foliage props.
Alpha (renderamt) <integer> (in all games since Left 4 Dead)
Alpha of the fade, where 0 is fully transparent and 255 is fully opaque.
Render Color (R G B) (rendercolor) <color255> (in all games since Left 4 Dead)
Tint the model with this color.
Generate (and use) lightmaps for this static prop (generatelightmaps) <boolean> (only in Source 2013 Multiplayer) (also in Garry's Mod)
Generate a lightmap for this prop. Requires -StaticPropLighting to be enabled in VRAD. For more information, visit tf2maps.net.
Note.pngNote:Lightmapping can be also faked on static props using the Modulate shader in all games, although syncing the lighting can be difficult.
Icon-Bug.pngBug:Counter-Strike: Source This setting doesn't work on models with multiple skins.
Warning.pngWarning:Several caveats and limitations; see note and warnings above.
Note.pngNote:(not in Black Mesa) While this KV does exist in Black Mesa's FGD, it is unused; Xengine does not support lightmapped props.
Lightmap Resolution X (lightmapresolutionx) <integer> (only in Source 2013 Multiplayer) (also in Garry's Mod)
The resolution of the generated lightmap in the X (or U) direction. (Only used if Generate Lightmaps is Yes.)
Lightmap Resolution Y (lightmapresolutiony) <integer> (only in Source 2013 Multiplayer) (also in Garry's Mod)
The resolution of the generated lightmap in the Y (or V) direction. (Only used if Generate Lightmaps is Yes.)
Enable Bounced Lighting (enablelightbounce) <boolean> (in all games since CS:GO engine branch)
Whether VRAD should create indirect lighting from this prop.
Disable Prop Combine (preventpropcombine) <boolean> (in all games since CS:GO engine branch)
Prevent this static prop from combining with any other static props in vbsp.
Uniform Scaling (uniformscale) <float> (in all games since CS:GO engine branch)
Evenly scales a given model along the X Y Z axis.
Icon-Bug.pngBug:In Hammer, undoing/redoing any changes (whether they are slight unit movements or scale changes) will result in the prop appearing "normal" sized in the 3D Textured Viewport (the model only appears normal sized and the value given is still shown upon reload of the VMF).
Blank image.pngTodo: add scaling kvs from p2ce
Name (targetname) <targetname> (only in The Ship: Murder PartyTeamSpen's Hammer Addons)
The name that ship_base_interactionThe Ship: Murder Party/postcompileTeamSpen's Hammer Addons entities refer to this entity by[How?]. Also useful regardless of game for being able to recognize specific prop_static entities in Entity Report. The name will not be in the compiled BSP.

Studiomodel:
World Model (model) <string>
The model this entity should appear as. 128-character limit.
Skin (skin) <integer>
Some models have multiple skins. This value selects from the index, starting with 0.
Tip.pngTip:Hammer's model browser automatically updates this value if you use it to view different skins.
Icon-Bug.pngBug:Static props with multiple skins will always use the alpha channel(s) from the default skin's texture(s), even though the alternative skins' alpha textures are loaded by VRAD. (tested in Day of Defeat: Source).

}}

Uniform Scale Override (uniformscale) <float> (in all games since Counter-Strike: Global Offensive)
A multiplier for the size of the static prop model.

Shadow:

Disable Shadows (disableshadows) <boolean>
Prevents the entity from creating cheap render-to-texture shadows, or lightmap shadows if the entity is a prop_static. Does not affect shadow mapping.
Disable Receiving Shadows (disablereceiveshadows) <boolean>
Prevent the entity from receiving dynamic shadows on itself.
Shadow Cast Distance (shadowcastdist) <integer> !FGD
Sets how far the entity casts dynamic shadows. 0 means default distance from the shadow_control entity.
Disable ShadowDepth (disableshadowdepth) <boolean> (in all games since Portal 2)
Used to disable rendering into shadow depth (for projected textures) for this entity.
Disable flashlight (disableflashlight) <boolean> (in all games since Portal 2)
Used to disable projected texture lighting and shadows on this entity.
Projected Texture Cache (shadowdepthnocache) <choices> (in all games since Portal 2)
Used to hint projected texture system whether it is sufficient to cache shadow volume of this entity or to force render it every frame instead.
Choices
  • 0 : Default
  • 1 : No cache - render every frame
  • 2 : Cache it - render only once

Reflection:
Render in Fast Reflections (drawinfastreflection) <boolean> (in all games since Portal 2)
If enabled, this entity will render in fast water reflections (i.e. when a water material specifies $reflectonlymarkedentities) and in the world impostor pass.

}} BaseFadeProp:

Start Fade Dist (fademindist) <float>
Distance at which the entity starts to fade.
End Fade Dist (fademaxdist) <float>
Max fade distance at which the entity is visible.
  • If start fade is <0, the entity will disappear instantly when end fade is hit.
  • If end fade is <0, the entity won't disappear at all. (This is the default behavior.)
The values will scale appropriately if the entity is in a 3D Skybox.
Fade Scale (fadescale) <float>
If you specify so in worldspawn, or if the engine is running below DirectX 8 (DX7 in Source 2006), props will fade out even if the fade distances above aren't specified. This value gives you some control over when this happens: numbers smaller than 1 cause the prop to fade out at further distances, while those greater than 1 cause it to fade out at closer distances. Using 0 turns off the forced fade altogether. See also the QC command $noforcedfade.

DXLevelChoice:

Minimum / Maximum DX Level (mindxlevel / maxdxlevel) <choices> (removed since Left 4 Dead)
The entity will not exist if the engine is running outside the given range of DirectX Versions.
Choices
Warning.pngWarning:If these are used, the object may break when the user switches their DirectX settings.
Tip.pngTip:Set maxdxlevel to 60 (along with disablevertexlighting set to 1) to create a prop that can cast shadows, but doesn't appear in-game. This is cheaper than using blocklight brushes, as it does not count towards brush and brushside limits.
Confirm.pngConfirm: Setting a fake non-zero dxlevel, such as 50, might work as well.

SystemLevelChoice:

Minimum / Maximum Effect Details Level (mincpulevel / maxcpulevel) <choices> (in all games since Left 4 Dead)
Don't render for players with Effect Details levels that exceed the minimum or maximum.[Note.pngKey names are related to cpu_level cvar used by Effect Details.]
Choices
  • 0: Default ("Low" formincpulevel, "High" formaxcpulevel)
  • 1: Low
  • 2: Medium
  • 3: High
Minimum / Maximum Shader Details Level (mingpulevel / maxgpulevel) <choices> (in all games since Left 4 Dead)
Don't render for players with Shader Details levels that exceed the minimum or maximum.[Note.pngKey names are related to gpu_level cvar used by Shader Details.]
Choices
  • 0: Default ("Low" formingpulevel, "Very High" formaxgpulevel)
  • 1: Low
  • 2: Medium
  • 3: High
  • 4: Very High

Angles:

Pitch Yaw Roll (Y Z X) (angles) <angle>
This entity's orientation in the world. Pitch is rotation around the Y axis, yaw is the rotation around the Z axis, roll is the rotation around the X axis.

Common Mistakes

VBSP deletes model

Error! prop_static using model "[model]", which must be used on a dynamic entity (i.e. prop_physics). Deleted.

The prop is not currently compatible to be used as prop_static. Note that this does not necessarily mean the model cannot be used with prop_static.

If the model does not have "static" flag in the model viewer (as in, was not compiled with $staticprop):

If the model is your custom model:

$KeyValues
{
	prop_data 
	{
		"base" "Metal.Medium"
		"allowstatic" "1"
	}
}

If it is not your custom model, but has the "static" flag in the model viewer (was compiled with $staticprop:

Model is off-center

If for some reason your model located incorrectly, check declared bone name in $definebone of a model; it should be without any slashes. Also check position there, values should be zeroed.

See also