GetNextObjectInArea(object)

Determines the next object in an area.

object GetNextObjectInArea(
    object oArea = OBJECT_INVALID
);

Parameters

oArea

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

Description

Returns the next object in oArea and OBJECT_INVALID if no more objects are found or on any errors.

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

Remarks

You must call GetFirstObjectInArea with the same parameter before calling this function.

Useful for making sure all things of a cirtain 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.

There is no way to loop areas in a module, which is a shame (unless a system is devised). Therefore, it is hard to loop all objects in a module (although this is almost never ever ever required).

Known Bugs

Creatures possessed by a DM are skipped.

The remark before about encounters not being picked up by this seem to have changed in the Hordes patches. They are now picked up.

Version

1.62

Example

// Any objects in the area tagged "DESTROY" are destroyed.
// Uses OBJECT_SELF as the area, but this can be subsituted 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);
    }
}

functions:	GetFirstObjectInArea
categories:	Area Functions