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.
For more about common game object types and behaviors, see Scripting.
This page assumes some familiarity with common Quake mapping terms.
History
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 TrenchBroom for Quake 1 / Half-Life engines.
Syntax (basic)
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:
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.
Entity types and settings (basic)
There are three core FGD entity types: point, solid, and base.
@PointClass
begins 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)model
(path, skin, frame, scale)
displays a 3D model for the entity. This can get a little complicated, see Display models for entities.
@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 (basic)
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
Type: there are four (4) basic property types:
string
,integer
,choices
(multiple choice integer enumeration), andflags
(bitmask).flags
are 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 brush entity definition that demonstrates all four property types:
Display models for entities
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:
An example of a basic hardcoded model from Quake.FGD:
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:
An example with placeholders from HalfLife.FGD:
TrenchBroom's FGD flavor also supports conditional expressions. An example with expressions:
For more on placeholders and expressions, see Trenchbroom Manual > "Display models for entities":
FGD resources and links
FGD examples
FGD authoring
Valve Developer Union: "Anatomy of an FGD (and How to Write Your Own)" is a great introduction
Valve Developer Union: "Advanced FGD Editing Made Easy" shows off tips and tricks
Valve Developer Community: "FGD" goes into detail about Source Engine 1 specific FGD extensions and quirks... not useful for TrenchBroom though
FGD parsers
C++ FGD parser example: TrenchBroom (via GitHub)
C# FGD parser library: Sledge.Formats (via GitHub)
Last updated