FGD file format
entity definition file / mapping aid for Quake-era level editors
Last updated
entity definition file / mapping aid for Quake-era level editors
Last updated
FGD is a common text file format used across several Quake-era level editor tools (like ) 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.
For more about common game object types and behaviors, see .
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 the core FGD syntax used in 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 .
Each entity entry follows this pattern:
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":
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.
@PointClass begins a point entity definition, like an NPC or a light
size(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)
@SolidClass begins a brush entity definition, like worldspawn or func_wall
@BaseClass begins 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 BaseClass Monster with a health property, and then set all monster types to include that Monster base:
Entity properties are typed key-value pairs that follow this general pattern:
keyName(type) : "In-Editor Display 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
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 brush entity definition that demonstrates all four property types:
TrenchBroom can display 3D models for point entities, if the FGD file specifies it. This is useful for placing NPCs or props, where previewing model size / rotation / appearance is useful.
TB uses Asset Importer (AssImp) which has basic support for most 3D formats (.OBJ, .FBX, etc).
For certain model formats like Quake .MDL or Half-Life .MDL, you can also swap textures or preview animation frames based on the entity properties. See below for usage.
Remember: model() is TrenchBroom only, and won't necessarily work in other editors.
The most basic hardcoded usage looks like:
However, hardcoding the model settings in the FGD can be too limiting for swappable "prop" entities or NPCs with multiple skins or scripted animation.
To support map-defined per-entity model display settings, TrenchBroom's can parse dynamic FGD placeholders with JSON-like syntax (curly braces, named parameters in quotes):
Replace "MODEL" or "FRAME" etc. with the keyvalue property name you want, and TrenchBroom will swap in the actual value for the placeholder.
An example generic "prop" entity that uses placeholders:
TrenchBroom's FGD flavor also supports conditional expressions. An example with expressions:
model(path, skin, frame, scale)
displays a 3D model for the entity. This can get a little complicated, see .
Type: there are four (4) basic property types: string, integer, choices (multiple choice integer ), and flags (bitmask).
flags are a set of boolean (true / false) values, stored together as a single number through the magic of math ()
An example of a basic hardcoded model from :
An example with placeholders from :
For more on placeholders and expressions, see
is a great introduction
shows off tips and tricks
goes into detail about Source Engine 1 specific FGD extensions and quirks... not useful for TrenchBroom though
C++ FGD parser example:
C# FGD parser library:
