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 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.

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).

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.

Optional Parameter

There is an unused optional parameter for GetFirst/NextObjectInArea, which allows an object filter. This appears to be fully functional and simply defaults to OBJECT_TYPE_ALL in the game code if unused. This will speed up the use of loops when targeting specific object types. It's unknown why Bioware didn't expose this in nwscript.nss

To use it you'd need to use an edited nwscript.nss file with these lines in place of the originals to use the parameter:

// Get the first object in oArea.
// If no valid area is specified, it will use the caller's area.
// - nObjectFilter: Object filter to use, noting sounds cannot be sought
// * Return value on error: OBJECT_INVALID
object GetFirstObjectInArea(object oArea=OBJECT_INVALID, int nObjectFilter = OBJECT_TYPE_ALL);
 
// Get the next object in oArea.
// If no valid area is specified, it will use the caller's area.
// - nObjectFilter: Object filter to use, noting sounds cannot be sought
// * Return value on error: OBJECT_INVALID
object GetNextObjectInArea(object oArea=OBJECT_INVALID, int nObjectFilter = OBJECT_TYPE_ALL);

Known Bugs

Sound objects, DMs and creatures possessed by a DM are skipped. Sound objects can instead be fetched by using GetObjectByTag, GetNearestObjectByTag or similar. DMs can be sought with GetFirstPC/GetNextPC loops.

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:

GetFirstObjectInArea GetFirstArea GetNextArea

---

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