TiMan: Created page with "{{Hpl3ScriptingGuideMenuAdvanced}} {{shortPageTitle}} {| style="border:0px;" cellspacing="0" |- valign="top" | style="padding-right:0.2em" | An '''object handle''' is a variab..."

2026-07-30T08:01:48Z

Created page with "{{Hpl3ScriptingGuideMenuAdvanced}} {{shortPageTitle}} {| style="border:0px;" cellspacing="0" |- valign="top" | style="padding-right:0.2em" | An '''object handle''' is a variab..."

New page

{{Hpl3ScriptingGuideMenuAdvanced}}
{{shortPageTitle}}
{| style="border:0px;" cellspacing="0"
|- valign="top"
| style="padding-right:0.2em" |
An '''object handle''' is a variable that refers to an existing object instead of containing a separate copy of that object. Handles are used throughout HPL3: functions such as <code>Map_GetEntity</code> return handles, and many engine methods accept handles as parameters.

The handle symbol is <code>@</code>. It is written after the object type:

<syntaxhighlight lang="c++">
iLuxEntity@ pEntity;
</syntaxhighlight>

The variable above does not yet refer to an entity. An uninitialized handle is <code>null</code>.

{{note|This page describes AngelScript object handles. HPL3 also has the <code>tID</code> type, which is commonly used to remember engine-owned objects safely across updates and save/load. Object handles and IDs are related, but they are not the same thing.}}
| style="width:0.1%" |
|}

== Retrieving an object ==

Most HPL3 objects are retrieved from an API or helper function rather than constructed directly. The function's return type shows whether it returns a handle. For example, <code>Map_GetEntity</code> returns <code>iLuxEntity@</code>:

<syntaxhighlight lang="c++">
void MoveEntity()
{
iLuxEntity@ pEntity = Map_GetEntity("MyEntity");

if(pEntity is null)
{
cLux_AddDebugMessage("Could not find MyEntity");
return;
}

pEntity.SetPosition(cVector3f(55, 5, 25));
}
</syntaxhighlight>

The compiler can infer that the returned object should be assigned to the handle, so the extra handle symbol is not required during initialization.

Once a handle refers to an object, its members are accessed with the normal member access operator (<code>.</code>). AngelScript automatically accesses the object to which the handle refers:

<syntaxhighlight lang="c++">
tString sName = pEntity.GetName();
cVector3f vPosition = pEntity.GetPosition();
</syntaxhighlight>

== Null handles ==

The special value <code>null</code> means that a handle does not refer to an object. A handle can be null because:

* it has not been assigned yet;
* a lookup function did not find a matching object;
* a cast failed;
* an HPL3-owned object was destroyed or became unavailable; or
* the handle was deliberately cleared.

Use the identity operators <code>is</code> and <code>!is</code> when checking handles:

<syntaxhighlight lang="c++">
if(pEntity is null)
{
// The handle is empty.
}

if(pEntity !is null)
{
// The handle currently refers to an object.
}
</syntaxhighlight>

{{warning|Do not access members through a null handle. Always check the result of a lookup when failure is possible. A missing map object, an incorrect name, or an incompatible cast can otherwise cause a script warning or runtime error.}}

== Handle assignment ==

More than one handle can refer to the same object. Changing the object through either handle changes that same underlying object:

<syntaxhighlight lang="c++">
iLuxEntity@ pFirst = Map_GetEntity("MyEntity");
iLuxEntity@ pSecond;

@pSecond = @pFirst;

if(pSecond !is null)
pSecond.SetActive(false);
</syntaxhighlight>

The <code>@</code> placed before an expression means "use the handle itself." It makes it explicit that <code>pSecond</code> should be rebound to the same object as <code>pFirst</code>.

The compiler can infer handle assignment in many contexts:

<syntaxhighlight lang="c++">
iLuxEntity@ pEntity = Map_GetEntity("MyEntity");
</syntaxhighlight>

For later reassignment, using the explicit form makes the intention clear:

<syntaxhighlight lang="c++">
@pEntity = Map_GetEntity("OtherEntity");
@pEntity = null;
</syntaxhighlight>

This distinction matters because an ordinary <code>=</code> expression can mean "assign to the referenced object" for types that implement an assignment operator, while <code>@=</code> always rebinds the handle.

== Comparing handles ==

Use <code>is</code> and <code>!is</code> to test whether two handles refer to the exact same object:

<syntaxhighlight lang="c++">
iLuxEntity@ pFirst = Map_GetEntity("FirstEntity");
iLuxEntity@ pSecond = Map_GetEntity("SecondEntity");

if(pFirst is pSecond)
{
// Both handles refer to the same object.
}
</syntaxhighlight>

The operators <code>==</code> and <code>!=</code> may perform a value comparison defined by the object's class. They should not be used when the intention is to compare object identity.

== Handles in functions ==

Handles can be used as function parameters and return values:

<syntaxhighlight lang="c++">
void MoveTo(iLuxEntity@ apEntity, const cVector3f &in avPosition)
{
if(apEntity is null)
return;

apEntity.SetPosition(avPosition);
}

iLuxEntity@ FindEntity(const tString &in asName)
{
iLuxEntity@ pEntity = Map_GetEntity(asName);

if(pEntity is null)
return null;

return pEntity;
}
</syntaxhighlight>

A handle parameter gives the function access to the same underlying object. The function can therefore call methods which change that object.

The handle itself is passed by value. Rebinding the parameter to another object does not rebind the caller's handle. Passing the handle variable by reference is only required when the function must change which object the caller's handle refers to.

== Handles, inheritance, and casting ==

A handle to a base class or interface can refer to a compatible derived object. HPL3 uses this frequently; for example, <code>Map_GetEntity</code> returns the base type <code>iLuxEntity@</code>, while the actual object may be a prop, area, agent, or another entity type.

When functionality from a more specific type is needed, cast the handle and check the result:

<syntaxhighlight lang="c++">
iLuxEntity@ pEntity = Map_GetEntity("MyProp");
cLuxProp@ pProp = cast<cLuxProp>(pEntity);

if(pProp is null)
{
cLux_AddDebugMessage("MyProp is not a compatible prop");
return;
}

// Use cLuxProp-specific methods here.
</syntaxhighlight>

An incompatible cast returns a null handle. See [[HPL3/Scripting/Scripting Guide/Type Casting|Type Casting]] for more information.

== Handles in arrays ==

An array may store object handles:

<syntaxhighlight lang="c++">
array<iLuxEntity@> vEntities;
Map_GetEntityArray("Lamp_*", vEntities);

for(uint i = 0; i < vEntities.length(); ++i)
{
iLuxEntity@ pEntity = vEntities[i];

if(pEntity !is null)
pEntity.SetActive(false);
}
</syntaxhighlight>

Each element in <code>array<iLuxEntity@></code> is a handle to an entity. Copying one of its elements creates another handle to the same entity; it does not copy the entity.

Do not confuse an ''array of handles'' with a ''handle to an array'':

<syntaxhighlight lang="c++">
array<iLuxEntity@> vEntities; // An array whose elements are entity handles.
array<tString>@ pNames; // A handle which can refer to an array object.
</syntaxhighlight>

A handle to an array can be useful when several variables should operate on the same array rather than on separate copies.

== Object lifetime in HPL3 ==

For script-declared reference types, AngelScript keeps track of handles to an object. The object can remain alive while a valid handle still refers to it, and releasing the final handle allows it to be destroyed.

HPL3 also exposes objects owned by the engine, such as entities, physics bodies, lights, particle systems, textures, GUI objects, and world objects. Their lifetime is controlled by the relevant HPL3 subsystem. A script handle to one of these objects must not be assumed to keep it alive. It may become invalid when, for example:

* the object is destroyed;
* the map or entity data is reloaded;
* the player leaves the map;
* a temporary particle system or sound removes itself; or
* a resource is explicitly destroyed.

Use engine handles as short-lived access variables, and reacquire objects when their lifetime may have changed.

When explicitly destroying a resource, clear stored handles to it:

<syntaxhighlight lang="c++">
if(pTexture !is null)
{
cResources_DestroyTexture(pTexture);
@pTexture = null;
}
</syntaxhighlight>

{{warning|A non-null check proves only that the handle currently contains a reference. It is not a permanent guarantee that an HPL3-owned object will remain valid after the engine destroys or reloads it.}}

== Persistent references and <code>tID</code> ==

Do not rely on a raw handle to an HPL3-owned map or world object as persistent saved state. The shipped game scripts normally store the object's <code>tID</code>, then retrieve a temporary handle when the object is needed:

<syntaxhighlight lang="c++">
class cTargetData
{
tID mTargetID = tID_Invalid;

void SetTarget(iLuxEntity@ apEntity)
{
mTargetID = apEntity is null ? tID_Invalid : apEntity.GetID();
}

iLuxEntity@ GetTarget()
{
if(mTargetID == tID_Invalid)
return null;

return cLux_ID_Entity(mTargetID);
}

void Update()
{
iLuxEntity@ pTarget = GetTarget();

if(pTarget is null)
{
mTargetID = tID_Invalid;
return;
}

// Use pTarget only after validating it.
}
}
</syntaxhighlight>

The typed <code>cLux_ID_*</code> functions return null if the ID cannot be resolved as the requested type. For example, <code>cLux_ID_Entity</code>, <code>cLux_ID_Body</code>, <code>cLux_ID_Light</code>, and <code>cLux_ID_Prop</code> each return a corresponding object handle.

Raw engine handles stored as class fields are generally transient. In classes which participate in HPL3's save system, mark such fields <code>[nosave]</code> and reconstruct them when required:

<syntaxhighlight lang="c++">
[nosave] iPhysicsBody@ mpBody = null;
tID mBodyID = tID_Invalid;
</syntaxhighlight>

{{tip|A useful rule is: use a local object handle while working with an object now; store a <code>tID</code> when the reference must survive over time or through save/load.}}

== Common mistakes ==

{| class="wikitable"
! Mistake
! Correct approach
|-
| Calling a method immediately after a lookup which may fail.
| Store the returned handle and check it with <code>is null</code>.
|-
| Using <code>== null</code> or <code>!= null</code>.
| Use <code>is null</code> or <code>!is null</code>.
|-
| Expecting a second handle to contain a copy of the object.
| Both handles refer to the same object; create a new instance if an independent object is required.
|-
| Using an ordinary assignment when the intention is to rebind a handle.
| Use explicit handle assignment, such as <code>@pTarget = @pOther;</code>.
|-
| Keeping a raw handle to an engine-owned object as saved or long-lived state.
| Store its <code>tID</code>, resolve it when needed, and validate the returned handle.
|-
| Assuming a successful base-to-derived cast.
| Check the resulting handle for <code>null</code>.
|-
| Confusing <code>array<Type@></code> with <code>array<Type>@</code>.
| The first is an array of handles; the second is a handle to an array.
|}

== See Also ==

* [[HPL3/Scripting/Scripting Guide/Object Instances vs Object Handles|Object Instances vs Object Handles]]
* [[HPL3/Scripting/Scripting Guide/Type Casting|Type Casting]]
* [[HPL3/Scripting/ID Handles|ID Handles]]
* [[HPL3/Scripting/AngelScript Fundamentals/Chapter 8 - Classes|Classes - AngelScript]]

{{NavBar|HPL3/Scripting/Scripting Guide/Working with Classes|Working with Classes|HPL3/Scripting/HPL3 Scripting Guide|HPL3 Scripting Guide|HPL3/Scripting/Scripting Guide/Object Instances vs Object Handles|Object Instances vs Object Handles}}

[[Category:HPL3 Scripting]]
[[Category:English]]

HPL3/Scripting/Scripting Guide/Object Handles - Revision history

TiMan: Created page with "{{Hpl3ScriptingGuideMenuAdvanced}} {{shortPageTitle}} {| style="border:0px;" cellspacing="0" |- valign="top" | style="padding-right:0.2em" | An '''object handle''' is a variab..."