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).
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: |
author: Tom Cassiotis, editor: Jasperre, additional contributor(s): Enigmatic, Jazael, Charles Feduke, Jasperre