GetNearestObjectByTag(string, object, int)

Returns the nearest object to a target by searching for the object’s tag value.

object GetNearestObjectByTag(
    string sTag,
    object oTarget = OBJECT_SELF,
    int nNth = 1
);

Parameters

sTag

oTarget

(Default: OBJECT_SELF)

nNth

(Default: 1)


Description

Returns the Nth object nearest to oTarget that has sTag as its tag value.
Return value on error: OBJECT_INVALID

The function selects the Nth (default is 1, i.e. nearest) nearest object to the given object that matches the supplied tag string. By default the oTARGET is equal to OBJECT_SELF but may be set to another object.

The only parameter required for this function is tag value of type string. For example GetNearestObjectByTag(sFoo) would return the nearest object to the object caller (OBJECT_SELF) that has sFoo as its tag string.

You could also retrieve the 3rd nearest object oStatue1 that has the string tag value of sFoo: GetNearestObjectByTag(sFoo, oStatue1, 3)

Reminder: The required parameter sTag must be a string value. You can do this one of two ways: 1) set the value outside the function call (i.e. string sFoo = “myObjectsTagName”) or 2) use double quotes in the function to input the tag name directly into the function parameters (i.e. GetNearestObjectByTag(“myObjectTagName”) )

You could also retrieve the 3rd nearest object oStatue1 that has the string tag value of sFoo: GetNearestObjectByTag(sFoo, oStatue1, 3)

Reminder: The required parameter stag must be a string value. You can do this one of two ways: 1) set the value outside the function call (i.e. string sFoo = “myObjectsTagName”) or 2) use double quotes in the function to input the tag name directly into the function parameters (i.e. GetNearestObjectByTag(“myObjectTagName”) )



Remarks

GetNearestObjectByTag() only retrieves the nearest object in the area that oTarget occupies.


Version

1.22

Example

//retrieves the nearest object in the area with the same tag as the object calling the function.

void main()
{
     string sTag=GetTag(OBJECT_SELF);
     object oNearestObject=GetNearestObjectByTag(sTag);
}

See Also

functions: GetNearestObject | GetObjectByTag
categories: Get Data from Object Functions


 author: Jason Simpson, editor: Sarev0k
 Send comments on this topic.