GetObjectByTag(string, int)

Retrieves an object based on the tag given to it.

object GetObjectByTag(
    string sTag,
    int nNth = 0
);

Parameters

sTag

The tag of the object to search for.

nNth

The Nth object with this tag may be requested. (Default: 0)


Description

Returns the nNth object of the specified tag or OBJECT_INVALID if the object cannot be found.



Remarks

The nNth parameter has been determined to return the nNth closest object to the object executing the script within a current area. Outside of the current area, the scan will begin starting with the last (most recent) area added to the module following this hierarchy:

OBJECT_TYPE_STORE (128)
OBJECT_TYPE_PLACEABLE (64)
OBJECT_TYPE_WAYPOINT (32)
OBJECT_TYPE_AREA_OF_EFFECT (16) (sounds)
OBJECT_TYPE_DOOR (8)
OBJECT_TYPE_TRIGGER (4)
OBJECT_TYPE_ITEM (2)
OBJECT_TYPE_CREATURE (1)


Known Bugs

Previously noted bugs were fixed in a patch some time ago.


Version

1.29

Example

// Demonstrates how to retrieve an object with the GetObjectByTag() funciton and apply a spell effect to it.

void main()
{
     //makes the world appear dark to NPC Bob
     ApplyEffectToObject(DURATION_TYPE_PERMANENT, EffectDarkness(), GetObjectByTag("NPC_BOB"));
}

See Also

functions: ActionJumpToObject | GetNearestObjectByTag | GetNearestObjectToLocation | GetTag
categories: Get Data from Object Functions


 author: Sarev0k, editor: Charles Feduke, additional contributor(s): David Scott, Glenn Berden
 Send comments on this topic.