EntityDef

From The DarkMod Wiki
Revision as of 16:53, 28 March 2020 by Geep (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

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 (plus "origin" in the map) 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 *.def files, generally located in:

  • for AI, various tdm_ai_*/def/ folders
  • otherwise, tdm_defs01/def/

The *.def files 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
}

Remarks

  • DO NOT include any filename or folder (path) with special characters such as dash "-" or ampersand "&". The Dark Mod def parser cannot read paths with special characters.
  • 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. Likewise, "origin".
  • 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.
  • An EntityDef's "spawnclass" is the class object name used in the engine's C++ code. So, for example, consider the various Func/Movers entities (e.g., func_bobber). They are defined in tdm_defs01/def/func.def, which is organized by spawnclass, e.g., "idBobber". Within the engine's source code, the functionality of the idBobber class is found in Mover.cpp.
  • The engine's C++ spawnclass inheritance structure will be largely mimicked in simplified form by that of EntityDefs.
  • The functional spawnargs defined in an EntityDef are those read and used by the engine's corresponding object functions (including spawnargs that are inherited in the C++ manner).

See also