XBLAH's Modding Tool | details.vbsp

details.vbsp

Home |Wiki
Source Source

The purpose of details.vbsp is to describe the detail props to the vbsp compiler. It's a text file that can be opened and manually edited on any text editor, or can be edited using XBLAH's Modding Tool XBLAH's Modding Tool using an intuitive interface, that provides all the available fields for edition.

Detail props are cheap, non-solid objects that randomly emit from materials used by brushes and displacements. They fade out at a distance (by default 1200 units), so are only good for small, surface-hugging features like grass and shrubs.

Contents

File structure

The details.vbsp use a keyvalue structure, with detail as the root key, detail types as children, detail groups as grandchildren, and detail models as great-grandchildren.

details.vbsp
keyvalue
// Root detail { detail_type_name { // ... detail_group_name { // ... detail_model_name { // ... } } } }

Detail type

A single file can contain multiple detail types. The key of the code block is the detail type name. This string will be used in the vmt to define which detail type will be used in the material.

 Example: %detailtype "grass01"
density <int>
A parameter used in the equation amount * density * surface_area * 1e-6 to define the number of detail models per unit square.
 Example: A density of 1.000.000 will produce one detail model per square unit.

Detail group

A detail type can have multiple detail groups. It should have at least one.

Note:The key of the code block isn't used anywhere, so it can be anything.
alpha <float>
A value between 0.0 and 0.1 that defines the opacity of the whole group.
 Example: alpha "0.0" - invisible; alpha "1.0" - fully visible

Detail model

A detail group can have multiple detail models. It should have at least one.

Note:The key of the code block isn't used anywhere, so it can be anything.
amount <float>
The proportion of the group that this model will account for. The parameter is used in the equation amount * density * surface_area * 1e-6.
 Example: If the amount values of a group add up to less than 1, fewer detail props will be emitted than specified by density.
upright <bool>
If true, the model will be vertically aligned with the world. If false, it will be vertically aligned with the surface's normal.
minangle <int>
Define the minimum angle the model can be relative to the world's Z axis, if upright is false. 0 means the surface is horizontal, 90 means the surface is vertical. It can range between 0 and 180.
maxangle <int>
Define the maximum angle the model can be relative to the world's Z axis, if upright is false. 0 means the surface is horizontal, 90 means the surface is vertical. It can range between 0 and 180.

Sprites

sprite <string>
UV maps the sprite in the sprite sheet. The string has the format sprite_x sprite_y sprite_width sprite_height sheet_width.
 Example: sprite "498 386 126 112 1024" - the sprite is located at 498,386px in the sprite sheet, its size is 126x112px and the sheet width is 1024px.
spritesize <string>
Defines the origin and size of the sprite when it appears in the world. The string format is U V W H, where U and V represent the origin coordinates, and W and H represent the width and height of the sprite in world units.
 Example: spritesize "0 0 32 32" - the sprite starts at the origin (0, 0) and has a size of 32x32 world units.
spriterandomscale <float>
Specifies how much the sprite's size can randomly vary, ranging from 0.0 to 1.0.
 Example: spriterandomscale "0.0" - the sprite has a fixed size; spriterandomscale "0.5" - the sprite size will vary +-50%.
detailorientation <int>
Determines how the sprite will react to the camera's perspective. The values are:
  • 0 - The sprite will not rotate.
  • 1 - The sprite will always face the camera head-on.
  • 2 - The sprite will rotate around its Z-axis only to face the camera.
    • spriteshape <string>
    Defines the shape of the sprite group, allowing for a pseudo-3D effect. The options include:
  • tri - Three sprites arranged in a triangle formation.
  • cross - Two sprites that cross over each other in the middle.
    • sway <float>
    Determines the percentage of cl_detail_max_sway that the sprite will sway or bend, simulating a breeze.
    shape_angle <float>
    This keyvalue is applicable when using the tri sprite shape. It specifies the angle in degrees at which the individual sprites are spread outward from the center. The value typically ranges between 0 and 45 degrees.
    shape_size <float>
    This keyvalue also applies to the tri sprite shape. It defines the distance between the center of the triangle and the sprites, as a percentage of the sprites' width. A value of 0 means the sprites will cross at the center.

    Props

    model <string>
    Specifies the model file to use for the prop. The model must be $staticprop and use the UnlitGeneric shader for all skins. Include the full path, such as models\props\example.mdl.
    Warning:Models should be used sparingly due to their performance overhead. Overusing models can cause crashes during cubemap building, especially in games based on SDK 2013.

    Example

    A simple details.vbsp for a Half-Life 2 Half-Life 2 mod.

    details.vbsp
    keyvalue
    // Made with XBLAH's Modding tool. // Download it at https://xblah.dev/modding-tool/ detail { my_grass01 { density "1500" group1 { alpha "0.7" model1 { sprite "498 386 126 112 1024" spritesize "0 0 24 24" spriterandomscale "0.2" detailorientation "2" amount "5" } model2 { model "models/props_junk/rock001a.mdl" amount "1" } model3 { sprite "928 380 92 132 1024" spritesize "0 0 24 24" spriterandomscale "0.2" detailorientation "2" amount "1" } } } }

    References

  • https://developer.valvesoftware.com/wiki/Detail_props