View source for EHandle

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:

 <nowiki>
EHandle g_hHandle;

void StoreEntity( CBaseEntity@ pEntity )
{
    g_hHandle = pEntity; // CBaseEntity@ (and child types) instances implicitly cast to EHandle
}

void DoSomethingWithStoredEntity()
{
    if( g_hHandle ) // Check if the EHandle is valid first before using it.
    {
        CBaseEntity@ pEntity = g_hHandle.GetEntity();

        //Do something with "pEntity"
    }
}</nowiki>

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.

Never declare a CBase* handle as a global or member variable, always use EHandle.

For the same reason, avoid passing CBase* handles through scheduled function/method parameters. In situations where you have to pass an entity through a scheduled function, its recommended to overload the scheduled function changing the CBase* parameter to EHandle and scheduling that overload:

 <nowiki>
void ScheduleEntity( CBaseEntity@ pEntity )
{
    // This will schedule "DoSomethingWithEntity( CBaseEntity@ pEntity )" - unsafe, avoid doing this
    // g_Scheduler.SetTimeout( "DoSomethingWithEntity", 0.0f, pEntity );
    
    // This will schedule "DoSomethingWithEntity( EHandle hEntity )" - safe
    g_Scheduler.SetTimeout( "DoSomethingWithEntity", 0.0f, EHandle( pEntity ) );
}

void DoSomethingWithEntity( CBaseEntity@ pEntity ) // Original function
{
    pEntity.DoSomething();
}

void DoSomethingWithEntity( EHandle hEntity ) // Overload
{
    if( hEntity )
        DoSomethingWithEntity( hEntity.GetEntity() );
}</nowiki>

== Methods ==

{| class="wikitable" 
|- style="font-weight:bold; text-align:center; vertical-align:middle;"
! Declaration
! Description
|-
| <code>void EHandle()
| style="vertical-align:middle;" | Default constructs this handle.
|-
| <code>void EHandle(const EHandle& in other)
| style="vertical-align:middle;" | Copy constructs this handle.
|-
| <code>void EHandle(CBaseEntity@ pEntity)
| style="vertical-align:middle;" | Constructs this handle with a reference to the given entity.
|-
| <code>bool IsValid() const
| style="vertical-align:middle;" | Returns whether this handle is valid.
|-
| <code>bool opImplConv() const
| style="vertical-align:middle;" | Returns whether this handle is valid.
|-
| <code>CBaseEntity@ GetEntity() const
| style="vertical-align:middle;" | Gets the Entity this handle refers to.<br />Returns null if invalid.
|-
| <code>CBaseEntity@ opImplCast() const
| style="vertical-align:middle;" | Gets the Entity this handle refers to.<br />Returns null if invalid.
|-
| <code>CBaseEntity@ opAssign(CBaseEntity@ pEntity)
| style="vertical-align:middle;" | Assigns the given entity to this handle.
|-
| <code>EHandle& opAssign(const EHandle& in other)
| style="vertical-align:middle;" | Makes this handle refer to the same entity as the given handle.
|-
| <code>int GetSerialNumber() const
| CBaseEntity serial number. Used to determine if the entity is still valid.
|}

[[Category:Scripting]]