FGD file format
entity definition file / mapping aid for Quake-era level editors
FGD is a common text file format used across several Quake-era level editor tools (like TrenchBroom) to define entities.
An entity is basically any game object that isn't static world geometry -- NPCs, items, lights, sounds, doors, player spawns, etc. Anything that can move, change, or react.
Note that an FGD is just an editing aid that adds templates and documentation. It does not implement any in-engine game functionality by itself. It's only there to help level designers understand and configure objects. Technically you don't need an FGD to map for a game; in theory you could simply memorize and validate all the level scripting data manually.
This page assumes some familiarity with common Quake mapping terms.
FGD stands for "Forge Game Data", leftover from when the Half-Life 2 level editor Hammer used to be the Half-Life 1 editor Worldcraft, and before that when it was a Quake tool called Forge.
Because multiple studios, engines, and editor tools have used FGD, there are several different "flavors" of FGD. For example, Valve added syntax to support its unique entity input / output scripting system in Source Engine. There is no formal FGD file specification standard.
This page covers only the basic common FGD syntax used in TrenchBroom for Quake 1 / Half-Life engines.
FGD is a text-based format. We recommend using UTF-8 encoding to support more languages. TrenchBroom requires UTF-8 without BOM.
Each entity entry follows this pattern:
// comments begin with "//"
@EntityType EntitySettings() = EntityClassName : "In-Editor Help"
[
propertyKey(propertyType) : "In-Editor Name" : defaultValue : "In-Editor Help"
]
Here's a simple entity example, a zombie NPC that is 32 map units wide and 64 map units tall, with one property called "Health":
@PointClass size(-16 -16 -32, 16 16 32) = monster_zombie : "A humanoid zombie with 100 health (default)."
[
health(integer) : "Health" : 100 : "Initial health points. Set to -1 to make the zombie start sleeping."
]
Note how the in-editor help text is very important. Tell the level designer about important functionality that isn't obvious, give advice or tips / tricks.
There are three core FGD entity types: point, solid, and base.
@PointClassbegins a point entity definition, like an NPC or a lightsize(minX minY minZ, maxX maxY maxZ)is the axis-aligned bounding box (AABB) size of the point entity, defined as two 3D vectors, the min extent (smallest corner) and the max extent (largest corner)
@SolidClassbegins a brush entity definition, like worldspawn or func_wall@BaseClassbegins an entity base template; you can set entities to "inherit" a common base.base(BaseClassName1, BaseClassName2, ... )set an entity to include the listed base class(es)... you can also set a base to include a base, so this feature can be quite powerful / useful but beware of recursion
For example, if all monsters in your game have health, then you could create a MonsterBase with a health property, and then set all monster types to include that MonsterBase:
@BaseClass = MonsterBase
[
health(integer) : "Health" : 100 : "Initial health as a percentage."
]
@PointClass base(MonsterBase) size(-16 -16 -32, 16 16 32) = monster_zombie : "Humanoid zombie"
[
// zombie will automatically inherit the health property from MonsterBase
]
@PointClass base(MonsterBase) size(-32 -32 -64, 32 32 64) = monster_troll : "Big melee monster"
[
// troll will automatically inherit the health property from MonsterBase
]
Entity properties are typed key-value pairs that follow this general pattern:
propertyKey(type) : "In-Editor Name" : defaultValue : "In-Editor Help"- Key name: like a variable name, usually a lower case string
- sometimes with an underscore at the beginning to denote that it is a compiler-time property that won't be present in-game
- Type: there are four (4) basic property types:
string,integer,choices(multiple choice integer enumeration), andflags(bitmask).flagsare a set of boolean (true / false) values, stored together as a single number through the magic of math (bitmask)- in most level editors, an entity can only have a single flags property and it must be called "spawnflags"
- Value: whatever the level designer typed into the level editor
An example entity definition that demonstrates all four property types:
@SolidClass = func_door : "A simple sliding door"
[
// note that there is no defaultValue specified below; default is optional
targetname(string): "Name" : : "Named doors won't open automatically. Leave blank to open automatically."
speed(integer): "Move Speed" : 60 : "How fast the door opens / closes, in map units per second."
_shadow(choices): "Cast Shadows" : 1 : "Should the door block light? default: On" =
[
0 : "Off"
1 : "On"
2 : "Two Sided"
3 : "Shadows Only"
]
// in most level editors, flags type MUST be called "spawnflags"
spawnflags(flags) =
[
1 : "Starts Locked" : 0
2 : "Starts Open" : 0
]
// a flag follows this syntax:
// PowerOfTwoNumber : "Flag Label" : DefaultBoolValue
]
- Valve Developer Community: "FGD" goes into detail about Source Engine 1 specific FGD extensions and quirks... not useful for TrenchBroom though
Last modified 1yr ago