GetNextObjectInShape(int, float, location, int, int, vector)

Determines the next object of a specific type (creature, door etc) in shape.

object GetNextObjectInShape(
    int nShape,
    float fSize,
    location lTarget,
    int bLineOfSight = FALSE,
    int nObjectFilter = OBJECT_TYPE_CREATURE,
    vector vOrigin = [0.0,0.0,0.0]
);

Parameters

nShape

SHAPE_*

fSize

The size of the shape (Look at description for more information).

lTarget

The starting location of the shape.

bLineOfSight

This controls whether to do a line-of-sight check on the object returned. (This can be used to ensure that spell effects do not go through walls.) (Default: FALSE)

nObjectFilter

OBJECT_TYPE_* (Default: OBJECT_TYPE_CREATURE)

vOrigin

This is only used for cylinders and cones, and specifies the origin of the effect (normally the spell-caster's position). (Default: [0.0,0.0,0.0])

Description

Returns the next object that is within the specified nShape and fSize and OBJECT_INVALID if no more objects contained.

fSize
- If nShape == SHAPE_SPHERE, this is the radius of the sphere
- If nShape == SHAPE_SPELLCYLINDER, this is the radius of the cylinder
- If nShape == SHAPE_CONE, this is the widest radius of the cone
- If nShape == SHAPE_CUBE, this is half the length of one of the sides of the cube

nObjectFilter
This allows you to filter out undesired object types, using bitwise "or". For example, to return only creatures and doors, the value for this parameter would be OBJECT_TYPE_CREATURE | OBJECT_TYPE_DOOR

For example, to return only creatures and doors, the value for this parameter would be OBJECT_TYPE_CREATURE | OBJECT_TYPE_DOOR

The order for things got during this is not based on range or anything, but normall works clockwise from west (0.0), but this rarely matters.

Remarks

You must first call GetFirstObjectInShape with the same parameters before using this function.

The other shape constant that is not mentioned in the function description, SHAPE_SPELLCONE, is actually used by Bioware in spell scripts - it is probably exactly the same as SHAPE_CONE however.

Known Bugs

Some users have reported that the SHAPE_CONE is not shaped as a cone, and the fact that the constant is only used in one function call throughout the entire official campaign, leads me to believe it may be a bit buggy.

For the SHAPE_SPELLCONE constant, appears lTarget is used for cone angle, ltarget is fSize away in direction of lTarget. "vOrigin" is ignored - it is NOT origin of cone -- origin of cone is location of OBJECT_SELF.

For the SHAPE_SPELLCYLINDER, "fSize" is actually LENGTH of cylinder
"end" of cylinder is "fSize" along line from vOrigin to lTarget.
cylinder width (diameter) is ALWAYS approx. 10 feet?
-Reported by Korak on the Official Forums.

Version

1.22

Example

// From Bioware script that implements Burning Hands

// [Snip][Snip]
oTarget = GetFirstObjectInShape(SHAPE_SPELLCONE, 10.0, GetSpellTargetLocation(), TRUE, OBJECT_TYPE_CREATURE | OBJECT_TYPE_DOOR | OBJECT_TYPE_PLACEABLE);

//Cycle through the targets within the spell shape until an invalid object is captured.
while(GetIsObjectValid(oTarget))
{
   if(!GetIsReactionTypeFriendly(oTarget))
   {
      // Handle saving throws, damage, effects etc.
   }
   //Select the next target within the spell shape.
   oTarget = GetNextObjectInShape(SHAPE_SPELLCONE, 10.0, GetSpellTargetLocation(), TRUE, OBJECT_TYPE_CREATURE | OBJECT_TYPE_DOOR | OBJECT_TYPE_PLACEABLE);
}
// [Snip][Snip]

functions:	GetFirstObjectInShape
categories:	Miscellaneous Functions
constants:	OBJECT_TYPE_* Constants \| SHAPE_* Constants