GetNearestObject(int, object, int)

From NWN Lexicon
Jump to: navigation, search

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