Difference between revisions of "GetNearestObject"

From NWN Lexicon
Jump to: navigation, search
(Undo revision 22659 by 208.91.68.228 (talk))
 
(3 intermediate revisions by 3 users not shown)
Line 1: Line 1:
=GetNearestObject(int, object, int)=
+
{{DISPLAYTITLE:GetNearestObject(int, object, int)}}__NOTOC__
 
 
 
Gets the nearest object, which matches given criteria, to the selected target.
 
Gets the nearest object, which matches given criteria, to the selected target.
 
 
<nwscript>
 
<nwscript>
 
object GetNearestObject(
 
object GetNearestObject(
    OBJECT_TYPE_ALL,
+
    int nObjectType = OBJECT_TYPE_ALL,
 
    object oTarget = OBJECT_SELF,
 
    object oTarget = OBJECT_SELF,
 
    int nNth = 1
 
    int nNth = 1
Line 13: Line 11:
 
====Parameters====
 
====Parameters====
  
''nObjectType''
+
;nObjectType
 +
:Object type to find, an [[object_type|OBJECT_TYPE_* constant]]. More than one can be included with [[Bitwise Operators|bitwise OR]] | (Default: [[ object_type | OBJECT_TYPE_ALL ]])
  
[[ object_type | OBJECT_TYPE_ALL ]])
+
;oTarget
 +
:Object to find things near (Default: OBJECT_SELF)
  
''oTarget''
+
;nNth
 +
:The nNth thing to find (Default: 1)
  
(Default: OBJECT_SELF)
 
  
''nNth''
+
====Description====
  
(Default: 1)
+
Get the Nth object nearest to oTarget that is of the specified type ([[object_type|OBJECT_TYPE_* constant]]). You can use [[Bitwise Operators|bitwise OR]] to contatinate multiple options, eg: doors and placeables would be GetNearestObject(OBJECT_TYPE_DOOR | OBJECT_TYPE_PLACEABLE, OBJECT_SELF, 1);
  
<br />
+
Return value on error: OBJECT_INVALID.
  
====Description====
+
For example, the following script snippet would set object oNearestDoor to the third nearest door to the object oPC:
  
Get the Nth object nearest to oTarget that is of the specified type. <br /> Return value on error: OBJECT_INVALID <br /><br /> The function returns the Nth (default is 1, i.e. nearest) object that matches specified type. By default ‘type’ is set to OBJECT_TYPE_ALL, therefore the function will return the Nth nearest valid object unless you specify a type in the form OBJECT_TYPE_* (see end of description for a complete list of valid object types). Also by default the oTARGET is equal to OBJECT_SELF but may be set to another object. <br /><br /> For example, the following script snippet would set object oNearestDoor to the third nearest door to the object oPC: <br /> object oNearestDoor = GetNearestObject(OBJECT_TYPE_DOOR, oPC, 3) <br /><br /> List of available object types constants: <br /> OBJECT_TYPE_ALL (default) <br /> OBJECT_TYPE_AREA_OF_EFFECT <br /> OBJECT_TYPE_CREATURE <br /> OBJECT_TYPE_DOOR <br /> OBJECT_TYPE_ITEM <br /> OBJECT_TYPE_PLACEABLE <br /> OBJECT_TYPE_STORE <br /> OBJECT_TYPE_TRIGGER <br /> OBJECT_TYPE_WAYPOINT
+
<nwscript>
 +
object o3rdNearestDoor = GetNearestObject(OBJECT_TYPE_DOOR, oPC, 3);
 +
</nwscript>
  
<br /><br />
 
  
 
====Remarks====
 
====Remarks====
  
It can only return objects in oTarget's area, as GetNearestObjectByTag does, and is intended behaviour. <br /><br /> Obviously, this also means Modules and Areas cannot return a valid value for this.
+
It can only return objects in oTarget's area, as [[GetNearestObjectByTag]] does, and is intended behaviour. Obviously, this also means Modules and Areas cannot return a valid value for this.
 +
 
 +
Along with [[GetNearestObjectToLocation]], [[GetNearestObjectByTag]] and [[GetNearestCreature]] if you are running a huge loop - say of a lot of different objects in an area - this function each time it is called runs an entire check of objects from scratch unlike [[GetFirstObjectInShape]]/[[GetNextObjectInShape]]. Therefore in very busy areas it might be better to use [[GetFirstObjectInArea]]/[[GetNextObjectInArea]] to more efficiently loop over the objects you need to affect. For smaller loops or scripts though this is unlikely to be a problem.
  
<br />
 
  
 
====Version====
 
====Version====
  
 
1.22
 
1.22
 +
  
 
====Example====
 
====Example====
Line 57: Line 60:
 
     // Bar maid walks to the third nearest door.
 
     // Bar maid walks to the third nearest door.
 
     ActionForceMoveToObject(oDoor)
 
     ActionForceMoveToObject(oDoor)
 +
}
 +
</nwscript>
 +
 +
<nwscript>
 +
// This script will get the nearest placeable or door object and walk to it
 +
void main()
 +
{
 +
    object oDoorOrPlaceable = GetNearestObject(OBJECT_TYPE_DOOR | OBJECT_TYPE_PLACEABLE, OBJECT_SELF, 1);
 +
    ActionMoveToObject(oDoorOrPlaceable);
 
}
 
}
 
</nwscript>
 
</nwscript>
Line 65: Line 77:
 
| width="1px" align="right" valign="top" | <font color="gray">functions: </font>
 
| width="1px" align="right" valign="top" | <font color="gray">functions: </font>
 
|
 
|
[[ GetNearestObjectToLocation  | GetNearestObjectToLocation ]]
+
[[GetNearestObjectToLocation ]], [[GetNearestCreature]], [[GetNearestObjectByTag]]
|-
 
 
|-
 
|-
 
| width="1px" align="right" valign="top" | <font color="gray">constants: </font>
 
| width="1px" align="right" valign="top" | <font color="gray">constants: </font>

Latest revision as of 16:03, 28 August 2021

Gets the nearest object, which matches given criteria, to the selected target.

object GetNearestObject(
    int nObjectType = OBJECT_TYPE_ALL,
    object oTarget = OBJECT_SELF,
    int nNth = 1
);

Parameters

nObjectType
Object type to find, an OBJECT_TYPE_* constant. More than one can be included with bitwise OR | (Default: OBJECT_TYPE_ALL )
oTarget
Object to find things near (Default: OBJECT_SELF)
nNth
The nNth thing to find (Default: 1)


Description

Get the Nth object nearest to oTarget that is of the specified type (OBJECT_TYPE_* constant). You can use bitwise OR to contatinate multiple options, eg: doors and placeables would be GetNearestObject(OBJECT_TYPE_DOOR | OBJECT_TYPE_PLACEABLE, OBJECT_SELF, 1);

Return value on error: OBJECT_INVALID.

For example, the following script snippet would set object oNearestDoor to the third nearest door to the object oPC:

object o3rdNearestDoor = GetNearestObject(OBJECT_TYPE_DOOR, oPC, 3);


Remarks

It can only return objects in oTarget's area, as GetNearestObjectByTag does, and is intended behaviour. Obviously, this also means Modules and Areas cannot return a valid value for this.

Along with GetNearestObjectToLocation, GetNearestObjectByTag and GetNearestCreature if you are running a huge loop - say of a lot of different objects in an area - this function each time it is called runs an entire check of objects from scratch unlike GetFirstObjectInShape/GetNextObjectInShape. Therefore in very busy areas it might be better to use GetFirstObjectInArea/GetNextObjectInArea to more efficiently loop over the objects you need to affect. For smaller loops or scripts though this is unlikely to be a problem.


Version

1.22


Example

// This script is for a bar maid tagged "BAR_MAID".
// The bar maid will find the third nearest door
// and attempt to walk to it.
 
void main
{
     // Initialize objects.
     object oBarMaid = GetObjectByTag("BAR_MAID");
     object oDoor = GetNearestObject(OBJECT_TYPE_DOOR, oBarMaid, 3)
     // Bar maid walks to the third nearest door.
     ActionForceMoveToObject(oDoor)
}
// This script will get the nearest placeable or door object and walk to it
void main()
{
    object oDoorOrPlaceable = GetNearestObject(OBJECT_TYPE_DOOR | OBJECT_TYPE_PLACEABLE, OBJECT_SELF, 1);
    ActionMoveToObject(oDoorOrPlaceable);
}

See Also

functions: 

GetNearestObjectToLocation , GetNearestCreature, GetNearestObjectByTag

constants: 

OBJECT_TYPE_* Constants



 author: Jason Simpson, editor: Jasperre