vbsp_config barriers

Barrier definitions allow creating custom glass or grating items, as well as holes cut into them. The BEE compiler generates appropriate frames. Several different blocks can be defined.

Unfortunately, only the standard barrier item ID is allowed to have other items (like cubes or turrets) placed on it. For this reason, custom barriers are instead made by placine an invisible item, then connecting it with antlines to a regular glass or grating item to transform it. The same works with custom shape items.

Frames and barrier types are defined directly in vbsp_config.cfg, while barrier holes are package objects and so are defined in info.txt.

`BarrierFrames`:

Barrier frames define how to construct the frames around a barrier. This allows the same definition to be used to surround multiple different barrier types. Each ID must therefore be unique. The definition has two forms, one allowing definining different frames for the vertical/horizontal parts of a upright frame, and one which has all orientations the same:

"BarrierFrames"
  {
  "FRAME_ID"
    {
    "cornersize" "8"
    "straight" // "Prop" segment
      {
      "length" "8"
      "offset" "0 0 0"
      "angles" "0 90 0"
      "model" "models/props_special/my_frame_straight.mdl"
      }
    "corner" // "Brush" segment
      {
      "offset" "0 0 0"
      "angles" "0 0 0"
      "template" "BARRIER_FANCY_FRAME:corner"
      }
    "concavecorner"
      {
      "model" "models/props_special/my_frame_corner.mdl"
      }
    }
  "MULTIFRAME_ID"
    {
    "vert"
      {
      ...
      }
    "horiz"
      {
      ...
      }
    "flat"
      {
      ...
      }
    }
  }

For the different-frame form, vert,horiz and flat wrap each variation of settings. Each straight, corner and concavecorner section defines a possible "segment" that can be used to piece together the barrier. Segments can either produce a prop or a brush. If multiple are defined, these are all placed overlapping each other.

A special case is prop-style straight sections. Each definition needs to specify a length. The compiler determines the most efficient combination of provided lengths, then places them as necessary. It is recommended to ensure you provide at least a 32,32-corner and 32-2*corner section, to make sure any barrier size can be constructed. More sizes allow the compiler to more efficiently cover larger distances.

Frames have only one global option:

CornerSize defines the distance inward that corners take up, where straight sections do not need to appear.

Segments have the following options:

length: If a prop-type straight section, the length of the section.
angles: Defines a rotation to apply to the segment.
offset: Offsets the segment from the desired position.
model: Specifies the model, for prop-type segments.
template: Specifies the template ID, for brush-type segments.

Barriers

Each barrier definition defines a set of brushes, and the frame to use. Two special names exist, VALVE_GLASS and VALVE_GRATING, applied to the default item. Any custom ones require the use of a CustomBarrier condition result, or a bee2_template_barriersetter in a template.

"Barriers"
  {
  "BARRIER_ID"
    {
    "Frame" "FANCY_FRAME"
    "error_tex" "glass"
    "coll_thick" "4"
    "mergeable" "1"
    "frame_world_brush" "0"
    
    "HoleVariant" "PREFERRED_FRAME"
	"HoleVariant" "FALLBACK_FRAME"

    "Brush"
      {
      "offset" "2"
      "thickness" "4"
      "tooltexture" "0"
      "world" "0"
      "carve_by_hole" "1"
      "material" "effects/fizzler_center"
      "side_mat" "tools/toolsinvisible"

      "keys"
        {
        "classname" "trigger_portal_cleanser"
        "spawnflags" "0"
        }
      }
    "Collide"
      {
      "offset" "1"
      "thickness" "6"
      "contents" "SOLID"
      }

    "FloorBeam"
      {
      "template" "BEE2_P1_GLASS_BEAM"
      "min" "32"
      "max" "128"
      "step" "8"
      "border_width" "4"
      }
    }
  }

General options:

Frame links the frame to use. If multiple are specified, each are independently added.
Error_Tex defines the appearance of the barrier in the error display shown after a compile failure. To ensure the reliability of that display, currently custom textures are not possible, so the only valid values are glass, grating, white or black. Error data is taken before conditions execute, so custom items won't appear anyway.
Mergeable determines if adjacent items of the same type can merge together, or if each must be kept separate. This should be disabled if the barrier takes inputs or otherwise has logic. If merged, exactly which parts get names from which underlying item is random and uncontrollable.
HoleVariant may be defined multiple times, and specifies the hole variant IDs to use in order of preference. When a hole is placed on a barrier, it will use the first variant that is defined, or abort compilation if none are found. It is recommended to specify several fallbacks so that holes still work even if it doesn't quite match. For example P1, Overgrown and Clean barriers all specify each other's frames, since those will look reasonably correct.
Frame_World_Brush forces the frames to use world brushes instead of func_detail. This is a hack to prevent Tinted Glass's surface from carving into frames - if a better solution is found this will probably be deprecated and removed.

Brushes

Each Brush block defines a brush which is placed to fill the barrier interior.

offset: The distance to the brush from the outside of the voxel.
thickness: The thickness of the brush.
carve_by_hole: Determines if the brush should be cut into by hole items, or be left continous. Hint brushes for example do not need to be split. This defaults to being enabled.
material defines the material to use on the front and back of the brush.
side_mat specifies the material to use on brush sides. This defaults to nodraw.
tooltexture is a convenience setting - if set, the side material is the front/back material.
template, if specified is an optional scaling template to orient the surface of the brush.
world, if set makes the brush a world brush. This is mutually exclusive with setting keyvalues.
keys is a block of entity keyvalues to apply.
static_player_clip enables some special behaviour for player clips. In Portal 2, to get a player clip with appropriate surfaceprop for footsteps it must be a func_brush. But this is irrelevant on walls. Enabling this option will switch the brush to instead be func_detail and the standard tools/toolsplayerclip material in that case. In addition, on floors a thinner func_detail brush is also placed, to ensure players are blocked from entering a portal placed behind the barrier.

Collide

Each Collide block provides parameters to define collision data for the barrier. This allows BEE to know exactly where the barrier is, and what sorts of things it collides with.

For example, the Sendificator uses this to know whether a surface is glass, or just an opaque thin wall. In Portal 1 style, the collision needs to precisely match the frame shape, since it is used to start/stop the floorbeam brushes.

offset: the distance to the collision from the outside of the voxel.
thickness: the thickness of the collision.
carve_by_hole: Determines whether the collision should be cut into by hole items, or be left continous.
contents: Specifies vbsp_config#collision-types to apply to the collision.

FloorBeams

This is a specialised block of configuration, used to add additional support beams in Portal 1 styled floors. These use hole collision volumes to split the beam across any that are in the way.

min, max: Defines the min/maximum distance allowed between the center of two beams. 10 different positions are tried, before skipping further ahead - beams may not be possible if overlapping the edge of the barrier or holes.
step: The increments at which distances can be picked within the min/max range.
border_width: This defines the width of the frame itself, specifying how far inward to start/stop the beams.
template: The ID of a template containing a single brush for the beam geometry. This needs to be very specifically positioned, with skip brushes on the front/back ends.

Barrier Holes

Barrier holes define an item which cuts into barriers. To allow them to match the rest of the frame, holes may define multiple variants, depending which would match the frame used. If no variant is defined for a frame, the hole cannot be placed on it. To allow defining these in multiple packages, Barrier holes are defined as package objects in info.txt.

Note that the behaviour of large holes are somewhat hardcoded, since it has a complex placement scheme to allow it to overlap in some cases.

The variant IDs defined for the builtin hole are currently as follows:

THIN_MODERN_PETI: The thin grey frame added especially for puzzlemaker.
THIN_MODERN_TESTCHAMBER: The standard hole composed of dirty brown frame used in most of the Portal 2 campaign.
THIN_MODERN_P1_PLASTICWALL: Brush holes composed of plasticwall004, like in Portal 1. These are square/octagonal, not circular.
THIN_SQUARE_OLDAP: Rusty squarebeam frames to fit Old Aperture. These are also square/octagonal.
THICK_SQUARE_OLDAP: Thicker (depthwise) squarebeam frames, used for Tinted Glass. Of course any ID can be defined, and will only be used if a barrier specifies it.

// info.txt:
"BarrierHole"
  {
  "ID" "SOME_HOLE"
  "footprint" "SOME_HOLE_FOOTPRINT"
  "error_shape" "small"

  "variants" "path_to_variants.cfg"
  }

// Variants config:
"FRAME_ID"
  {
  "Instance" "instances/clean/items/some_hole/frame.vmf"
  "Template" "SOME_HOLE:norm_frame"
  }
"ANOTHER_ID"
  {
  "Instance" "instances/clean/items/some_hole/another.vmf"
  "Template" "SOME_HOLE:another_frame"
  }

footprint: This defines which 1/4-voxel sections the hole occupies, and so must be replaced by custom brushes. Other barriers cannot overlap these subvoxels.
- The definition is done by using a template, with bee_temp_tilesetters placed at the appopriate positions.
- The settings of the tile setters and anything else in the template are ignored. This is done to make it easier to visualise/specify the pattern.
- Currently, only the large hole is allowed to have a footprint extending out of its voxel.
error_shape: If a barrier hole is not placed correctly, this defines the shape used in the error visual. Currently it is not possible to provide custom models here, so the only valid values are small, medium, large, slot_center and slot_offset.
variants: Either a config file, or an inline definition for the variants to use. This contains one block for each frame the hole wants to support. If multiple packages define the hole type, these are merged (though the variant IDs would need to be unique).

Variants use templates to define the geometry and collisions for the specified footprint. These should overlap the Z plane. The exact thickness and material is ignored, since the barrier type defines that. Collision volumes should also be included, which similarly have their types overridden by the barrier type.

Each variant has a few options:

Instance: The instance to place.
Template: Specifies a template ID/visgroup for the geometry and collisions.

Large barrier holes act specially - it places 4 templates, one for each quadrant, and has three template ID/visgroup configs:

Template: This is a quarter hole, excluding the outer corner subvoxel (which is not actually ocuppied by the hole).
TemplateSquare: This is a quarter hole with the outer corner subvoxel included. In most cases that subvoxel is present, so this simplifies the brushwork.
TemplateDiagonal: This is a combination of two quarter holes, placed overlapping diagonally. The footprints would normally collide, but this is allowed as a special case.