FGD

FGD (Forge Game Data) is a plain-text file format used to define all of the entities of a game for a map editor, allowing mappers can select them from within the editor and configure their properties.
While Hammer was originally called , 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.
For Custom FGD files to work in Hammer or Jack, they must be added through Tools > Options.
==File Format==
An FGD file consists of keywords that start with an character that might be followed by properties or even a body surrounded with square brackets . This may be the definition of an entity class or any other information that the map editor will use, depending on the keyword. In the following, all the different types of keywords are covered.
Comments can only be added as line comments, starting with . Block comments or multiline comments are not supported.
==Entities==
The syntactic components of an entity structure as defined in the FGD include:
# the class type of the entity (@PointClass),
# (optional) whitespace delimited class properties (base(...) studio(...)),
# an equals sign and the classname of the entity (example_entity_name),
# (optional) a colon followed by a description for it ("..."),
# (optional) a colon followed by a url for it ("https://developer.valvesoftware.com/FGD") and
# a body surrounded by square brackets [ ] containing the entity's keyvalues, flags and Inputs and Outputs.
Explanations of what each of these parameters do will be explained on this page, in order.
===Class Types and Properties===
The class type of an entity tells the map editor how this entity can be placed.
Class Name	Supported Editors	Description
 	 	A set of properties that can be inherited, reducing clutter. See @BaseClass.
 	 	Brush Entity: This entity has a volume that is defined by the solid (also referred to as a brush) that it is attached to. A solid is tied to an entity by selecting it and pressing . Other solids are world brushes.
This also includes brush entities that get converted to world brushes at compile time, such as and .
 	 	Point Entity: This entity exists at a certain non-arbitrary point. These entities are placed within Hammer by using the Hammer Entity Tool, .
 	 	This is a special form of point entity tailored for NPC (Non-Player Character) entities. It is useful in conjunction with the npcclass property type (see below).
 	 	This is a special form of point entity tailored for and . This causes the NextKeysprite property to be linked up when the entity is copied.
 	 	This is a special form of point entity tailored for and similar entities. This causes the targetsprite property to be linked up when the entity is copied.
 	 	This is a special form of point entity tailored for filters, which are 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 type.
 	 	Parsed last, after all FGDs have already been loaded and parsed. Appends KeyValues to an existing entity class. This can be useful for when another FGD is , and is used by , which is hardcoded to always loaded by .
Things between the class type declaration and the "" help to define properties of the entity, how it will act and be displayed in the map editor. There are a number of different keywords that can used here. Multiple of these can be used, each separated by a space.
Property	Supported Editors	Description 	Ilustration
 	 	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. 	
 	 	This lets you attach previously defined es (see below) to an entity. You can specify multiple BaseClasses, each separated by a comma. 	
 	 	This setting will change the color of the wireframe box in the Hammer 2D views, as well as the the cube/octahedron in 3D view if no model is present. 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. 	
 	 	Draw a cylinder between two entities. This is similar to line(), but with the addition of two radius properties that are looked up on the target entities. These define the size of the start and end of the cylinder. 	
 	 	Allows for multiple different editor flags, separated by commas:
* - Shows an arrow in the 3D view indicating which direction point entity is angled.
* - Shows the entity as a instead of a cube or rectangular prism. Also shows in the 3D view if no model or sprite is present.
* - Allow the entity to be hidden using View > Hide Paths, even if its classname is not prefixed with .
* - Allow the entity to be hidden using View > Hide Items, even if its classname is not prefixed with .	
 	 	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 _fov, _nearplane, _farplane, and _light, respectively. pitch_scale is set to -1.	
 	 	When moving this entity, it will snap to half the current grid size. This is somewhat special as it takes no arguments or parentheses. 	
 	 	If this is used, the specified sprite will be shown in the editor's 3D view instead of a flat-shaded colored box. This will work along-side the studio() or studioprop() commands. 
Uses VMT in , VMAT in , and SPR (QSPR and/or HLSPR) in all other editors.
* 0.25 scale by default. scale, rendermode, _light and angles properties affect the sprite. If no sprite name is set, it uses the model property.
* Scaled up or down to fit . , , , and affect the sprite.
* 1.0 scale by default; sprites defined using this parameter will be too big. Treated as alias for with no special properties.	
 	 	Renders the cone used on entities. inner_fov is the key for the innermost cone section, outer_fov is the outermost. pitch_scale allows inverting the pitch angle when rendering the cone. Values are taken from _inner_cone, _cone, and _light, respectively, if they aren't specified. This reads many other values corresponding to light_spot properties. 	
 	 	Identical to studioprop(), except that the pitch of the model is inverted. 	
 	 	Draws a line between two entities. The value properties in this entity give the names to look for in the key property on other entities. key is usually set to targetname. The color sets the color of the line when the entity is not selected. The second entity defaults to this one if not set. 	
 	 	A more verbose alternative to for displaying in-editor models, which supports rescaling the displayed model, displaying a specific skin, and display a specific frame of a Quake MDL, an MD2, or an MD3, or the first frame of a specific Half-Life MDL animation sequence.
Can also be used instead of for editor sprites, to select a specific frame of an SPR to display. Sprites can also be scaled this way, which may be necessary due to discrepancies between how Trenchbroom handles default scale vs Hammer and Jack.	
 	
:
: 	Draws a box oriented to the entity's angles. 	
 	 	Allows positioning a vector property in the map. 	
 	 	Default animation index (Half-Life MDL) or keyframe (Quake MDL, MD2, MD3, SPR, SP2) to display for the entity's model or sprite, if not overridden by the keyvalue. 	
 	 	Highlight brush faces listed in the given property (as a space-seperated ID list). If not specified, the property used is sides. 	
or 	 	Defines the size of the default cube (16x16x16) used when no model or sprite is specified. 	
 	 	Default skin to display on the entity's model, if not overridden by the keyvalue. Only supported on Quake MDL, Half-Life MDL, MD2, and MD3 models, as LWO and ASE models do not support selectable skins. 	
 	 	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 radius property. 	
 	 	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 model property will be used, if available . Multiple models can be defined, separated by commas.
In , this parameter also supports BSP, MD2, MD3, ASE, and LWO.
In , this parameter supports all formats that supports, plus SPR (both QSPR and HLSPR), SP2, and all formats that FreeImage and Assimp support.
In , the is used for displaying bounding boxes for HLMDL models, and an auto-calculated bounding box is used for other model formats, ignoring .	
 	 	Identical to , but is affected by the model's bounding box, ignoring . 	
 	 	Allows positioning a vector property in the map. This also draws a line from the entity to the position. 	
 	 	Draws a bounding box for two properties. origin() helpers should be defined as well to allow moving the points. 	
The following helpers take no arguments and are special-cased for specific entity types:
Property	Supported Editors	Description
 	 	Renders decals on nearby surfaces. This uses the texture property to set the material to use.
 	 	Renders overlays on a surface. (For )
 	 	Renders overlays on the intersections between water and the shore. (For )
 	 	Present on ; works only in . In this allows entity to cast point (), spot (), directional () and global directional () light source in .
 	 	Renders the sprite material specified in the model keyvalue ( and variants). For entity icons, use iconsprite.
 	 	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 origin() helpers for those properties.
 	 	Renders the instance in the map. It also generates additional properties dynamically corresponding to the instance parameters.
 	 	Used for . Automatically sets the 4 corners of the textured face on save.
 	
:
: 	Displays the contents of the message keyvalue in the 3D viewport.
 	 	Used for to preview fog.
 	 	Used for to preview 3D Skybox.
 	 	Draws a green arrow in 3D and 2D windows, it shows direction from from the specified property. For example, used for to show direction in which it will moving to open.
 	 	Used for to preview some properties.
 	 	Used for to simulate ragdoll physics when using Physics tool. Without this, ragdolls simulates the same as regular objects.
 	 	Used for to preview sprites of this entity.
 	 	Used for to preview beam.
 	 	Used for to preview laser.
 	 	Used for to preview text panel.
 	 	Used for to preview sprites of this entity.
===Entity Description===
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.
In , 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. Other editors, such as and , properly handle longer descriptions without chopping them up.
You may write \n the insert a line break, where the map editor 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)
]
===Entity Properties===
Everything between the main set of square brackets is used to define the entity's properties, including their keyvalues, inputs and outputs.
====Keyvalues====
Individual keyvalues consist of
# a name,
# a value type declaration in parentheses,
# (optional) the readonly modifier (controls if the user is able to assign a value to the key) ,
# (optional) the report modifier (controls if the keyvalue appears in the Entity Report; by default, targetname is used) ,
# (optional) a colon followed by a string as the SmartEdit display name,
# (optional) a colon followed by either a default value or no value and
# (optional) a colon followed by a string as the description .
The two modifiers can be present regardless of the presence of the display name, default value, or description.
The most common value types are:
Property Type	Supported Editors 	Description
 	 	A character sequence. The default value must have quotation marks around it.
 	 	A whole number.
 	 	A decimal number. The default value must be quoted unless it is a whole number with no decimal point.
 	
:
:
: 	A value that is either (1) or (0). This type needs a default value and it must be either 0 or 1. This creates a dropdown menu for the values Yes/No. For older versions of Hammer, use instead.
 	( KV only) ( KV only) ( KV only)	An integer value that is (supposed to be) read bitwise, making it ideal for multiple boolean values. All editors except and only actually read it bitwise for the property. See below.
 	 	A value that must be one of a pre-defined set of values. This keyvalue type lets you setup a dropdown menu with a number of distinct choices.
You can also use strings, floats, or null as values, instead of integers, like this:
In , additional help text can be added after the SmartEdit name, like so:
Flags and Choices do not function as input/output types.
There is also a number of special purpose property types that modify the entity properties dialog UI, for example to allow for easy browsing for files or easier manipulation of complex properties like colors or angles.
Property	Supported Editors	Description
 	 	Adds an angle widget for this property to the entity dialog UI.
 	 	Identical to angle, except the pitch is inverted.
 	 	Adds a relative 2-point axis helper.
 	 	Adds a button that brings up the color choosing UI, which takes the color you select and translate it into a three-number RGB value. Allows extra parameters (e.g., brightness), which get written as-is after using the color picker.
 	 	Adds a color button, but writes the output value as a float [0,1] instead of an integer (0,255). Allows extra parameters (e.g., brightness), which get written as-is after using the color picker.
 	 	
* Identical to shader, except it will automatically filter to decals.wad (if loaded). Doesn't allow manually typing the texture name in SmartEdit mode.
* Identical to material, except it will automatically replace your search filter with decals/ when opening the material browser.
 	 	
 	 	Marks property as being the name of the filter to use.
 	 	
 	 	Adds a button that brings up the file browser, letting you browse for instance files.
 	 	Used in to define fixup variables.
 	 	Used in to set fixup variables.
 	 	Adds a button that brings up the texture browser.
 	 	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.
 	 	Adds a drop-down selection list populated by entities of the NPCClass type.
 	 	The origin of the entity; automatically updates when the entity (and/or its origin) is moved in the 2D or 3D viewports.
 	 	
 	
:
: 	Adds a button that brings up the particle browser, letting you browse for particle systems.
 	 	Adds a drop-down selection list populated by entities of the PointClass type.
 	 	Acts the same as a KV named , uniformly multiplying the scale of the displayed model or sprite.
 	 	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.
 	 	Adds a button that brings up the texture browser. Doesn't allow manually typing the texture name in SmartEdit mode.
 	 	Adds a side selection eyedropper that allows you to choose sides (multiple with ).
 	 	
* - Displays a drop down list of all available skyboxes, in in and modes, or in in mode. No effect in mode.
* (beta) - Brings up the texture browser, with the filter set to and greyed out. Selecting a texture writes the result without the preceding path, stripping the UP/DN/LF/RT/FT/BK if present.
 	 	
* - Brings up the file browser, starting in the directory and narrowing search to WAV files.
* - Adds a button that brings up the sound browser, letting you browse for soundscripts or raw sound files.
 	 	
* Adds a drop down list with all soundscapes from .
 	 	
* - Brings up the file browser, starting in the directory. Narrows search to only SPR files in and modes, and only SP2 files in mode (no filter in mode).
* - Identical to material, except it will automatically replace your search filter with sprites/ when opening the material browser, and it will add .vmt to the end of the material name.
 	 	
* Adds a button that brings up the model browser.
* - Brings up the file browser, starting in the directory. Narrows search to: 
** MDL and BSP files in mode
** only MDL files in mode
** only MD2 files in mode
** MD3, ASE, and LWO files in mode).
 	 	Provides a drop-down list of other entity's target_source values.
* Automatically draws a line from this entity to named entity.
 	 	Marks property as another entity's targetname or classname.
 	 	Marks property as being the name that other entities may target.
 	 	Adds an absolute 1-point axis helper, similar to the origin marker.
 	 	3D vector property. A string consisting of three space delimited numbers.
====Inputs and Outputs====
Individual inputs and outputs consist of
# the keyword or ,
# a name,
# a value type declaration in round brackets and
# (optional) a colon followed by a string as the description.
Property Type	Supported Editors	Description
 	 	No value is passed.
 	 	A character sequence. The default value must have quotation marks around it.
 	 	A whole number.
 	 	A decimal number. The default value must be quoted unless it is a whole number with no decimal point.
 	 	A value that is either (1) or (0).
 	 	Passes the new entity that is generated by an entity.
====Flags====
The flags tab of an entity is configured through its keyvalue named "spawnflags" using the value type "flags". This keyvalue type has a different syntax as seen in the following example:
* After follows an equals sign and a body surrounded by square brackets containing a number of flags.
* Each flag consists of an integer as flag value, a colon, a display string and optionally another colon followed by a default value of 0 or 1.
The flag value should be a power of 2 (20=1, 21=2, 22=4, etc.).
Their default values are either 0 (off) or 1 (on), indicating that the flag's checkbox is either not ticked or ticked. If no default is specified, it is considered off.
In and , flag descriptions can be set following the default value, like with regular KVs:
In , a custom tab is added to the Object Properties window for each flags keyvalue.
This means that flags can now optionally have a display name and description.
The description is still optional when the display name is present:
Due to most games using integer size of 4 bytes, there can be at most 32 disjoint flags. On the right is a template for all possible flag values, namely 20, ..., 231.
==Other File Sections==
===@mapsize===
This value defines how big a map is allowed to be:
* Changes the maximum usable area.
* Warns the user if the maximum map size in the application settings is lower than this.
* Overrides the default soft map bounds defined in gameconfig.cfg (this can be further overridden on a per-map basis).
This should be used with caution:
* Unless the game has been coded to allow this size, using anything beyond default values will cause VBSP to crash.
* Unless the game has been coded to allow this size, geometry outside of the soft bounds will have no collision and be clipped off.
* Geometry outside of the soft bounds will have no lighting or collision and be clipped off
Default values per-engine:
; , 
; , (protocol 666), (pre-remaster)
; 
===@include===
If the game you are writing your FGD for has a lot in common with another game ( and , 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 has a FGD which @include's halflife2.fgd, which in turn @include's the base.fgd.
The game or mod you are creating must ship with all FGD's that your own mod is including.
The included FGD should be in the same directory as the FGD it is being called from.
===@BaseClass===
A 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.
The 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.
===@MaterialExclusion===
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.
===@AutoVisGroup===
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 to the list "World Details".
===@version===
This value defines the current FGD's version. uses this value to make sure the loaded FGD is up to date. For example:
===@ExtendClass===
This is a new special class type. It should take the name of another class in other FGDs. If the class is not found in other FGDs, this class will simply be ignored. This classes helpers + keyvalues defined will be "appended" to the actual class found in other FGDs. If the keyvalue/helper share names in this class and actual class, it will be overwritten with the keyvalue/helper defined here instead. A helper will not be appended if the exact name and parameters are already defined in the actual class (stops duplicates), the class description is ignored here as well. Extension classes are parsed last, after all FGDs have been loaded first. The purpose of all this is to not break thirdparty FGDs, and (hopefully) keep compatibility.
===@Main===
Stores various metadata about an FGD, such as game name, which color palette to use, and which entity to use when tying world brushes to an entity.
==Source 2 Additions==
The following things have been found in FGD files. These will not work in Source 1.
===Classes===
Class Name	Description
 	This can be used to quite literally overwrite data of existing entities, as well as adding new keyvalues and inputs/outputs.
 	Seen in models_gamedata.fgd
 	Seen in base.fgd
;Examples of these Classes
===Other commands===
Class Name	Description
 	This can exclude individual entities that are in @include'd FGD's. One entity per line
 	Seen in hlvr.fgd
 	Seen in workshop_addoninfo.fgd
 	Custom game-based properties that will be embedded in the model's $keyvalues. These will show up in ModelDoc as GameData nodes. Seen in models_gamedata.fgd
 	Seen in models_gamedata.fgdSeems to work simillar to $collisiontext
 	Seen in models_base.fgdSeems to work simillar to Animation_Events in Sequences.
} 	Seen in hlvr.fgd
 	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.
==Files==
The FGD files of a game can be found under <steam directory>/steamapps/common/<full game name>/bin/*.fgd, for example .../common/Half-Life 2/bin/halflife2.fgd.
==See also==
* :Category:FGD
* Base.fgd
==External links==
* SE FGD's Updated FGD's for some Valve games, made by Pinsplash.
* Forge Game Data Language .fgd syntax highlighting available in textmate format (SublimeText Compatible)
fgd
fgd
fgd