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

2026-07-30T08:08:44Z

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

New page

{{Hpl3ScriptingGuideMenuAdvanced}}
{{shortPageTitle}}
{| style="border:0px;" cellspacing="0"
|- valign="top"
| style="padding-right:0.2em" |
An '''object instance''' is one particular object created from a class. An '''object handle''' is a variable which can refer to an instance.

The difference determines whether an assignment copies an object's data or makes another variable refer to the same object:

<syntaxhighlight lang="c++">
cExample first; // Create an instance.
cExample second; // Create a separate instance.
second = first; // Copy first's data into second.

cExample@ pExample;
@pExample = @first; // Make pExample refer to first.
</syntaxhighlight>

After the value assignment, <code>first</code> and <code>second</code> are independent instances. After the handle assignment, <code>pExample</code> and <code>first</code> provide access to the same instance.

{{note|The class is the object's type or blueprint. The instance is the actual object created from that class. A handle is a reference through which an instance can be accessed.}}
| style="width:0.1%" |
|}

== Object variables ==

For an instantiable object type, a declaration without <code>@</code> creates an object variable:

<syntaxhighlight lang="c++">
class cCounter
{
int mlValue;
}

void Example()
{
cCounter counter;
counter.mlValue = 10;
}
</syntaxhighlight>

The <code>counter</code> variable owns an instance of <code>cCounter</code>. It is constructed when the declaration is reached and destroyed when its lifetime ends, unless a handle keeps a reference to it.

Unlike a handle, an initialized object variable is not optional and cannot be set to <code>null</code>. Its identity does not change during its lifetime. Assigning another object to it copies data into the existing instance:

<syntaxhighlight lang="c++">
cCounter first;
first.mlValue = 10;

cCounter second;
second = first;

second.mlValue = 20;

// first.mlValue is still 10.
// second.mlValue is 20.
</syntaxhighlight>

For script-declared classes, AngelScript automatically supplies an assignment operator which copies each member unless the class defines its own <code>opAssign</code>.

== Object handles ==

A declaration with <code>@</code> creates a handle:

<syntaxhighlight lang="c++">
cCounter@ pCounter;
</syntaxhighlight>

This does not create a <code>cCounter</code> instance. The handle is initially <code>null</code> and must be made to refer to an existing or newly created object:

<syntaxhighlight lang="c++">
cCounter counter;
cCounter@ pCounter = @counter;

pCounter.mlValue = 30;

// counter.mlValue is now 30 because pCounter refers to counter.
</syntaxhighlight>

Several handles may refer to the same instance:

<syntaxhighlight lang="c++">
cCounter counter;

cCounter@ pFirst = @counter;
cCounter@ pSecond = @counter;

pFirst.mlValue = 50;

// pSecond.mlValue and counter.mlValue are also 50.
</syntaxhighlight>

The handles are separate variables, but the object behind them is shared.

== Value assignment versus handle assignment ==

The assignment operator <code>=</code> normally operates on object values. For script classes, it copies the source instance's members into the destination instance:

<syntaxhighlight lang="c++">
second = first;
</syntaxhighlight>

The handle assignment operator <code>@=</code> changes which object a handle refers to:

<syntaxhighlight lang="c++">
@pCurrent = @first;
@pCurrent = @second;
@pCurrent = null;
</syntaxhighlight>

Rebinding <code>pCurrent</code> does not copy, modify, or destroy <code>first</code> or <code>second</code>. It only changes the reference stored in <code>pCurrent</code>.

AngelScript can infer handle assignment in many declarations and function calls:

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

When reassigning an existing handle, writing the leading <code>@</code> explicitly makes the intended operation unambiguous.

== Complete comparison ==

{| class="wikitable"
! Property
! Object variable
! Object handle
|-
| Example declaration
| <code>cCounter counter;</code>
| <code>cCounter@ pCounter;</code>
|-
| Creates an instance
| Yes, for an instantiable type.
| No.
|-
| Default state
| A constructed object.
| <code>null</code>.
|-
| Assignment
| Copies or assigns object data using <code>=</code>.
| Rebinds the reference using <code>@=</code>.
|-
| Can be null
| No, after successful construction.
| Yes.
|-
| Can alias another variable's instance
| No.
| Yes.
|-
| Member access
| <code>counter.Method()</code>
| <code>pCounter.Method()</code>
|-
| Identity comparison
| Take handles to the objects when identity must be compared.
| Use <code>is</code> and <code>!is</code>.
|-
| Typical HPL3 use
| Independent script data and value-like utility objects.
| Entities, bodies, lights, resources, GUI objects, polymorphism, and optional references.
|}

== Value types and reference types ==

AngelScript distinguishes between '''value types''' and '''reference types'''.

=== Value types ===

Value types directly contain their data. Assigning a value type creates an independent copy. Primitive types such as <code>int</code>, <code>float</code>, and <code>bool</code> are value types and cannot have object handles.

HPL3 also registers many utility classes as value-like types. Vectors, colors, matrices, and IDs are normally passed or stored as values:

<syntaxhighlight lang="c++">
cVector3f firstPosition = cVector3f(1, 2, 3);
cVector3f secondPosition = firstPosition;

secondPosition.x = 10;

// firstPosition.x is still 1.
</syntaxhighlight>

Whether an application-registered object type supports handles is decided by HPL3. Do not assume that <code>@</code> can be used with every class shown in the scripting API.

=== Reference types ===

Reference types are created separately in memory and may be accessed through handles. All script-declared classes are reference types. Many HPL3 engine classes are also exposed as reference types.

Engine objects are usually retrieved as handles:

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

if(pEntity !is null)
@pBody = pEntity.GetMainBody();
</syntaxhighlight>

Classes such as <code>iLuxEntity</code> represent engine-owned objects. They are normally obtained from HPL3 rather than instantiated directly in a map script.

{{note|Reference type does not mean that every variable is automatically a nullable handle. A script-class object variable declared without <code>@</code> still creates and owns an instance; adding <code>@</code> creates a separately rebindable, nullable handle.}}

== Copying script-class instances ==

The automatically generated assignment operator for a script class copies each member:

<syntaxhighlight lang="c++">
class cSettings
{
float mfVolume;
bool mbEnabled;
}

cSettings original;
original.mfVolume = 0.5f;
original.mbEnabled = true;

cSettings copy;
copy = original;

copy.mfVolume = 1.0f;

// original.mfVolume is still 0.5f.
</syntaxhighlight>

A class may implement <code>opAssign</code> to define different assignment behavior. HPL3 application types may also provide their own assignment operators, so the exact meaning of value assignment ultimately belongs to the type.

=== Shallow copies of handle members ===

Copying an object does not necessarily duplicate every object to which its members refer. If a class contains a handle, the generated assignment operator copies that handle:

<syntaxhighlight lang="c++">
class cTarget
{
int mlValue;
}

class cContainer
{
cTarget@ mpTarget;
}

cTarget target;

cContainer first;
@first.mpTarget = @target;

cContainer second;
second = first;

second.mpTarget.mlValue = 25;

// first.mpTarget and second.mpTarget still refer to the same target.
// target.mlValue is now 25.
</syntaxhighlight>

This is called a '''shallow copy'''. The <code>cContainer</code> data was copied, but the target object was not duplicated. A true independent or '''deep copy''' must be implemented explicitly by constructing new referenced objects and copying their contents.

== Function parameters ==

The same distinction applies when passing objects to functions.

Passing an object by value gives the function a copy:

<syntaxhighlight lang="c++">
void ChangeCopy(cCounter counter)
{
counter.mlValue = 100;
}
</syntaxhighlight>

Passing a handle gives the function access to the same instance:

<syntaxhighlight lang="c++">
void ChangeOriginal(cCounter@ pCounter)
{
if(pCounter !is null)
pCounter.mlValue = 100;
}
</syntaxhighlight>

Passing a value object by constant reference avoids a copy while preventing assignment through that parameter:

<syntaxhighlight lang="c++">
float GetDistanceFromOrigin(const cVector3f &in avPosition)
{
return avPosition.Length();
}
</syntaxhighlight>

HPL3 functions commonly use <code>const Type &in</code> for strings, vectors, colors, matrices, and other value objects which only need to be read.

{{note|A handle parameter is itself passed by value. The called function can modify the shared object, but rebinding its local parameter does not rebind the caller's handle.}}

== Instances and handles in arrays ==

An array declaration also determines whether it stores instances or handles:

<syntaxhighlight lang="c++">
array<cCounter> counters; // Stores counter instances.
array<cCounter@> targets; // Stores handles to counter instances.
</syntaxhighlight>

An array of instances owns independent elements. Reading an element into another object variable copies it:

<syntaxhighlight lang="c++">
cCounter copy;
copy = counters[0];

copy.mlValue = 5;

// counters[0].mlValue was not changed.
</syntaxhighlight>

To edit the actual instance inside the array through an alias, take a handle to that element:

<syntaxhighlight lang="c++">
cCounter@ pCounter = @counters[0];
pCounter.mlValue = 5;

// counters[0].mlValue is now 5.
</syntaxhighlight>

This pattern is used by the shipped HPL3 scripts when updating class instances stored in arrays:

<syntaxhighlight lang="c++">
for(uint i = 0; i < mvShakes.size(); ++i)
{
cLuxEffect_ShakeInstance@ pShake = @mvShakes[i];
pShake.mfTime -= afTimeStep;
}
</syntaxhighlight>

An array of handles behaves differently. Its elements may be <code>null</code>, and several elements can refer to the same object:

<syntaxhighlight lang="c++">
array<iLuxEntity@> vEntities;
vEntities.push_back(Map_GetEntity("EntityA"));
vEntities.push_back(Map_GetEntity("EntityA"));

// Both elements may refer to the same map entity.
</syntaxhighlight>

== Choosing between an instance and a handle ==

Use an object instance when:

* the variable should own independent data;
* copying the object's state is the desired behavior;
* the value must always exist rather than being optional; or
* working with an HPL3 value type such as a vector, color, matrix, or ID.

Use an object handle when:

* referring to an object which already exists;
* several parts of the script must share the same object;
* <code>null</code> is a useful "no object" state;
* working with HPL3-owned entities, physics objects, resources, or GUI objects;
* using a base class or interface to refer to different derived types; or
* modifying an existing instance stored inside a container.

For a long-lived reference to an HPL3-owned world object, store its <code>tID</code> and resolve a temporary handle when needed. See [[HPL3/Scripting/Scripting Guide/Object Handles#Persistent references and tID|Object Handles]] and [[HPL3/Scripting/ID Handles|ID Handles]].

== Common mistakes ==

{| class="wikitable"
! Mistake
! Result
! Correct approach
|-
| Expecting <code>second = first</code> to make <code>second</code> an alias.
| The destination receives copied object data.
| Declare a handle and use <code>@second = @first</code>.
|-
| Expecting a handle assignment to copy the object.
| Both handles refer to one shared instance.
| Create another instance and use value assignment when an independent copy is needed.
|-
| Changing a copied array element and expecting the array to change.
| Only the local copy changes.
| Take a handle to the element with <code>@array[index]</code>, or assign the changed value back.
|-
| Assuming an object copy is always deep.
| Handle members in the copy still refer to the original referenced objects.
| Implement explicit deep-copy behavior when required.
|-
| Declaring an engine interface as a local instance.
| The type may be abstract, non-instantiable, or engine-owned.
| Retrieve the object through an HPL3 function and store the returned handle.
|-
| Using a handle where independent state is required.
| Changes made through any alias affect the shared object.
| Store an instance or create an explicit copy.
|-
| Keeping a raw engine-object handle as persistent saved state.
| The referenced engine object may be destroyed or reconstructed.
| Store a <code>tID</code>, resolve it when needed, and validate the returned handle.
|}

== See Also ==

* [[HPL3/Scripting/Scripting Guide/Object Handles|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]]
* [[HPL3/Scripting/AngelScript Fundamentals/Chapter 9 - Miscellaneous AngelScript Features|Miscellaneous AngelScript Features]]

{{NavBar|HPL3/Scripting/Scripting Guide/Object Handles|Object Handles|HPL3/Scripting/HPL3 Scripting Guide|HPL3 Scripting Guide|HPL3/Scripting/Scripting Guide/Type Casting|Type Casting}}

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

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

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