conditions_intro

Conditions

Conditions are the core method for manipulating and customising the map. Almost all features of BEEmod are triggered by them. Essentially, conditions are a set of rules that specify how instances should be manipulated. Each condition is composed of a series of "tests" and "results". It is checked against every instance in the map. If all the tests pass, then the results are executed.

Adding conditions

Most object types in packages have an option to specify a compiler config, which can contain one or more conditions among other things. For items and styles, this is the vbsp_config.cfg file in their folder.

A basic Condition

Here is a very simple condition. It looks for chair.vmf instances, and changes them to be couch.vmf instances instead.

"Conditions"
	{
	"Condition"
		{
		"instance" "instances/BEE2/demo/chair.vmf"
		"Result"
			{
			"changeInstance" "instances/BEE2/demo/couch.vmf"
			}
		}
	}

For almost all conditions, they will want to start with the "instance" test, to ensure they only modify instances with a specific filename. Otherwise they'd affect everything.

This first example isn't particularly useful, since it'd be easier to just change the original item definition to point to the new filename. But changing instances is very helpful in other situations. For example, the "Cube Type" item property results in the $cube_type fixup variable being set. If you needed to change the contents of the instance, a condition would be required to switch them out:

"Conditions"
	{
	"Condition"
		{
		"instance" "instances/BEE2/demo/cube_item.vmf"
		"instvar" "$cube_type = 0"
		"Result"
			{
			"changeInstance" "instances/BEE2/demo/cube_item/standard.vmf"
			}
		}
	"Condition"
		{
		"instance" "instances/BEE2/demo/cube_item.vmf"
		"instvar" "$cube_type = 1"
		"Result"
			{
			"changeInstance" "instances/BEE2/demo/cube_item/companion.vmf"
			}
		}
	"Condition"
		{
		"instance" "instances/BEE2/demo/cube_item.vmf"
		"instvar" "$cube_type = 2"
		"Result"
			{
			"changeInstance" "instances/BEE2/demo/cube_item/reflection.vmf"
			}
		}
	// And so on for values of 2-4
	}

The InstVar test is another very important test, which allows checking the value of a fixup variable. This set of conditions also demonstrates a common trick: the instances defined in editoritems.txt do not have to actually exist. In many cases, they just need to be a unique filename, which is then processed by conditions. Of course if the final map references an invalid file, a compile error will occur.

However, this set of conditions is somewhat inefficient. Each condition is checked against every instance before moving onto the next, so this definition will result in the same "instance" test being done 3 times for every instance. To solve this, it is possible to use another condition as a result of an outer one. That will be checked only against instances that succeed for the outer one:

"Conditions"
	{
	"Condition"
		{
		"instance" "instances/BEE2/demo/cube_item.vmf"
		"Result"
			{
			"Condition"
				{
				"instvar" "$cube_type = 0"
				"Result"
					{
					"changeInstance" "instances/BEE2/demo/cube_item/standard.vmf"
					}
				}
			"Condition"
				{
				"instvar" "$cube_type = 1"
				"Result"
					{
					"changeInstance" "instances/BEE2/demo/cube_item/companion.vmf"
					}
				}
			"Condition"
				{
				"instvar" "$cube_type = 2"
				"Result"
					{
					"changeInstance" "instances/BEE2/demo/cube_item/reflection.vmf"
					}
				}
			}
		}
	}