Entity

An entity is a functional unit of all games basing on id software technology.

Examples for entities are:

• lights
• AI (guards, spiders)
• the player
• path nodes
• moveables
• readables
• models (or "static meshes" to be more precise)
• the world itself ("worldspawn")

An entity's functional behaviour is entirely defined through its spawnargs, a collection of key/value pairs. The spawnargs define the type of an entity, and the parameters which are passed to the code. There is virtually no limit on the number of spawnargs - some entities like the player have over 200 key/values.

Each entity needs to have at least two spawnargs to be valid: a "name" and a "classname". The "name" of an entity must be unique in a map - no two entities are allowed to have the same name. (The next most important thing is the "origin" spawnarg which defines the absolute world location the entity is spawned at.)

entityDef

It would be tiresome to type the full set spawnargs into the editor each time, that's why there are some prototypes or entity classes available, which is exactly what the entityDefs are. The term entityDef is obviously shorthand for entity definition'. (The terms entity class and entityDef are interchangeable.)

An entityDef are nothing more than a predefined set of spawnargs, to make things convenient for the mapper. The mission author can select from all available entity classes in a nice dialog window and puts the resulting entity in his or her map. Apart from a unique "name" (which is automatically assigned by the editor) the "classname" spawnarg is added to that entity, and it refers (you have guessed it) to the name of the entityDef:

"name"      "Rich"
"classname" "atdm:ai_merc_elite"

These two spawnargs are enough to tell the game to spawn a new elite mercenary guard in the map, and his name is "Rich".

EntityDefs are defined in the darkmod/def/*.def files, which are investigated by the engine at startup. Let's look at such an example:

entityDef atdm:loot_base
{
	"inherit"			"atdm:item_base"
	"spawnclass"			"idStaticEntity"

	"solid"				"1"

	"inv_category"			"Loot"
       "inv_droppable"			"0"

	"snd_acquire"			"frob_loot"	
       "s_volume"                      "0"
   
	"editor_displayFolder"		"Loot/Static"
	"editor_usage"			"Base class for loot."
  	"editor_color"			".6 .6 1"
}

This entityDef defines a basic loot item. Apart from a few functional parameters like solid and inv_category there are two more noticeable things in this entityDef, namely the inherit keyvalue and a few editor_* spawnargs. The spawnargs with the editor_ prefix are for use in the map editor only, as they provide some meta-data to make the mapper experience more convenient.

The inherit spawnarg is the most useful thing with regard to entityDefs - it allows to specify another entityDef which this one will be based on, hence the common term base class. Technically, this means that all spawnargs defined in the base class are inherited/copied to this entityDef. This way you can centralise a set of commonly used spawnargs into a base entityDef and let the various specialised entityDefs derive from that base. The following is an example of such an inheriting entity:

entityDef atdm:loot_purse 
{
	"inherit"			"atdm:loot_base"
	"editor_mins"			"-3 -3 0"
	"editor_maxs"			"3 3 3"
	
	"editor_usage"			"Loot item: Purse"

	"model"                         "models/darkmod/loot/purse_p.lwo"
	"inv_name"			"Coin Purse"
  	"inv_loot_value"		"50"
	"inv_loot_type"			"2"
}

This entity extends the base class atdm:loot_base by defining a few additional spawnargs (e.g. model and inv_name). Therefore this entity has all the spawnargs of the base class plus a few custom ones.

It's of course possible to override spawnargs inherited from the base class, which is done by just defining them again (compare editor_usage which is defined in both the base class and the derived class). The value in the subclass always overrides the inherited ones.

To remove inherited spawnargs from the derived class, the keyvalue just needs to be set to empty, like this:

entityDef atdm:loot_purse_no_category
{
	"inherit"			"atdm:loot_base"
       "inv_category"                  ""                // clear inherited value
}

Some remarks to entityDefs

• You might notice that the key/values "name" and "classname" are missing, which makes sense, as these entityDefs are just prototypes, they are not ready to spawn yet. These two spawnargs are added when the mapper places the entity into the map file using the editor, which finally renders the entity valid.
• Each entityDef can only derive from one single base class. Multiple inheritance as known from object oriented languages is not possible.
• It's possible to place C++ style comments into the .def files:
  • // lets the parser ignore everything till the end of the line
  • /* */ defines the start and end of a comment, which can extend over multiple lines or even the entire file.