UnitMaxState

[Earth-Fury]

Version 2.1

Introduction

UnitMaxState is written in vJass and requires the NewGen editor, or Jass Helper with PitzerMike's Object Merger configured for it. UnitMaxState requires the latest version of Jass Helper.

UnitMaxState is a library which allows you to modify a unit's maximum life, or maximum mana. To achieve this, the library abuses a bug with the AIlf and AImz abilities, explained by PitzerMike in his ability guide. I do believe it was indeed Blade.dk who initially found this bug. If not, it's still his system I stole and rewrote. Further, let me thank Deaod for writing up his version of this system, which inspired both the reality of this rewrite, and the method abilities are handled within it.

This library provides two functions for modifying a unit's maximum states:
function SetUnitMaxState takes unit target, unitstate state, real targetValue returns nothing
function AddUnitMaxState takes unit target, unitstate state, real additionalValue returns nothing
More information on the API is available in the libraries documentation.

Credits

• Blade.dk for the original SetUnitMaxState function
• Deaod for his version of UnitMaxState
• PitzerMike for the ObjectMerger
• Earth-Fury for the rewrite of UnitMaxState
• weaaddar for BonusMod and thus inspiration
• Vexorian for vJass / Jass Helper
• All of the contributors to the NewGen editor

The UnitMaxState Library

Requirements:

• Optionally, either:
  • AbilityPreload
  • xepreload

To add UnitMaxState to your map, copy and paste the below library in to a custom-text trigger in your map.

You will want to close your map after the first time you save it with UnitMaxState in it, reopen it, and disable ability (re)generation in the configuration section. If you fail to do that, a small delay will be added every time you save your map.

UnitMaxState Test Map 2.1.0.w3x

UnitMaxState:

library UnitMaxState initializer Initialize requires optional AbilityPreload, optional xepreload
//==============================================================================
// UnitMaxState v2.1
//==============================================================================
// Credits:
//------------------------------------------------------------------------------
// Written By:
//     Earth-Fury
// 
// Original System By:
//     Blade.dk
// 
// Intermittent Version By:
//     Deaod
//
// With Thanks To:
//     - weaaddar for BonusMod and thus inspiration
//     - PitzerMike for the ObjectMerger
//     - Vexorian for vJass and Jass Helper
//     - PipeDream for Grimoire
//     - SFilip for TESH
//     - MindWorX for maintaining NewGen
//------------------------------------------------------------------------------
// If you use this library in your map, please at least give credit to Blade.dk.
// Without him, this library would not exist.
//==============================================================================
// Introduction:
//------------------------------------------------------------------------------
// UnitMaxState is a library which allows you to modify a unit's maximum life,
// or maximum mana. To achieve this, the library abuses a bug with the AIlf and
// AImz abilities, which is too complex to explain here.
// 
// I do believe it was indeed Blade.dk who initially found this bug. If not,
// it's still his system I stole and rewrote. Further, let me thank Deaod for
// writing up his version of this system, which inspired both the reality of
// this rewrite, and the method abilities are handled within it.
// 
//==============================================================================
// Requirements:
//------------------------------------------------------------------------------
// UnitMaxState is written in vJass and requires the NewGen editor, or
// Jass Helper with PitzerMike's Object Merger configured for it.
// 
// UnitMaxState requires the latest version of Jass Helper.
// 
// Preloading of abilities requires either AbilityPreload or xepreload. Neither
// are required for the library to function; however, having one or the other
// will remove the slight delay the first time a unit's max state is changed.
// 
//==============================================================================
// Using UnitMaxState:
//------------------------------------------------------------------------------
// UnitMaxState comes with two useful functions:
// 
// nothing SetUnitMaxState(unit <target>, unitstate <state>, real <value>)
//     Changes <target>'s unitstate <state> to be equal to <value>.
//
// nothing AddUnitMaxState(unit <target>, unitstate <state>, real <value>)
//     Adds <value> to <target>'s <state> unitstate. Note that you can use
//     negative values with this function.
//
// Both of these functions accept unitstate's other than UNIT_STATE_MAX_LIFE and
// UNIT_STATE_MAX_MANA. There is a small performance penalty in using these over
// direct usage of SetUnitState.
// 
// You must not use life/mana boosting upgrades in combination with this system.
// 
// Attempting to set a unit's maximum life below 1, or mana below 0 will do
// nothing. A debug message will be output if the script is compiled in
// debug mode.
//==============================================================================



//==============================================================================
// Configuration:
//------------------------------------------------------------------------------
// The below textmacro call is an all-in-one configuration line.
//------------------------------------------------------------------------------
// The first parameter is a boolean.
// 
// If true, the abilities used by this system will be created on save. This adds
// a slight delay to saving your map. You only ever have to create the abilities
// the first time this library is added to your map, or if you modify any of
// the other configuration options.
// 
// Note that to make the ability creation permanent, you must save with ability
// creation enabled, close your map, and reopen it in the editor. You can then
// disable ability creation, as the abilities will be permanently in your map.
//------------------------------------------------------------------------------
// The second parameter is an integer.
// 
// This is the number of abilities this system will use for adding/removing
// life/mana. Note that this system uses four sets of abilities, so the actual
// number of abilities generated and used will be the value you pass here,
// multiplied by 4.
// 
// The higher this number, the faster large bonuses will be added. This number
// should never have to go above 13. Between 3 and 5 will work fine for most
// maps.
//------------------------------------------------------------------------------
// The fourth and fifth parameters are 3 character prefixes for rawcodes.
//
// The first one is for the life-modifying abilities, while the second is for
// the mana-modifying abilities.
// 
// Please, make sure your map has no abilities whose rawcodes begin with either
// of these prefixes before saving! Otherwise, those abilities will be
// overwritten. You can change these to any 3 character combination, if your
// map does already contain abilities whose rawcodes begin with these prefixes.
//------------------------------------------------------------------------------

//! runtextmacro UnitMaxState_Configuration("true", "3", "ZxL", "ZxM")

//------------------------------------------------------------------------------
// End of configuration
//------------------------------------------------------------------------------

//! textmacro UnitMaxState_Configuration takes LOAD_ABILITIES, ABILITY_COUNT, LIFE_PREFIX, MANA_PREFIX
    //*
    //! externalblock extension=lua ObjectMerger $FILENAME$
    //! i function CreateAbilities(baseAbility, rawcodePrefix, field, name, icon)
    //! i     k = 0
    //! i     for sign = -1, 1, 2 do
    //! i         signStr = "+"
    //! i         if sign < 0 then
    //! i             signStr = "-"
    //! i         end
    //! i         j = 0
    //! i         for i = 0, (abilityCount - 1) * 3, 3 do
    //! i             j = j + 1
    //! i             createobject(baseAbility, rawcodePrefix .. string.sub(Chars, k + 1, k + 1))
    //! i             makechange(current, "anam", "UnitMaxState - " .. name)
    //! i             makechange(current, "ansf", "(" .. signStr .. tostring(j) .. ")")
    //! i             makechange(current, "aart", "ReplaceableTextures\\CommandButtons\\" .. icon)
    //! i             makechange(current, "aite", 0)
    //! i             makechange(current, "alev", 4)
    //! i             makechange(current, field, 1, 0)
    //! i             makechange(current, field, 2, 2^(i + 0) * sign)
    //! i             makechange(current, field, 3, 2^(i + 1) * sign)
    //! i             makechange(current, field, 4, 2^(i + 2) * sign)
    //! i             k = k + 1
    //! i         end
    //! i     end
    //! i end
    //! i if $LOAD_ABILITIES$ then
    //! i     setobjecttype("abilities")
    //! i     abilityCount = $ABILITY_COUNT$
    //! i     Chars = "abcdefghijklmnopqrstuvwxyz"
    //! i     CreateAbilities("AIlf", "$LIFE_PREFIX$", "Ilif", "Life", "BTNHealthStone.blp")
    //! i     CreateAbilities("AImz", "$MANA_PREFIX$", "Iman", "Mana", "BTNManaStone.blp")
    //! i end
    //! endexternalblock
    // */
    
    globals
        private constant integer RAWCODE_LIFE = '$LIFE_PREFIX$a'
        private constant integer RAWCODE_MANA = '$MANA_PREFIX$a'
        
        public constant integer ABILITY_COUNT = $ABILITY_COUNT$
    endglobals
//! endtextmacro
globals
    private constant boolean PRELOAD_ABILITIES = true
    
    private integer array POWERS_OF_2
endglobals

private function ErrorMsg takes string s returns nothing
    debug call BJDebugMsg("SetUnitMaxState: " + s)
endfunction

function SetUnitMaxState takes unit target, unitstate state, real targetValue returns nothing
    local integer difference
    local integer rawcode
    
    local integer abilityId
    local integer abilityLevel
    
    local integer currentAbility
    
    if state == UNIT_STATE_MAX_LIFE then
        set rawcode = RAWCODE_LIFE
        
        if targetValue < 1 then
            call ErrorMsg("You can not set a unit's max life to below 1")
            return
        endif
    elseif state == UNIT_STATE_MAX_MANA then
        set rawcode = RAWCODE_MANA
        
        if targetValue < 0 then
            call ErrorMsg("You can not set a unit's max mana to below 0")
            return
        endif
    else
        call SetUnitState(target, state, targetValue)
        return
    endif
    
    set difference = R2I(targetValue) - R2I(GetUnitState(target, state))
    
    if difference < 0 then
        set difference = -difference
        set rawcode = rawcode + ABILITY_COUNT
    endif
    
    set abilityId = ABILITY_COUNT - 1
    set abilityLevel = 4
    set currentAbility = rawcode + abilityId
    loop
        exitwhen difference == 0
        
        if difference >= POWERS_OF_2[abilityId * 3 + (abilityLevel - 2)] then
            call UnitAddAbility(target, currentAbility)
            call SetUnitAbilityLevel(target, currentAbility, abilityLevel)
            call UnitRemoveAbility(target, currentAbility)
            
            set difference = difference - POWERS_OF_2[abilityId * 3 + (abilityLevel - 2)]
        else
            set abilityLevel = abilityLevel - 1
            if abilityLevel <= 1 then
                set abilityId = abilityId - 1
                set abilityLevel = 4
                set currentAbility = rawcode + abilityId
            endif
        endif
    endloop
endfunction

function AddUnitMaxState takes unit target, unitstate state, real additionalValue returns nothing
    call SetUnitMaxState(target, state, GetUnitState(target, state) + additionalValue)
endfunction

//! textmacro UnitMaxState_Preload takes RAWCODE
    set i = 0
    loop
        exitwhen i == ABILITY_COUNT * 2 - 1
        
        static if LIBRARY_AbilityPreload then
            call AbilityPreload($RAWCODE$ + i)
        elseif LIBRARY_xepreload then
            call XE_PreloadAbility($RAWCODE$ + i)
        endif
        
        set i = i + 1
    endloop
//! endtextmacro

private function Initialize takes nothing returns nothing
    local integer i
    local integer k
    
    set i = 1
    set POWERS_OF_2[0] = 1
    loop
        exitwhen i == ABILITY_COUNT * 2 * 2 * 3 + 1
        
        set POWERS_OF_2[i] = POWERS_OF_2[i - 1] * 2
        set i = i + 1
    endloop
    
    static if DEBUG_MODE and PRELOAD_ABILITIES and not LIBRARY_AbilityPreload and not LIBRARY_xepreload then
        call ErrorMsg("Ability preloading was enabled, but neither of the supported preload libraries are present")
    elseif PRELOAD_ABILITIES then
        //! runtextmacro UnitMaxState_Preload("RAWCODE_LIFE")
        //! runtextmacro UnitMaxState_Preload("RAWCODE_MANA")
    endif
endfunction
endlibrary

Change Log

Change Log 2.1: Switched ability creation to lua Switched to optionally using external preload libraries 2.0: Complete rewrite 1.0: Ancient version

[Karawasa]

Could you be kind enough to explain the differences between the systems? Why should I use your system over his, and vice versa? I notice the difference in the base, perhaps you could elaborate on that too.

I also think that you should give more credit to Deaod. Let's face it, your system didn't handle the abilities the way it does now. It used one giant dummy ability, and it's only this new version that has this change (in response to Deaod doing it). Please correct me if I am wrong...

[Rising_Dusk]

EF's system not being submitted here was the reason Deaod submitted his. I have a funny feeling that Deaod would not feel hurt at all if his was graveyarded in light of this being submitted.

[Earth-Fury]

Originally Posted by Rising_Dusk

EF's system not being submitted here was the reason Deaod submitted his. I have a funny feeling that Deaod would not feel hurt at all if his was graveyarded in light of this being submitted.

I certainly hope I've created no animosity with this submission. I simply got thinking about better ways to do it, and ended up with a full implementation.

Originally Posted by Karawasa

I also think that you should give more credit to Deaod. Let's face it, your system didn't handle the abilities the way it does now. It used one giant dummy ability, and it's only this new version that has this change (in response to Deaod doing it). Please correct me if I am wrong...

I did try to give Deaod a good measure of credit. You'll note that his name is the 3rd mentioned, and is mentioned separately from the list of much more indirect contributors. If he himself feels he deserves more credit than is currently given to him in this post and library, I will be more than happy to oblige. :) Though, I will add a mention for him in the first post of this thread right now, as opposed to just in the documentation for the library.

For the record, you are not wrong.

Originally Posted by Karawasa

Could you be kind enough to explain the differences between the systems? Why should I use your system over his, and vice versa? I notice the difference in the base, perhaps you could elaborate on that too.

They are functionally identical, except in a few border-cases. (Eg: Handling unitstates other than max ones.) I would imagine most of those border cases are irrelevant to 99.9% of users.

As for which is superior... I've not examined the matter closely enough. I'll get on to doing a benchmark and such in a while. (Mayhaps later today)

Further comments welcome! :)

[Karawasa]

Originally Posted by Earth-Fury

Though, I will add a mention for him in the first post of this thread right now, as opposed to just in the documentation for the library.

I'm a nitpick for these type of things, so thank you for doing it.

Originally Posted by Earth-Fury

I certainly hope I've created no animosity with this submission. I simply got thinking about better ways to do it, and ended up with a full implementation.

I can't speak for Deaod, but my experiences with the guy tell me there is probably no animosity at all. As a mapper, I like the competition :). I hope nothing gets graveyarded until we get benchmarks though.

Originally Posted by Earth-Fury

As for which is superior... I've not examined the matter closely enough. I'll get on to doing a benchmark and such in a while. (Mayhaps later today)

That would be very much welcomed. I've been wondering about this ever since he posted his version (I was using your old version previous to that).

[Rising_Dusk]

Is there any particular reason you went against all indentation standards and made the globals and englobals keywords at the beginning of your script right-justified?

[Earth-Fury]

Originally Posted by Rising_Dusk

Is there any particular reason you went against all indentation standards and made the globals and englobals keywords at the beginning of your script right-justified?

Yes. It fit the layout of the configuration block better. (In my opinion, of course.)

[Karawasa]

Originally Posted by Earth-Fury

Yes. It fit the layout of the configuration block better. (In my opinion, of course.)

Meh, I'd prefer to see it follow convention but I'm just one guy. Your constants also aren't indented correctly.

[Rising_Dusk]

Other than weird indentation in spots, I don't see anything wrong with the code. I will wait until Ani has a look at it, though, and if after that no problems are spotted then this will be approved.

[Earth-Fury]

Originally Posted by Rising_Dusk

Other than weird indentation in spots, I don't see anything wrong with the code. I will wait until Ani has a look at it, though, and if after that no problems are spotted then this will be approved.

I'd like to hold off on approval/rejection until benchmarks are done. Of course, I can't seem to find working stopwatch natives anywhere... If anyone has a combination of stopwatch natives + war3.exe that work together, send em my way.

(If I can't get stopwatch for benchmarks in a few days, and if no one else does benchmarks, then I guess my request to hold off becomes a bit of a moot point...)

[Karawasa]

Originally Posted by Rising_Dusk

Other than weird indentation in spots, I don't see anything wrong with the code. I will wait until Ani has a look at it, though, and if after that no problems are spotted then this will be approved.

Since we have two submissions that accomplish the same thing but via different methods, don't you think it's a bit unwise to rush into approval?

Originally Posted by Earth-Fury

I'd like to hold off on approval/rejection until benchmarks are done. Of course, I can't seem to find working stopwatch natives anywhere... If anyone has a combination of stopwatch natives + war3.exe that work together, send em my way.

Thank you for being reasonable. I hope you find what you're looking for soon.

[Rising_Dusk]

These are the best that we have at current, and I've no clue if they still apply to the most recent 1.24b patch.

[Rising_Dusk]

I tested this library and like it very much. I have only a few concerns.

• Your preload libraries suck. What you should do is in the main library's initializer, create a dummy footman and add the abilities, then remove the footman. This would eliminate the whole overwhelming-ness of having the preload libraries.
• call InitializeAbilitiesArray() is useless. Simply do everything in the Initializer and comment it to tell users what is going on.
• You shouldn't make your error messages configurable. If a user screws up, you as the library author know where he screwed up, so you will tell him how he screwed up. If he plays with that configuration error function and is some terribad noob, he may confuse himself. It is our job as library authors to protect users from themselves.
  
  I say inline your ErrorMsg function and remove it from configuration entirely.

If you fix these things, this will be ready for approval.

[Earth-Fury]

Originally Posted by Rising_Dusk

• Your preload libraries suck. What you should do is in the main library's initializer, create a dummy footman and add the abilities, then remove the footman. This would eliminate the whole overwhelming-ness of having the preload libraries.

Is it so overwhelming to add a second library to a map if you want preloading, with the option to use the xe library in the event you aren't a crazy ass NIHilist?

I'm perfectly willing to concede this point if you are not willing to concede it. It's a rather trivial matter.

Originally Posted by Rising_Dusk

• call InitializeAbilitiesArray() is useless. Simply do everything in the Initializer and comment it to tell users what is going on.

Yes. A relic from the way I initially wrote the system. (A whole lot of variable initialization...)

Originally Posted by Rising_Dusk

• You shouldn't make your error messages configurable. If a user screws up, you as the library author know where he screwed up, so you will tell him how he screwed up. If he plays with that configuration error function and is some terribad noob, he may confuse himself. It is our job as library authors to protect users from themselves.
  
  I say inline your ErrorMsg function and remove it from configuration entirely.

You've spent time in the acrid halls of the eternally vile Hive Workshop. You have seen the horrors stupidity can do to a man. One minute he's just sitting there, drinking an energy drink, coding a spell. Then, the idiocy comes. His guts laid bare. Flesh sundered from bone and soul to rot in the stench of the perverted den know as "The world editor help zone".

You can fight it as hard as your body will allow. Rend your arms through the almost solid wall of stupidity. Fight with every ounce of strength, until your body lies bruised and beaten; broken and defeated on the shores of some distant land of horror. Barely beyond the wet of the ocean before the idiocy has won.

We can't win against it. No one can. We can, however, lose. We lose by removing useful functionality which can only be abused by true stupidity. We lose by diminishing the works of the great, for the sake of those too tiny to even grasp the magnitude of the creation, let alone use it in the fabrication of the awe-inspiring. We lose by destroying ourselves for fear that we are of no use to those that would doom us to a fate no better than the eternal fires of hell!

TL;DR: It is out job to protect users from crazy unexpected border cases, by preventing undefined behaviour in every way possible. It is not our job to protect users from utter stupidity.

[Karawasa]

Originally Posted by Earth-Fury

You've spent time in the acrid halls of the eternally vile Hive Workshop. You have seen the horrors stupidity can do to a man. One minute he's just sitting there, drinking an energy drink, coding a spell. Then, the idiocy comes. His guts laid bare. Flesh sundered from bone and soul to rot in the stench of the perverted den know as "The world editor help zone".

Best description of THW I've seen.

Any luck with benchmarking? I only persist because I am dealing with insanely high health bonuses so...