In the previous chapter, we covered weapons. Weapons are a special type of entity, but an entity nonetheless.
In this chapter, we will look at entities more generally, and see how they work. Later on, we'll dive into writing some useful entities for mappers.

entvars_t vs. edict_t vs. entity classes

Let's make this clear. The engine doesn't know the difference between a CBaseEntity and a CFuncWall. Instead, the engine only knows one form of entity. And that is edict_t.

struct edict_s
{
    qboolean free;
    int serialnumber;
    link_t area; // linked to a division node or leaf

    int headnode;    // -1 to use normal leaf check
    int num_leafs; // How many leaves the entity occupies, shouldn't be more than MAX_ENT_LEAFS
    short leafnums[MAX_ENT_LEAFS];

    float freetime;    // sv.time when the object was freed

    void* pvPrivateData; // Alloced and freed by engine, used by DLLs; pointer to a HL SDK entity
    entvars_t v; // Common entity variables
};

It's basically an entity dictionary, containing data such as whether the entity's memory is free, its "serial number", its link to a BSP leaf, a pointer to the game entity (an instance of an HL SDK entity class), and an entvars_t variable to hold common entity variables.
Generally, you won't use edict_t often.

In CBaseEntity, there's a reference to this entvars_t.

entvars_t *pev;

"pev" stands for "Pointer to Entity Variables", and it is essentially a group of variables that is common to all entities. entvars_t is defined in progdefs.h, and constants that can be used with variables from entvars_t are in const.h.
Some of the most important variables from entvars_t are:

• classname - entity's classname
• targetname - entity's name
• target - target entity's name
• origin - entity's current position
• velocity - entity's current velocity
• movedir - entity's current movement direction
• angles - entity's current angles
• avelocity - angular velocity
• model - path to the model
• nextthink - next time the entity will call its think callback
• movetype - movement type of the entity, which can be:
  • MOVETYPE_NONE - entity won't move
  • MOVETYPE_WALK - entity will use walk physics (players only)
  • MOVETYPE_STEP - entity will use walk physics for monsters
  • MOVETYPE_FLY - entity not be affected by gravity
  • MOVETYPE_TOSS - affected by gravity
  • MOVETYPE_PUSH - entity can push other entities
  • MOVETYPE_NOCLIP - not affected by gravity, passes through everything
  • MOVETYPE_FLYMISSILE - same as MOVETYPE_FLY but with extra size so it can hit monsters
  • MOVETYPE_BOUNCE - affected by gravity, bounces from the surface depending on pev->friction
  • MOVETYPE_BOUNCEMISSILE - combination of FLYMISSILE and BOUNCE
  • MOVETYPE_FOLLOW - follows pev->aiment
  • MOVETYPE_PUSHSTEP - a combination of PUSH and STEP for brush entities, only works with SOLID_BSP

• solid - solidity mode of the entity, which can be:
  • SOLID_NOT - non-solid, everything passes through it
  • SOLID_TRIGGER - calls Touch, otherwise non-solid
  • SOLID_BBOX - uses its axis-aligned bounding box for collisions (this collision box cannot rotate, keep in mind), calls Touch when an entity touches one of its edges, can call Blocked
  • SOLID_SLIDEBOX - can only call Touch when on the ground, calls it when an entity touches one of its edges
  • SOLID_BSP - uses BSP cliphulls of the brush model for collisions, Touch on edge and can call Blocked

• rendermode - render mode of this entity, can be:
  • kRenderNormal - Normal
  • kRenderTransColor - Color
  • kRenderTransTexture - Texture
  • kRenderGlow - Glow
  • kRenderTransAlpha - Solid
  • kRenderTransAdd - Additive

• renderamt - render amount of this entity (typically wrongly named in FGDs as "FX Amount")
• rendercolor - render colour
• renderfx - render effect (look at const.h, it's got many of them)
• spawnflags - flags set in the map editor (in the Flags tab)
• flags - temporary entity flags. The constants are defined in const.h, and here are some of the more important ones:
  • FL_SKIPLOCALHOST - Tells the engine not to transmit the entity to the local host
  • FL_ONGROUND - Indicates whether the entity is on the ground or not; can be overridden
  • FL_FAKECLIENT - Indicates that this is a bot; set this while writing your own bots
  • FL_FLOAT - Tells the engine to apply buoyancy to the entity when in water
  • FL_ALWAYSTHINK - Calls Think every frame
  • FL_MONSTERCLIP - Only collide with and block entities that have this flag set
  • FL_ONTRAIN - Ignore the player's movement commands; useful to set this when controlling a vehicle
  • FL_WORLDBRUSH - Tells the engine that this is an entirely static brush entity, almost as if it were worldspawn
  • FL_KILLME - Marks the entity to be deleted from memory; this is set by UTIL_Remove
  • FL_DORMANT - Doesn't send updates to the client, thus saving on bandwidth; the entity cannot call Think if this is set

Uninitialised values will be 0, as this structure is memset'ed by the engine while spawning the entity.

Certain utility functions will accept edict_t as a parameter, so you'll need to convert your CBaseEntity or CFuncWall or any entity class you're using into edict_t. While there's no direct conversion, you can use the ENT utility function to 'convert' an entvars_t into an edict_t. For example:

SET_MODEL( ENT( pev ), STRING( pev->model ) );

We'll discuss utility functions later on.

string_t

You may have noticed several string_t members. This is not a C string. Here is an example usage of the API:

// Allocating a string
string_t exampleString = ALLOC_STRING( "Example string" );
// Evaluating/reading a string
const char* exampleStringValue = STRING( exampleString );

If you're a beginner, you may get confused by it, since it's defined as an unsigned int. So, here is an explanation:
The engine has a string allocator, which is essentially a very large buffer of characters. You can imagine it this way:

H  e  l  l  o     w  o  r  l  d \0 f  u  n  c  _  w  a  l  l  \0
0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21

If we had a string_t variable with a value of 11, in this very example, STRING would return "func_wall".

In reality, you may get garbage at low values, and usable strings could show up around, for example, 250 million. So in summary, it's most convenient to think of string_t as a handle.

CBaseEntity

The mother of all entities.
As mentioned previously, every entity in the HL SDK inherits from CBaseEntity. We won't cover all of its methods and members, but we will go through the most important ones.

Spawn

Called for every entity in the map by the engine when the map is loaded for the first time. When loading a save game, this is not called unless the entity has the FCAP_MUST_SPAWN flag.

If your entity has a custom Precache method, it should be called from Spawn. The engine will not automatically call Precache except when loading a save game.

Precache

Entities override this so they can load model, sound and other files that they may use.
Files can be precached with the following macros:
PRECACHE_MODEL - precaches studio models
PRECACHE_SOUND - precaches audio files
PRECACHE_GENERIC - precaches any file, you can even precache a whole .bsp if you wanted to

KeyValue

Handles map keyvalues and assigns values from them to member variables. The engine calls this multiple times until it covers all keyvalues of every entity.

Parameters:

• pkvd - the data of one keyvalue

This is how keyvalues are typically handled:

if (FStrEq(pkvd->szKeyName, "myKeyvalue"))
{
    m_myVariable = atoi(pkvd->szValue); // m_myVariable is assumed to be an "int" (or anything similar) here. Common examples for other kinds of variables are "atof" for "float", "ALLOC_STRING" for "string_t" and "bool" is the same as "int" but with an additional "!= 0" check.
    return true;
}
else
    return CBaseEntity::KeyValue(pkvd);

We compare szKeyName to all possible keyvalues this entity may have, and then convert the szValue string into a value of the type we need.
If no match is found, then go back up to the KeyValue method of our superclass.

Save & Restore

Save and Restore are the key methods for saving and loading custom data fields across save files (the ones in the mod's SAVE folder). In order for those to know what to save/load and what not to save/load, they need a "save/restore table". Needless to say that this is a requirement for singleplayer modifications (and not needed for multiplayer only ones).

Everything you need to know about the save/restore system is available on it's dedicated page, the choice to read now or later is up to you.

ObjectCaps

A way of storing "capability flags" for entities. Entities can override this to return certain constants that will make the entity usable by the player, or held down continuously, transferable between levels etc.

The constants can be:
FCAP_CUSTOMSAVE - unknown and unused
FCAP_ACROSS_TRANSITION - the entity will transfer across level transitions
FCAP_MUST_SPAWN - calls Spawn instead of Precache right after Restore, i.e. after loading a savefile
FCAP_DONT_SAVE - don't write into the savefile
FCAP_IMPULSE_USE - can be used by the player
FCAP_CONTINUOUS_USE - can be held by the player (such as levers and valves)
FCAP_ONOFF_USE - can be toggled by the player
FCAP_DIRECTIONAL_USE - receives +/- from the player, only used by func_tracktrain
FCAP_MASTER - entity can be used as a master (multisource has this cap)
FCAP_FORCE_TRANSITION - entity always goes across transitions

You can add your own cap flags as well.

Activate

Called on every entity after the server is activated. It is used, for example, by CFuncTrain/func_train to teleport itself to the first path_corner as soon as the server starts.

Modular methods

CBaseEntity has a lot of overrideable methods, but some of these are modular - they can be changed dynamically at runtime.
One of those is Think:

virtual void Think( void )
{
    if ( m_pfnThink )
        (this->*m_pfnThink)();
}

These methods actually call callbacks.

void (CBaseEntity ::*m_pfnThink)(void);
void (CBaseEntity ::*m_pfnTouch)( CBaseEntity *pOther );
void (CBaseEntity ::*m_pfnUse)( CBaseEntity *pActivator, CBaseEntity *pCaller, USE_TYPE useType, float value );
void (CBaseEntity ::*m_pfnBlocked)( CBaseEntity *pOther );

Keep in mind, however, that you don't really have to use these, and for simple entities, you can just override these methods without consequences.

Think

Called every time period, or every tick, this method is often used by entities to perform real-time or otherwise periodic logic, e.g. check if a certain entity is within radius every 0.5 seconds.

To set a think callback, use the SetThink macro.

To set the next time an entity will "think", set the pev->nextthink variable.
Example:

pev->nextthink = gpGlobals->time + 0.5; // think every 0.5 seconds

Touch

Called every time the entity is touched by another entity. Entities such as trigger_once absolutely rely on this to work.

To set a touch callback, use the SetTouch macro.

Parameters:

• pOther - entity that touched this entity

Use

Called either by players when pressing the use button aiming at an entity (if the respective object cap is enabled), or by other entities that have the ability to trigger other entities. For example, when a func_button triggers a func_door, it is calling the func_door's Use method.

To set the use callback, use the SetUse macro.

Parameters:

• pActivator - entity that started the trigger sequence
• pCaller - entity that actually fired this entity
• useType - type of usage: USE_TOGGLE, USE_ON, USE_OFF and USE_SET
• value - the value sent from pCaller, typically used only in func_tracktrain

Blocked

Called every time an entity blocks this entity.
This is essentially how doors and trains damage and gib things. They apply damage to any entity that blocked them.

Parameters:

• pOther - entity that blocked this entity

Static methods

These methods are useful in certain situations.

Create

Allocates a new entity of any classname and spawns it at given coordinates. Returns a CBaseEntity pointer to the newly spawned entity.

Parameters:

• szName - the classname itself, e.g. env_sprite, monster_zombie etc.
• vecOrigin - the position at which it'll spawn
• vecAngles - the angles it'll have after spawning
• pentOwner - owner of the newly created entity (NULL by default)

Instance

Retrieves a class pointer from an existing entity. It is used to 'convert' edict_t*, entvars_t* or entity indices into CBaseEntity*.

Parameters:

• pent - entity dictionary/edict to convert from (edict_t* overload)
• pev - entity variables to convert from (entvars_t* overload)
• eoffset - entity index to retrieve from (int overload)

Dispatch functions

If you wonder how the engine actually calls these functions, it is done through the various Dispatch functions:

DispatchSpawn
DispatchKeyValue
DispatchTouch
DispatchUse
DispatchThink
DispatchBlocked
DispatchSave
DispatchRestore
DispatchObjectCollsionBox
ServerActivate

The game exports these to the engine when hl.dll is loaded, after which the engine calls them for each edict_t in its internal array of entities.

Entity lifecycle

When the game is loaded, the dispatch functions are called by the engine, which then call the matching functions on every entity. This is the order of when those functions are called:

Loading a new map

1. KeyValue(pkvd) for each keyvalue for the entity
2. Spawn()
3. Activate()

Notice that Precache() is not called. If your entity has a custom Precache function, you should call it from the Spawn method.

Saving a save game

1. ObjectCaps()
   • This is called by DispatchSave to see if the entity has the FCAP_DONT_SAVE flag, in which case Save will not be called.
2. Save()

Loading a save game

1. ObjectCaps()
   • This is called by DispatchRestore to see if the entity has the FCAP_MUST_SPAWN flag, in which case Spawn will be called instead of Precache below.
2. Restore()
3. Precache()
4. Activate()

Entity index

Entity indexes is a way to identify entities and in specific contexts/scenarios "refer" to other entities. Everything you need to know about this is covered in the Entity index definition page so please read it before proceeding here.

Other base classes and important entity classes

CWorld - worldspawn entity
CItem - base item class
CBaseDelay - generic delay entity, can be spawned when an entity tries to trigger another entity with a delay

• CBaseAnimating - entity that supports studio model animations, provides utilities for submodels, setting controllers etc.
  • CBasePlayerItem - generic player item
    • CBasePlayerWeapon - generic player weapon
  • CBaseToggle - generic toggleable entity, implements linear movement for trains, opening and closing mechanism for doors etc.
    • CBaseMonster - base monster class
      • CBasePlayer - player class

On the next page, you'll learn how to create a very basic entity that will print a mapper-defined message to the console.