Accessing Other Entities

This article or section should be converted to third person to conform to wiki standards.

In Hammer, entities can only communicate through pre-defined inputs and outputs. The good news is that in C++, this limitation goes away, and you can access anything that isn't explicitly "private." The bad news is that you have to work a bit harder to get off the ground.

An Example

CBreakable* pWall = GetFuncBreakable(); // Made-up function!
if (!pWall) return;

pWall->Break(this);

In the above code we:

1. Declare a pointer and assign an entity we want to it (a func_breakable)
2. Confirm that the pointer was successfully assigned a value
3. Access a member function of the target entity

Tip:Prefixing 'p' to the names of pointers makes identifying them later on much easier, but isn't necessary.

Pointers

A pointer is the C++ equivalent of a desktop shortcut. The current target of a pointer is called the 'pointee'.

A pointer has five main rules:

1. Pointers are declared like a variable, except for an asterisk before the name (e.g. CBaseEntity* pOther). Don't use the asterisk anywhere else - it's just for declarations.
2. You must #include the header file of any class you want to create a pointer for.
3. A pointer can only be assigned an object that matches its class. The compiler will throw an error otherwise.
4. When accessing members of a pointee, you must use -> instead of the usual period character.
5. Any attempt to access an unassigned ('null') pointer will immediately crash your mod. Welcome to C++!

These aside, the syntax surrounding a pointer is the same as any other member of the current class.

Tip:You can quickly create a pointer for use as a function argument with &. SomeFunc(&MyVar) is the same as SomeType* pMyVar = MyVar; SomeFunc(pMyVar).

Casting

Pointees must be of the same class as the pointer. But what about touch functions, which provide the other entity involved as CBaseEntity*? There's no such thing as a pure CBaseEntity, right?

Indeed there isn't. The pointee isn't CBaseEntity, but the pointer has been "cast" to act as if it were one. This is possible when one class inherits from another; since everything inherits from CBaseEntity everything can be cast to CBaseEntity*. Essential knowledge if you don't know what entities your code will be dealing with!

A CBaseEntity* pointer is fine if you want to access something defined in CBaseEntity. But if you need to access something defined further downstream, then the pointer must be cast to a class that has access to it. This is achieved with dynamic_cast.

CMyEntity::Touch( CBaseEntity* pOther )
{
	CBreakable* pWall = dynamic_cast<CBreakable*>(pOther);
	if (!pWall) return;

	pWall->Break(this);
}

We cast pOther to CBreakable*, storing the result in pWall. We can then access the CBreakable function Break().

It's doubly important to check that the pointer is assigned this time because the cast will be attempted whenever the entity touches something. If pOther isn't actually a CBreakable then the operation will fail, leading to a dangerous null pointer.

Note:Remember that casting a pointer does not affect the pointee itself.

Tip:If the classes of both objects are known, you can perform a time saving static cast like this: CBreakable* pWall = static_cast<CBreakable*>(pOther).

CHandle

Pointers represent physical locations in system memory. If you want to transfer a pointer between the client and server or store it in a saved game, you must use a CHandle (aka EHANDLE).

Finding Entities

There isn't much point in knowing how to create pointers if you don't have an entity to work with in the first place. gEntList is the place to get one. It's a global object available through cbase.h.

gEntList offers various search functions, the names of which all start with Find or Next. Each one will only return one CBaseEntity* at a time however, so if you want to iterate through all the results a bit of padding is needed:

CBaseEntity* pResult = gEntList.FindEntityByClassname(NULL,"npc_*");
while (pResult)
{
	CAI_BaseNPC* pNPC = dynamic_cast<CAI_BaseNPC*>(pResult);
	if (pNPC)
		pNPC->SetState(NPC_STATE_IDLE);

	pResult = gEntList.FindEntityByClassname(pResult,"npc_*");
}

Here we:

1. Call gEntList.FindEntityByClassname() to get the first entity with the Hammer classname "npc_*".
   Note:The asterisk is a search wildcard in this context.
2. Enter a loop that ends when pResult becomes invalid.
3. Cast our CBaseEntity*, pResult, to CAI_BaseNPC* so that we can access its AI-related members.
4. Confirm that the cast has been successful.
5. Perform our desired operation.
6. Call FindEntityByClassname() and search for "npc_*" again, this time starting at pResult's position in the list.
7. Return to the start of the loop.

Searching the whole entity list all the time is expensive so try to avoid doing it if you can. For example if your class will need to access the other entity again later, keep it stored away in a member pointer.

See also

• Wikipedia:Pointer (computing)