handle (
void*
object);
Returns a handle of an engine object. A handle is a unique number that
can
be assigned to any
var or skill
, and identifies that object.
Parameters:
object - ENTITY*, STRING*, BMAP*, VIEW*, PANEL*, TEXT*, FONT*,
SOUND*, or MATERIAL* pointer.
Returns:
Handle of object.
Speed:
Fast
Remarks:
- Unlike a pointer,
a handle to an engine object survives saving/loading and contains the same value at every run of the application.
-
For getting a handle to a lite-C struct that is not an engine object, use the pVars pointer.
- On a single player system, the entity handle
is valid immediately after entity creation (► ent_create). On multiplayer
systems, it can take up to 0.5 seconds until the entity is
created on all connected machines and the handle becomes valid.
The client_id variable can be polled until the handle becomes valid: while (client_id != dplay_id) wait(1);
. Before it becomes valid, the entity handle can not be used.
- For using a handle to get the
referenced object, it can be converted to a pointer through the ptr_for_handle instruction.
- The handle is stored
in the first 4 bytes of an engine object.
It consists of
a unique index number plus an object type identifier
in the high byte, taken
from the following table
.
The handle can be used to identify the type of the object.
For converting the handle to a var that contains the index
number, right shift it by
24, then left shift the resulting int by
10. The identifiers are defined in atypes.h:
No object (invalid) |
-1 |
HBYTE_STRING |
2 |
HBYTE_ENTITY |
4 |
HBYTE_ENTITY_LOCAL |
5 |
HBYTE_ENTITY_LAYER |
8 |
HBYTE_FONT |
11 |
HBYTE_BMAP |
12 |
HBYTE_MATERIAL |
13 |
HBYTE_SOUND |
14 |
HBYTE_STREAM |
15 |
HBYTE_TEXT |
20 |
HBYTE_PANEL |
21 |
HBYTE_VIEW |
22 |
HBYTE_PARTICLE |
23 |
Example:
if(entity)
{
my.skill48 = handle(entity); // store entity pointer
}
you = ptr_for_handle(my.skill48); // restore YOU;
See also:
ptr_for_handle,
pVars
► latest
version online