In general all “.ent” files are created in the model editor tool. Exactly how an entity functions is largely up to the app using the engine. Entities can be background props, enemies, and pretty much whatever. For more specific information on the basic types that are provided in the default game setup, check the Game Scripting Guide.

On this page the more general structure of entities will be covered.

At the very basic level, an entity comes as an “.ent” file that is loaded by the engine. The engine provides a basic loader for entities that handles loading of the basic types contained in it. The game can provide its own loader built from scratch, but one almost always wants to use the loader that the engine provides. The default game provides a few basic types like Props (doors, buttons, dynamic crates, etc.) and Agents (enemies, NPCs, etc.) that are used as foundations for the entity used in the game. The final entity type is defined by a script file, which takes care of all specific entity loading, setup and logic.

In order to specify a type, it first needs to be added to “config/EntityTypes.cfg” under the basic game type it should use (Prop, Agent, etc.). Here the name (used as an identfier), the script file, the class name (refering to the main class in the script file) and whether it is forced to have full game save (if all data is always saved) is specified. The editor must also know about this type and to do this “editor/EntityClasses.def” needs to be updated with the type's variables. Once this is done, the type is ready to be used in the game and editor.

Inside the game, each entity has a complete copy of all data, except for mesh and animations. So this means that the type variables are contained in each copy of the entity. This takes up a bit of extra memory but makes it much easier to handle entities. For instance, it is okay to change a type-defined variable for one specific instance of an entity if needed.

Example:
The entity “Prop_Lamp” uses the basic type “Prop” and is meant to be used for any lamp-like objects in the game. The file “config/EntityTypes.cfg” has been updated with:

<PropType
	Name = "Prop_Lamp"
	ScriptFile = "props/Prop_Lamp.hps"
	ScriptClass = "cScrPropLamp"
	ForceFullGameSave = "false"
/>

This is added to the PropTypes element and contains the needed data for the game.
To use it in the editor, “editor/EntityClasses.def” has also been updated with the following:

<Class Name="Prop_Lamp" InheritsFrom="Prop">
	<EditorSetupVars>
		<Var Name="AffectLightsVar" Value="Lit" />
		...
	</EditorSetupVars>
	<TypeVars>
		<Var Name="CanBeLitByPlayer" Type="Bool"  DefaultValue="true" Description="If the player can light this lamp by direct interaction." />
		...
	</TypeVars>
	<InstanceVars>
		<Var Name="Lit" Type="Bool" DefaultValue="true" Description="If the lamp is lit or not." />
		...
	</InstanceVars>
</Class>

This makes the editors (model and level) aware that the type exists and provides them with info on what variables it should have, as well as any special behavior. More specifics are found below.

An entity is built up from several different elements, all contained or referenced to by the ent file.

Mesh
This is the core object for almost all entities. The data is a mesh file (“.dae” or “.msh”) that comes in the form of a separate file in which the entity references. An entity can only have a single mesh connected to it. Note that several entities can connect to the same mesh file however. This is the only part of the data that is required for the entity to load properly.

Animations
An entity file can have one or more animations. In order to have animations there needs to be a mesh connected to the entity file as well. Animations are connected to the entity as separate files (“.dae_anim” or “.anim”). It is okay for several entities to share the same animations.

Bodies
This gives the entity its physics properties and allows it to collide and interact with the game's world and other entities. A body is made up from more or many shapes. If the mesh has several submeshes and there are several bodies, it must be specified which submesh belong to which body. This data is defined in the entity file.

Joints
These are used to joint up several bodies in various ways (e.g. create a door hinge between door and frame) or just attach a single body to the world in some way. This data is defined in the entity file.

Effects
This includes stuff like particles, billboards, flares, sounds, etc. Everything that can be added to spice the entity up. If there are multiple bodies then it needs to be specified where each effect is attached. Effects can also be attached to the bones of a skinned character. This data is defined in the entity file.

Here is a summary of the basic kind of workflow that is used when creating an entity.