ChanceToProc

// ==================================================================================
// ChanceToProc - by Ammorth, April 13, 2009 - rev2
// Please give credit when using this in your map
// This, and myself, can be found at wc3c.net
//
// Can be used for random events to prevent a string of the same event happening for 
// an extended period of time (think critical strike or bash).
//
// This does not return a number, only if it proced or not!
//
// Requirements:
//   - vJass
//
// Installation:
//   - Create a new trigger called ChanceToProc and convert it to custom text
//   - Copy the code to the new trigger, placing everything
//
// How To Use:
//   - Create a new Chance struct with Chance.create(percent, weight)
//   - call .isProc() to get if an event is to proc
//   - call .getWeight() and .getPercent() to check the current values
//   - call .setPercent(percent, weight) to chance the percent and weight values
//   - call .reset() to reset the proc chance "table"
//   - destroy with .destroy()
//
// Notes:
//   - Percent and weight are values within 0.000 and 1.000, other values
//     will be rounded to this range and will show a message when in debug mode.
//   - .isProc(), when called, will change the chance to stop strings of the event
//     from happenning.  Therefore, only call this once each time, as it does change.
//   - Weight is a scalar value that multiplies the weight value (based on the base percent)
//     which determines how much the code tries to change the base percent and keep the short
//     term random within the desired value.  Aka:  A higher weight will me less randomness
//     while a lower weight will be more random but may deviate farther from the desired percent
//     Using a weight value of 0 will cause the script to act like the generic "is X greater than number."
//
// ==================================================================================

library ChanceToProc

struct Chance
    private real base 
    private real current
    private real weight
    
    method setPercent takes real base, real weight returns nothing
        if base < 0. then
            set .base = 0.
            debug call BJDebugMsg("SpecialRandom: Base must be between 0.00 and 1.00")
        elseif base > 1. then
            set .base = 1.
            debug call BJDebugMsg("SpecialRandom: Base must be between 0.00 and 1.00")
        else
            set .base = base
        endif
        if weight < 0. then
            set .weight = 0.
            debug call BJDebugMsg("SpecialRandom: Weight must be between 0.00 and 1.00")
        elseif weight > 1. then
            set .weight = 1.
            debug call BJDebugMsg("SpecialRandom: Weight must be between 0.00 and 1.00")
        else
            set .weight = weight
        endif
        set .weight = .weight/4 // since weight is only effective from 0.0 to .25, this normalizes it up to 1.0
        set .current = base
    endmethod
    
    static method create takes real base, real weight returns Chance
        local Chance this = Chance.allocate()
        call .setPercent(base, weight)
        return this
    endmethod
    
    method isProc takes nothing returns boolean // true if procs (for lack of a better word)
        if .base == 1.0 then // why should it even be random then?
            return true
        elseif .base == .0 then // why should it even be random then?
            return false
        else
            if (.current >= GetRandomReal(0., 1.)) then // this is the random part
                set .current = .current - ((.weight)/(.base)) //reduce the threshold to make it less likely
                return true
            else
                set .current = .current + ((.weight)/(1-.base)) //increase the threshold to make it more likely
                return false
            endif
        endif
    endmethod
    
    method getPercent takes nothing returns real
        return .base
    endmethod
    
    method getWeight takes nothing returns real
        return .weight*4 // multiply by 4 to get back to the original value
    endmethod
    
    method reset takes nothing returns nothing
        set .current = .base // incase you want to reset the threshold for some reason
    endmethod
endstruct

endlibrary