Left 4 Dead 2/Scripting/Expanded Mutation System/ConfigureHammerForEntityGroupCompilation

From Valve Developer Community
Jump to: navigation, search

Configuring Hammer to compile Entity Groups

Entity Groups, used extensively in Valve's EMS showcase mutations, are script files containing entity data which are exported contents of a VMF file. However Hammer does not support this by default, but Valve has provided the tools necessary to use. This tutorial should give a basic idea of how Valve configured Hammer to be capable of auto-generating Entity Group scripts.

There are quirks of Entity Group exporting to take note of first:

  • Only entities can be compiled into an Entity Group, so world data (geometry and all) is ditched.
  • Brush entities can be compiled but they will not have brush models. For example, compile a func_tracktrain and it'll still be exported into the script, but any associated brushes will be discarded.
    • Brushes will not maintain their angles when you export; You'll have to add PostPlaceCB to the entity you want for the compiled script later. Within it, useCBaseEntity.SetAngles()to change the brush's rotation. (see here for a list of functions for Entity Groups.).
      • Hammer doesn't allow you to view the rotated degrees of a brush, so your best bet is to start at the default rotation, then do trial and error with the Transform tool until you get a number you end up liking, or its close enough to what you wanted.
  • All entities that have their Visgroups active will be treated that they should be compiled into the Entity Group script.
Note.pngNote:With the Transform tool, Z coord lets you rotate the brush entity, but when converting toQAngles, the number you tested with should be put into the Y coord for theangles key.

The following entities are converted on compile:

Pre-Compile Post-Compile
func_button script_func_button
func_clip_vphysics script_clip_vphysics
func_nav_attribute_region script_nav_attribute_region
func_nav_blocker script_nav_blocker
trigger_* (except trigger_finale) script_trigger_*
point_template point_script_template
func_instance Any entity part of func_instance
func_instance_parms Applicable settings to any func_instance entity

These however, are discarded:

Install Perl

Executing a Perl script, specifically the one namedexport_entity_group.pl, provided by Valve which compile entity groups. In order to proceed you must have the Perl programming language installed or the script can't be ran.

Download Perl at www.perl.org. If you are running Windows, download and install ActiveState Perl.

Set up Hammer

  • Load up a .VMF with Hammer that you wish to compile into an entity group.
  • Ensure that you have configured Hammer to compile maps and the game executable and paths are correct. Below are example images showing the tabs you'll need to configure in order to compile entity groups.

Build programs.jpg

EXAMPLE: The Build Programs tab located in Tools->Options. Your file paths may differ!



Build configuration.jpg

EXAMPLE: The Game Configurations tab located in Tools->Options. Your file paths may differ!



  • If you make changes you may be prompted to restart Hammer in order for the changes to take effect
  • Load a vmf you wish to compile into an entity group (NOTE: file must be saved in EntityGroups folder as of this writing)
  • Open the "Run Map dialog" by pressing F9 or by clicking the game pad button on the Map Operations bar:

Run map.jpg


Expert dialog.jpg

If you are not in "Expert" mode click the button at the bottom of the dialog labeled "Expert"


  • Click the "Edit" button to open the Run Map Configurations panel and then click "New"

Run map configurations dialog.jpg


  • Name your configuration (e.g., Export Entity Group) and click Close
  • Ensure that your new configuration is selected in the Configurations dropdown
  • Click the "New" button to add a new command and check the checkbox to enable it.

Checkbox dialog.jpg

  • In the Command field in Command Properties enter the path to your perl.exe. If you prefer, you can click Cmds then select Executable from the list that appears and browse to where you installed perl.exe.


  • In the Parameters field use these parameters:
$gamedir\..\bin\export_entity_group.pl $path\$file.$ext $gamedir\scripts\vscripts\entitygroups\$file_group.nut

Entity dialog.jpg

  • It is highly recommended that you check the box labeled "Wait for keypress when done compiling" so you can examine the output of the script.
  • Click 'GO!' and it should compile your entity group.