4. Entities - QodotPlugin/qodot-plugin GitHub Wiki

This Wiki is outdated and no longer being maintained. Qodot's new documentation can be found here: https://qodotplugin.github.io

Qodot supports spawning custom nodes and instanced scenes from entities stored in a .map file.

Terminology

This section relies on certain Quake-specific terms, which will be delineated here for clarity:

Worldspawn is the structural geometry of your map. It's comprised of static, non-entity brushes and is combined into a single mesh at build time.

Entities are Quake's equivalent of actors: Objects in the world that are independent of the worldspawn. They have specific properties and gameplay logic dictated by their classname.

Classname is a string used to identify an entity's type, much like a class name in programming.

FGD stands for 'Forge Game Data', and is the text-based file format used with Quake-based map editors to define the entity types available to a given game.

Entity System

Qodot's entity system is implemented by representing FGD files and their contents as resources, and extending them with Qodot-specific metadata for use during the build process.

FGD File (QodotFGDFile)

This is the top-level resource for Qodot's entity system. You can use it to export a custom set of entities to a FGD file for use with a compatible editor, and plug it into a QodotMap in order to build maps created with those entities.

Export File - Used as a pseudo-button to export the selected FGD resource to a file

Target Folder - The destination folder for FGD export

FGD Name - The human-readable name for this FGD file, used as the filename during export.

Entity Definitions - An array of FGD class resources, used to populate the FGD's contents during export.

Entity classes are separated into the following types:

Base Class (QodotFGDBaseClass)

Base classes are abstract, in that they cannot be spawned via map editor, and exist only to provide a basis for the more concrete class types. They're identified by a classname, and provide various information to both the map editor and game client.

They can define meta properties, such as the entity's bounding box and color in compatible editors, as well as class properties, which represent script variables used to configure the entities for gameplay.

Classname - The name used to identify this class in the map editor.

Description - Short description of this class for display in the map editor.

Class Properties - Dictionary of gameplay properties, used to define editor-addressable variables for this class.

Properties are stored as strings for the purposes of map editing, but will have type metadata attached to them for custom editor UI such as checkboxes, dropdowns or color pickers. Variable types are inferred from the dictionary, and the following are valid:

• Integer
• Float
• String
• Vector3
  • Stored as a string in the form X Y Z
• Color
  • Stored as a string in the form R G B
• Dictionary
  • Used for defining a set of choice keys and their associated values
  • Will display a dropdown in compatible editors
• Array
  • Used for bitmask flag properties
  • Each entry represents a flag as a nested array in the form [name, value, default]
  • Will display a grid of checkboxes in compatible editors

Class Property Descriptions - Dictionary of property descriptions, for display in compatible map editors.

Meta Properties - Editor-specific properties, such as the default color and size used to represent this class.

Solid Class (QodotFGDSolidClass)

Solid classes (or 'Brush Entities') are entities with attached brush geometry. Common examples include doors, elevators, triggers, rotating fan blades, and various other elements whose appearance is defined in the map editor, and behavior is defined by the game client.

In addition to the properties available in QodotFGDBaseClass, QodotFGDSolidClass can define the following:

Spawn Type - Whether the class should act as the worldspawn, be merged with the worldspawn, or act as a free-standing entity

Build Visuals - Whether visual meshes should be built

Physics Body Type - The type of physics body node spawned during build

Collision Shape Type - The type of collision shape attached to the entity during build

Script Class - A script class applied to the entity's node during build

Point Class (QodotFGDPointClass)

Point Classes (or 'Point Entities') are entities with no attached brush geometry. Common examples include the player, monsters, pickups, lights, ambient sounds, and any other element whose appearance and behaviour is defined entirely by the game client.

In addition to the properties available in QodotFGDBaseClass, QodotFGDPointClass can define the following:

Scene File - A PackedScene resource that will be used to represent this class in the scene tree

• Used for gameplay entities with a predefined hierarchy, such as players, monsters or pickups

Script Class - A script class applied to the entity's node during build

• Used for non-hierarchical entities, such as lights or ambient sounds

Display Models for Entities

You might want to display a model in TrenchBroom to represent a point entity. If you want to display a 3D .obj model, you can add a Meta Properties in your point entity definition with model as the key and the relative path of your .obj file as the value.

Example: Key: model Value: "entities/models/my_model.obj" <--- (Note the quotes surrounding it).

You have to quote the value string, or TrenchBroom may crash when placing your entity class.

Workflow

The typical workflow for adding a new entity type to a Godot project is as follows:

• Create a new script class or instanced scene to represent the entity

• Create a QodotFGD*Class resource to represent the entity

• Create a QodotFGDFile file resource to represent your game

  • It's recommended to use the default Qodot FGD as a base, which can be found in addons/qodot/game-definitions/fgd

• Add the FGD class to the FGD resource

• Export the QodotFGDFile resource to a FGD file

• Add the FGD file to a supported editor

  • FGDs can be exported as part of a full TrenchBroom game config. See the TrenchBroom page for instructions.

• Use a compatible editor to build a map using the FGD file, and populate it with instances of your entity

• Plug your QodotFGDFile resource into the FGD Files array on a QodotMap node

• Use the QodotMap node to build your map

• Instances of your script or instanced scene will be spawned in the tree hierarchy

Example

An example of custom FGD files and classes can be found in the qodot-example repository.