FGD

What Is It?

FGD 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.

History

FGD stands for Forge Game Data. While Hammer was originally called Worldcraft, it was developed under the name The Forge. Due to trademark issues, that name couldn't be used for the final version.

File format

The FGD file follows a fairly simple format. It is a script file that sets up entity structures and relationships for Hammer. In order to explain the structure, I'll break down the various parts of the Half-Life 2 FGD below.

[The Half-Life 2 FGD (halflife2.fgd) can be found in your Steam folder, in the SteamApps/SteamUsername/sourcesdk/bin folder]

//====== Copyright © 1996-2005, Valve Corporation, All rights reserved. =======
//
// Purpose: Half-Life 2 game definition file (.fgd) 
//
//=============================================================================

Comments are defined simply by starting a line with //. They can be preceded by spaces or tabs.

@include "base.fgd"

If the game you are writing your FGD for has a lot in common with another game (Half-Life 2 and Counter-Strike: Source, for example), you can include a file that has all of the common structures defined in it. The FGDs for Half-Life 2 and Counter-Strike: Source both include the base.fgd file, and the FGD for Half-Life 2 Deathmatch includes the halflife2.fgd file.

@BaseClass base(BaseNPC) = TalkNPC
[
	UseSentence(string) : "Use Sentence"
	UnUseSentence(string) : "Un-Use Sentence"
]

A BaseClass is used to setup structures that are used by several different entities. They are referenced in an entity structure by adding 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. (We'll discuss the complete entity structure below).

@PointClass base(Targetname, Origin) = example_entity : "example"
[
	spawnflags(Flags) =
	[
		32 : "A flag"
		64 : "Another flag" : 1
	]

	foobarname(string) : "Name" : : "Name of foobar"
	foobargroup(string) : "Group" : "Squad1" : "Name of foobar group"
	foo(float) "Floating point number" : "100.7" : "Decimal points = fun"
	something(integer) : "first number" : 0 : "This is a number"
	something2(choices) : "second number" : "Your choice of numbers!"
	[
		0 : "Default"
		1 : "Something"
		2 : "Another Thing"
	]

	// Outputs
	output OnSomethingHappened(void) : "Fires when something happens"
	output OnSomethingElse(void) : "Fires when something else happens"

	// Inputs
	input DoSomething(void) : "Do something"
]

Above is a generic example of an entity structure as defined in the FGD. Let's break it down bit by but, starting with the first line:

• @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 npcclass property type, below.
• @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".

• base(Targetname, Origin) - Things between the type declaration and the "=" character help to define properties of the entity and 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.)

• base( BaseClass1, BaseClass2, ... ) - This lets you attach previously defined BaseClasses (see above) to an entity. You can specify multiple BaseClasses, separated by a comma.
• color( rrr ggg bbb ) 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.
• 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.
• 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 radius property. Multiple spheres can be defined for one entity.
• studio( "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 "model" property will be used, if available.
• studioprop( "path/model.mdl ) - Similar to studio(), but prop specific.

• example_entity : "example" - This is the entity's name followed by a description. The description is displayed in Hammer when you click on the Help button inside the entity property dialog. For visual ease, the description can span multiple lines by joining "blocks of text" with the plus (+) character. For example:

@PointClass = example_entity :

"This is an example description for"+

"this example entity. It will appear"+

" in the help dialog for this entity"

[

entity properties go here

]

• entity properties - 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 short description, a default value, and a long description. The most common properties are:

• string - This creates a property of the string type.

name(string) : "Short description" : "Default" : "Long description"

• integer - This creates a property of the integer type.

name(integer) : "Short description" : 1 : "Long description"

• 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.

name(float) : "Short description" : "1.5" : "Long description"

There are also two common special case property types, choices and flags, that follow a slightly different format.

• choices - A property of this type lets you setup a number of distinct choices. Their format is similar to the other types:

name(choices) : "Short description" : "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:

name(choices) : "Short description" : "models/something02.mdl" =
[

"models/something01.mdl" : "something"

"models/something02.mdl" : "something else (default)"

"models/something03.mdl" : "something completely different"

]

• Flags - The Flags property type lets you setup what will appear in the Flags portion of the entity property dialog. It is setup similar to the choices property type. The flags are all powers of 2 - 2⁰, 2¹, 2², 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

]

Note that spawnflags is always the name of this property.

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.
• color255 - 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.
• filterclass - ?
• material - adds a button that brings up the material browser.
• npcclass - adds a drop-down selection list populated by entities of the NPCClass type.
• pointentityclass - adds a drop-down selection list populated by entities of the PointClass type.
• scene - adds a button that brings up the file browser, letting you browse for scene files.
• sidelist - this is a test, ignore for now.
• sound - adds a button that brings up the file browser, letting you browse for sound files.
• sprite - adds a button that brings up the file browser, letting you browse for sprite files.
• studio - adds a button that brings up the file browser, letting you browse for model files.
• target_destination - marks property as targeting something.
• target_name_or_class - ?
• target_source - marks property as being the name that other entities may target.

Left To Cover

• inputs and outputs
• closing notes