04/13/97 Worldcraft University Class - The FGD file format
<autolycus> ok, todays class is about Worldcraft's FGD file
<autolycus> first off, FGD stands for Forge Game Data...Ben ended up calling it Worldcraft because of a copyright conflict with someone elses product
<autolycus> an FGD entry breaks down into a fairly simple formula:
<autolycus> @ClassType base([, ...]) size(x y z, x y z) color(RRR GGG BBB) = : ""
<autolycus> [
<autolycus>    key(var-type) : "" : default value
<autolycus> ]
<autolycus> The @ClassType can be one of three things: BaseClass, PointClass or SolidClass
<autolycus> PointClass and BaseClass both define the actual entities for use in Quake
<autolycus> More on those after
<autolycus> First, the BaseClass, which is quite important if you plan to create many entities
<autolycus> BaseClasses are used to define building blocks for entities
<autolycus> The following example, for instance:
<autolycus> @BaseClass = Appearflags [
<autolycus>    spawnflags(Flags) =
<autolycus>    [
<autolycus>       256 : "Not in Easy" : 0
<autolycus>       512 : "Not in Normal" : 0
<autolycus>       1024 : "Not in Hard" : 0
<autolycus>       2048 : "Not in Deathmatch" : 0
<autolycus>    ]
<autolycus> ]
<autolycus> @BaseClass base(Appearflags) size(-16 -16 -32, 16 16 32) color(0 255 0) = PlayerClass []
<autolycus> @PointClass base(PlayerClass) = info_player_start : "Player 1 start" []
<autolycus> ...covers almost everything in the FGD format, although in a rather simple method
<autolycus> The first entry, for Appearflags, defines itself as a BaseClass. Appearflags will be used to make other entities have the ability to only appear at certain skill levels.
<autolycus> The second entry, which is also a BaseClass, creates PlayerClass. By specifying the base(Appearflags), PlayerClass becomes a descendant of Appearflags, and gains all its properties.
<autolycus> Also, the size() and color() parts of the definition will let Worldcraft know how to display the entity when you are making a level.
<autolycus> The third entry finally defines an entity, info_player_start, which is a PointClass. It is a descendant of PlayerClass, and therefore has the properties defined in both PlayerClass and Appearflags.
<autolycus> If you were to write this entity out by itself, you would write:
<autolycus> @PointClass size(-16 -16 -32, 16 16 32) color(0 255 0) = info_player_start : "Player 1 start"
<autolycus> [
<autolycus>    spawnflags(Flags) =
<autolycus>    [
<autolycus>       256 : "Not in Easy" : 0
<autolycus>       512 : "Not in Normal" : 0
<autolycus>       1024 : "Not in Hard" : 0
<autolycus>       2048 : "Not in Deathmatch" : 0
<autolycus>    ]
<autolycus> ]
<autolycus> thats only 10 lines of code...thats not soooo bad...right?
<autolycus> but by defining the two BaseClasses above, it also allows you to define the following...
<autolycus> @PointClass base(PlayerClass) = info_player_start : "Player 1 start" []
<autolycus> @PointClass base(PlayerClass) = info_player_deathmatch : "Player deathmatch start" []
<autolycus> @PointClass base(PlayerClass) = info_player_coop : "Player cooperative start" []
<autolycus> @PointClass base(PlayerClass) = info_player_start2 : "Player episode return point" []
<autolycus> @PointClass base(PlayerClass, Targetname) = info_teleport_destination : "Teleport destination" []
<autolycus> ...in 5 lines of code, instead of the 50 lines it would otherwise require to define each entity separately.
<autolycus> fifth entity there, info_teleport_destination, also includes the BaseClass Targetname, which inserts a Name field in Worldcraft's SmartEdit properties for that entity, and a "targetname" key in the .MAP.
<autolycus> ok, the next part of that formula i'll cover is base([, ...]), size(x y z, x y z), color(RRR GGG BBB)
<autolycus> the base() part is used to include the BaseClass names as covered above
<autolycus> you can include a bunch of BaseClasses by going base(Target, Targetname, Appearflags, Whatever, Else, You, Want)
<autolycus> there isnt really a limit
<autolycus> a base entry is not required tho, and an entity will work perfectly fine with no base() declarations
<autolycus> The BaseClasses in the standard Worldcraft quake.fgd file are: Appearflags, Target, Targetname, PlayerClass, Ammo, Weapon, Monster, Light, Door, and Trigger.
<autolycus> The size() declaration controls how big the bounding box of the entity will appear in Worldcraft
<autolycus> You only need to specify a size for pointclass entities. SolidClass entities are those entities that have to be attached to a brush
<autolycus> The reason for the two sets of values in size(x y z, x y z), instead of just giving one width, height, and depth, is that some entities are not "centered" at their middle point.
<autolycus> An example of this is the entry for the monster_army entity. It has a size defined as size(-16 -16 -24, 16 16 40), so its center is not in the middle, but 24 units above the bottom of its bounding box.
<autolycus> the color(rrr ggg bbb) declaration is quite simple - you dont need it. :)
<autolycus> Worldcraft defaults to using the standard magenta (?) color for entities if no color is specified
<autolycus> But, if you think that your custom entity deserves to have some flashy color, say...tangerine...you can specify color(255 136 17), which would be the red/green/blue color values for a bright orange.
<autolycus> Custom color values can be found with a number of paint programs (I used Paint Shop Pro to get this example).
<autolycus> The = : "" part of the entry defines the actual entity name for use in worldcraft and the Quake .MAP.
<autolycus> the "description" i have found no use for...anyone else?
<autolycus> ok, now for the part that can be a pain in the ass
<autolycus> keys and flags and stuff
<autolycus> :)
<autolycus> anything that is individual about the object must be entered between the [ and the ]
<autolycus> all keys follow the format key(var-type) : "SmartEdit description" : default value
<autolycus> the key is the .MAP variable thing...."wait", "delay", "target", etc
<autolycus> There are five types of variables that can be used with the keys: integer, string, choices, Flags, and target_source. Of the 5, Flags and target_source types seem to be the most specialized.
<autolycus> Flags may only be used with the spawnflags() key. Its values typically ascend in powers of 2 (1, 2, 4, 8, 16, 32, etc.). The appropriate values for these can almost always be found in the .qc files, if they are handy.
<autolycus> The flags define what will appear in the entities Flag section when you are looking at its properties
<autolycus> An example from above had the following:
<autolycus> spawnflags(Flags) =
<autolycus> [
<autolycus>    256 : "Not in Easy" : 0
<autolycus>    512 : "Not in Normal" : 0
<autolycus>    1024 : "Not in Hard" : 0
<autolycus>    2048 : "Not in Deathmatch" : 0
<autolycus> ]
<autolycus> 256 is the value for the spawnflags key, "Not in Easy" will appear ni Worldcraft as the description for that flag, and 0 tells worldcraft to have that as off for a default
<autolycus> You will not have to add these flags to any of your entities, as the BaseClass Appearflags is already defined. But there are other things which will require flags.
<autolycus> An example: the Light entity will start either on or off, depending on the value of its flag, "initially dark"
<autolycus> The target_source is used 8 times within the standard quake.fgd, and is restricted to use in target, targetname, and killtarget keys.
<autolycus> I have seen no problems with using the string variable in place of a target_source variable, however.
<autolycus> The integer variable type is self explanatory, but the string is a little misleading. You can use a string for characters (of course) or for rational numbers ("1.1", "1.2", etc)
<autolycus> The choices variable type is best used when a key has several values that correspond to different things. A good example is the sound key. Each number stands for a different sound, but just having a choice of 1 to 4 is not very intuitive, so by adding this to the definition
<autolycus> sounds(choices) : "Sounds" : 1 =
<autolycus> [
<autolycus>    1 : "secret"
<autolycus>    2 : "beep beep"
<autolycus>    3 : "large switch"
<autolycus>    4 : "Set message to text string"
<autolycus> ]
<autolycus> you can just select from the list the appropriate sound, which is then translated to the numeric value for the .MAP.
<autolycus> ok the next stuff is from The Forge Add-ons section, and deals with some errors you might encounter from worldcraft when you play around with the fgd
<autolycus> since they are text (Doh..you all knew that right? :) you can go in and change stuff to suit yourself better
<autolycus> but, Worldcraft isnt very forgiving when you screw up
<autolycus> Currently, Worldcraft does not like it when an entity is declared twice. When this happens, Worldcraft will pop up a messages window when you start up, and the following error will occur: (this is only an example)
<autolycus> error parsing quake.fgd, line 1055: redefinition of class 'func_bobbingwater'
<autolycus> This is quite easy to fix...just take out the damn entity...er...you may run into this a bit if you copy the Hipnotic fgd patch onto the end of the standard quake.fgd
<autolycus> when you remove the offending entity, be sure to get the first line AND everything between the [ and ]...this seems to be a problem, judging by my email
<autolycus> error parsing quake.fgd, line 1052: expected @
<autolycus> error parsing quake.fgd, line 1052: unrecognized section in name base
<autolycus> These will occur when you neglect to put a '@' before you start to define an entity, starting a definition with SolidClass, as opposed to @SolidClass.
<autolycus> error parsing quake.fgd, line 1052: expecting '(', but found ':'
<autolycus> This will happen when you don't place a '=' character in the entity definition's first line (@SolidClass base(Appearflags) func_bobbingwater : "Bobbing Water")
<autolycus> error parsing quake.fgd, line 1052: expecting '=', but found ':'
<autolycus> This will happen when you entirely leave out the entity's name (@SolidClass base(Appearflags) : "Bobbing Water")
<autolycus> error parsing quake.fgd, line 1054: expecting string
<autolycus> This occurs when you do not properly add the quotations around a string. This is most commonly done when, by mistake, you are setting up a default value for a string, and enter something like 4, as opposed to "4".
<autolycus> This last error tends to...um....crash worldcraft.
<autolycus> When i wrote the hipnotic.fgd, i didnt do any testing while i was writing it. After many hours, i ran it and it locked up wc...
<autolycus> i wanted to cry...
<autolycus> turns out i'd missed one measly little quotation mark...so dont do that
<autolycus> this has been fixed in the newest verison of Worldcraft (1.3) so i've been told
<autolycus> well...that about wraps it up
The Forge: The Official Worldcraft Editing Site - ©1997