Forge Game Data is a descriptive file format used by level editors to define the list of entities and their keys and spawnflags that will be available during level creation.
In Worldcraft and derived editors, the FGD is also used to give descriptive names to entity keys with SmartEdit enabled, as well as provide default values, dropdown menus of available values and colour pickers for the appropriate types of keys.

The "Forge" part of the name comes from The Forge, the level editor that eventually became Worldcraft, and in turn both Hammer and J.A.C.K.

---

Descriptive, not prescriptive

FGD files can only describe entities and properties that are already defined in the gamecode of the game/mod you're working on.
This means that it's not possible to define new entities, keys or spawnflags solely within a FGD file.

Formatting

The format is a plaintext type structured as a list of entity definitions.
Each entity begins with a declaration, followed by a list of properties (keys and spawnflags) if any.

Declaration

Here's an example of a simple entity declaration:

@PointClass base(Targetname) size(-4 -4 -4, 4 4 4) = my_entity : "My point entity" []

It begins with specifying its entity class which may be one of three values:

• @PointClass: The class all point entities belongs to, which is all entities not made of brushes, such as sprites and monsters.
• @SolidClass: All brush entities belongs to this class, such as func_door and trigger volumes such as trigger_multiple.
• @BaseClass: This isn't used by any entity directly but instead is a base that other entity declarations can inherit from.

This is followed by various optional parameters:

• base(): Lists one or more base classes to inherit properties from, as a comma-separated list.
• size(): Used by point entities to define the size of the cube used to display it, using the minimum X, Y, Z coordinates followed by the maximum X, Y, Z coordinates.
• color(): Can be used to set the colour of the display cube for point entities, in R, G, B (0-255). Otherwise it will use the default magenta.
• iconsprite(): Tells the editor to render the point entity using a sprite instead of a cube, e.g. iconsprite("sprites/light.spr").
• studio(): Can be used to specify a specific model for the editor to render the point entity with instead of a cube, similar to iconsprite().

After the parameters follows an equality sign and the entity's name (in the code), which is "my_entity" in this case.

Lastly we have a colon and the description for our entity within quotation marks.

Properties

Following the entity declaration we list its properties (keys and spawnflags) in square brackets.

@PointClass base(Targetname) size(-4 -4 -4, 4 4 4) = my_entity : "My point entity"
[
    health(integer) : "Health" : 10
    scale(string) : "Scale"
    skin(choices): "Hat color" : 0 =
    [
        0 : "Red"
        1 : "Yellow"
        2 : "Orange"
        3 : "Black"
    ]

    spawnflags(flags) =
    [
        1: "Start on" : 0
        2: "Prefer bananas" : 1
    ]
]

Properties are defined with the key and its type in parenthesis, next is its descriptive name in quotation marks, and lastly an optional default value for the property, all three separated by colons.
A property using the choices type can additionally list preset values in square brackets after an equality sign, with each item starting with the value following the descriptive name, separated by a colon.

The entity's spawnflags are simply another property in this list, using spawnflags(flags) as the key. The flags themselves are listed within square brackets with the flag value first (1, 2, 4, 8, etc), then its descriptive name, and finally whether it should be disabled (0) or enabled (1) by default. Again, all three are separated by colons.

Property types

The entity's properties must use one of several types which lets the editor handle these in different ways:

• string: Used for text and decimal numbers.
• integer: Intended to be used for integer (whole) numbers only.
• flags: As far as I know is only used for the spawnflags key.
• studio: Used with the model key and can be used by editors use a file picker in the models folder, and to use this model to display the entity with.
• sprite: Similar to studio but for sprites.
• color255: Lets the editor know the value can be set using a colour picker
• choices: Allows the editor to display a dropdown of preset values for the key.

---

Sources and further reference

• FGD page on Valve Developer Community
• Anatomy of an FGD (and How to Write Your Own)
• Advanced FGD Editing Made Easy