VScript

VScript Improvements

HammerAddons has a number of features aimed at improving the experience of using VScript in entities, mainly by automatically generating and packing .nut script files. Note that these are automatically deduplicated, so entities with the same configuration will reuse the files. You can identify the generated scripts by their name - scripts/vscripts/inject/INJECT_<random characters>.nut.

Double Quotes In Keyvalues

Normally, entering double-quote characters (") anywhere into a VMF will result in file corruption, preventing the use of strings directly in Hammer. With the postcompiler, backticks(`) may be used in RunScriptCode parameters and Init Code fields. The postcompiler will swap these with double quotes, then convert the usage into a reference to a packed .nut file.

Init Code

In all entities which support Entity Scripts, new options are available named Init Code 1-2. Arbitary VScript code can be entered here, which will be joined together into a .nut file, which is packed and added to the end of the Entity Script. This is most useful to set configuration variables.

comp_scriptvar_setter

This pseudo-entity reads information from a number of sources, then generates script code which assigns a variable in the script scope. This can be used as a relay to pass allong instance $fixup variables to a script, or to make it easier to specify coordinate positions.

In the entity, you can specify the target script (or choose to set a ::global variable), the name of the variable, a reference to another entity, the mode, and a constant value. The constant and entity reference's behaviour varies depending on the mode.

Multiple entities may be specified for the target script entity, which will cause the same code to be assigned to all of them. Only the first reference entity is used, on the other hand. If not specified, the comp_scriptvar_setter itself is used.

In addition to specifying single variables, an array index can be specified like varname[4]. These entries will all be collected and ordered, then a single [1, 2, 3] array definition will be assigned to the variable. Any "holes" in this array will be set to null. The index may be omitted (like varname[]), which will cause this entry to be put in any unused index or at the end. In that case the order may change from compile to compile.

The following modes are available:

• Constant simply executes the constant field directly. This is suitable for simple numbers, entering code, etc.
• Stringified Constant wraps the constant field in ", so the contents are assigned as a string.
• Boolean Constant interprets the constant field as a bool (1, 0, true, false, yes, no), then assigns the variable to the matching Squirrel bool.
• Inverted Boolean Constant is the same, but first inverts the result. This is particularly useful if you want to offer a $fixup variable in an instance, but internally the opposite is most convenient in code.
• Entity Name returns the name of the reference entity. This is useful inside instances, since the scriptvar_setter will have instance fixups applied.
• Entity Handle produces a reference to the reference entity. If it has a targetname, this is done by Entities.FindByNameWithin(); otherwise, Entities.FindByClassnameWithin() is used. If there's identically named entities at the same position, using this method means it may not select the correct entity.
• Entity Keyvalue takes the reference entity, then reads the keyvalue specified by the constant value and produces that value. This looks up the type of keyvalue defined, then produces the appropriate corresponding Squirrel code.
  • Strings, booleans, integers, vectors and floats use those types.
  • Angles are returned as vectors.
  • Color values produce a 4-element array.
  • Lists of brush sides produce an array of integers.
  • The Entity Script field produces an array of strings.
  • All others are strings.
• Position produces the reference entity's location, as a vector object. If a constant value is specified, it is treated as a scaling factor, multiplied with each axis. Since if no reference is specified the comp_scriptvar_setter is used, this is an easy way to specify some location in the map.
• Postiion - X/Y/Z only functions similarly, except it produces only the specified axis as a float.
• Angle reads the reference entity (or the comp_scriptvar_setter)'s orientation, and returns it wrapped in either a QAngle() or Vector constructor, depending on the variant. Only some Source branches expose the angles class, older ones simply reusing Vector.
• Offset To Reference produces the offset of the reference entity, relative to the comp_scriptvar_setter's location. If a constant value is specified, it is treated as a scaling factor. This does not take into account the orientation of either entity.
• Distance To Reference produces the distance between the reference entity and the comp_scriptvar_setter, multiplied by the constant value if that is specified.
• Forward/Left/Up Direction each produce a vector pointing along the specified direction based on the reference entity's orientation. In Hammer, these are visualised as the red/green/blue lines, respectively. If a constant value is specified, it scales the length of these vectors, reversing them if negative.