%getTargets()

    Use this function to retrieve a list of targets from the world. This
    function can find objects, mobiles, exits, and extras from anywhere in the
    world. The following information is EXTREMELY useful for determining how
    to find a target from a range or series of ranges.

    @keywords   - This should be a string of the form used when playing the
                  game. For instance if you wanted to target a troll, you
                  might type any of the folloing:

                    troll       tro/        trol
                    1.troll     1.tr/       1.trol

                  Note that this function does not require the trailing / on a
                  partial match. A partial match without a trailing / will
                  attempt to match exactly first, if tha fails then a partial
                  match will be attempted.

    @range      - This parameter defines a search pattern for finding targets
                  in the world. The general syntax is of the form:

                    "range1[types] range2[types]"

                  The range may be any one of the following characters and has
                  the given meaning:

                    w - the entire world in which @roomId exists
                    t - the entire continent in which @roomId exists
                    a - the entire area in which @roomId exists
                    z - the entire zone in which @roomId exists
                    r - the room defined by @roomId
                    i - the inventory of @source
                    e - the equipped items of @source
                    c - the contents of @container

                The types may be any of the following characters or character
                combinations and has the given meaning:

                    m - search for a mobile in the controlling range
                    p - search for a PC mobile in the controlling range
                    n - search for an NPC mobile in the controlling range
                    o - search for an object in the controlling range
                    e - search for an exit in the controlling range

                    x - search for an extra in the controlling range, this
                        option MUST be followed by one of the following
                        options:

                    r - room extras
                    o - object extras
                    i - inventory
                    e - equipment extras
                    c - container extras (with @container defined)

                For example to first find a mobile target in the current room,
                then an inventory target, then an equipment list target, and
                finally a room object target then you would set the range to
                the following:

                    "r[m] i[o] e[o] r[o]"

                On the other hand, if you weren't interested in inventory or
                equipped items, you could have just done:

                    "r[mo]"

                Finally, if the first character of the range is '!' or '*'
                then the matching will be restricted to exact or partial
                matching respectively.

    @max        - Limit the number of returned targets to at most @max.

    @visible    - If this is set to true (non zero), then the actor defined by
                  @source must be able to see the target. If no @source is
                  defined then this parameter has no bearing on the matched
                  targets. Ifthis parameter is not defined then it defaults to
                  true (non zero).

    @container  - When searching containers for targets, this parameter should
                  be set to the container to be searched.

    @source     - This should be set to the source entity that is doing the
                  targetting. If this is not set then it defaults to the owner
                  of the script, @this. If this is set to the null value then
                  the source is ignored, and so parameters relating to
                  visibility, inventory, and equipment are ignored.

    @roomId     - If you would like the search to take place in a specific
                  location, then you may set this parameter to an appropriate
                  room ID.  If this value is not set, then it defaults to the
                  room in which the script was invoked.

    This function is extremly power, and enables a script developer to find
    complex targets int he world with very few instructions. For instance,
    let's say you want to override a command input by a player and somehow
    affect the target before or after the real command runs, then you might do
    the following:

    Example:
    --------------------------------------------------------------------------

    catch_custom_command
    headbutt

    protect
    {
        @keyword = %stringToWords( %filterActionWords( @arguments ) )->1

        //
        // Check that a keyword was input.
        //
        if( @keyword == "" )
        {
            return
        }
        endif

        //
        // Search for the target mobile in the room.
        //
        @target = %getTargets( @keyword, "r[m]", 1 )

        //
        // Run the normal command first.
        //
        %runCommand( @actor, @command " " @arguments )

        //
        // Do something to the target.
        //
    }
    endprotect