GetFirstObjectInShape(int, float, location, int, int, vector)

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

object GetFirstObjectInShape(
    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) or RADIUS_SIZE_*.

lTarget

The starting location of the shape.

bLineOfSight

This can be used to ensure that spell effects do not go through walls. (Default: FALSE)

nObjectFilter

Restrict results to this object type (OBJECT_TYPE_*). (Default: OBJECT_TYPE_CREATURE)

vOrigin

Normally the spell-caster's position. (Default: [0.0,0.0,0.0])

Description

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

The meaning of fSize depends on nShape:
If nShape == SHAPE_SPHERE, fSize is the radius of the sphere.
If nShape == SHAPE_SPELLCYLINDER, fSize is the radius of the cylinder.
If nShape == SHAPE_CONE, fSize is the widest radius of the cone.
If nShape == SHAPE_CUBE, fSize is half the length of one of the sides of the cube.

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

Known Bugs

This function does not appear to return OBJECT_TYPE_PLACEABLE objects, either by using that keyword or OBJECT_TYPE_ALL.

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

Example

// From the Bioware script that implements the burning hands spell

// [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]