GetFirstObjectInArea

From NWN Lexicon
Jump to: navigation, search

GetFirstObjectInArea(object)

Determines the first object in an area.

object GetFirstObjectInArea(
    object oArea = OBJECT_INVALID
);

Parameters

oArea

The area that contains the objects. (Default: OBJECT_INVALID)


Description

Returns the first object in oArea and OBJECT_INVALID if no objects exists or on any error.

If no valid area is specified, it will use the caller's area.



Remarks

Useful for making sure all things of a certain tag, or type, in an area are destroyed and may be easier then using GetObjectByTag().

Do not do it too often in larger, or more populated areas.

For the older Bioware version of the game, there is no way to loop areas in a module. Therefore, it is hard to loop all objects in a module.

Warning icon orange.png Caution: This section documents changes arising in NWN: Enhanced Edition content. The content is available in both the classic version and the Enhanced Edition of the game. However, the behavior may vary in each version. More details may be available in the NWN Enhanced Edition patch notes.
For users of the BeamDog Enhanced Edition of the game, this feature is available by way of the GetFirstArea() and GetNextArea() functions.


Known Bugs

Sound objects and creatures possessed by a DM are skipped. Sound objects can instead be fetched by using GetObjectByTag, GetNearestObjectByTag or similar.


Version

1.62

Example

// Any objects in the area tagged "DESTROY" are destroyed.
// Uses OBJECT_SELF as the area, but this can be substituted for
// many things.
 
void main()
{
    // Loop all objects in us, an area
    object oArea = OBJECT_SELF;
    object oObject = GetFirstObjectInArea(oArea);
    while(GetIsObjectValid(oObject))
    {
         // Destroy any objects tagged "DESTROY"
         if(GetTag(oObject) == "DESTROY")
         {
             DestroyObject(oObject);
         }
         oObject = GetNextObjectInArea(oArea);
    }
}

See Also

functions: 

GetNextObjectInArea



 author: Tom Cassiotis, editor: Jasperre, additional contributor(s): Enigmatic, Jazael, Charles Feduke, Jasperre, Shadguy