Home For Builders Scripting Tutorials Defining An Object

Defining An Object

Intended Audience:
By David Gaider

[Printer Friendly / Syntax Highlight]

Now, this topic is a little more complicated... but I've found myself running into this wall more than once when trying to do something.

Most actions require an object as the target. The easiest way to define an object is to have its particular tag handy... which is great if you know what the target object is going to be. But what if you don't? What if you want to find the nearest PC character... whoever it might be? What if you want to target the nearest creature? What if you want to check how far away something is?

There are lots of different way of checking for things like this... I'm going to focus on three, here: GetNearestCreature, GetNearestObject and GetDistanceBetween.

GetNearestCreature
This command allows you to sort through creatures by their nearness to the object by up to three parameters. Note that the target does not have to be the first nearest of that type... that's simply the default. If you wanted to locate the second-nearest non-PC human rogue, for instance, this is the command that you would use.

The grammar is as follows:

object GetNearestCreature (int nFirstCreatureType, int nFirstParameter, object oTarget=OBJECT_SELF, int nNth=1, int nSecondCreatureType = -1, int nSecondParameter = -1, int nThirdCreatureType = -1, int nThirdParameter = -1 )

This may look a bit confusing, but let's go through it step by step.

The 'nFirstCreatureType' and 'nFirstParameter' are the required initial quality that you are looking for. Say you were looking only for the nearest human... the 'nFirstCreatureType' would be the attribute CREATURE_TYPE_ RACIAL_TYPE, and the 'nFirstParameter' would be RACIAL_TYPE_HUMAN.

Make sense? You have up to three qualities that you can narrow your search by... each requiring both the attribute and the parameter.

The 'oTarget' object is, of course, what the creature you're looking for is near to. It might be OBJECT_SELF (and that's the default) if you're looking for the nearness to the one running the script. You could also do something funky like check for the nearest creature to the nearest PC... but I don't even want to type that out.

The integer 'nNth' is what you use to determine whether you want the first-nearest or otherwise. The default is the first nearest... but any number you specify here will determine how many nearer creatures of the parameter you specify are skipped. Note that any function can be used here so long as it returns an integer... you could put d4() here, for instance, if you randomly wanted the first- to fourth-nearest.

Here, then, are the list of creature types you can sort by:

• CREATURE_TYPE_CLASS = character or monster class
  
• CREATURE_TYPE_DOES_ NOT_HAVE_SPELL_EFFECT = if you were looking for a particular creature that didn't have a specific spell on him (referenced by the constant SPELL_*)... I don't imagine this comes up often.
  
• CREATURE_TYPE_SPELL_EFFECT = the opposite of the above, of course... looking for a creature with a particular spell on him. Note that not all spell effects are 'spells', per se.
  
• CREATURE_TYPE_IS_ALIVE = self-explanatory, should you wish to skip the dead ones.
  
• CREATURE_TYPE_PERCEPTION = this is an odd one, as it technically isn't an attribute of the creature but rather the nature of their perception to the target object... like whether they can be seen or heard.
  
• CREATURE_TYPE_PLAYER_CHAR = this basically sorts whether a creature is a PC or not.
  
• CREATURE_TYPE_RACIAL_TYPE = creature race
  CREATURE_TYPE_REPUTATION = sorts by faction reputation level to the target.

I won't go through all the particular classes, races and effects that can be used as parameters since they are pretty obvious. Some of the others are not so obvious, however.

CREATURE_TYPE_IS_ALIVE:

• TRUE or FALSE (easy)

CREATURE_TYPE_PERCEPTION:

• PERCEPTION_HEARD
  
• PERCEPTION_HEARD_ AND_NOT_SEEN
  
• PERCEPTION_NOT_HEARD
  
• PERCEPTION_NOT_SEEN
  
• PERCEPTION_NOT_SEEN_ AND_NOT_HEARD
  
• PERCEPTION_SEEN
  
• PERCEPTION_SEEN_AND_HEARD
  
• PERCEPTION_SEEN_ AND_NOT_HEARD

CREATURE_TYPE_PLAYER_CHAR:

• PLAYER_CHAR_IS_PC
  
• PLAYER_CHAR_NOT_PC

CREATURE_TYPE_REPUTATION:

• REPUTATION_TYPE_ENEMY
  
• REPUTATION_TYPE_FRIEND
  
• REPUTATION_TYPE_NEUTRAL

------------

So, then... how do we find the nearest PC character to myself?

GetNearestCreature (CREATURE_TYPE_PLAYER_CHAR, PLAYER_CHAR_IS_PC);

The nearest enemy wizard to myself?

GetNearestCreature (CREATURE_TYPE_ REPUTATION, REPUTATION_ENEMY, OBJECT_SELF, 1, CREATURE_TYPE_CLASS, CLASS_TYPE_WIZARD);

The nearest living enemy to my nearest PC ally?

GetNearestCreature (CREATURE_TYPE_ REPUTATION, REPUTATION_ENEMY, GetNearestCreature (CREATURE_TYPE_ PLAYER_CHAR, PLAYER_CHAR_IS_PC, OBJECT_SELF, 1, CREATURE_TYPE_ REPUTATION, REPUTATION_FRIENDLY), 1, CREATURE_TYPE_ IS_ALIVE, TRUE);

The nearest non-PC that I can see?

GetNearestCreature (CREATURE_TYPE_PLAYER_CHAR, PLAYER_CHAR_NOT_PC, OBJECT_SELF, 1, CREATURE_TYPE_ PERCEPTION, PERCEPTION_TYPE_ SEEN);

GetNearestObject
This is much less complicated simply because you can only sort objects by their type... you don't have the multiple parameters that creatures do. Otherwise, however, it works much the same:

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

The 'nObjectType' is, obviously, the kind of object you're looking for. If you don't specify anything, than it will be the nearest object of any kind.

Again, the 'oTarget' object is what your checking the nearest object in relation to... default is OBJECT_SELF, though it doesn't have to be.

'nNth' is the integer that allows you to go beyond the 'nearest'... an nNth of 3 would look for the 'third nearest', for example.

The object types, then, are:

• OBJECT_TYPE_ALL
  
• OBJECT_TYPE_AREA_OF_EFFECT
  
• OBJECT_TYPE_CREATURE
  
• OBJECT_TYPE_DOOR
  
• OBJECT_TYPE_INVALID
  
• OBJECT_TYPE_ITEM
  
• OBJECT_TYPE_PLACEABLE
  
• OBJECT_TYPE_STORE
  
• OBJECT_TYPE_TRIGGER
  
• OBJECT_TYPE_WAYPOINT
  

--------------------

GetDistanceBetween
This reports the distance (in metres) between two valid objects. It is important that both objects be valid, else the distance returned will be 0.

float GetDistanceBetween(object oObjectA, object oObjectB)

(what's a float, incidentally? A float, like an integer, is just a number... but a float always has decimal places. '50' would be an integer... '50.0' would be a float. If you need to, you can use the command int FloatToInt(float fFloat) to convert a float to an integer.)

If you're simply checking how far something is away from the creature or object that is running the script, it is actually easier to use this command:

float GetDistanceToObject(object oObject)

That way you don't have to constantly specify OBJECT_SELF in the GetDistanceBetween command.