Was ist eine FGD-Datei?

In diesem Tutorial wird erklärt, was es mit den FGD-Dateien (game definition file) auf sich hat.

Der Hammer-Editor benötigt eine FGD-Datei, damit Entities (Point- und Brush-Entities) editiert werden können. Für jede Entity gibt es einen Eintrag, in dem beschrieben wird, wie die Entity im Hammer-Editor aussieht (bzw. im Object-Properties-Dialog ausgewählt werden kann) und wie sie später im Entity-Script der Map (BSP-Datei) steht.

Skript-Dateien haben den Vorteil, dass man sie 'leicht' lesen und mit einem Texteditor bearbeiten kann. Dadurch kann man den Hammer-Editor für jedes MOD benutzen, egal welche Entities man dafür definiert. Man muss nur seine eigene FDG schreiben. An einem Beispiel wird erkärt, wie die Waffen-Entities in derFGD für Counter-Strike erweitert werden können.

Auch wenn hier am Beispiel einiger Entities (aus Counter-Strike) die FGD erkärt wird, ist dies kein Tutorial über Enities und was in ihnen definiert werden muss. Etwas Basiswissen über Entities wird also vorausgesetzt.

Wie bindet man eine FGD-Datei ein?
Für CSS ist das die Datei 'cstrike.fgd'. Ihr findet sie im Ordner sourcesdk/bin.

Natürlich kann man die Datei 'cstrike.fgd' auch direkt verändern, nur sind beim nächsten Start alle Einträge wieder weg. Steam merkt nämlich, dass die Datei nicht mit dem Original übereinstimmt und 'denkt', da ist ein Update fällig. Tja, und schon ist die Datei 'erneuert' und die änderungen sind den Bach runter.

Damit das neue FGD auch im Hammer-Editor wirksam wird, müsst Ihr unter 'Tools->Options' folgende Einstellung vornehmen.

1. Im Menü Tools den Eintrag Options auswählen
   

   

2. Den Eintrag 'cstrike.fgd' löschen (Remove).
   

   

3. Die neue Datei (hier 'jdk.fgd') hinzufügen (Add).
   

   

Welche Struktur hat eine Entity-Beschreibung?

Jetzt zur Skript-Datei: Wie Ihr Euch sicher denken könnt, muss man in der Skript-Datei gewissen Formate einhalten. Die Grobstruktur eines Eintrags ist:

@[color=blue]EntityKlasse[/color]
Verweise = [color=red]EntityName[/color]
[color=green][
    Inhalt-Beschreibung
][/color]
// Kommentare

Als EntityKlassen können include, BaseClass, PointClass oder SolidClass verwendet werden (es gibt noch andere, die für uns aber keine Rolle spielen).

Die Verweise und die Inhalts-Beschreibung sind optional, d.h. sie müssen nicht enthalten sein. Kommentare werden mit den Zeichen "//" eingeleitet und gehen bis zum Ende der Zeile.

Ein minimale Entity-Eintrag könnte dann lauten:

@[color=blue]PointClass[/color] = [color=red][i]MeineErsteEntity[/i][/color]
[color=green][
][/color]

Na klar, mit einer Entity names MeineErsteEntity wird die Engine nichts anfangen können. Deshalb dürfen in der FGD-Datei nur Entity-Namen verwendet werden, die die Engine auch versteht.

Im Tutorial werden alle Namen, die im MOD definiert sind in rot und kursiv dargestellt.

Was bedeuten die EntityKlassen?

Mit '@include' kann man bereits bestehenden Skript-Dateien laden. Das macht das 'cstrike.fgd' ganz zu Anfang und lädt die Datei 'base.fgd'; und so macht es auch mein Skript (was ja eine Erweiterung von 'cstrike.fgd' ist).

Die beiden Entity-Typen (PointClass, SolidClass) beschreiben die Entities, die im Hammer-Editor verwendet werden können. Wenn Ihr jetzt im Skript eine solche Entity-Beschreibung löscht, ist sie auch im Hammer-Editor verschwunden. Und entsprechend, wenn Ihr eine neue Beschreibung einfügt, kann die verwendet werden.

Damit man in den Entities häufig wiederkehrende Teile nicht immer wieder hinschreiben muss, kann man Basis-Entities (BaseClass) definieren, die dann einfach in der Verweis-Liste aufgenommen werden.

Was darf in den Verweisen stehen?

Die Verweise beziehen sich entweder auf Basis-Entities (base (...)), die ebenfalls in der neuen Entity enthalten sein sollen, oder definiern das Erscheinungsbild (color (0, 0, 200), studio("path"), iconsprite("path"), sphere() und size()) im Hammer-Editor.

So bedeutet die Zeile:

@[color=blue]BaseClass[/color] color(0 0 200) base([color=red]Targetname[/color], [color=red]Angles[/color]) = [color=red]Weapon [/color]...

dass die Entity 'Weapon' im Hammer-Editor durch einen blauen Würfel dargestellt werden soll und außerdem alles, was in der Basisklasse 'Targetname' und 'Angles' enthalten ist, auch in der Entity Weapon enthalten sein soll. Natürlich dürfen die verwendeten Entities nur vom Klassentype BaseClass sein.

Diese Entity (Weapon) kann im Hammer-Editor nicht direkt verwendet werden, sondern nur zur Definition von Point- oder Brush-Entities dienen. Die Namen der Base-Entities sind nur für die FGD-Datei und den Editor intern von Bedeutung. Im Entity-Skript der BSP-Datei tauchen sie nicht mehr auf.

Hier eine Zusammenfassung der wichtigsten Elemente in der Verweisliste:

• base
  Alle aufgeführten BaseClass Entities sollen Bestandteil dieser Entity werden.
• size
  Im Hammer-Editor wird die Entity als Würfel dargestellt. Angegeben werden zwei Eckpunkte.
• color
  Im Hammer-Editor bekomnt die Entity die in RGB Werten (0..255) angegebene Farbe.
• sphare
  Die Entity bekommt zusätzlich eine Gitter-Kugel. Die Größe der Gitter-Kugel kann durch einen Wert in der Entity bestimmt werden (z.B. sphare(radius)).
• studio
  Die Entity wird durch ein Model dargestellt. Angeben wird der Pfad des Models (MDL-Datei).
• iconsprite
  Die Entity wird durch eine Textur (genauer Sprite) dargestellt. Angeben wird der Pfad der Textur (VMT-Datei).

Die Point- und Solid-Entities können eine Erklärhilfe erhalten. Man schreibt einfach das Zeichen ':' hinter den Entity-Namen und fügt den Erklär-Text ein. Texte müssen immer in Gänsefüsschen eingeschlossen werden. So wie
"hier". Interessanter Weise kann man Texte auch addiern. Der Text "Anfang" + "Und" + "Ende" wird zu "AnfangUndEnde".

Die Beschreibung der Point-Entity 'info_player_terrorist' (und der BasisEntity Angles) sieht dann so aus:

@[color=blue]BaseClass[/color] = [color=red]Angles[/color]
[color=green][[/color]
    [color=red][i]angles[/i][/color](angle)[color=green] : "Pitch Yaw Roll (Y Z X)" : "0 0 0" :[/color] 
        [color=orange]"This entity's orientation in the world. Pitch is rotation around the Y axis, "[/color] +
        [color=orange]"yaw is the rotation around the Z axis, roll is the rotation around the X axis."[/color]
[color=green]][/color]

@[color=blue]PointClass[/color] base([color=red]Angles[/color]) studio("models/player/terror.mdl") = [color=red][i]info_player_terrorist[/i][/color] :
        [color=orange]"This entity marks the start point for terrorists."[/color] +
        [color=orange]"One of these needs to be placed for each team member."[/color] +
        [color=orange]"20 start points is typical. Should be placed at least 128 units away "[/color] +
        [color=orange]"from each other and surrounding walls."[/color]
[color=green][
][/color]

Verwendet wird die Basisklasse 'Angles' und im Hammer-Editor soll das Entity durch das Model "models/player/terror.mdl" dargestellt werden. Die Inhalts-Beschreibung ist leer, da ja alles Nötige bereits in der Basisklasse 'Angles' beschrieben ist.

Das Element "origin" wird vom Hammer-Editor eingefügt.

• Der Property Dialog im Hammer-Editor
  

  

• SmartEdit off
  

  

• Der Eintrag im Entity-Skript der BSP-Datei
  

  
    {
    "origin" "52 272 96"
    "angles" "0 180 0"
    "classname" "info_player_terrorist"
    }
  

Was steht in der Inhalts-Beschreibung?

Kommen wir nun zur Inhalts-Beschreibung. Alle Inhalts-Elemente haben einen Namen (Key) und einen Wert. Wenn Ihr bei den Properties SmartEdit abschaltet seht Ihr sie. Im Entity-Skript der BSP sind nur noch diese Pärchen abgespeichert. Für den Hammer-Editor muss aber noch eine Bezeichnung eingetragen werden. Wenn man will, kann auch den Inhalts-Elementen noch eine Erklärhilfe hinzugefügt werden.

Eine Erweiterung für eine Waffen-Entity könnte so aussehen:

@[color=blue]PointClass[/color] base([color=red]Weapon[/color]) studio("models/weapons/w_rif_m4a1.mdl") = [color=red][i]weapon_m4a1[/i][/color] :
[color=orange]"Maverick M4A1 Carbine"[/color]
[color=green][[/color]
    [color=red][i]ammo[/i][/color](integer) [color=green]: "Munition" : 0 :[/color] [color=orange]"Zusätzliche Munition"[/color]
[color=green]][/color]

Die Einträge müssen mit dem Zeichen ':' getrennt werden. Sie haben folgende Bedeutung:

• ammo(integer)
  Der Name des Elements, wie er in das Entity-Skript der BSP geschreiben wird.
  Der in Klammern stehende Name bezeichnet den Typ der Werte. In diesem Fall nur ganzzalig.
• "Munition"
  Die Bezeichnung, wie sie im Object-Properties Dialog im Hammer-Editor verwendet wird.
• 0
  Der Standard-Wert. Hier kann man den Wert eintragen, der genommen werden soll, wenn nichts anderes eingetragen wird.
• [color=orange]"Zusätzliche Munition"
  Erklärhilfe. Hier kann ein beliebieger Text stehen, der im Object-Properties-Dialog im Hammer-Editor angezeigt wird.

Der Standard-Wert und die Erklärhilfe sind optional, d.h. sie dürfen auch weggelassen werden.

• Die Definition in der FGD-Datei
  

  
  @[color=blue]PointClass[/color] base([color=red]Weapon[/color]) studio("models/weapons/w_rif_m4a1.mdl") = [color=red][i]weapon_m4a1[/i][/color] :
  [color=orange]"Maverick M4A1 Carbine"[/color]
  [color=green][[/color]
      [color=red][i]ammo[/i][/color](integer) [color=green]: "Munition" : 0 :[/color] [color=orange]"Zusätzliche Munition"[/color]
  [color=green]][/color]
  

• Die Property im Hammer-Editor
  

  

• Der Eintrag im Entity-Skript der BSP-Datei
  

  
  {
  "origin" "528 272 0"
  "ammo" "100"
  "angles" "0 0 0"
  "classname" "weapon_m4a1"
  }
  

• In-Game nach dem Aufnehmen der Waffe
  

  

Damit wir diese Erweiterung nicht auch in den anderen Waffen eintragen müssen, können wir eine eigene Basis-Entity definieren, die dann mit in die Verweisliste aufgenommen wird. Dazu brauch man nur die Basis-Entity Weapon erweitern:

@[color=blue]BaseClass[/color] base([color=red]Weapon[/color]) = [color=red]WeaponPlus[/color]
[color=green][[/color]
    [color=red][i]ammo[/i][/color](integer) [color=green]: "Munition" : 0 :[/color] [color=orange]"Zusätzliche Munition"[/color]
[color=green]][/color]

Nun brauchen wir nur überall, wo Waffen noch Munition erhalten können, statt der Basis-Entity Weapon auf WeaponPlus verweisen. In unserem Fall sieht das dann so aus:

@[color=blue]PointClass[/color] base([color=red]WeaponPlus[/color]) studio("models/weapons/w_rif_m4a1.mdl") = [color=red][i]weapon_m4a1[/i][/color] :
[color=orange]"Maverick M4A1 Carbine"[/color]
[color=green][
][/color]

Welche Element-Typen gibt es?

Die Element-Namen und -Typen haben natürlich nur dann eine Bedeutung, wenn sie im MOD verstanden werden. Als Element-Typen sind folgenden Einträge möglich:

• integer
  Eingetragen werden ganzzahlige Werte.
• float
  Eingetragen werden reelle Werte.
• color255
  Eingetragen werden Farb-Werte in RGB (rot/grün/blau) Darstellung. Jeder Farbwert muss im Bereich 0..255 liegen. Der Farb-Wert für rot wird als 255 0 0 angegeben.
• angle
  Eingetragen werden Gradzahlen für die Drehung um die Y-, Z- und X-Achse des Objekts.
• string
  Eingetragen werden können beliebige Texte.
• sound
  Eingetragen werden können Namen (Texte).
• studio
  Eingetragen werden können Modelle.
• target_source
  Eingetragen werden können Namen (Texte). Auf diese Entity kann mit dem eingetragenen Namen (von anderen Entities aus) verwiesen werden.
• target_destination
  Eingetragen werden können Namen (Texte). Es muss eine Entity mit diesem Namen (target_source) existieren, auf die mit diesem Eintrag verwiesen wird.
• choices
  Aus verschiedenen Werten kann einer ausgewählt werden. Diesem Eintrag muss noch eine weitere Definition folgen.
• flags
  Aus einer Liste von Möglichkeiten dürfen beliebig viele ausgewählt werden. Auch diesem Eintrag muss noch eine weitere Definition folgen.

Was sind Choices und Flags?

Die Werte-Definition für "flags" und "choices" werden wieder mit einem Gleichheitszeichen ('=') eingeleitet und mit eckigen Klammern ('[' und ']') eingeschlossen:

• Der Skript-Eintrag choices
  

  
  [color=red][i]disableshadows[/i][/color][color=green]([b]choices[/b]) : "Disable Shadows" : 0 :
      [color=orange]"Used to disable dynamic shadows on this entity."[/color] = 
  [
      0 : "No"
      1 : "Yes"
  ][/color]
  

• Der Object-Properties-Dialog
  

  

Beim Element-Typ choices kann ein Standard-Wert eingetragen werden. Jeder der aufgezählten Werte muss eine Bezeichnung bekommen. Im Editor kann genau einer der Werte ausgewählt werden.

Diesen Elementtyp nimmt man, wenn die Werte bestimmte Bedeutungen haben sollen.

• Der Skript-Eintrag flags
  

  
  [color=red][i]spawnflags[/i][/color][color=green]([b]flags[/b]) = 
  [
      1 : "Only Break on Trigger" : 0
      2 : "Break on Touch" : 0
      4 : "Break on Pressure" : 0
      512: "Break immediately on Physics" : 0
      1024: "Don't take physics damage" : 0
  ][/color]
  

• Der Object-Properties-Dialog
  

  

Der Element-Typ flags wird eigentlich nur für die 'Spawnflags' verwendet und trägt deshalb keine Bezeichnung (und weder Standard-Wert noch Erklärungstext). Die Flag-Werte müssen 2er Potenzen sein (d.h. 1, 2, 4, 8, usw.). Im Hammer-Editor können mehrere der angebenen Optionen angeklickt werden. Die Standard-Auswahl wird in der Options-Liste angegeben (0 oder 1).

Im Entity-Skript der BSP wird dann die Summe der ausgewählten Options-Werte eingetragen. Bei der Auswahl "Break on Pressure" und "Don't take physics damage" würde im Entity-Skript "spwanflags" "1028" stehen.

Wie definiert man Input/Output?

Input und Output Einträge werden im Prinzip wie normale Elemente definiert. Sie werden mit dem Wort "input" bzw. "output" eingeleitet, bestehen aber nur aus dem Namen (mit Elementtyp) und einem Erklärtext. Beispiele hierfür sind:

@PointClass ... = [color=red][i]light_dynamic[/i][/color] :
    [color=orange]"An invisible lightsource ..."[/color]
[color=green][
    ...
    [/color]// Inputs
    [color=green]input Color(color255) : "Set the light's render color (R G B)."
    input brightness(integer) : "Set the light brightness."
][/color]