View source for FGD

{{LanguageBar}}

{{seealso|[[:Category:FGD]]}}
'''FGD''' ('''Forge Game Data''') is a plain-text file format used to define all of the [[entity|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 {{worldcraft|4}}, 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'''.

{{note|In {{hammer|4}}, FGDs are loaded in alphabetical order. If you do not include <code>@include "base.fgd"</code> at the top of a Source 1 or 2 FGD and it is loaded before <code>base.fgd</code>, you will encounter errors.

In {{Jack|4}}, FGDs are loaded in the order in which they are listed in the game configuration.

In {{trenchbroom|4}}, only one FGD (or DEF or ENT) can be loaded at a time. GoldSrc mappers who use Trenchbroom should add <code>@include "zhlt.fgd"</code> to the top or bottom of the given game's FGD.}}
{{ModernImportant|'''An FGD is nothing more than a reference for the map editor.'''<br>You cannot create or modify entities by editing a FGD, you merely give the map editor 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.}}

{{todo|Make it clearer what features are available in which map editors. The following editors should be documented, at minimum:
* {{hammer3|4|nt=5}}
* {{hammer4|4}}
:: (if something is supported by {{hammer++|4}}, {{slamminsrc|4|nt=4}}, and/or {{strata hammer|4}} but not {{hammer|4}}, note this, but otherwise assume them as identical).
* {{hammer5|4}}
* {{jack|4}}
* {{trenchbroom|4}}
Information regarding other notable editors, such as {{nrc|2}} or older versions of {{worldcraft|2}}, may be included, but are not a priority, as the majority of mappers for Valve engines will be using one of the above editors.<br>
Prefer editor-agnostic language when not referring to a specific editor; unless something is specific to Hammer, refer to the program used to create maps as "the map editor". If it is specific to Hammer, specify the major version (3.x, 4.x, 5.x).
}}


==File Format==
An FGD file consists of keywords that start with an {{mono|@}} character that might be followed by properties or even a body surrounded with square brackets {{mono|[ ]}}. 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 {{mono|//}}. Block comments or multiline comments are not supported.
{{pre|
//<nowiki>====== Copyright © 1996-2005, Valve Corporation, All rights reserved. =======</nowiki>
//
// Purpose: Half-Life 2 game definition file (.fgd) 
//
//<nowiki>=============================================================================</nowiki>
}}

==Entities==
The syntactic components of an entity structure as defined in the FGD include:
# the '''class type''' of the entity (<code>@PointClass</code>),
# ''(optional)'' whitespace delimited '''class properties''' (<code>base(...) studio(...)</code>),
# an '''equals sign''' and the '''classname''' of the entity (<code>example_entity_name</code>),
# ''(optional)'' '''a colon''' followed by a '''description''' for it (<code>"..."</code>),
# {{jack|only}} ''(optional)'' '''a colon''' followed by a '''url''' for it (<code><nowiki>"https://developer.valvesoftware.com/FGD"</nowiki></code>) and
# a body surrounded by square brackets <code>[ ]</code> 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.
{{ModernExample|{{pre|<nowiki>
@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"	: "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) : "second number" : 0 : "Your choice of numbers!" =
	[
		0 : "Default"
		1 : "Something"
		2 : "Another Thing"
	]

	spawnflags(flags) =
	[
		1 : "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"

]
</nowiki>}}}}

===Class Types and Properties===
The class type of an entity tells the map editor how this entity can be placed.
{| class="wikitable"
! Class Name
! Supported Editors
! Description
|-
| {{mono|@BaseClass}}
| {{hammer3|4}}<br>{{hammer4|4}}<br>{{hammer5|4}}<br>{{jack|4}}<br>{{trenchbroom|4}}
| A set of properties that can be inherited, reducing clutter. See [[#@BaseClass|@BaseClass]].
|-
| {{mono|@SolidClass}}
| {{hammer3|4}}<br>{{hammer4|4}}<br>{{hammer5|4}}<br>{{jack|4}}<br>{{trenchbroom|4}}
| [[brush entity|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 {{key|Ctrl|T}}. Other solids are [[world brush]]es.<br>
This also includes brush entities that get converted to world brushes at compile time, such as {{ent|func_detail}} and {{ent|func_group}}.
|-
| {{mono|@PointClass}}
| {{hammer3|4}}<br>{{hammer4|4}}<br>{{hammer5|4}}<br>{{jack|4}}<br>{{trenchbroom|4}}
| [[point entity|Point Entity]]: This entity exists at a certain non-arbitrary point. These entities are placed within Hammer by using the [[Hammer Entity Tool]], {{key|Shift|E}}.
|-
| {{mono|@NPCClass}}
| {{hammer4|4}}<br>{{hammer5|4}}
| This is a special form of point entity tailored for [[NPC]] ('''N'''on-'''P'''layer '''C'''haracter) entities. It is useful in conjunction with the <code>npcclass</code> property type (see below).
|-
| {{mono|@KeyFrameClass}}
| {{hammer4|4}}<br>{{hammer5|4}}
| This is a special form of point entity tailored for {{Ent|move_rope}} and {{Ent|keyframe_rope}}. This causes the <code>NextKeysprite</code> property to be linked up when the entity is copied.
|-
| {{mono|@MoveClass}}
| {{hammer4|4}}<br>{{hammer5|4}}
| This is a special form of point entity tailored for {{Ent|path_track}} and similar entities. This causes the <code>targetsprite</code> property to be linked up when the entity is copied.
|-
| {{mono|@FilterClass}}
| {{hammer4|4}}<br>{{hammer5|4}}
| This is a special form of point entity tailored for [[filter]]s, 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 {{mono|filterclass}} type.
|-
| {{mono|@ExtendClass}}
| {{hammer++|4}}
| 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 {{mono|[[#@include|@include]]d}}, and is used by {{file|[[hammerplusplus_fgd.fgd|hammerplusplus_fgd]]|fgd}}, which is hardcoded to always loaded by {{hammer++|4}}.
|}
{{modernImportant|If multiple of classes of the same name exist, the last one defined will be the one used in the map editor, even if the classes' types are different.
{{bug|{{hammer|2}} will delete the brush data of any non-brush entity!}}
{{workaround|If it is not possible to modify game code to create an alias name for the entity, use a precompiler such as {{mess|2}} or a postcompiler such as {{teamspen|2}} to rename the entity's class when compiling.}}
}}

Things between the class type declaration and the "{{mono|1== <entity_name_here>}}" 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.
{| class="wikitable mw-collapsible" style="background:transparent" width=100%
! Property
! Supported Editors
! Description
! Ilustration
|-
| {{mono|axis( ''property'' )}}
| {{hammer4|4}}
| 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.
|
|-
| {{mono|base( ''BaseClass1, BaseClass2, …'' )}}
| {{hammer3|4}}<br>{{hammer4|4}}<br>{{jack|4}}<br>{{trenchbroom|4}}
| This lets you attach previously defined {{mono|BaseClass}}es (see [[#@BaseClass|below]]) to an entity. You can specify multiple <code>BaseClass</code>es, each separated by a comma.
|
|-
| {{mono|color( ''red green blue'' )}}
| {{hammer3|4}}<br>{{hammer4|4}}<br>{{jack|4}}<br>{{trenchbroom|4}}
| 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.
{{bug|Doesn't affect color of the entity in {{hammer4|2}} (only affects text color); an arbitrary color will be chosen if not part of a visgroup, defaulting to grey when first created. This is fixed in {{hammer++|2}}.}}
|
|-
| {{mono|cylinder( ''color, start_key, start_name, start_radius, end_key, end_value, end_radius'' )}}
| {{hammer4|4}}
| Draw a cylinder between two entities. This is similar to <code>line()</code>, but with the addition of two ''<code>radius</code>'' properties that are looked up on the target entities. These define the size of the start and end of the cylinder.
|
|-
| {{mono|flags(''flagname(s)'')}}
| {{jack|4}}
| Allows for multiple different editor flags, separated by commas:
* {{code|Angle}} - Shows an arrow in the 3D view indicating which direction point entity is angled.
* {{code|Light}} - Shows the entity as a {{w|octahedron}} instead of a cube or rectangular prism. Also shows in the 3D view if no model or sprite is present.
* {{code|Path}} - Allow the entity to be hidden using '''View > Hide Paths''', even if its classname is not prefixed with {{code|path_}}.
* {{code|Item}} - Allow the entity to be hidden using '''View > Hide Items''', even if its classname is not prefixed with {{code|item_}}.
{{bug|{{code|Item}} is mentioned in the reference manual but is not implemented properly.}}
|
|-
| {{mono|frustum( ''fov,near,far,color, pitch_scale'' )}}
| {{hammer4|4}}
| 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 <code>_fov</code>, <code>_nearplane</code>, <code>_farplane</code>, and <code>_light</code>, respectively. ''<code>pitch_scale</code>'' is set to -1. {{bug|In {{hammer++|2}} an entity with both <code>frustum</code> and <code>studio</code> (or <code>studioprop</code>) will rotate twice as far when using the mouse in the 2d and 3d views. Setting the <code>angles</code> manually or using the <code>Point At...</code> helper is required.}}
|
|-
| {{mono|halfgridsnap}}
| {{hammer4|4}}
| When moving this entity, it will snap to half the current grid size. This is somewhat special as it takes no arguments or parentheses.
|
|-
| {{mono|iconsprite( "''path/sprite.ext''" )}}
| {{hammer3|4}}<br>{{hammer4|4}}<br>{{jack|4}}<br>{{trenchbroom|4|addtext={{nbsp}}(limited support)}}
| 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 <code>studio()</code> or <code>studioprop()</code> commands. 

Uses [[VMT]] in {{hammer4|2}}, [[VMAT]] in {{hammer5|2}}, and [[SPR]] (QSPR and/or HLSPR) in all other editors.
* {{Hammer3}}{{hammer4}} 0.25 scale by default. <code>scale</code>, <code>rendermode</code>, <code>_light</code> and <code>angles</code> properties affect the sprite. If no sprite name is set, it uses the <code>model</code> property.
* {{jack}} Scaled up or down to fit {{mono|size()}}. {{mono|_light}}, {{mono|_color}}, {{mono|rendermode}}, and {{mono|renderamt}} affect the sprite.
* {{trenchbroom}} 1.0 scale by default; sprites defined using this parameter will be too big. Treated as alias for {{mono|model()}} with no special properties.
|
|-
| {{mono|lightcone( ''inner_fov, outer_fov, color, pitch_scale'' )}}
| {{hammer4|4}}
| Renders the cone used on {{Ent|light_spot}} entities. ''<code>inner_fov</code>'' is the key for the innermost cone section, ''<code>outer_fov</code>'' is the outermost. ''<code>pitch_scale</code>'' allows inverting the pitch angle when rendering the cone. Values are taken from <code>_inner_cone</code>, <code>_cone</code>, and <code>_light</code>, respectively, if they aren't specified. This reads many other values corresponding to light_spot properties.
|
|-
| {{mono|lightprop( "''path/model.mdl''" )}}
| {{hammer4|4}}
| Identical to <code>studioprop()</code>, except that the pitch of the model is inverted.
|
|-
| {{mono|line( ''color, start_key, start_value, end_key, end_value'' )}}
| {{hammer4|4}}
| Draws a line between two entities. The ''<code>value</code>'' properties in this entity give the names to look for in the ''<code>key</code>'' property on other entities. ''<code>key</code>'' is usually set to <code>targetname</code>. The color sets the color of the line when the entity is not selected. The second entity defaults to this one if not set.
{{bug|Color value is ignored, always being treated as 255 0 255.}}
{{note|
* Only supports KVs, not I/O.
* {{jack|2}} and {{nrc|2}} automatically draw lines from {{code|target_destination}} to {{code|target_source}}.
* {{tb|2}} automatically draws lines from {{code|target}} and {{code|killtarget}} to {{code|targetname}}.
}}
|
|-
| {{mono|model({ "path": ''"path/file.ext"'', "frame": ''#'', "skin": #, "scale": ''#'' })}}
| {{trenchbroom|4}}
| A more verbose alternative to {{code|studio()}} for displaying in-editor models, which supports rescaling the displayed model, displaying a specific [[skin]], and display a specific frame of a {{quake}} [[Quake MDL]], an {{quake2}} [[MD2]], or an {{quake3}} [[MD3]], or the first frame of a specific {{Gldsrc}} [[Half-Life MDL]] animation [[sequence]].

Can also be used instead of {{code|iconsprite()}} 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.
{{tip|All parameters except {{code|"path"}} are optional.}}
{{note|Can do a lot, including conditional values, more verbose documentation can be found in the [https://trenchbroom.github.io/manual/latest/#display-models-for-entities Trenchbroom manual].}}
{{warning|{{code|model()}} is ''only'' supported by Trenchbroom! If it is not necessary to use the extra features available, then {{code|studio()}} or {{code|iconsprite()}} should be used instead, to retain compatibility with other editors.}}
|
|-
| {{mono|obb( ''min,max'' )}}
| {{hammer4|4}}
:{{L4d2|only}}
:{{hammer++|also}}
| Draws a box oriented to the entity's angles.
|
|-
| {{mono|origin( ''property'' )}}
| {{hammer4|4}}
| Allows positioning a vector property in the map. 
|
|-
| {{mono|sequence( ''index'' )}}
| {{jack|4}}
| 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 {{code|sequence}} keyvalue. 
|
|-
| {{mono|sidelist( ''sides'' )}}
| {{hammer4|4}}
| Highlight brush faces listed in the given property (as a space-seperated ID list). If not specified, the property used is <code>sides</code>.
|
|-
| {{mono|size(''x y z'')}}<br>or<br>{{mono|size( ''-x -y -z, +x +y +z'' )}}
| {{hammer3|4}}<br>{{hammer4|4}}<br>{{jack|4}}<br>{{trenchbroom|4}}
| Defines the size of the default cube (16x16x16) used when no model or sprite is specified. 
|
|-
| {{mono|skin( ''index'' )}}
| {{jack|4}}
| Default [[skin]] to display on the entity's model, if not overridden by the {{code|skin}} keyvalue. Only supported on [[Quake MDL]], [[Half-Life MDL]], [[MD2]], and [[MD3]] models, as LWO and ASE models do not support selectable skins.
|
|-
| {{mono|sphere( ''propertyname'' )}}
| {{hammer4|4}}
| 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 <code>radius</code> property. 
|
|-
| {{mono|studio( "''path/model.mdl''" )}}
| {{hammer3|4|nt=5}}<br>{{hammer4|4}}<br>{{jack|4}}<br>{{trenchbroom|4|addtext={{nbsp}}(limited support)}}
| 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 <code>model</code> property will be used, if available {{not|{{trenchbroom}}}}. Multiple models can be defined, separated by commas.
In {{jack|4}}, this parameter also supports [[BSP]], [[MD2]], [[MD3]], ASE, and LWO.
In {{trenchbroom|4}}, this parameter supports all formats that {{Jack |2}} supports, plus [[SPR]] (both QSPR and HLSPR), SP2, and all formats that FreeImage and Assimp support.
{{note|In {{hammer|4}} and {{jack|4}}, if no model is specified, the value of the entity's <code>model</code> property will be override which model is displayed, if available. Additional values also are affect the model's appearance:
* {{hammer4}} {{mono|skin}}, {{mono|rendercolor}}, {{mono|uniformscale}}{{since|{{csgo}}}}
** {{hammer++}} Everything in {{hammer4}}, plus {{mono|modelscale}}
* {{jack}} {{mono|rendermode}}{{goldsrc|only}}, {{mono|renderamt}}{{goldsrc|only}}, {{mono|body}}{{goldsrc|only}}, {{mono|scale}}, {{mono|sequence}}, {{mono|alpha}}{{quake|only}} 
{{trenchbroom|4}} requires using special {{code|model()}} syntax instead.}}
In {{Jack|2}}, the {{cmd|$cbox}}<!--NOT $bbox--> is used for displaying bounding boxes for [[HLMDL]] models, and an auto-calculated bounding box is used for other model formats, ignoring {{mono|size()}}.
| 
[[File:Studio("models-combine soldier.mdl").png|300px|studio("models/combine_soldier.mdl")]]
|-
| {{mono|studioprop( "''path/model.mdl''" )}}
| {{hammer4|4}}
| Identical to {{mono|studio()}}, but is affected by the model's bounding box, ignoring {{mono|size()}}.
{{note|{{hammer}} 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.}}
| 
[[File:Studioprop("models-combine soldier.mdl").png|300px|studioprop("models/combine_soldier.mdl")]]
|-
| {{mono|vecline( ''property'' )}}
| {{hammer4|4}}
| Allows positioning a vector property in the map. This also draws a line from the entity to the position.
|
|-
| {{mono|wirebox( ''min,max'' )}}
| {{hammer4|4}}
| Draws a bounding box for two properties. <code>origin()</code> 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:
{| class="wikitable"
|-
! Property
! Supported Editors
! Description
|-
| {{mono|decal()}}
| {{hammer3|4}}<br>{{hammer4|4}}<br>{{jack|4}}<br>{{trenchbroom|4}}
| Renders decals on nearby surfaces. This uses the '''texture''' property to set the material to use.
|-
| {{mono|overlay()}}
| {{hammer4|4}}
| Renders overlays on a surface. (For {{Ent|info_overlay}})
|-
| {{mono|overlay_transition()}}
| {{hammer4|4}}
| Renders overlays on the intersections between water and the shore. (For {{Ent|info_overlay_transition}})
|-
| {{mono|light( point OR spot OR sun OR sun, global )}}
| {{hammer4|4}}
| Present on {{Ent|light}}; works only in {{hammer++|4}}. In {{hammer++|4}} this allows entity to cast point ({{ent|light}}), spot ({{ent|light_spot}}), directional ({{ent|light_directional}}) and global directional ({{ent|light_environment}}) light source in {{code|3D Lighting Preview}}.
|-
| {{mono|sprite()}}
| {{hammer3|4}}<br>{{hammer4|4}}<br>{{jack|4}}<br>{{trenchbroom|4}}
| Renders the sprite material specified in the <code>model</code> keyvalue ({{Ent|env_sprite}} and variants). For entity icons, use <code>iconsprite</code>.
|-
| {{mono|sweptplayerhull()}}
| {{hammer4|4}}
| 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 <code>origin()</code> helpers for those properties.
|-
| {{mono|instance()}}
| {{hammer4|4}}
| Renders the [[func_instance|instance]] in the map. It also generates additional properties dynamically corresponding to the instance parameters.
|-
| {{mono|quadbounds()}}
| {{hammer4|4}}
| Used for {{Ent|func_breakable_surf}}. Automatically sets the 4 corners of the textured face on save. {{todo|Does this also control the "error" keyvalue?}}
|-
| {{mono|worldtext()}}
| {{hammer4|4}}
:{{csgobranch|only}}
:{{hammer++|also}}
| Displays the contents of the <code>message</code> keyvalue in the 3D viewport.
|-
| {{mono|fogcontroller()}}
| {{hammer++|4}}
| Used for {{Ent|env_fog_controller}} to preview fog.
|-
| {{mono|skycamera()}}
| {{hammer++|4}}
| Used for {{Ent|sky_camera}} to preview [[3D Skybox]].
|-
| {{mono|direction( propertyname )}}
| {{hammer++|4}}
| Draws a green arrow in 3D and 2D windows, it shows direction from from the specified property. For example, used for {{ent|func_door}} to show direction in which it will moving to open.
|-
| {{mono|catapult()}}
| {{strata|4}}<br>{{hammer++|4}}
| Used for {{Ent|trigger_catapult}} to preview some {{Ent|trigger_catapult}} properties.
|-
| {{mono|ragdoll()}}
| {{hammer++|4}}
| Used for {{ent|prop_ragdoll}} to simulate ragdoll physics when using [[Physics tool]]. Without this, ragdolls simulates the same as regular objects.
|-
| {{mono|spotlight()}}
| {{hammer++|4}}
| Used for {{Ent|point_spotlight}} to preview sprites of this entity.
|-
| {{mono|beam( propertyname, propertyname )}}
| {{hammer++|4}}
| Used for {{Ent|env_beam}} to preview beam.
|-
| {{mono|laser( propertyname )}}
| {{hammer++|4}}
| Used for {{Ent|env_laser}} to preview laser.
|-
| {{mono|worldtextvgui()}}
| {{hammer++|4}}
| Used for {{Ent|vgui_world_text_panel}} to preview text panel.
|-
| {{mono|sun()}}
| {{hammer++|4}}
| Used for {{Ent|env_sun}} to preview sprites of this entity.
|}

===Entity Description===
[[File:Hammer entity help.jpg|300px|thumb|right|The entity help box containing the message written on the left.]]
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 {{hammer|2}}, 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.{{confirm}} Other editors, such as {{Jack|2}} and {{trenchbroom|2}}, properly handle longer descriptions without chopping them up, and this is fixed in {{hammer++|2}}.

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.

{{warning|Quotation marks <code>" "</code> are not allowed inside the description, as this will terminate the string. Use Apostrophes <code>' '</code> instead.<br>In {{hammer|2}}, using any of these "fancier" quotation mark options will also not work, as they're displayed wrong: <code>“ ”</code>, <code>„ “</code>, <code>‚ ’</code>, <code>‘ ’</code>, <code>« »</code>, <code>《 》</code>.}}
<syntaxhighlight lang=text highlight=2-5>
@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)
]
</syntaxhighlight>

===Entity Properties===
Everything between the main set of square brackets {{mono|[ ]}} is used to define the entity's properties, including their keyvalues, inputs and outputs.
{{bug|{{hammer|4.1}} only supports up to 127 properties; attempting to select or modify additional properties will cause Hammer to crash.|tested={{hammer}}{{bms}}}}
{{bug|Attempt to change entity class to entity with more than 118 properties will cause Hammer to crash (still can be placed via [[Entity Tool]]).|tested={{hammer}}{{bms}}}}

====Keyvalues====
Individual keyvalues consist of
# a name,
# a value type declaration in parentheses,
# ''(optional)'' the <code>readonly</code> modifier (controls if the user is able to assign a value to the key) {{only|{{hammer4}}}},
# ''(optional)'' the <code>report</code> modifier (controls if the keyvalue appears in the Entity Report; by default, <tt>targetname</tt> is used) {{only|{{hammer4}}}},
# ''(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 {{hammer3|not}}.

The two modifiers can be present regardless of the presence of the display name, default value, or description.
{{todo|Are <code>readonly</code> and <code>report</code> only valid when using Hammer 4? Do they exist in Hammer 5 still?}}

{{ModernExample|{{pre|
health(integer)
health(integer) readonly
health(integer) : "Strength"
health(integer) : "Strength" : 1
health(integer) : "Strength" : 1 : "Number of points of damage to take before breaking. 0 means don't break."
health(integer) : "Strength" :   : "Number of points of damage to take before breaking. 0 means don't break."
health(integer) readonly : "Strength" : : "This keyvalue is not editable."
health(integer) report : "Strength" : : "This keyvalue will show up in the Entity Report."
}}}}
{{ModernImportant|The default value is autofilled by the map editor; if an entity should not have a certain keyvalue by default, then the default value should be left blank!}}

The most common value types are:
{| class="wikitable"
|-
! Property Type !! Supported Editors !! Description
|-
| {{mono|[[string]]}}
| {{hammer3|4}}<br>{{hammer4|4}}<br>{{jack|4}}<br>{{trenchbroom|4}}
| A character sequence. The default value must have quotation marks {{mono|" "}} around it.
|-
| {{mono|[[integer]]}}
| {{hammer3|4}}<br>{{hammer4|4}}<br>{{jack|4}}<br>{{trenchbroom|4}}
| A whole number. {{bug|In {{hammer|4}}, the default value may '''not''' be quoted.<br>Other editors, like {{jack|4}} and {{trenchbroom|4}} allow quoted integers.}}
|-
| {{mono|[[float]]}}
| {{hammer3|4}}<br>{{hammer4|4}}<br>{{jack|4}}<br>{{trenchbroom|4}}
| A decimal number. The default value must be quoted unless it is a whole number with no decimal point. {{ModernConfirm|Appears to accept scientific notation such as {{mono|1.2e-3}}?}}
|-
| {{mono|[[boolean]]}}
| {{hammer4|4}}
:{{as|since}}<br>
:{{hammer++|also}}
{{slamminsrc|4|nt=4}}<br>
:{{also|{{Gmod}}}}
| A value that is either {{mono|true}} (1) or {{mono|false}} (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 {{mono|choices}} instead.
{{modernConfusion|For keyvalues it is {{mono|boolean}} but for I/O it is {{mono|bool}}.}}
{{tip|For editors without Boolean, use {{mono|choices}} instead, as so:
{{pre|Property_name_5(choices) : "Display name" : 0 {{=}}
[
    0 : "No"
    1 : "Yes"
]}} }}
|-
| {{mono|[[flags]]}}
| {{hammer3|4}} ({{mono|spawnflags}} KV only)<br>{{hammer4|4}} ({{mono|spawnflags}} KV only)<br>{{jack|4}} ({{mono|spawnflags}} KV only)<br>{{trenchbroom|4}}
| An integer value that is (supposed to be) read bitwise, making it ideal for multiple boolean values. All editors except {{trenchbroom|2}} and {{stratahammer|2}} only actually read it bitwise for the {{mono|spawnflags}} property. See [[#Flags|below]].
|-
| {{mono|choices}}
| {{hammer3|4}}<br>{{hammer4|4}}<br>{{jack|4}}<br>{{trenchbroom|4}}
| 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.
{{pre|1=
Property_name_5(choices) : "Display name" : 1 =
[
    // <value> : "Display Value"
    0 : "something"
    1 : "something else (default)"
    2 : "something completely different"
]
}}
{{bug|{{hammer|4}} sometimes treats an option set to 0 as null, stripping the key from the entity. {{jack|2}} and {{trenchbroom|2}} handle zeroes correctly.}}
You can also use strings, floats, or null as values, instead of integers, like this:
{{pre|1=
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"
    "" : "nothing" // null; strips key from entity
]
}}
In {{jack|2}}, additional help text can be added after the SmartEdit name, like so:
{{pre|1=
Property_name_5(choices) : "Display name" : 1 =
[
    0 : "something" : "This is something"
    1 : "something else (default)" : "This is something else"
    2 : "something completely different" : "This is something completely different"
]
}}
|}
<code>Flags</code> and <code>Choices</code> do not function as input/output types.<br>

{{ModernExample|{{pre|
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"
}}}}

{{note|The third value, depicted here as "Example", 15, 1.5 and 1 are the default values. Those will always be there when the entity is being placed. Some string values can also be left empty by using "". in which case there is no default value at all.}}
{{note|{{hammer}} Unlike entity descriptions, keyvalue descriptions can not make use of '''\n'''. Only workaround is to manually find out how many spaces you need to fill up a line in the description window.}}


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.
{{todo|Document supported variable types in {{hammer3|4}} and {{trenchbroom|4}}.}}
{| class="wikitable mw-collapsible" style="background:transparent" width=100%
|-
! Property
! Supported Editors
! Description
|-
| {{mono|angle}}
| {{hammer4|4}}<br>{{jack|4}}
| Adds an angle widget for this property to the entity dialog UI.
|-
| {{mono|angle_negative_pitch}}
| {{hammer4|4}}
| Identical to <code>angle</code>, except the pitch is inverted.
|-
| {{mono|axis}}
| {{hammer4|4}}
| Adds a relative 2-point axis helper.
|-
| {{mono|[[color255]]}}
| {{hammer3|4}}<br>{{hammer4|4}}<br>{{jack|4}}
| 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.
|-
| {{mono|[[color1]]}}
| {{hammer3|4}}<br>{{hammer4|4}}<br>{{jack|4}}
| 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.
|-
| {{mono|decal}}
| {{hammer4|4}}<br>{{jack|4}}
| 
* {{jack}} Identical to <code>shader</code>, except it will automatically filter to decals.wad (if loaded). Doesn't allow manually typing the texture name in [[SmartEdit]] mode.
* {{hammer4}} Identical to <code>material</code>, except it will automatically replace your search filter with <code>decals/</code> when opening the material browser.{{note|Sometimes, the material you want will be in <code>overlays/</code> or in another folder entirely.}}
|-
| {{mono|effect}}
| {{Jack|4}}
| {{confirm|Same as <code>shader</code>? Might be a leftover from Volatile3D support.}}
|-
| {{mono|filterclass}}
| {{hammer4|4}}
| Marks property as being the name of the filter to use.
|-
| {{mono|instance}}
| {{Jack|4}}
| {{confirm|Found in executable; does it work?}}
|-
| {{mono|instance_file}}
| {{hammer4|4}}
| Adds a button that brings up the file browser, letting you browse for instance files.
|-
| {{mono|instance_parm}}
| {{hammer4|4}}
| Used in {{Ent|func_instance_parms}} to define fixup variables.
|-
| {{mono|instance_variable}}
| {{hammer4|4}}
| Used in {{Ent|func_instance}} to set fixup variables.
|-
| {{mono|[[material]]}}
| {{hammer4|4}}
| Adds a button that brings up the texture browser.
|-
| {{mono|node_dest}}
| {{hammer4|4}}
| Adds an eyedropper to select a node in the 3d view
|-
| {{mono|node_id}}
| {{hammer4|4}}
:{{as|since}}
| On [[node]]s, 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.
|-
| {{mono|npcclass}}
| {{hammer4|4}}
| Adds a drop-down selection list populated by entities of the NPCClass type.
|-
| {{mono|[[origin]]}}
| {{hammer4|4}}
| The [[origin]] of the entity; automatically updates when the entity (and/or its origin) is moved in the 2D or 3D viewports.
|-
| {{mono|particle}}
| {{Jack|4}}
| {{confirm|Found in executable; what does this do? Might be a leftover from Volatile3D support.}}
|-
| {{mono|particlesystem}}
| {{hammer4|4}}
:{{as|since}}
:{{bms|also}}
| Adds a button that brings up the particle browser, letting you browse for particle systems.{{bug|The particle browser cannot read files from [[VPK]]s!{{ModernFix|You will need to extract the game's [[PCF]] files for anything to appear.}}
{{note|Works fine in {{bms|4}}.}}
}}
|-
| {{mono|pointentityclass}}
| {{hammer4|4}}
| Adds a drop-down selection list populated by entities of the <code>PointClass</code> type.
|-
| {{mono|scale}}
| {{Jack|4}}
| Acts the same as a KV named {{mono|scale}}, uniformly multiplying the scale of the displayed model or sprite.
|-
| {{mono|scene}}
| {{hammer4|4}}
| Adds a button that brings up the sound browser, letting you browse for scene files.
|-
| {{mono|script}}
| {{hammer4|4}}
:{{l4d2|since}}
| Adds a button that brings up the file browser, letting you browse for [[VScript]]s.
|-
| {{mono|scriptlist}}
| {{hammer4|4}}
:{{l4d2|since}}
| 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.}}
|-
| {{mono|shader}}
| {{Jack|4}}
| Adds a button that brings up the texture browser. Doesn't allow manually typing the texture name in [[SmartEdit]] mode.
|-
| {{mono|sidelist}}
| {{hammer4|4}}
| Adds a side selection eyedropper that allows you to choose sides (multiple with {{key|Ctrl}}).
|-
| {{mono|[[skybox|sky]]}}
| {{jack|4}}<br>{{jbep3|4}}
|
* {{jack}} - Displays a drop down list of all available skyboxes, in {{path|./gfx/env}} in {{Gldsrc|3.1}} and {{quake|3.1}} modes, or in {{path|./env}} in {{quake2|3.1}} mode. No effect in {{quake3|3.1}} mode.
* {{jbep3}} (beta) - Brings up the texture browser, with the filter set to {{mono|skybox/}} and greyed out. Selecting a texture writes the result without the preceding path, stripping the UP/DN/LF/RT/FT/BK if present.
|-
| {{mono|sound}}
| {{hammer4|4}}<br>{{jack|4}}
| 
* {{jack}} - Brings up the file browser, starting in the {{path|sounds}} directory and narrowing search to [[WAV]] files.
* {{hammer4}} - Adds a button that brings up the sound browser, letting you browse for soundscripts or raw sound files.
|-
| {{mono|[[soundscape]]}}
| {{jbep3|4}} {{strata|4}}
| 
* Adds a drop down list with all soundscapes from {{file|scripts/soundscapes_manifest|txt}}.
|-
| {{mono|[[sprite]]}}
| {{hammer4|4}}<br>{{jack|4}}
| 
* {{jack}} - Brings up the file browser, starting in the {{path|sprites/}} directory. Narrows search to only [[SPR]] files in {{quake|3.1}} and {{hl1|2}} modes, and only [[SP2]] files in {{quake2|3.1}} mode (no filter in {{quake3|3.1}} mode).
* {{hammer4}} - Identical to <code>material</code>, except it will automatically replace your search filter with <code>sprites/</code> when opening the material browser, and it will add <code>.vmt</code> to the end of the material name.
|-
| {{mono|studio}}
| {{hammer4|4}}<br>{{jack|4}}
| 
* {{hammer4}} Adds a button that brings up the model browser.
* {{jack}} - Brings up the file browser, starting in the {{path|models/}} directory. Narrows search to: 
** [[MDL]] and [[BSP]]{{confirm}} files in {{quake|3.1}} mode
** only [[MDL]] files in {{hl1|3.1}} mode
** only [[MD2]] files in {{quake2|3.1}} mode
** [[MD3]], [[ASE]], and [[LWO]] files in {{quake3|3.1}} mode).
|-
| {{mono|target_destination}}
| {{hammer4|4}}<br>{{jack|4}}
| Provides a drop-down list of other entity's <code>target_source</code> values.
* {{jack}}{{nrc}} Automatically draws a line from this entity to named entity.
|-
| {{mono|target_name_or_class}}
| {{hammer4|4}}<br>{{jack|4}}
| Marks property as another entity's <code>targetname</code> or <code>classname</code>.
|-
| {{mono|target_source}}
| {{hammer4|4}}<br>{{jack|4}}
| Marks property as being the name that other entities may target.
|-
| {{mono|vecline}}
| {{hammer4|4}}
| Adds an absolute 1-point axis helper, similar to the origin marker.
|-
| {{mono|[[vector]]}}
| {{hammer4|4}}<br>{{jack|4}}
| 3D vector property. A string consisting of three space delimited numbers.
|}

====Inputs and Outputs====
Individual inputs and outputs consist of
# the keyword {{mono|input}} or {{mono|output}},
# a name,
# a value type declaration in round brackets and
# ''(optional)'' a colon followed by a string as the description.
{{ModernExample|{{pre|
input Enable(void)
input Enable(void)  : "Enable this entity."

output OnTakeDamage(void)
output OnTakeDamage(void) : "Fired each time this breakable takes any damage."
}}}}

{| class="wikitable"
|-
! Property Type !! Supported Editors !! Description
|-
| {{mono|[[void]]}}
| {{hammer4|4}}
| No value is passed.
|-
| {{mono|[[string]]}}
| {{hammer4|4}}
| A character sequence. The default value must have quotation marks {{mono|" "}} around it.
|-
| {{mono|[[integer]]}}
| {{hammer4|4}}
| A whole number. {{bug|In {{hammer|4}}, the default value may '''not''' be quoted.<br>Other editors, like {{jack|4}} and {{trenchbroom|4}} allow quoted integers.}}
|-
| {{mono|[[float]]}}
| {{hammer4|4}}
| A decimal number. The default value must be quoted unless it is a whole number with no decimal point. {{ModernConfirm|Appears to accept scientific notation such as {{mono|1.2e-3}}?}}
|-
| {{mono|[[bool]]}}
| {{hammer4|4}}
| A value that is either {{mono|true}} (1) or {{mono|false}} (0).
{{modernConfusion|For keyvalues it is {{mono|boolean}} but for I/O it is {{mono|bool}}.
{{bug|hidetested=1|As of 20 Feb 2025, {{gmod}}'s default FGD uses {{mono|boolean}} for I/O instead of {{mono|bool}}.}} }}
|-
| {{mono|[[ehandle]]}}
| {{hammer4|4}}
| Passes the new entity that is generated by an entity. {{example|A grenade thrown; a missile launched; a headcrab that comes from a canister}}
|}

====Flags====
{{pre|style=float:right; margin:0 1em|
	spawnflags(flags) {{=}}
	[
		         1 : "Flag 01" : 0
		         2 : "Flag 02" : 0
		         4 : "Flag 03" : 0
		         8 : "Flag 04" : 0
		        16 : "Flag 05" : 0
		        32 : "Flag 06" : 0
		        64 : "Flag 07" : 0
		       128 : "Flag 08" : 0
		       256 : "Flag 09" : 0
		       512 : "Flag 10" : 0
		      1024 : "Flag 11" : 0
		      2048 : "Flag 12" : 0
		      4096 : "Flag 13" : 0
		      8192 : "Flag 14" : 0
		     16384 : "Flag 15" : 0
		     32768 : "Flag 16" : 0
		     65536 : "Flag 17" : 0
		    131072 : "Flag 18" : 0
		    262144 : "Flag 19" : 0
		    524288 : "Flag 20" : 0
		   1048576 : "Flag 21" : 0
		   2097152 : "Flag 22" : 0
		   4194304 : "Flag 23" : 0
		   8388608 : "Flag 24" : 0
		  16777216 : "Flag 25" : 0
		  33554432 : "Flag 26" : 0
		  67108864 : "Flag 27" : 0
		 134217728 : "Flag 28" : 0
		 268435456 : "Flag 29" : 0
		 536870912 : "Flag 30" : 0
		1073741824 : "Flag 31" : 0
		2147483648 : "Flag 32" : 0
	]
}}
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 {{mono|spawnflags(flags)}} follows an equals sign and a body surrounded by square brackets {{mono|[ ]}} 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 (2<sup>0</sup>=1, 2<sup>1</sup>=2, 2<sup>2</sup>=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.
{{ModernExample|{{pre|1=
spawnflags(flags) =
[
    // <flag value 2^i> : "Checkbox Display Text" : <is ticked by default?>

    1 : "something clever"   : 1
    2 : "something else"     : 0
    4 : "you said what now?" : 0
    8 : "nothing"            : 1
]
}}}}
In {{Jack|2}} and {{trenchbroom|2}}, flag descriptions can be set following the default value, like with regular KVs:
{{ModernExample|{{pre|1=
spawnflags(flags) =
[
    // <flag value 2^i> : "<SmartEdit display name>" : <is ticked by default?> : "<Description>"

    1 : "something clever"   : 1 : "This flag is clever"
    2 : "something else"     : 0 : "This flag is something else"
    4 : "you said what now?" : 0
    8 : "nothing"            : 1
]
}}}}
In {{StrataHammer|2}}, 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:
{{ModernExample|{{pre|1=
effects(flags) : "Effects" : "Controls various effects on the entity." =
[
    // flags defined same as usual
]
}}}}
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 2<sup>0</sup>, ..., 2<sup>31</sup>.
{{ModernImportant|{{hammer|4}} and {{jack|4}} only support GUI flags selection for the {{mono|spawnflags}} KV. {{StrataHammer|4}} and {{trenchbroom|4}} support GUI flags selection for any KVs using the {{mono|flags}} type.}}
{{bug|{{hammer3|4}} only properly writes the first 15 flags.}}
{{warning|{{code|spawnflags}} is an signed int in most {{src}} games, but an unsigned long in Hammer!}}
{{clr}}

==Other File Sections==
===@mapsize===
This value defines how big a map is allowed to be:
* {{hammer4}} Changes the maximum usable area.
* {{jack}} Warns the user if the maximum map size in the application settings is lower than this.
* {{trenchbroom}} 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:
* {{src}} Unless the game has been coded to allow this size, using anything beyond default values will cause [[VBSP]] to crash.
* {{goldsrc}} Unless the game has been coded to allow this size, geometry outside of the soft bounds will have no collision and be clipped off.
* {{src2}} Geometry outside of the soft bounds will have no lighting or collision and be clipped off
Default values per-engine:
; {{src|4}}, {{src2|4}}
{{pre|
@mapsize(-16384, 16384)
}}
; {{goldsrc|4}}, {{quake|4}} (protocol 666), {{quake2|4}} (pre-remaster)
{{pre|
@mapsize(-4096, 4096)
}}
; {{quake3|4}}
{{pre|
@mapsize(-65536, 65536)
}}

===@include===
If the game you are writing your FGD for has a lot in common with another game ({{hl2|2}} and {{hl2dm|2}}, for example), you can <code>@include</code> 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 <code>base.fgd</code>. For example {{hl2dm|2}} has a FGD which @include's <code>halflife2.fgd</code>, which in turn @include's the <code>base.fgd</code>.

The game or mod you are creating must ship with all FGD's that your own mod is including.
{{pre|
@include "base.fgd"
}}
The included FGD should be in the same directory as the FGD it is being called from.
{{warning|This will include '''all''' entities of the included FGD, making them all appear in your Hammer map editor even if your game does not even have these entities coded.<br>
If you only need a few base classes and entities, it would be recommended to only copy those few into your own FGD.}}
{{modernImportant|Unlike {{hammer|4}} and {{jack|4}}, {{trenchbroom|4}} doesn't currently support manually using multiple FGDs at the same time. As such, {{goldsrc|4}} mappers using TrenchBroom should add the following to the top or bottom in their game's FGD, to allow [[zhlt.fgd]] to be loaded:
{{pre|
@include "zhlt.fgd"
}}
}}

===@BaseClass===
A <code>BaseClass</code> is used to setup structures that are used by several different entities via the <code>base(BaseClassName)</code> to the main definition line of the structure.

The <code>BaseClass</code> 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.
{{pre|
@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."
]
}}

===@MaterialExclusion===
{{hammer4|only}}
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.
{{note|Any folder called <code>models/</code> will always be excluded, regardless of what is set here.}}
{{pre|
@MaterialExclusion
[
	// Names of the sub-directories we don't want to load materials from
	"console"
	"debug"
	"engine"
	"hud"
	"perftest/gman"
	"perftest/loader"
	"vgui"
	"voice"
	"vr"
]
}}

===@AutoVisGroup===
{{hammer4|only}}
This permits customizing the automatic Visgroups tab of the [[Hammer Filter Control Toolbar|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 {{Ent|func_brush}} to the list "World Details".
{{warning|Having too many AutoVisGroups can cause hammer to lag on startup and during runtime.}}
{{pre|<nowiki>
@AutoVisGroup = "Brushes"
[
    "Triggers"
    [
        "trigger_once"
        "trigger_multiple"
    ]
    "Tool Brushes"
    [
        "func_areaportal"
        "func_viscluster"
    ] 
]

@AutoVisGroup = "Tool Brushes"
[
    "Vis Clusters"
    [
        "func_viscluster"
    ]
]

</nowiki>
}}

===@version===
{{hammer++|only}}
This value defines the current FGD's version. {{hammer++|2}} uses this value to make sure the loaded FGD is up to date. For example:
{{pre|@version(8)}}

===@ExtendClass===
{{hammer++|only}}
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===
{{modernDeprecated|This class existed in Worldcraft 1.1, but has been removed since Worldcraft 1.6 or earlier; modern editors do ''not'' support this class. Trenchbroom silently ignores it, whereas Hammer and Jack report it as a syntax error.}}
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.
{{pre|<nowiki>@Main =
[
    Name: "Quake"
    Palette: "wc.pal"
    DefaultClass: "func_door"
]
</nowiki>}}

==Source 2 Additions==
The following things have been found in {{Source2|2}} FGD files. These will not work in Source 1.

{{todo|Find more things that are not listed here. Explain what these do. So far only occurrences of {{hla}} FGD's have been pasted here for documenting them.}}

===Classes===
{| class="wikitable"
|-
! Class Name
! Description
|-
| {{mono|@OverrideClass}}
| This can be used to quite literally overwrite data of existing entities, as well as adding new keyvalues and inputs/outputs.
|-
| {{mono|@CableClass}}
| {{todo|Explain what this does.}}<br>{{hla}} Seen in models_gamedata.fgd
|-
| {{mono|@PathClass}}
| {{todo|Explain what this does.}}<br>{{hla}} Seen in base.fgd
|}

;Examples of these Classes
{{ExpandBox|title=@OverrideClass|{{pre|<nowiki>
// Add an override of player start in order to add it to the ui.
@OverrideClass
	metadata
	{
		entity_tool_name = "Player Start"
		entity_tool_group = "Player"
		entity_tool_tip = "Entity which specifies where the player will start."
	}
= info_player_start :
[
]

@OverrideClass = npc_cscanner
[
	//Adds one single input to the npc_cscanner entity, which already existed in HL2 and is in halflife2.fgd
	//Doing this is easier than completely redefining the entire entity.
	input SpawnAsAltScanner(void): "Spawns the Russell skin/bodygroup scanner"
]
</nowiki>}}}}

{{ExpandBox|title=@CableClass|{{pre|<nowiki>
@CableClass = cable_static
[
]
@CableClass base( Targetname, Parentname, Global, RenderFields, Glow, EnableDisable) sphere(fademindist) sphere(fademaxdist) = cable_dynamic
[
	secondary_material(material) : "Secondary Material" : "" : "Optional secondary material, can be selected using Skin(1)"
	lightingorigin(target_destination) : "Lighting Origin" : "" : "Select an entity to specify a location to sample lighting from, instead of using this entity's origin."
	disableshadows(boolean) [ group="Misc" ] : "Disable Shadows" : 0 : "Used to disable dynamic shadows on this entity."

	// Inputs
	input TurnOn(void) : "Make the prop visible."
	input TurnOff(void) : "Make the prop invisible."
	input Skin(integer) : "Changes the model skin to the specified number."
	input EnableCollision(void) : "Enable collision on the prop."
	input DisableCollision(void) : "Disable collision on the prop."
	input SetNavIgnore(boolean) : "Enable and disable NAVIgnore on the prop."
	input DisableShadow(void) : "Turn shadow off."
	input EnableShadow(void) : "Turn shadow on."
	input AlternativeSorting(bool) : "Used to attempt to fix sorting problems when rendering. True activates, false deactivates"
	input SetRenderAttribute(string) : "Set the value of a render attribute used in material dynamic expressions. Examples: $myfloat=0.25 $myfloat4=1.0,0.0,1.0,1.0"
]
</nowiki>}}}}

{{ExpandBox|title=@PathClass|{{pre|<nowiki>
@PathClass base(Targetname) tags( Particles ) particle_rope()
	metadata
	{
		default_interpolation = "linear"
	}
= path_particle_rope
[
	effect_name(particlesystem) [report] : "Particle System Name" : "particles/entity/path_particle_cable_default.vpcf"
	start_active(boolean) : "Start Active" : 1 : "Will the particle system be visible on spawn"
	max_simulation_time(float) : "Max Time To Simulate" : 0 : "Max number of seconds to run the particle simulation for. A value of 0 means run the simulation indefinitely."
	particle_spacing(float) : "Spacing" : 32 : "Units between the individual partcles in the rope simulation."
	slack(float) : "Slack" : "0.5" : "Controls the amount the rope will drop between path nodes. Generally between 0.0 and 1.0, the value is a multiplier on the distance that particles on path can seperate relative to their initial distance."
	radius(float) : "Radius" : "4.0" : "Radius of the rope."
	static_collision( bool ) : "Create Static Collision" : "0" : "Create a static physics representation of the path. Note the collision is generated based on the path, movement applied by the particle system will not be included."
	surface_properties(surface_properties) : "Surface Properties" : "" : "Surface properties to apply to the static collision if generated"
	color_tint(color255) : "Color Tint" : "255 255 255"
	
	// Inputs
	input Start(void) : "Tell the particle system to start emitting."
	input Stop(void) : "Tell the particle system to stop emitting."
	input StopPlayEndCap(void) : "Tell the particle system to stop emitting and play its End Cap Effect."
	input DestroyImmediately(void) : "Destroy the particle system and remove all particles immediately."
	input SetRadius( float ) : "Set the radius parameter provided the particle system"
	input SetSlack( float ) : "Set the slack parameter which may be used by the particle system to determine how much the rope droops."
	input DisablePin( string ) : "Disable the contraint which pins a particle to the specified path node."
]
</nowiki>}}}}
===Other commands===
{| class="wikitable"
|-
! Class Name
! Description
|-
| {{mono|@Exclude}}
| This can exclude individual entities that are in @include'd FGD's. One entity per line
|-
| {{mono|@EntityGroup}}
| {{todo|Explain what this does.}}<br>{{hla}} Seen in hlvr.fgd
|-
| {{mono|@struct}}
| {{todo|Explain what this does.}}<br>{{hla}} Seen in workshop_addoninfo.fgd
|-
| {{mono|@ModelGameData}}
| Custom game-based properties that will be embedded in the model's [[$keyvalues]]. These will show up in ModelDoc as GameData nodes.<br><br>{{hla}} Seen in models_gamedata.fgd
|-
| {{mono|@ModelBreakCommand}}
| {{todo|Explain what this does.}}<br>{{hla}} Seen in models_gamedata.fgd<br>Seems to work simillar to [[$collisiontext]]
|-
| {{mono|@ModelAnimEvent}}
| {{todo|Explain what this does.}}<br>{{hla}} Seen in models_base.fgd<br>Seems to work simillar to [[Animation_Events]] in [[$sequence|Sequences]].
|-
| {{mono|1=Metadata<br> {<br> entity_tool_name = <string><br> entity_tool_tip = <string><br> entity_tool_group = <string><br> }}}
| {{todo|Explain what this does.}}<br>{{hla}} Seen in hlvr.fgd
|-
| {{mono|Deprecated()}}
| Marks a property as depracated and no longer in use.
|}

;Examples of these commands
Below are expandable examples of the above listed commands.<br>
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.

{{ExpandBox|title=@exclude|{{pre|
// Excluded entities. These are entities that are included from lower level fgd files that aren't 
// functional or useful in this mod. Excluding them removes them from the list of entities aviable 
// in Hammer or any other tool that loads the fgd. If support is added for any of the entities the 
// exclude can simply be removed.

// These entities have been excluded because are deprecated light entities which are
// explictly not supported, don't add these back unless you are working on lighting.
@exclude color_correction_volume
@exclude env_fog_controller
@exclude env_time_of_day
@exclude env_lightglow
@exclude env_particlelight
@exclude env_sun
@exclude fog_volume
@exclude info_lighting
@exclude light_dynamic
@exclude light_irradvolume
@exclude point_spotlight
@exclude postprocess_controller
@exclude shadow_control
}}}}

{{ExpandBox|title=@EntityGroup|{{pre|<nowiki>
// Entity groups. This list specifies which entity groups will show up in the entity tool and in what
// order. If an entity specifies a group that is not in this list it will not be displayed in the tool.
// This allows the mod specific fgd to control the ui.
@EntityGroup "Player" {	start_expanded = true }
@EntityGroup "Lighting" { start_expanded = true }
@EntityGroup "Fog & Sky" { start_expanded = true }
@EntityGroup "NPCs" { start_expanded = true }
@EntityGroup "Items"
@EntityGroup "Ammo"
@EntityGroup "Logic"
</nowiki>}}}}

{{ExpandBox|title=@struct|{{pre|<nowiki>
@struct = map_extension :
[
	parent_map(string) : "Parent Map" : "" : "This is the map that you are extending (eg. <font color='cyan'>{{mono|a1_intro_world}}</font>) - when it loads, your extension map will also be loaded."
	extension_map(string) : "Extension Map" : "" : "Name of a map to overlay on top of the parent map."
]
</nowiki>}}}}

{{ExpandBox|title=@ModelGameData|{{pre|<nowiki>
@ModelGameData = prop_data
[
	base(propdataname) 		: "Base Prop" : : "Base keys (entry from propdata.txt)"
	allowstatic(boolean) 	: "Allow As Static Prop" : 0
	bakelighting(boolean)	: "Bake Lighting As Static Prop" : 1
	damage_table(choices) 	: "Damage Table" : "" : "" =
	[
		""						:	"Inherit Default"
		"player"				:	"Player"
		"player_vehicle"		:	"Player Vehicle"
		"npc"					:	"NPC"
		"glass"					:	"Glass"
		"props"					:	"Props"
		"prevent_impact_damage"	:	"Prevent All Impact Damage"
	]
	dmg.bullets(float) 		: "Damage Bullets" : -1
	dmg.club(float) 		: "Damage Club" : -1
	dmg.explosive(float) 	: "Damage Explosive" : -1
	dmg.fire(float) 		: "Damage Fire" : -1
	health(float) 			: "Health" : -1
	spawn_motion_disabled(boolean) : "Spawn as Motion-Disabled" : 0
]
</nowiki>}}}}

{{ExpandBox|title=@ModelBreakCommand|{{pre|<nowiki>
@ModelBreakCommand base(base_break_force)
= break_uniform_burst : "Applies a radial burst to breakpieces outwards from the influence point (default is the origin of the model)"
[
	burst_scale(float) [ min="0", max="500" ]		: "Burst Scale"					: 0		: "Velocity added to each piece (radially away from the influence point)"
	burst_randomize(float) [ min="0", max="500" ]	: "Burst Randomize"				: 0		: "Magnitude of random vector that will be added to the burst velocity"
]

@ModelBreakCommand base(base_break_force)
= break_flip_pieces : "Applies an angular 'flip' to breakpieces (like objects tipping over from an explosion or flower petals opening) causing them to tip outwards from the influence point (default is the origin of the model)"
[
	burst_scale(float) [ min="-500", max="500" ]	: "Flip Scale"					: 0		: "Angular velocity added to each piece (Positive value will cause pieces to flip 'head-first' away from the influence point, negative is 'feet-first')"
	burst_randomize(float) [ min="0", max="500" ]	: "Flip Randomize"				: 0		: "Largest possible value that will be randomly added/removed to Flip Scale for each piece"
]

@ModelBreakCommand base(base_break_force)
= break_twist_pieces : "Applies an angular 'twist' to breakpieces, causing them to roll around the radial axis outward from the influence point (default is the origin of the model)"
[
	burst_scale(float) [ min="-500", max="500" ]	: "Twist Scale"					: 0		: "Angular velocity added to each piece"
	burst_randomize(float) [ min="0", max="500" ]	: "Twist Randomize"				: 0		: "Largest possible value that will be randomly added/removed to Twist Scale for each piece"
]
</nowiki>}}}}

{{ExpandBox|title=@ModelAnimEvent|{{pre|<nowiki>
@ModelAnimEvent = AE_CL_PLAYSOUND_ATTACHMENT
[
	name(sound) [report] : "Sound"
	attachment(model_attachment) : "Attachment"
	stop_on_seq_change(bool) : "Auto-stop on sequence change or death" : "0"
	use_layer_sequence(bool) : "Use Layer Sequence" : "0"
	tags(string)				: "Tags"
]
@ModelAnimEvent = AE_COMPANION_PRODUCE_FLARE 
[
	attachment(model_attachment) : "Attachment"
]

@ModelAnimEvent = AE_STRIDER_SHOOTMINIGUN 
[
	target(string) : "Target"
]
</nowiki>}}}}

{{ExpandBox|title=Metadata|<syntaxhighlight lang=text highlight=2-7>
@PointClass base(BasePropPhysics, Targetname, Parentname ) model( "models/props_combine/health_charger/health_vial.vmdl" )
	metadata
	{
		entity_tool_name = "Health Station Vial"
		entity_tool_tip = "Vial used to power a health station"
		entity_tool_group = "Items"
	}
= item_hlvr_health_station_vial : "Health Vial"
[
	vial_level(float) : "Health Vial Level (0-1)" : "1" : "Amount of health the vial starts with."
]</syntaxhighlight>}}

{{ExpandBox|title=deprecated()|{{pre|<nowiki>
@ModelAnimEvent deprecated() = AE_STRIDER_FOOTSTEP_LEFT [ ]
@ModelAnimEvent deprecated() = AE_STRIDER_FOOTSTEP_RIGHT [ ]
@ModelAnimEvent deprecated() = AE_STRIDER_FOOTSTEP_BACK [ ]
@ModelAnimEvent deprecated() = AE_MARINE_FOOTSTEP [ ]
@ModelAnimEvent deprecated() = AE_FOOTSTEP_LEFT [ ]
@ModelAnimEvent deprecated() = AE_FOOTSTEP_RIGHT [ ]
@ModelAnimEvent deprecated() = AE_SV_FOOTSTEP_LEFT [ ]
@ModelAnimEvent deprecated() = AE_SV_FOOTSTEP_RIGHT [ ]
@ModelAnimEvent deprecated() = AE_ANTLION_FOOTSTEP_HEAVY [ ]
@ModelAnimEvent deprecated() = AE_ANTLION_FOOTSTEP_SOFT [ ]
</nowiki>}}}}

==Files==
The FGD files of a {{src|nt=0|4.1}} game can be found under <code><steam directory>/steamapps/common/<full game name>/bin/*.fgd</code>, for example <code>.../common/Half-Life 2/bin/halflife2.fgd</code>.

==See also==
* [[:Category:FGD]]
* [[Base.fgd]]

==External links==
* [https://github.com/Pinsplash/SEFGD SE FGD's] Updated FGD's for some Valve games, made by Pinsplash.
* [https://github.com/Crowbar-Sledgehammer/forge-game-data-language Forge Game Data Language] <code>.fgd</code> syntax highlighting available in textmate format (SublimeText Compatible)

[[Category:File formats|fgd]]
[[Category:Files|fgd]]
[[category:Hammer|fgd]]