%randSelect()

    Selects and returns an entry at random from an array of candidates. In its
    simplest form the key of the selected candidate is returned; however,
    other parameters can change this behaviour. The following parameters are
    supported:

        candidates  - A list of candidates from which to select a winner.
        
        max         - Maximum range for random value generation. By default
                      the max is 100. If set to true then it will be the total
                      sum of all chances. If the total sum of all chances
                      exceeds max, then max will be set to the total sum.
        
        chanceKey   - For candidates that have array values. This defines
                      which key points to the probability chance.
        
        returnKey   - By default the winning candidate's key/index is
                      returned. Set this to false to return the value itself
                      or set it to a non empty value to return the value for
                      the associated sub-key in the winning value (expected to
                      be an array).

    This function is used to simplify defining potential actions or prizes
    such that the deifnition structure can be fed to this function and the
    complicated work is done by the function.

    Example:

        // Random action to choose.

        @actions->dance = 10    // 10/100 => 10% chance
        @actions->smile = 20    // 20/100 => 20% chance
        @actions->growl =  4    //  4/100 =>  4% chance
        @actions->glare = 12    // 12/100 => 12% chance

        @action = %randSelect( @actions )

    Result:

        The @action variable will contain a value of "dance", "smile",
        "growl", "glare", or null. Since the combined chances only add up to
        46% there is a 54% chance of no action being selected (since the
        default range is 100).

    Example:

        @actions->dance = 10    // 10/200 =>  5% chance
        @actions->smile = 20    // 20/200 => 10% chance
        @actions->growl =  4    //  4/200 =>  2% chance
        @actions->glare = 12    // 12/200 =>  6% chance

        @action = %randSelect( @actions, 200 )

    Result:

        This time we have set the max range to 200 which has the effect of
        halving the probabilities of any action being selected. There is now
        a corresponding 77% chance of no action.

    Example:

        @actions->dance = 10    // 10/46 => 21.7% chance
        @actions->smile = 20    // 20/46 => 43.5% chance
        @actions->growl =  4    //  4/46 =>  8.7% chance
        @actions->glare = 12    // 12/46 => 26.1% chance

        @action = %randSelect( @actions, true )

    Result:

        This time we have set the max range to true which has the effect of
        making the function calculate the sum of all chances and using that as
        the range. Since the range is based exclusively on the candidates
        chance value, it is guaranteed that an entry will be selected with the
        shown probabilities.

    Example:

        @actions->dance->chance = 10
        @actions->dance->action = "dance " @r

        @actions->smile->chance = 20
        @actions->smile->action = "smile " @r

        @actions->growl->chance =  4
        @actions->growl->action = "growl " @r

        @actions->glare->chance = 12
        @actions->glare->action = "glare " @r

        @action = %randSelect( @actions, true, "chance" )

    Result:

        This time our candidates are arrays. As a result we need to set the
        third parameter, @chanceKey, to say where the chance information can
        be found. In our case we created an entry called chance and so we pass
        "chance" as the third parameter. Similar to earlier examples this will
        still return a value of "dance", "smile", "growl", or "glare". To use
        the more complicated action that targets a person in the room we would
        just get the value using @actions->@action->action :) The next example
        shows how to simplify this.

    Example:

        @actions->dance->chance = 10
        @actions->dance->action = "dance " @r

        @actions->smile->chance = 20
        @actions->smile->action = "smile " @r

        @actions->growl->chance =  4
        @actions->growl->action = "growl " @r

        @actions->glare->chance = 12
        @actions->glare->action = "glare " @r

        @action = %randSelect( @actions, true, "chance", false )

    Result:

        In this example we have added the fourth parameter, @returnKey, to
        false so that instead of returning the selected candidate's key it
        will instead return the value. Instead of using
        @actions->@action->action we can now just use @action->action. The
        next example simplifies this further:

    Example:

        @actions->dance->chance = 10
        @actions->dance->action = "dance " @r

        @actions->smile->chance = 20
        @actions->smile->action = "smile " @r

        @actions->growl->chance =  4
        @actions->growl->action = "growl " @r

        @actions->glare->chance = 12
        @actions->glare->action = "glare " @r

        @action = %randSelect( @actions, true, "chance", "action" )

    Result:

        In this example we have changed the fourth parameter, @returnKey, from
        false to "action". This time the returned value will be the value
        found at that key in the selected candidate's array. In other word,
        if the selected candidate was "growl" the returned value saved in
        @action would be "glare @r". So now we can just use @action.

    Example (Very Practical Example):

        @i = 0

        @i += 1
        @loot->@i->desc   = "a Super Awesome Sword"
        @loot->@i->chance = 5
        @loot->@i->count  = 1
        @loot->@i->itemId = 12001

        @i += 1
        @loot->@i->desc   = "some semi-decent potions of self reflection"
        @loot->@i->chance = 15
        @loot->@i->count  = 3
        @loot->@i->itemId = 12008

        @i += 1
        @loot->@i->desc   = "trash, some seriously disappointing trash"
        @loot->@i->chance = 80
        @loot->@i->count  = 3
        @loot->@i->itemId = 12042

        @prize = %randSelect( @loot, true, "chance", false )

        %echoTo( "Something falls from the sky, it's... " @prize->desc )
        while( @prize->count > 0 )
        {
            %load( item, @prize->itemId, @room )
            @prize->count -= 1
        }
        endwhile