Entity basics
Entities are the backbone of the game. They represent everything from the game world, to buttons, doors, elevators, monsters, players, weapons, even visual effects. Every entity has a few properties you should know about and understand.
The first is edict_t. edict_t is a data structure used to represent an entity in a list of all entities (edict stands for entity dictionary).
edict_t has the following member variables:
| Variable | Description |
|---|---|
| int16 get_leafnums(uint) | Get leafnums (implemented as an array property accessor, accessed as edict.leafnums[index]) |
| const int free | Flag telling whether this edict is free |
| const int serialnumber | Serial number |
| const int headnode | Head node |
| const int num_leafs | Number of leafs |
| const float freetime | When this edict was last freed |
| entvars_t vars | Entity variables instance |
Most of these are for advanced users only, for special cases where the existing interfaces don't provide you with the information you need. You will very rarely need to use them, so don't worry about them. The variables you want to know about are free, the serialnumber (used to track whether another entity has taken ownership of this edict), and vars.
Free tells us whether this edict is currently in use or not. This is an easy way to tell whether it has an entity, and is much cheaper than using g_EntityFuncs.Instance to see if a valid entity is attached.
serialnumber is primarily used by EHandle (more on that later) to determine if the entity that was using it was destroyed and another has taken it. When an entity is created, the serialnumber in the edict assigned to it is incremented. The serialnumber starts at 0 for each edict, so they are not unique for every edict.
Vars is the most useful variable, since it gives you access to the most important variables that are used by every entity. The following entry describes this data structure.
You'll generally want to avoid working with edict_t directly, since it's a very low level interface to entities. Always try to use the actual entity type (any type derived from CBaseEntity) if possible.
entvars_t contains many important variables. It used by the engine to access variables in entities that should be networked, and/or used for rendering and physics. Everything from the entity's origin and angles, to the bounds, movement type and solidity, to render mode and render amount can be found here. The list of variables is too large to show again here, so you should consult the documentation for this type for more information.
This type is used to store a handle to an entity across multiple frames. If the entity is removed, EHandle will return null instead. Using EHandle is very easy:
EHandle g_hHandle;
void StoreEntity( CBaseEntity@ pEntity )
{
g_hHandle = pEntity;
}
void DoSomethingWithStoredEntity()
{
if( g_hHandle )
{
CBaseEntity@ pEntity = g_hHandle.GetEntity();
//Do something here
}
}
You should always check if the handle is valid before using it, otherwise, Angelscript will stop executing and raise an error.
You should always use EHandle when storing entity handles, unless you know that it will only be used in current frame. Even then, it is safer to use EHandle to avoid problems.
And finally, this is the type used to represent entities themselves. All entities derive from CBaseEntity, so you can do most things with this interface. It has a rather large amount of methods and variables, so be sure to check out the documentation for it.
There are several subclasses that extend functionality for different types of entities:
-
CBaseToggleprovides support for toggled behaviour, found in doors, buttons, trains, and platforms. -
CBaseAnimatingprovides support for entities using studio models. -
CBaseMonsterprovides the basis for all monsters and the player. This includes navigation, scheduling of tasks like movement, combat, and more.
There are many more classes available in the API, so be sure to check them out of as well. Here's a list of all entities in the API:
BaseEntityCBaseDelayCBaseAnimatingCBaseToggleCBasePlayerItemCBasePlayerWeaponCBasePlayerAmmoCItemInventoryCItemCGrenadeCBaseMonsterCCineMonsterCBasePlayerCSpriteCTalkMonsterCPathTrackCBeamCLaserCBaseTankCPathConditionCBaseButtonCBaseDoor
Note: Entity handles are not reference counted, which means that unlike most objects in Angelscript, they will not exist as long as you still have a handle to it. This also means that a handle can point to an entity that no longer exists. For this reason you should avoid using entity handles for storage and use EHandle instead. The game will scan for entity handles declared as global variables, and will prevent compilation from succeeding if it detects any of them.
