FGD Last edited 17 hours ago2024-07-15 12:37:23 UTC

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: This is followed by various optional parameters: 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:
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), J.A.C.K. and TrenchBroom (GoldSrc).

Sources and further reference

Comments

You must log in to post a comment. You can login or register a new account.