CHandle

CHandle is a C++ class that represents a 32-bit ID (entindex + serial number) unique to every past and present entity in a game. It is used to refer to entities where pointers and entity indexes are unsafe; mainly across the client/server divide and after restoring a saved game.

Tip:CHandles are slower to access than pointers. If you create pointers for access purposes and are supporting saved games, remember to repopulate them in Restore()!

Note:CHandles are only designed to work with fully fledged entities (as opposed to temporary particle effects and the like) which inherit from IHandleEntity. Attempting to assign an incompatible entity can result in ambiguous/technical runtime errors.

Todo: Layman's explanation of "ehandle" as an I/O parameter, as the explanation here is more programmer-focused. This is used on a few pages, such as ai_hint and env_projectedtexture.

Usage

CHandle<YourStoredClass> hMyHandle;

A CHandle is broadly similar to a pointer, but as it is a custom C++ class, and not a built-in feature, extra syntax is needed in some places:

• You must assign a pointer to the object, not the object itself.
• The CHandle's Get() function, or a cast, is required access the class it is storing.
• IsValid() is used to check whether a value is stored.
• To invalidate, call Term() or assign INVALID_EHANDLE_INDEX.

EHANDLE

CHandle is often used through the EHANDLE typedef, which is shorthand for CHandle<C_BaseEntity>. If you want to store a particular class it's better to declare a more specific CHandle manually (see previous section).

Example

// Create a pointer to an entity
CBasePlayer* pPlayer = gEntList.FindEntityByClassname( NULL, "player" );
 
// Store it (twice, for demonstration purposes)
EHANDLE hPlayer = pPlayer;
CHandle<CBasePlayer> hPlayer_ = pPlayer;
 
// Convert the EHANDLE back to a CBasePlayer pointer
pPlayer = dynamic_cast<CBasePlayer*>( hPlayer.Get() );

See also

• Accessing other entities
• Entity index
• Networking Entities