FGD stands for Forge Game Data. It is the file extension for Hammer's game definition files. They define all of the entities of a game so mappers can select them from within the editor. It is a key point to understand that an FGD is nothing more than a reference. You cannot create or modify entities by editing a FGD, you merely give Hammer different information about what it expects to find within the game. Sometimes editing reveals hidden or unused features or even entities, but they were always there and could be used even without the updated FGD. For Custom FGD files to work in Hammer, they must be added through Tools > Options.
@include "base.fgd"at the top of your FGD and it is loaded before
base.fgd, you will encounter errors.
To do: Source 2 adds some extra features to the FGD format. document those.
- 1 History
- 2 File Format
- 3 Individual Entity listings
- 4 Other File Sections
- 5 Source 2 Additions
- 6 External Links
While Hammer was originally called Worldcraft, it was developed under the name The Forge (hence the name Forge Game Data). Due to trademark issues, however, the name Forge couldn't be used for the final version of Hammer. Even so, the file extension stayed.
The FGD file follows a fairly simple format. It is a script file that sets up entity structures and relationships for Hammer. The various parts of the Half-Life 2 FGD (found in your SDK binary directory, for example:
(path_to_steam)/SteamApps/common/Source SDK Base 2013 Singleplayer/bin/) are explained below.
Comments are defined simply by starting a line with //. They can be preceded by spaces or tabs.
//====== Copyright © 1996-2005, Valve Corporation, All rights reserved. ======= // // Purpose: Half-Life 2 game definition file (.fgd) // //=============================================================================
This value defines the maximum usable area in Hammer. This visually changes the area in Hammer, but unless the game has been coded to allow this size, using anything beyond default values causes vbsp to crash.
If the game you are writing your FGD for has a lot in common with another game ( Half-Life 2 and Half-Life 2: Deathmatch, for example), you can
@include a file that has all of the common structures defined in it. This allows your FGD to read all the data of that FGD.
@Include can be nested. Meaning a game can include another game's FGD, which already includes the
base.fgd. For example Half-Life 2: Deathmatch has a FGD which @include's
halflife2.fgd, which in turn @include's the
The game or mod you are creating must ship with all FGD's that your own mod is including.
If you only need a few base classes and entities, it would be recommended to only copy those few into your own FGD.
BaseClass is used to setup structures that are used by several different entities via the
base(BaseClassName) to the main definition line of the structure.
BaseClass structure is defined just like a normal entity in all respects. The only difference is that it doesn't appear in the entity lists in Hammer.
@BaseClass = Angles [ angles(angle) : "Pitch Yaw Roll (Y Z X)" : "0 0 0" : "This entity's orientation in the world. Pitch is rotation around the Y axis, " + "yaw is the rotation around the Z axis, roll is the rotation around the X axis." ] @BaseClass = Origin [ origin(origin) : "Origin (X Y Z)" : : "The position of this entity's center in the world. Rotating entities typically rotate around their origin." ]
Point classes are the entities you will be able to see in Hammer's entity list which can be placed
@PointClass base(Targetname, Angles, Origin) studio("path/model.mdl") = example_entity_name : "example entity description, visible in Hammers 'help' Box. [ Property_name_1(string) : "Example String Name" : "Example" : "Description" Property_name_2(integer) : "Example Interger Name" : 15 : "Description" Property_name_3(float) : "Example Float Name" : "1.5" : "Description" Property_name_4(boolean) : "Example Boolean Name" : 1 : "Description" Property_name_5(choices) : "second number" : 0 : "Your choice of numbers!" = [ 0 : "Default" 1 : "Something" 2 : "Another Thing" ] spawnflags(flags) = [ 2 : "A flag" : 0 // 0 means the flag isn't ticked by default 2 : "Another flag" : 1 // 1 means the flag is ticked by default ] // Inputs input DoSomething(void) : "Do something" // Outputs output OnSomethingHappened(void) : "Fires when something happens" output OnSomethingElse(void) : "Fires when something else happens" ]
Above is a generic example of an entity structure as defined in the FGD.
The first line defines the class name of your entity, followed by class properties, name of the entity and a description for it.
Everything in between the [ / ] brackets defines how the entity itself works. It defines keyvaules, flags and Inputs and Outputs.
Explanations of what each of these parameters do will be explained on this page, in order.
Individual Entity listings
The class type of an entity tells Hammer how this entity can be placed.
|@PointClass||The class type of an entity tells Hammer how this entity can be placed.|
|@PointClass||This entity exists at a certain non-arbitrary point. It is typically referred to as a "point entity." The entities are placed within Hammer by using the Entity tool (Shift+E).|
|@NPCClass||This is a special form of point entity tailored for NPC (non-player character) entities. It is useful in conjunction with the |
|@SolidClass||This entity's area is defined by the solid (also referred to as a brush) that it is attached to. It is typically referred to as a "brush entity" or "solid entity."|
|@KeyFrameClass||Used for |
|@MoveClass||Used for |
|@FilterClass||One of the special filter classes used to define what entities will be able to interact with each other in some way. This mainly causes the entity to be shown in properties with the |
Things between the Classtype declaration and the "= <entity name here>" help to define properties of the entity, how it will act and be displayed in Hammer. There are a number of different things that can used here. (More than one of these can be used, each separated by a space.)
|axis( property )||Allows positioning two points joined by a line in the map. The property value is set to "x1 y1 z1, x2 y2 z2" by default.|
|base( BaseClass1, BaseClass2, … )||This lets you attach previously defined |
|bbox( min,max )||Sets the size of the entity's bounding box.|
|color( red grn blu )||This setting will change the color of the wireframe box in the Hammer 2D views. If this isn't present, the color will default to magenta. The values specified here are the RGB values of a color, and each number has a range from 0 to 255.|
|cylinder( color, start_key, start_name, start_radius, end_key, end_value, end_radius )||Draw a cylinder between two entities. This is similar to |
|frustum( fov,near,far,color, pitch_scale )||Creates a rectangular cone extending from the entity. FOV defines the spread angle (0-180). Near and far define at what distances will be highlighted. The color value defines what color the cone will be shown with. Pitch_scale allows inverting the pitch angle when rendering the cone. The first four values must be property names, the last is a literal. If not specified, values are taken from |
|halfgridsnap||When moving this entity, it will snap to half the current grid size. This is somewhat special as it takes no arguments or parentheses.|
|iconsprite( "path/sprite.vmt" )||If this is used, the specified sprite will be shown in the Hammer 3D view instead of a flat-shaded colored box. This will work along-side the |
|lightcone( inner_fov, outer_fov, color, pitch_scale )||Renders the cone used on |
|lightprop( "path/model.mdl" )||Identical to |
|line( color, start_key, start_value, end_key, end_value )||Draws a line between two entities. The |
|obb( min,max )||Identical to |
|origin( property )||Allows positioning a vector property in the map.|
|sidelist( sides )||Highlight brush faces listed in the given property (as a space-seperated ID list). If not specified, the property used is |
|size( -x,-y,-z,+x,+y,+z )||Defines the size of the default cube used when no model or sprite is specified.|
|sphere( propertyname )||If an entity has a radius of effect, like a sound for example, a sphere will be displayed in Hammer's 2D and 3D views. You need to specify the property that will control the sphere size. If no property is specified, it will look for a |
|studio( "path/model.mdl" )||Identical to |
|studioprop( "path/model.mdl" )||If this is used, the entity will be displayed in the 3D view as the specified model. If no model is specified, the value of the entity's |
Note: If you have an entity with the "angles" property that you want to be able to rotate in Hammer using the mouse (as opposed to only through property editing), you may need to add this modifier.
Note: The appearance is affected by the
|vecline( property )||Allows positioning a vector property in the map. This also draws a line from the entity to the position.|
|wirebox( min,max )||Draws a bounding box for two properties. |
||Displays the contents of the |
The following helpers take no arguments and are special-cased for specific entity types:
|decal()||Renders decals on nearby surfaces. This uses the texture property to set the material to use.|
|overlay()||Renders overlays on a surface. (For |
|overlay_transition()||Renders overlays on the intersections between water and the shore. (For |
|light()||Present on |
|sprite()||Renders the sprite material specified in the |
|sweptplayerhull()||Draws 32x32x72-sized rectangular prisms at two points (point0 and point1), then links corners to show the space needed for one rectangle to move to the other's position. This also adds |
|instance()||Renders the instance in the map. It also generates additional properties dynamically corresponding to the instance parameters.|
|quadbounds()||Used for |
The entity description is a very important thing, as it the one single piece of help you can see in Hammer without consulting any website or developer, by pressing the "Help" button.
Each line of a description may not exceed 125 letters, in which case you must terminate the line and append a + at the end to start a new line in the FGD.
You may write \n To insert a line break, where hammer will start writing on a new line. You may also enter \n \n to skip one line entirely.
@PointClass = example_entity : "This is an example description for this example entity. It will appear in the help dialog for this entity.\n " + "Sometimes a description string gets very long, which cause errors. In which case we need to terminate the line and " + "append a + to the end, telling Hammer the next line is a continuation of the current line. Like in this example.\n " + "Note how the Quotation mark appears after a space at the end of the line. Without it, the words between lines get merged" [ (entity properties go here) ]
Everything between the main set of [ / ] brackets is used to define the entity's properties, including their inputs and outputs. Individual property structures consist of a name, a type declaration, a display name, a default value, and a description.
The most common properties are:
|string||This creates a property of the string type.|
|integer||This creates a property of the integer type.|
|float||This creates a property of the float type. Although it deals with numbers, the structure of it is similar to the string type. The default value must have quotes around it.|
||This creates a property of the boolean type, with a dropdown for yes/no. For older versions of Hammer, use choices instead.|
|flags||The flags property type lets you setup what will appear in the Flags portion of the entity property dialog. It is set up similar to the choices property type. The flags are all powers of 2 (2⁰=1, 2¹=2, 2²=4, etc.), and their values are either 0 (off) or 1 (on). If no default is specified for a flag, it is considered to be off.|
|choices||A property of this type lets you setup a number of distinct choices.|
Choices follow a slightly different format. They do not function as input/output types.
Property_name_1(string) : "Example String Name" : "Example" : "Keyvalue Description" Property_name_2(integer) : "Example Interger Name" : 15 : "Keyvalue Description" Property_name_3(float) : "Example Float Name" : "1.5" : "Keyvalue Description" Property_name_4(boolean) : "Example Boolean Name" : 1 : "Keyvalue Description"
Property_name_5(choices) : "Display name" : "1" = [ 0 : "something" 1 : "something else (default)" 2 : "something completely different" ]
- You can also use strings (or floats) as values, instead of integers, like this:
Property_name_5(choices) : "Model used" : "models/something02.mdl" = [ "models/something01.mdl" : "something" "models/something02.mdl" : "something else (default)" "models/something03.mdl" : "something completely different" ]
flags property type lets you setup what will appear in the Flags portion of the entity property dialog. It is set up similar to the
choices property type. The flags are all powers of 2 (2⁰=1, 2¹=2, 2²=4, etc.), and their values are either 0 (off) or 1 (on). If no default is specified for a flag, it is considered to be off.
spawnflags(flags) = [ 1 : "something clever" : 1 2 : "something else" : 0 4 : "you said what now?" : 0 8 : "nothing" : 1 ]
There are also a number of special purpose property types that modify the entity properties dialog UI to allow for easy browsing for files or easier manipulation of complex properties (like colors or angles).
|angle||Adds an angle widget for this property to the entity dialog UI.|
|angle_negative_pitch||Identical to |
|axis||Adds a relative 2-point axis helper.|
||Adds a button that brings up the color choosing UI, which takes the color you select and translated it into the three-number RGB value. Allows extra parameters (e.g., brightness).|
|color1||Adds a color button, but uses a float [0,1] instead of an integer (0,255). Allows extra parameters (e.g., brightness).|
|decal||Identical to |
Note: Sometimes, the material you want will be in
|filterclass||Marks property as being the name of the filter to use.|
|instance_file||Adds a button that brings up the file browser, letting you browse for instance files.|
|instance_parm||Used in |
|instance_variable||Used in |
|material||Adds a button that brings up the material browser.|
|node_dest||adds an eyedropper to select a node in the 3d view|
||On nodes, this is used for the Node ID keyvalue to automatically increment it with each consecutive node placed. Does not appear to function when used on other entities.|
|npcclass||Adds a drop-down selection list populated by entities of the NPCClass type.|
||Adds a button that brings up the particle browser, letting you browse for particle systems.|
Bug: The particle browser cannot read files from VPKs!
|pointentityclass||Adds a drop-down selection list populated by entities of the |
|scene||Adds a button that brings up the sound browser, letting you browse for scene files.|
||Adds a button that brings up the file browser, letting you browse for VScripts.|
||Adds a button that brings up a list of VScripts with buttons to add/remove scripts and open each file.|
Note: Vscript browser is most of the time empty. Instead a Vscript name without extension will work just fine.
|sidelist||Adds a side selection eyedropper that allows you to choose sides (multiple with).|
|sound||Adds a button that brings up the sound browser, letting you browse for soundscripts or raw sounds.|
|sprite||identical to |
|studio||Adds a button that brings up the model browser.|
|target_destination||Marks property as another entity's |
|target_name_or_class||Marks property as another entity's |
|target_source||Marks property as being the name that other entities may target.|
|vecline||Adds an absolute 1-point axis helper, similar to the origin marker.|
|vector||3D vector property.|
Other File Sections
Material Exclusion Lists
These lists define paths that Hammer's Material Browser will not use when presenting you with a palette of textures to choose from. It should have no effect on what files are actually available to a custom map.
models/will always be excluded, regardless of what is set here.
@MaterialExclusion [ // Names of the sub-directories we don't want to load materials from "debug" "engine" "hud" "vgui" ]
This permits customizing the automatic Visgroups tab of the Filter Control toolbar. The first title is the name of the "parent," and the next is the "children." Finally comes a list of entity classes that will be placed in the visgroup.
If the parent already exists, the new entry will be merged with the previous ones (including the default list of groups). This permits creating trees with multiple levels of grouping. If a visgroup becomes entirely empty, it will not appear in the list.
You may add entities to existing groups if the "Parent" of the autovisgroup is the name of an existing group, like "World Details". For example, you could add
func_brush to the list "World Details".
@AutoVisGroup = "Brushes" [ "Triggers" [ "trigger_once" "trigger_multiple" ] "Tool Brushes" [ "func_areaportal" "func_viscluster" ] ] @AutoVisGroup = "Tool Brushes" [ "Vis Clusters" [ "func_viscluster" ] ]
Source 2 Additions
The following things have been found in Source 2 FGD files. These will not work in Source 1.
To do: Find more things that are not listed here. Explain what these do. So far only occurrences of FGD's have been pasted here for documenting them.
Example of these Classes
@OverrideClass This can be used to quite literally overwrite data of existing entities, as well as adding new keyvalues and inputs/outputs.
|@Exclude||This can exclude individual entities that are in @include'd FGD's. One entity per line|
|@EntityGroup||To do: Explain what this does.|
Seen in hlvr.fgd
|@struct||To do: Explain what this does.|
Seen in workshop_addoninfo.fgd
|@ModelGameData||To do: Explain what this does.|
Seen in models_gamedata.fgd
Seems to work simillar to $keyvalues.
|@ModelBreakCommand||To do: Explain what this does.|
Seen in models_gamedata.fgd
Seems to work simillar to $collisiontext
|@ModelAnimEvent||To do: Explain what this does.|
Seen in models_base.fgd
Seems to work simillar to Animation_Events in Sequences.
entity_tool_name = <string>
entity_tool_tip = <string>
entity_tool_group = <string>
|To do: Explain what this does.|
Seen in hlvr.fgd
|Deprecated()||Marks a property as depracated and no longer in use.|
Examples of these commands
Below are expandable examples of the above listed commands.
We currently do not have any more good information on what these commands do, but at least we have examples of how to use them.