GetNearestCreature(int, int, object, int, int, int, int, int)

Determines the nearest creature to a target object.

object GetNearestCreature(
    int nFirstCriteriaType,
    int nFirstCriteriaValue,
    object oTarget = OBJECT_SELF,
    int nNth = 1,
    int nSecondCriteriaType = -1,
    int nSecondCriteriaValue = -1,
    int nThirdCriteriaType = -1,
    int nThirdCriteriaValue = -1
);

Parameters

nFirstCriteriaType

CREATURE_TYPE_* (see description below for more details)

nFirstCriteriaValue

CLASS_TYPE_*, SPELL_*, PERCEPTION_*, PLAYER_CHAR_IS_PC, PLAYER_CHAR_NOT_PC , RACIAL_TYPE_* , REPUTATION_TYPE_*, TRUE OR FALSE (value is dependent on nFirstCriteriaType, see function description below for details)

oTarget

We're trying to find the creature of the specified type that is nearest to oTarget (Default: OBJECT_SELF)

nNth

We don't have to find the first nearest: we can find the Nth nearest... (Default: 1)

nSecondCriteriaType

This is used in the same way as nFirstCriteriaType to further specify the type of creature that we are looking for. (Default: -1)

nSecondCriteriaValue

This is used in the same way as nFirstCriteriaValue to further specify the type of creature that we are looking for. (Default: -1)

nThirdCriteriaType

This is used in the same way as nFirstCriteriaType to further specify the type of creature that we are looking for. (Default: -1)

nThirdCriteriaValue

This is used in the same way as nFirstCriteriaValue to further specify the type of creature that we are looking for. (Default: -1)

Description

Get the creature nearest to oTarget, subject to all the criteria specified.
Return value on error: OBJECT_INVALID

The function selects the Nth (default is 1, or the nearest) creature that matches the given criteria. By default the oTARGET is equal to OBJECT_SELF but may be set to another object. The first set of criteria (nFirstCriteriaType & nFirstCriteriaValue) is required. The second and third sets of criteria are optional.

Criteria parameters are paired by type and values, and only accept constant group values. For example, if int nFirstCriteriaType is equal to CREATURE_TYPE_CLASS then nFirstCriteriaValue should be of the form CLASS_TYPE_*. So in this example, the parameters (CREATURE_TYPE_CLASS, CLASS_TYPE_CLERIC) would return the nearest creature that was of class cleric. For a complete list of type/value constant pairings, see the end of this description.

You can further specify the type of creature that you are looking for by using the second and third criteria type/value pairs. For example, (CREATURE_TYPE_PLAYER_CHAR, PLAYER_CHAR_IS_PC, CREATURE_TYPE_IS_ALIVE, TRUE, CREATURE_TYPE_RACIAL_TYPE, RACIAL_TYPE_DWARF) would return the nearest creature that is first a player character, second is alive, and third a dwarf.

The following list shows the criteria types that may be used and the values associated with those types (type value).

CREATURE_TYPE_CLASS CLASS_TYPE_*
CREATURE_TYPE_DOES_NOT_HAVE_SPELL_EFFECT SPELL_*
CREATURE_TYPE_HAS_SPELL_EFFECT SPELL_*
CREATURE_TYPE_IS_ALIVE TRUE OR FALSE
CREATURE_TYPE_PERCEPTION PERCEPTION_*
CREATURE_TYPE_PLAYER_CHAR PLAYER_CHAR_IS_PC OR PLAYER_CHAR_NOT_PC
CREATURE_TYPE_RACIAL_TYPE RACIAL_TYPE_*
CREATURE_TYPE_REPUTATION REPUTATION_TYPE_*

To see the entire list of criteria value constants available, enter one the above value fragments (i.e. SPELL_) into the Aurora editor filter and select the Constants button.

Remarks

Note that the reputation type is applied as if GetIsFriend(oTarget, OBJECT_SELF) and similar functions were used.

Known Bugs

Prior to patch 1.28, this function always returned OBJECT_INVALID when the first and only criteria specified was CREATURE_TYPE_IS_ALIVE.

Version

1.28