DamageEvent & DamageModifiers

10-21-2009, 02:54 PM

This is a compilation of libraries intended to replace the damage detection and prevention engine ADamage. Originally, this was intended to be merely the next version of ADamage, but some conceptual changes such as moving from damage prevention to more general damage modification made it difficult to maintain backwards compatibility, so I decided to make it a new resource instead which could provide a more general, robust and modular damage detection and modification framework than ADamage. Also, I know some people will like that fact that I gave it a new name.

The resource is split into two libraries:

DamageEvent, a damage detection engine.

If you are already using another damage detection system in your map, DamageEvent will interface with it instead of creating its own damage detection triggers to avoid wasting performance. Currently supported damage detection systems are IDDS and LLDD.

DamageEvent:

library DamageEvent initializer Init requires optional DamageModifiers, optional LightLeaklessDamageDetect, optional IntuitiveDamageSystem, optional xedamage

//*****************************************************************
//*  DAMAGE EVENT LIBRARY
//*
//*  written by: Anitarf
//*  supports: -DamageModifiers
//*
//*  This is a damage detection library designed to compensate for
//*  the lack of a generic "unit takes damage" event in JASS.
//*
//*  All functions following the Response function interface that
//*  is defined at the end of the calibration section of this
//*  library can be used to respond to damage events. Simply add
//*  such functions to the system's call list with the
//*  RegisterDamageResponse function.
//*
//*  function RegisterDamageResponse takes Response r returns nothing
//*
//*  DamageEvent fully supports the use of DamageModifiers. As
//*  long as you have the DamageModifiers library in your map
//*  DamageEvent will use it to modify the damage before calling
//*  the response functions.
//*
//*  If the map contains another damage detection library,
//*  DamageEvent will interface with it instead of creating
//*  it's own damage event triggers to improve performance.
//*  Currently supported libraries are LightLeaklessDamageDetect
//*  and IntuitiveDamageSystem.
//*
//*  DamageEvent is also set up to automatically ignore dummy
//*  damage events sometimes caused by xedamage when validating
//*  targets (only works with xedamage 0.7 or higher).
//*****************************************************************

    globals
        // In wc3, damage events sometimes occur when no real damage is dealt,
        // for example when some spells are cast that don't really deal damage,
        // so this system will only consider damage events where damage is
        // higher than this threshold value.
        private constant real DAMAGE_THRESHOLD = 0.0
        
    // The following calibration options are only used if the system uses
    // it's own damage detection triggers instead of interfacing with other
    // damage event engines:

        // If this boolean is true, the damage detection trigger used by this
        // system will be periodically destroyed and remade, thus getting rid
        // of damage detection events for units that have decayed/been removed.
        private constant boolean REFRESH_TRIGGER = true

        // Each how many seconds should the trigger be refreshed?
        private constant real TRIGGER_REFRESH_PERIOD = 300.0
    endglobals

    private function CanTakeDamage takes unit u returns boolean
        // You can filter out which units need damage detection events with this function.
        // For example, dummy casters will never take damage so the system doesn't need to register events for them,
        // by filtering them out you are reducing the number of handles the game will create, thus increasing performance.
        //return GetUnitTypeId(u)!='e000' // This is a sample return statement that lets you ignore a specific unit type.
        return true
    endfunction

    // This function interface is included in the calibration section
    // for user reference only and should not be changed in any way.
    public function interface Response takes unit damagedUnit, unit damageSource, real damage returns nothing

// END OF CALIBRATION SECTION    
// ================================================================

    globals
        private Response array responses
        private integer responsesCount = 0
    endglobals

    function RegisterDamageResponse takes Response r returns nothing
        set responses[responsesCount]=r
        set responsesCount=responsesCount+1
    endfunction
    
    private function Damage takes nothing returns nothing
        // Main damage event function.
        local unit damaged=GetTriggerUnit()
        local unit damager=GetEventDamageSource()
        local real damage=GetEventDamage()
        local integer i = 0
        
        loop
            exitwhen not (damage>DAMAGE_THRESHOLD)
          static if LIBRARY_xedamage then
            exitwhen xedamage.isDummyDamage
          endif

          static if LIBRARY_DamageModifiers then
            set damage=RunDamageModifiers()
          endif
            
            loop
                exitwhen i>=responsesCount
                call responses[i].execute(damaged, damager, damage)
                set i=i+1
            endloop
            exitwhen true
        endloop

        set damaged=null
        set damager=null
    endfunction
    
    private function DamageC takes nothing returns boolean
        call Damage() // Used to interface with LLDD.
        return false
    endfunction

// ================================================================

    globals
        private group g
        private boolexpr b
        private boolean clear
        
        private trigger currentTrg
        private triggeraction currentTrgA
        private trigger oldTrg = null
        private triggeraction oldTrgA = null
    endglobals

    private function TriggerRefreshEnum takes nothing returns nothing
        // Code "borrowed" from Captain Griffen's GroupRefresh function.
        // This clears the group of any "shadows" left by removed units.
        if clear then
            call GroupClear(g)
            set clear = false
        endif
        call GroupAddUnit(g, GetEnumUnit())
        // For units that are still in the game, add the event to the new trigger.
        call TriggerRegisterUnitEvent( currentTrg, GetEnumUnit(), EVENT_UNIT_DAMAGED )
    endfunction
    private function TriggerRefresh takes nothing returns nothing
        // The old trigger is destroyed with a delay for extra safety.
        // If you get bugs despite this then turn off trigger refreshing.
        if oldTrg!=null then
            call TriggerRemoveAction(oldTrg, oldTrgA)
            call DestroyTrigger(oldTrg)
        endif
        // The current trigger is prepared for delayed destruction.
        call DisableTrigger(currentTrg)
        set oldTrg=currentTrg
        set oldTrgA=currentTrgA
        // The current trigger is then replaced with a new trigger.
        set currentTrg = CreateTrigger()
        set currentTrgA = TriggerAddAction(currentTrg, function Damage)
        set clear = true
        call ForGroup(g, function TriggerRefreshEnum)
        if clear then
            call GroupClear(g)
        endif
    endfunction

// ================================================================

    private function DamageRegister takes nothing returns boolean
        local unit u = GetFilterUnit()
        if CanTakeDamage(u) then
            call TriggerRegisterUnitEvent( currentTrg, u, EVENT_UNIT_DAMAGED )
            call GroupAddUnit(g, u)
        endif
        set u = null
        return false
    endfunction

    private function Init takes nothing returns nothing
        local rect rec
        local region reg
        local trigger t
        
      static if LIBRARY_IntuitiveDamageSystem then

        // IDDS initialization code
        set t=CreateTrigger()
        call TriggerAddAction(t, function Damage)
        call TriggerRegisterDamageEvent(t, 0)

      else
      static if LIBRARY_LightLeaklessDamageDetect then

        // LLDD initialization code
        call AddOnDamageFunc(Condition(function DamageC))

      else
        
        // DamageEvent initialization code
        set rec = GetWorldBounds()
        set reg = CreateRegion()
        set t = CreateTrigger()
        call RegionAddRect(reg, rec)
        call TriggerRegisterEnterRegion(t, reg, Condition(function DamageRegister))
        
        set currentTrg = CreateTrigger()
        set currentTrgA = TriggerAddAction(currentTrg, function Damage)

        set g = CreateGroup()
        call GroupEnumUnitsInRect(g, rec, Condition(function DamageRegister))
        
        if REFRESH_TRIGGER then
            call TimerStart(CreateTimer(), TRIGGER_REFRESH_PERIOD, true, function TriggerRefresh)
        endif
        
        call RemoveRect(rec)
        set rec = null
        set b = null
        
      endif
      endif
    endfunction
endlibrary

DamageModifiers, an optional addon that allows you to modify damage.

Two versions of DamageModifiers are provided, one that uses Table and one that uses AutoIndex.
DamageModifiers can use either xepreload or AbilityPreload to preload the ability it uses.

DamageModifiers (Table version):

library DamageModifiers initializer Init requires Table, optional AbilityPreload, optional xepreload

//*****************************************************************
//*  DAMAGE MODIFIERS LIBRARY (Table version) 1.1
//*
//*  written by: Anitarf
//*  requires: -Table
//*            -a damage detection system (DamageEvent recommended)
//*  optional: -AbilityPreload or xepreload
//*
//*    This is a library that allows you to modify the damage taken
//*  by units. It is the most robust system of this kind available,
//*  it can both reduce and increase damage, when increasing
//*  damage it still awards bounty for kills correctly, it can
//*  tolerate users dealing additional damage on the damage event
//*  as well as allow them to get the correct life of the unit on
//*  this event rather than a value inflated by damage prevention.
//*
//*  IMPLEMENTATION:
//*
//*    It is important to note that different damage modifying
//*  systems can not operate in the same map, so you can not use
//*  this system if you are already using a different one.
//*
//*    DamageModifiers does not work on its own, but is designed to
//*  be used in combination with a damage detection system, which
//*  needs to call the RunDamageModifiers function once whenever a
//*  damage event occurs. The DamageEvent damage detection system
//*  is already configured to do this.
//*
//*    function RunDamageModifiers takes nothing returns real
//*
//*  The real value that the RunDamageModifiers function returns
//*  equals what the damage is after it has been affected by all
//*  modifiers.
//*
//*    To be able to modify damage in situations where it exceeds
//*  the max hp of the damaged unit, this system must temporarily
//*  add a bonus hp ability to the unit. An external Objectmerger
//*  call is provided in the calibration section that generates
//*  this ability in a map automatically when the map is saved.
//*  The ability will also get automatically preloaded to prevent
//*  first-use lag as long as either the xepreload library or the
//*  AbilityPreload library is present in the map.
//*
//*  USAGE:
//*
//*    Damage modifiers are implemented as structs that extend the
//*  system's DamageModifier struct. A damage modifier is created
//*  for a specific unit and can modify both the damage that the
//*  unit deals and receives (using the onDamageDealt and
//*  onDamageTaken methods respectively, see the interface defined
//*  at the end of the calibration section).
//*
//*    Keep in mind that when a struct extends DamageModifier, the
//*  allocate method of that struct must match the create method of
//*  DamageModifier:
//*
//*    static method create takes unit u, integer priority returns DamageModifier
//*
//*    The unit argument determines on which unit will the modifier
//*  be applied and the priority argument determines the order in
//*  which the modifiers will be evaluated. The system always
//*  evaluates the modifiers on the unit dealing the damage and on
//*  the unit taking the damage simultaneously, starting with the
//*  modifiers with the highest priority. If two modifiers share
//*  the same priority, the one on the unit dealing the damage
//*  is evaluated first, if the two modifiers are on the same unit
//*  then the NEW_MODIFIER_ON_TOP calibration constant determines
//*  which gets evaluated first.
//*
//*    The library also provides the functions GetUnitLife and
//*  SetUnitLife. When used outside damage detection, these
//*  functions work the same as the natives GetWidgetLife and
//*  SetWidgetLife, however when called on a unit that has damage
//*  stacked on it these functions will return/modify the life the
//*  unit will have after the damage resolves, rather than its
//*  current life which will be overwritten when damage modifiers
//*  finish processing the unit. Again, the functions are:
//*
//*    function GetUnitLife takes unit u returns real
//*    function SetUnitLife takes unit u, real newLife returns nothing
//*
//*  EXAMPLE:
 /*
    // This damage modifier will simply reduce all damage a unit takes by a constant value.
    struct armour extends DamageModifier
        // All additional struct members are optional:
        static integer PRIORITY=0 // Default priority
        real power // This lets us give different units differently strong armour.

        // create method is optional, if you don't declare one then you must use
        // the .allocate parameters (unit, integer) when creating a modifier of this kind.
        static method create takes unit u, real power returns armour
            // Note the parameters for .allocate, this is because this struct extends
            // DamageModifier which asks for these parameters in its create method:
            local armour this = armour.allocate(u, armour.PRIORITY)
            set this.power = power
            return this
        endmethod

        // This is the method that runs when damage is dealt to the unit with the modifier.
        // The damage parameter tells how much damage got to this modifier past any modifiers
        // with a higher priority that the unit may have.
        // The value that the method returns tells the system by how much to modify the damage,
        // a positive return value increases damage while a negative value reduces it.
        method onDamageTaken takes unit damageSource, real damage returns real
            // This is a simple modifier that just gives a flat damage reduction.
            if this.power>damage then
                return -damage
            endif
            return -this.power
        endmethod
        // There is no onDamageDealt method so this modifier does not affect the damage that the unit deals.
        // onDestroy method is optional, in this case we don't need it.
    endstruct
 */
//*  VERSION HISTORY:
//*  1.1 -Fixed a bug that would cause an incorrect total damage to
//*       be reported back to DamageEvent in some circumstances.
//*      -GetUnitLife returns 0.0 instead of negative values for
//*       for units that are about to die from the stacked damage.
//*      -Narrowed the criteria for applying the survival ability.
//*       it should now only be applied when it is really needed.
//*      -Improved the documentation.
//*****************************************************************

    globals
        // If two modifiers have the same priority, which one should
        // modify the damage first? If true, the newer modifier will.
        private constant boolean NEW_MODIFIER_ON_TOP = true 

        // If more damage is dealt to the unit than the unit's max hp, then this
        // system must temporarily add a bonus hp ability to the unit in order to
        // facilitate damage prevention.
        // An objectmerger call is provided below that automatically generates
        // the ability when you save the map in the NewGen world editor.
        private constant integer SURVIVAL_ABILITY = 'DMsa'
    endglobals

    // This objectmerger call only needs to run once to generate the ability in a map,
    // just save the map to run it, then close the map and re-open it and the ability
    // should be there, after that you can disable the objectmerget call to speed up
    // the map saving process in the future.
    // (To disable the call, delete the "!" so it turns from a command into a comment.)
    //! external ObjectMerger w3a AIl1 DMsa anam "LifeBonus" ansf "(DamageModifiers)" Ilif 1 100000 aite 0

    // This interface is included in the calibration section
    // for user reference only and should not be changed in any way.
    // It is private because your modifiers shouldn't extend it directly,
    // but should extend the DamageModifer struct instead.
    private interface DamageModiferTemplate
        // Returned real determines by how much the damage the unit deals should be modified.
        method onDamageDealt takes unit damagedUnit, real damage returns real defaults 0.0 
        // Returned real determines by how much the damage the unit is dealt should be modified.
        method onDamageTaken takes unit damageSource, real damage returns real defaults 0.0
    endinterface

// END OF CALIBRATION SECTION    
// ================================================================

    private keyword Evaluate

    // DAMAGE MODIFIER STRUCT
    // To create your own damage modifiers, extend this struct.
    struct DamageModifier extends DamageModiferTemplate
        private unit targetunit
        integer priority

        private DamageModifier next=0
        private static HandleTable first

        private method listInsert takes nothing returns nothing
            local DamageModifier dm=DamageModifier(DamageModifier.first[.targetunit])
            if dm==0 or dm.priority<.priority or (NEW_MODIFIER_ON_TOP and dm.priority==.priority) then
                set .next=DamageModifier(DamageModifier.first[.targetunit])
                set DamageModifier.first[.targetunit]=integer(this)
            else
                loop
                    exitwhen dm.next == 0 or dm.next.priority<.priority or (NEW_MODIFIER_ON_TOP and dm.next.priority==.priority)
                    set dm=dm.next
                endloop
                set .next=dm.next
                set dm.next=this
            endif
        endmethod

        private method listRemove takes nothing returns nothing
            local DamageModifier dm=DamageModifier(DamageModifier.first[.targetunit])
            if dm==this then
                set DamageModifier.first[.targetunit]=integer(.next)
            else
                loop
                    exitwhen dm.next==this
                    set dm=dm.next
                endloop
                set dm.next=.next
            endif
        endmethod

        // ================================================================

        static method create takes unit u, integer priority returns DamageModifier
            local DamageModifier this
            if u==null then
                return 0
            endif
            set this=DamageModifier.allocate()
            set .targetunit=u
            set .priority = priority
            
            call .listInsert()

            return this
        endmethod

        method onDestroy takes nothing returns nothing
            call .listRemove()
            if DamageModifier.first[.targetunit]==0 then
                call DamageModifier.first.flush(.targetunit)
            endif
        endmethod

        // ================================================================

        static method onInit takes nothing returns nothing
            set DamageModifier.first=HandleTable.create()
        endmethod

        static method Evaluate takes unit damaged, unit damager, real damage returns real
        // Loops through all the modifiers involved in a damage event and
        // returns the total amount by which the damage must be modified.
        // Positive values meaning a damage increase and negative a damage decrease.
            local real modifier=0.0
            local DamageModifier this=DamageModifier(DamageModifier.first[damager])
            local DamageModifier that=DamageModifier(DamageModifier.first[damaged])
            loop
                exitwhen this==0 and that==0
                if this!=0 and (that==0 or this.priority>=that.priority) then
                    set modifier=modifier+this.onDamageDealt(damaged, damage+modifier)
                    set this=this.next
                elseif that !=0 then
                    set modifier=modifier+that.onDamageTaken(damager, damage+modifier)
                    set that=that.next
                endif
            endloop
            return modifier
        endmethod
    endstruct

// ================================================================

    // DAMAGE STRUCT
    // This is an internal struct created whenever a unit takes damage and
    // destroyed after a 0.0 second timer to allow the damage to be dealt.
    // If multiple damage events occur on that unit in that time, a single
    // Damage struct will handle all of them.
    private struct Damage
        unit u

        real hp=0.0
        // Stores the correct hp of the unit. The actual hp may be higher
        // if not all damage that was stacked on the unit has resolved yet,
        // however once the damage resolves the correct hp and actual hp
        // values should match again.
        // There are two exceptions when this does not happen:
        // - Actual hp could not be set correctly because that would kill the unit.
        //   (in case of damage modifiers that increase damage)
        // - Actual hp could not be set correctly because of unit's max life limit.
        //   (in case of damage modifiers that reduce damage)

        real temp=0.0
        // In the case of the two exceptions mentioned above, this stores by how
        // much the life of the unit could not be increased or reduced, so this
        // is essentially the difference between the unit's actual and correct hp
        // (after the damage stacked on the unit is resolved, of course).

        // If another damage event should occur before the first one resolves,
        // this value will be added to the new damage modifier, ensuring that any
        // life modifications that couldn't be done previously are not forgotten.
        // This way, if one damage event has a positive modifier and an event that
        // occurs in response has a negative modifier or vice versa, the two will
        // properly cancel each other even if the first one of them couldn't be
        // fully applied. Likewise, if the unit is given the survival ability, any
        // damage reduction that couldn't be aplied earlier due to max hp limit
        // will get applied properly once the unit's max hp is increased.
        
        private Damage next
        private static Damage first=0
        // A list of all active Damage structs.
        private static timer delay=CreateTimer()
        // The timer used to wait for the damage to be dealt.

        private static method get takes unit u returns Damage
            // In most cases, only one or very few units will be damaged
            // at the same time, so a linear O(n) search is acceptable.
            local Damage this=Damage.first
            loop
                exitwhen this==0 or .u==u
                set this=.next
            endloop
            return this
        endmethod
        private static method create takes unit u returns Damage
            // The only time a Damage is created is when it doesn't yet exist for the unit.
            local Damage this=Damage.allocate()
            set .u = u
            set .next = Damage.first
            set Damage.first=this
            return this
        endmethod
        method onDestroy takes nothing returns nothing
            // The only time a Damage is destroyed is when it is first, so this works.
            set Damage.first=.next
            set .u = null
        endmethod
        
        // ================================================================

        private static method end takes nothing returns nothing
            // This method is called with a very slight delay, which allows it to run
            // after the life of the damaged unit has already been reduced by the damage.
            loop
                exitwhen Damage.first==0
                call UnitRemoveAbility(Damage.first.u, SURVIVAL_ABILITY)
                call SetWidgetLife(Damage.first.u, Damage.first.hp)
                call Damage.first.destroy()
            endloop
        endmethod

        static method RunModifiers takes nothing returns real
            local unit damaged = GetTriggerUnit()
            local unit damager = GetEventDamageSource()
            local real damage = GetEventDamage()
            local real modifier = 0.0
            local real life = GetWidgetLife(damaged)
            local real maxlife = GetUnitState(damaged,UNIT_STATE_MAX_LIFE)
            local real stackeddamage
            local Damage d
        
            if damaged==null then
                // Method not called from a damage event, terminate.
                set damager=null
                set damaged=null
                return 0.0
            endif
        
            // Calculate by how much to modify the damage.
            set modifier=DamageModifier.Evaluate(damaged, damager, damage)

            // Get the unit's Damage struct.
            set d=Damage.get(damaged)
            if d==0 then
                // First damage, create a new damage struct.
                set d=Damage.create(damaged)
                set d.hp=life
                call TimerStart(Damage.delay, 0.0, false, function Damage.end)
            endif

            // Calculate the unresolved real damage stacked on the unit.
            set stackeddamage=((life-d.temp)-d.hp)+damage
            // Calculate the modified damage.
            set damage=damage+modifier
            // Calculate the correct hp of the unit.
            set d.hp=d.hp-damage
            // Check if we need to add the survival ability.
            if d.hp>0.405 and maxlife-stackeddamage<=0.405 then
                call UnitAddAbility(damaged, SURVIVAL_ABILITY)
                set maxlife = GetUnitState(damaged,UNIT_STATE_MAX_LIFE)
            endif
            // If the unit's life couldn't be reduced or increased as much as we wanted
            // on a previous damage event, it's time we compensate for that now.
            set modifier=modifier+d.temp
            set d.temp=0.0

            // Modify unit life to make it appear as if damage was modified.
            if life-modifier>0.405 and life-modifier<=maxlife then
                // Set the unit's life so that after the damage is dealt, it will be correct.
                call SetWidgetLife(damaged, life-modifier)
            elseif life-modifier>maxlife then
                // The unit's maxlife is preventing us from increasing life as needed,
                // we need to remember that in the case the survival ability is ever added
                // to the unit on another damage event before this damage resolves.
                set d.temp=modifier-(life-maxlife)
                call SetWidgetLife(damaged, maxlife)
            else
                // We have a damage modifier value that would kill the unit, so we
                // let the actual damage kill it instead, thus awarding proper bounty.
                // We need to remember that we failed to reduce the life as needed in case
                // the unit is healed in response to this damage.
                set d.temp=modifier-(life-0.406)
                call SetWidgetLife(damaged, 0.406)
            endif

            set damaged=null
            set damager=null
            return damage
        endmethod
        
        // ================================================================

        static method getLife takes unit u returns real
            local Damage d=Damage.get(u)
            if d==0 then
                return GetWidgetLife(u)
            endif
            if d.hp<=0.405 then
                return 0.0
            endif
             return d.hp
        endmethod

        static method setLife takes unit u, real newLife returns nothing
           local Damage d=Damage.get(u)
            local real modifier
            local real life
            local real maxlife
            local real stackeddamage

            if d==0 then
                // Unit not taking damage, proceed with setting the unit's life.
                call SetWidgetLife(u, newLife)
            else
                // Calculate by how much the unit's life will change.
                set modifier=newLife-d.hp
                if modifier>0 and d.hp<=0.405 then
                // Increasing life in a situation where the damage is about to kill the unit,
                // so we must intervene and increase the unit's actual life as well.
                    set life=GetWidgetLife(u)
                    set maxlife = GetUnitState(u,UNIT_STATE_MAX_LIFE)
                    // Calculate the unresolved damage stacked on the unit.
                    set stackeddamage=(life-d.temp)-d.hp
                    // Check if we need to add the survival ability.
                    if d.hp>0.405 and maxlife-stackeddamage<=0.405 then
                        call UnitAddAbility(u, SURVIVAL_ABILITY)
                        set maxlife = GetUnitState(u,UNIT_STATE_MAX_LIFE)
                    endif
                    set d.hp=newLife
                    if maxlife-life>modifier then
                        call SetWidgetLife(u, life+modifier)
                    else
                        call SetWidgetLife(u, maxlife)
                        set d.temp=d.temp-modifier+maxlife-life
                    endif
                else
                // Nothing to worry about, the rest of the code will handle everything.
                    set d.hp=newLife
                    set d.temp=d.temp-modifier
                endif
            endif
        endmethod
    endstruct
    
// ================================================================

    private function Init takes nothing returns nothing
      static if LIBRARY_xepreload then
        call XE_PreloadAbility(SURVIVAL_ABILITY)
      else
      static if LIBRARY_AbilityPreload then
        call AbilityPreload(SURVIVAL_ABILITY)
      endif
      endif
    endfunction

// ================================================================

    // To make this system work, call this function once whenever a damage event occurs.
    // The DamageEvent library is already designed to do this.
    function RunDamageModifiers takes nothing returns real
        return Damage.RunModifiers()
    endfunction

    // These functions allow you to get/set the proper life of a unit even when it's taking damage.
    function GetUnitLife takes unit u returns real
        return Damage.getLife(u)
    endfunction
    function SetUnitLife takes unit u, real newLife returns nothing
        call Damage.setLife(u, newLife)
    endfunction
endlibrary

DamageModifiers (AutoIndex version):

library DamageModifiers initializer Init requires AutoIndex, optional AbilityPreload, optional xepreload

//*****************************************************************
//*  DAMAGE MODIFIERS LIBRARY (AutoIndex version) 1.1
//*
//*  written by: Anitarf
//*  requires: -AutoIndex
//*            -a damage detection system (DamageEvent recommended)
//*  optional: -AbilityPreload or xepreload
//*
//*    This is a library that allows you to modify the damage taken
//*  by units. It is the most robust system of this kind available,
//*  it can both reduce and increase damage, when increasing
//*  damage it still awards bounty for kills correctly, it can
//*  tolerate users dealing additional damage on the damage event
//*  as well as allow them to get the correct life of the unit on
//*  this event rather than a value inflated by damage prevention.
//*
//*  IMPLEMENTATION:
//*
//*    It is important to note that different damage modifying
//*  systems can not operate in the same map, so you can not use
//*  this system if you are already using a different one.
//*
//*    DamageModifiers does not work on its own, but is designed to
//*  be used in combination with a damage detection system, which
//*  needs to call the RunDamageModifiers function once whenever a
//*  damage event occurs. The DamageEvent damage detection system
//*  is already configured to do this.
//*
//*    function RunDamageModifiers takes nothing returns real
//*
//*  The real value that the RunDamageModifiers function returns
//*  equals what the damage is after it has been affected by all
//*  modifiers.
//*
//*    To be able to modify damage in situations where it exceeds
//*  the max hp of the damaged unit, this system must temporarily
//*  add a bonus hp ability to the unit. An external Objectmerger
//*  call is provided in the calibration section that generates
//*  this ability in a map automatically when the map is saved.
//*  The ability will also get automatically preloaded to prevent
//*  first-use lag as long as either the xepreload library or the
//*  AbilityPreload library is present in the map.
//*
//*    In this AutoIndex version of this library, damage modifiers
//*  can not be added to units that are not indexed, also, if such
//*  units take damage, damage modifiers will not be evaluated.
//*
//*  USAGE:
//*
//*    Damage modifiers are implemented as structs that extend the
//*  system's DamageModifier struct. A damage modifier is created
//*  for a specific unit and can modify both the damage that the
//*  unit deals and receives (using the onDamageDealt and
//*  onDamageTaken methods respectively, see the interface defined
//*  at the end of the calibration section).
//*
//*    Keep in mind that when a struct extends DamageModifier, the
//*  allocate method of that struct must match the create method of
//*  DamageModifier:
//*
//*    static method create takes unit u, integer priority returns DamageModifier
//*
//*    The unit argument determines on which unit will the modifier
//*  be applied and the priority argument determines the order in
//*  which the modifiers will be evaluated. The system always
//*  evaluates the modifiers on the unit dealing the damage and on
//*  the unit taking the damage simultaneously, starting with the
//*  modifiers with the highest priority. If two modifiers share
//*  the same priority, the one on the unit dealing the damage
//*  is evaluated first, if the two modifiers are on the same unit
//*  then the NEW_MODIFIER_ON_TOP calibration constant determines
//*  which gets evaluated first.
//*
//*    The library also provides the functions GetUnitLife and
//*  SetUnitLife. When used outside damage detection, these
//*  functions work the same as the natives GetWidgetLife and
//*  SetWidgetLife, however when called on a unit that has damage
//*  stacked on it these functions will return/modify the life the
//*  unit will have after the damage resolves, rather than its
//*  current life which will be overwritten when damage modifiers
//*  finish processing the unit. Again, the functions are:
//*
//*    function GetUnitLife takes unit u returns real
//*    function SetUnitLife takes unit u, real newLife returns nothing
//*
//*  EXAMPLE:
 /*
    // This damage modifier will simply reduce all damage a unit takes by a constant value.
    struct armour extends DamageModifier
        // All additional struct members are optional:
        static integer PRIORITY=0 // Default priority
        real power // This lets us give different units differently strong armour.

        // create method is optional, if you don't declare one then you must use
        // the .allocate parameters (unit, integer) when creating a modifier of this kind.
        static method create takes unit u, real power returns armour
            // Note the parameters for .allocate, this is because this struct extends
            // DamageModifier which asks for these parameters in its create method:
            local armour this = armour.allocate(u, armour.PRIORITY)
            set this.power = power
            return this
        endmethod

        // This is the method that runs when damage is dealt to the unit with the modifier.
        // The damage parameter tells how much damage got to this modifier past any modifiers
        // with a higher priority that the unit may have.
        // The value that the method returns tells the system by how much to modify the damage,
        // a positive return value increases damage while a negative value reduces it.
        method onDamageTaken takes unit damageSource, real damage returns real
            // This is a simple modifier that just gives a flat damage reduction.
            if this.power>damage then
                return -damage
            endif
            return -this.power
        endmethod
        // There is no onDamageDealt method so this modifier does not affect the damage that the unit deals.
        // onDestroy method is optional, in this case we don't need it.
    endstruct
 */
//*  VERSION HISTORY:
//*  1.1 -Fixed a bug that would cause an incorrect total damage to
//*       be reported back to DamageEvent in some circumstances.
//*      -GetUnitLife returns 0.0 instead of negative values for
//*       for units that are about to die from the stacked damage.
//*      -Narrowed the criteria for applying the survival ability,
//*       it should now only be applied when it is really needed.
//*      -Improved the documentation.
//*****************************************************************

    globals
        // If two modifiers have the same priority, which one should
        // modify the damage first? If true, the newer modifier will.
        private constant boolean NEW_MODIFIER_ON_TOP = true 

        // If more damage is dealt to the unit than the unit's max hp, then this
        // system must temporarily add a bonus hp ability to the unit in order to
        // facilitate damage prevention.
        // An objectmerger call is provided below that automatically generates
        // the ability when you save the map in the NewGen world editor.
        private constant integer SURVIVAL_ABILITY = 'DMsa'
    endglobals

    // This objectmerger call only needs to run once to generate the ability in a map,
    // just save the map to run it, then close the map and re-open it and the ability
    // should be there, after that you can disable the objectmerget call to speed up
    // the map saving process in the future.
    // (To disable the call, delete the "!" so it turns from a command into a comment.)
    //! external ObjectMerger w3a AIl1 DMsa anam "LifeBonus" ansf "(DamageModifiers)" Ilif 1 100000 aite 0

    // This interface is included in the calibration section
    // for user reference only and should not be changed in any way.
    // It is private because your modifiers shouldn't extend it directly,
    // but should extend the DamageModifer struct instead.
    private interface DamageModiferTemplate
        // Returned real determines by how much the damage the unit deals should be modified.
        method onDamageDealt takes unit damagedUnit, real damage returns real defaults 0.0 
        // Returned real determines by how much the damage the unit is dealt should be modified.
        method onDamageTaken takes unit damageSource, real damage returns real defaults 0.0
    endinterface

// END OF CALIBRATION SECTION    
// ================================================================

    private keyword Evaluate

    // DAMAGE MODIFIER STRUCT
    // To create your own damage modifiers, extend this struct.
    struct DamageModifier extends DamageModiferTemplate
        private unit targetunit
        private integer priority

        private DamageModifier next=0
        private static DamageModifier array first

        private method listInsert takes nothing returns nothing
            local DamageModifier dm=DamageModifier.first[GetUnitId(.targetunit)]
            if dm==0 or dm.priority<.priority or (NEW_MODIFIER_ON_TOP and dm.priority==.priority) then
                set .next=DamageModifier.first[GetUnitId(.targetunit)]
                set DamageModifier.first[GetUnitId(.targetunit)]=this
            else
                loop
                    exitwhen dm.next == 0 or dm.next.priority<.priority or (NEW_MODIFIER_ON_TOP and dm.next.priority==.priority)
                    set dm=dm.next
                endloop
                set .next=dm.next
                set dm.next=this
            endif
        endmethod

        private method listRemove takes nothing returns nothing
            local DamageModifier dm=DamageModifier.first[GetUnitId(.targetunit)]
            if dm==this then
                set DamageModifier.first[GetUnitId(.targetunit)]=.next
            else
                loop
                    exitwhen dm.next==this
                    set dm=dm.next
                endloop
                set dm.next=.next
            endif
        endmethod

        // ================================================================

        static method create takes unit u, integer priority returns DamageModifier
            local DamageModifier this
            if u==null or not(IsUnitIndexed(u)) then
                return 0
            endif
            set this=DamageModifier.allocate()
            set .targetunit=u
            set .priority = priority
            
            call .listInsert()

            return this
        endmethod

        method onDestroy takes nothing returns nothing
            call .listRemove()
        endmethod

        // ================================================================

        static method Evaluate takes unit damaged, unit damager, real damage returns real
        // Loops through all the modifiers involved in a damage event and
        // returns the total amount by which the damage must be modified.
        // Positive values meaning a damage increase and negative a damage decrease.
            local real modifier=0.0
            local DamageModifier this=0
            local DamageModifier that=DamageModifier(DamageModifier.first[GetUnitId(damaged)])
            if IsUnitIndexed(damager) then
                set this=DamageModifier(DamageModifier.first[GetUnitId(damager)])
            endif
            loop
                exitwhen this==0 and that==0
                if this!=0 and (that==0 or this.priority>=that.priority) then
                    set modifier=modifier+this.onDamageDealt(damaged, damage+modifier)
                    set this=this.next
                elseif that !=0 then
                    set modifier=modifier+that.onDamageTaken(damager, damage+modifier)
                    set that=that.next
                endif
            endloop
            return modifier
        endmethod
    endstruct

// ================================================================

    // DAMAGE STRUCT
    // This is an internal struct created whenever a unit takes damage and
    // destroyed after a 0.0 second timer to allow the damage to be dealt.
    // If multiple damage events occur on that unit in that time, a single
    // Damage struct will handle all of them.
    private struct Damage
        unit u

        real hp=0.0
        // Stores the correct hp of the unit. The actual hp may be higher
        // if not all damage that was stacked on the unit has resolved yet,
        // however once the damage resolves the correct hp and actual hp
        // values should match again.
        // There are two exceptions when this does not happen:
        // - Actual hp could not be set correctly because that would kill the unit.
        //   (in case of damage modifiers that increase damage)
        // - Actual hp could not be set correctly because of unit's max life limit.
        //   (in case of damage modifiers that reduce damage)

        real temp=0.0
        // In the case of the two exceptions mentioned above, this stores by how
        // much the life of the unit could not be increased or reduced, so this
        // is essentially the difference between the unit's actual and correct hp
        // (after the damage stacked on the unit is resolved, of course).

        // If another damage event should occur before the first one resolves,
        // this value will be added to the new damage modifier, ensuring that any
        // life modifications that couldn't be done previously are not forgotten.
        // This way, if one damage event has a positive modifier and an event that
        // occurs in response has a negative modifier or vice versa, the two will
        // properly cancel each other even if the first one of them couldn't be
        // fully applied. Likewise, if the unit is given the survival ability, any
        // damage reduction that couldn't be aplied earlier due to max hp limit
        // will get applied properly once the unit's max hp is increased.
        
        private Damage next
        private static Damage first=0
        // A list of all active Damage structs.
        private static timer delay=CreateTimer()
        // The timer used to wait for the damage to be dealt.
        private static Damage array unitlist
        // Each struct is associated with a specific unit.

        private static method get takes unit u returns Damage
            return Damage.unitlist[GetUnitId(u)]
        endmethod
        private static method create takes unit u returns Damage
            // The only time a Damage is created is when it doesn't yet exist for the unit.
            local Damage this=Damage.allocate()
            set .u = u
            set .next = Damage.first
            set Damage.first=this
            set Damage.unitlist[GetUnitId(.u)]=this
            return this
        endmethod
        method onDestroy takes nothing returns nothing
            // The only time a Damage is destroyed is when it is first, so this works.
            set Damage.first=.next
            set Damage.unitlist[GetUnitId(.u)]=0
            set .u = null
        endmethod
        
        // ================================================================

        private static method end takes nothing returns nothing
            // This method is called with a very slight delay, which allows it to run
            // after the life of the damaged unit has already been reduced by the damage.
            loop
                exitwhen Damage.first==0
                call UnitRemoveAbility(Damage.first.u, SURVIVAL_ABILITY)
                call SetWidgetLife(Damage.first.u, Damage.first.hp)
                call Damage.first.destroy()
            endloop
        endmethod

        static method RunModifiers takes nothing returns real
            local unit damaged = GetTriggerUnit()
            local unit damager = GetEventDamageSource()
            local real damage = GetEventDamage()
            local real modifier = 0.0
            local real life = GetWidgetLife(damaged)
            local real maxlife = GetUnitState(damaged,UNIT_STATE_MAX_LIFE)
            local real stackeddamage
            local Damage d
        
            if damaged==null or not(IsUnitIndexed(damaged)) then
                // Method not called from a damage event or damage event on an unindexed unit, terminate.
                set damager=null
                set damaged=null
                return 0.0
            endif
        
            // Calculate by how much to modify the damage.
            set modifier=DamageModifier.Evaluate(damaged, damager, damage)

            // Get the unit's Damage struct.
            set d=Damage.get(damaged)
            if d==0 then
                // First damage, create a new damage struct.
                set d=Damage.create(damaged)
                set d.hp=life
                call TimerStart(Damage.delay, 0.0, false, function Damage.end)
            endif

            // Calculate the unresolved real damage stacked on the unit.
            set stackeddamage=((life-d.temp)-d.hp)+damage
            // Calculate the modified damage.
            set damage=damage+modifier
            // Calculate the correct hp of the unit.
            set d.hp=d.hp-damage
            // Check if we need to add the survival ability.
            if d.hp>0.405 and maxlife-stackeddamage<=0.405 then
                call UnitAddAbility(damaged, SURVIVAL_ABILITY)
                set maxlife = GetUnitState(damaged,UNIT_STATE_MAX_LIFE)
            endif
            // If the unit's life couldn't be reduced or increased as much as we wanted
            // on a previous damage event, it's time we compensate for that now.
            set modifier=modifier+d.temp
            set d.temp=0.0

            // Modify unit life to make it appear as if damage was modified.
            if life-modifier>0.405 and life-modifier<=maxlife then
                // Set the unit's life so that after the damage is dealt, it will be correct.
                call SetWidgetLife(damaged, life-modifier)
            elseif life-modifier>maxlife then
                // The unit's maxlife is preventing us from increasing life as needed,
                // we need to remember that in the case the survival ability is ever added
                // to the unit on another damage event before this damage resolves.
                set d.temp=modifier-(life-maxlife)
                call SetWidgetLife(damaged, maxlife)
            else
                // We have a damage modifier value that would kill the unit, so we
                // let the actual damage kill it instead, thus awarding proper bounty.
                // We need to remember that we failed to reduce the life as needed in case
                // the unit is healed in response to this damage.
                set d.temp=modifier-(life-0.406)
                call SetWidgetLife(damaged, 0.406)
            endif

            set damaged=null
            set damager=null
            return damage
        endmethod
        
        // ================================================================

        static method getLife takes unit u returns real
            local Damage d=0
            if IsUnitIndexed(u) then
                set d=Damage.get(u)
            endif
            if d==0 then
                return GetWidgetLife(u)
            endif
            if d.hp<=0.405 then
                return 0.0
            endif
            return d.hp
        endmethod

        static method setLife takes unit u, real newLife returns nothing
            local Damage d=0
            local real modifier
            local real life
            local real maxlife
            local real stackeddamage

            if IsUnitIndexed(u) then
                set d=Damage.get(u)
            endif
            if d==0 then
                // Unit not taking damage, proceed with setting the unit's life.
                call SetWidgetLife(u, newLife)
            else
                // Calculate by how much the unit's life will change.
                set modifier=newLife-d.hp
                if modifier>0 and d.hp<=0.405 then
                // Increasing life in a situation where the damage is about to kill the unit,
                // so we must intervene and increase the unit's actual life as well.
                    set life=GetWidgetLife(u)
                    set maxlife = GetUnitState(u,UNIT_STATE_MAX_LIFE)
                    // Calculate the unresolved damage stacked on the unit.
                    set stackeddamage=(life-d.temp)-d.hp
                    // Check if we need to add the survival ability.
                    if d.hp>0.405 and maxlife-stackeddamage<=0.405 then
                        call UnitAddAbility(u, SURVIVAL_ABILITY)
                        set maxlife = GetUnitState(u,UNIT_STATE_MAX_LIFE)
                    endif
                    set d.hp=newLife
                    if maxlife-life>modifier then
                        call SetWidgetLife(u, life+modifier)
                    else
                        call SetWidgetLife(u, maxlife)
                        set d.temp=d.temp-modifier+maxlife-life
                    endif
                else
                // Nothing to worry about, the rest of the code will handle everything.
                    set d.hp=newLife
                    set d.temp=d.temp-modifier
                endif
            endif
        endmethod
    endstruct

// ================================================================

    private function Init takes nothing returns nothing
      static if LIBRARY_xepreload then
        call XE_PreloadAbility(SURVIVAL_ABILITY)
      else
      static if LIBRARY_AbilityPreload then
        call AbilityPreload(SURVIVAL_ABILITY)
      endif
      endif
    endfunction

// ================================================================

    // To make this system work, call this function once whenever a damage event occurs.
    // The DamageEvent library is already designed to do this.
    function RunDamageModifiers takes nothing returns real
        return Damage.RunModifiers()
    endfunction
    
    // These functions allow you to get/set the proper life of a unit even when it's taking damage.
    function GetUnitLife takes unit u returns real
        return Damage.getLife(u)
    endfunction
    function SetUnitLife takes unit u, real newLife returns nothing
        call Damage.setLife(u, newLife)
    endfunction
endlibrary

10-21-2009, 03:05 PM	#2
Tot	This is a really cool system, but a bit complecated!! can you please include a demo-map? would be nice

10-21-2009, 04:04 PM	#3
nichts	now that there are static ifs and optional library requirements: why don't you merge the Table and the AutoIndex version into one library - that would make later switching much easier (and they don't seem to be that different from each other anyway)

10-21-2009, 05:01 PM	#4
Anitarf	Well, optional requirements are just that, optional. In this case, however, the requirement isn't optional: either Table or AutoIndex, one of those requirements must be there. Furthermore, I need to declare globals depending on which library is used and I'm not sure I can do that in static ifs. I suppose I could use static ifs for alternate versions of DamageEvent, though.

10-22-2009, 07:42 AM

Anachron

JASS:

//*  Damage modifiers are implemented as structs that extend the
//*  system's DamageModifier struct. A damage modifier is created
//*  for a specific unit and can modify both the damage that the
//*  unit deals and receives (using the damage and damaged methods
//*  respectively, see the interface defined at the end of the
//*  calibration section).

Shouldn't it be UNIT_TYPE specific?

Further on, there is no example code.
No matter how good your documentation is, an example code is always on top when it comes to user friendly.

Some good stuff you did:
- Automatic Trigger Refresh
- Versions for Table, AutoIndex
- Versions for IDDS, LLDD

Edit:

JASS:

// In wc3, damage events sometimes occur when no real damage is dealt,
        // for example when some spells are cast that don't really deal damage,
        // also some systems use very small damages to test for valid targets,
        // so this system will only consider damage events where damage is
        // higher than this threashold value.
        private constant real DAMAGE_THRESHOLD = 0.05

Damage event bigger then DAMAGE_THRESHOLD AND smaller then 0 should be considered.

Edit2:

JASS:

public struct shield extends shield_template
        private ShieldRelay relay
        
        static method create takes unit u, integer priority returns shield

Is there any reason why you wrote that public to the struct, but not the public to the static?

Edit3:

JASS:

        method damaged takes unit damageSource, real damage returns real //returned real says how much damage to prevent

What do you mean with prevent? Elaborate please.

10-22-2009, 10:01 AM

Anitarf

Quote:

Originally Posted by Anachron

Shouldn't it be UNIT_TYPE specific?

No.

Quote:

Further on, there is no example code.
No matter how good your documentation is, an example code is always on top when it comes to user friendly.

There is an example in the DamageModifiers documentation.

Quote:

Damage event bigger then DAMAGE_THRESHOLD AND smaller then 0 should be considered.

Why?

Quote:

Is there any reason why you wrote that public to the struct, but not the public to the static?

Methods without a prefix are already considered public.

Quote:

What do you mean with prevent? Elaborate please.

No. Read the documentation.

10-22-2009, 04:35 PM

Anachron

Quote:

No.

Why not? I would rather set the data for a unittype instead for every single unit.

Quote:

There is an example in the DamageModifiers documentation.

Ehrm,... You can't call that example.

Quote:

Why?

Because else it doesn't register negative damage events?

Quote:

Methods without a prefix are already considered public.

Sure, but structs without a prefix are already considered as public too.

Quote:

No. Read the documentation.

I did but still its unclear for me.

10-22-2009, 05:30 PM

Rising_Dusk

Quote:

Originally Posted by Anachron

Why not? I would rather set the data for a unittype instead for every single unit.

I would rather, as a user, have control at the unit level than at the unittype level.

Quote:

Originally Posted by Anachron

Because else it doesn't register negative damage events?

No DDS supports negative damage, nor should they. If you want to heal a unit, negative damage is not the way to do it.

10-22-2009, 05:30 PM

Anitarf

Quote:

Originally Posted by Anachron

Why not? I would rather set the data for a unittype instead for every single unit.

I wouldn't. How am I supposed to make a buff that modifies incoming damage if I can't apply it to a specific unit?

Quote:

Ehrm,... You can't call that example.

I just did.

Quote:

Because else it doesn't register negative damage events?

Okay, I'll fix it when you manage to produce a negative damage event.

Quote:

Sure, but structs without a prefix are already considered as public too.

There is a difference between a struct with a public prefix and a struct without one. There is no such diference when it comes to struct methods.

Quote:

I did but still its unclear for me.

My point was that I don't care, the documentation clearly states that I do not intend to provide any further support for that library, this includes answering your vague questions about it.

10-23-2009, 07:45 AM

#10

Anachron

To Dusk:

to Anitarf:

10-23-2009, 08:31 AM

#11

Earth-Fury

Quote:

Originally Posted by Anachron

Which different? I didn't heard of any. (Wanna learn! :))

Quote:

Originally Posted by Anitarf

Read the documentation.

Though he was referring to his system's documentation, I am using that quote to refer to vJass' documentation.

If you want to learn, start with English.

10-23-2009, 08:43 AM

#12

Anachron

Quote:

Though he was referring to his system's documentation, I am using that quote to refer to vJass' documentation.

I am quite sure you learned vJass by getting help from other people, not from reading the documentation.

Quote:

If you want to learn, start with English.

Its not my fault that in school English isn't teached well, I already in a good english course but still my english isn't that good as yours.

So what about it?

10-23-2009, 08:47 AM

#13

Anitarf

Quote:

Its not looking as helping anyone who got questions, really.

If you have specific questions, then ask away.

Quote:

JASS:

native UnitDamageTarget             takes unit whichUnit, widget target, real amount, boolean attack, boolean ranged, attacktype attackType, damagetype damageType, weapontype weaponType returns boolean

Have you tested that? When I tried that with a negative value, I got a damage event with a total of 0 damage. Unless you can actually produce a negative damage event in a test map, shut up.

Quote:

If you don't care about users to get to know to your system who need help in your stuff, how can you submit it then? Its a insolence to provide such advanced stuff without further help.

Again, read the documentation. It clearly states that that is a compatibility library. I don't need to provide support for that, because noone is supposed to keep using it, it is just meant to provide backwards compatibility to old resources. If you really care so much about it, go read the ADamage documentation.

10-23-2009, 08:52 AM

#14

Anachron

Quote:

Have you tested that? When I tried that with a negative value, I got a damage event with a total of 0 damage. Unless you can actually produce a negative damage event in a test map, shut up.

You could also use any negative attack (UnitDamage - 1000), I am quite sure it will heal in every testmap.

10-23-2009, 08:55 AM

#15

Earth-Fury

Quote:

Originally Posted by Anachron

You could also use any negative attack (UnitDamage - 1000), I am quite sure it will heal in every testmap.

Quote:

Originally Posted by Anitarf

Unless you can actually produce a negative damage event in a test map, shut up.