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.

Note

There is no enforced standard for the descriptive names for keys (the name displayed with SmartEdit enabled). While different FGDs may agree on same or similar descriptive names (such as "Name" for the key targetname, or "Delay before close" for the key wait) they're not guaranteed to do so, which may cause confusion when discussing entity properties. In these cases one may opt to use the key directly instead of using its descriptive name.

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.

Note

Both entity declaration parameters and property types are editor dependent. The parameters and types described here are common ones supported by both Hammer and J.A.C.K., the latter of which supports additional parameters/types.

Includes

You may include definitions from another FGD by placing @include "base.fgd" at the very top of the FGD. This is useful when your mod has a lot of entities common with another mod as you can then gather all common entities in the base FGD and include it in each mod's FGD.

This feature only works in Hammer 4 (Source) and TrenchBroom (GoldSrc).

Sources and further reference

kimilil

Commented 2 months ago2024-09-02 18:20:23 UTC Comment #106356

The FGD grammar is technically whitespace-agnostic. You can for example spread the @ThingClass declaration across multiple lines in cases where there's a lot of attrs() with long values, for readability sake. The problem is that third party programs that doesn't use a proper DSL parser and parses directly, makes assumption that it's always on one line. Worse still there's one snapshot of TB that assumes property lines must be indented, and breaks with a custom FGD written with poor indent discipline.

FGD Last edited 4 months ago2024-07-15 12:35:20 UTC