Snippet Handle

[Bribe]

Expands on the API of handles to allow any handle other than weathereffects or terrain deformations to be saved/loaded from a hashtable. Pow!

This is a compliment to the common.j natives and to the TypeCasting Library.

library Handle
/**************************************************************************************************************
 *  Handle API
 *  ¯¯¯¯¯¯¯¯¯¯
 *  You can now save <every type> into hashtables and load almost** everything, thanks to these functions.
 *  
 *  Since many JASS types extend a handle instead of an agent, this library enables some very useful commands.
 *  Thanks to KingKing for the "ConvertFogState" trick used in many of these functions and for inspiration.
 *  Thanks to Vexorian for the awesome JassHelper; any/all of these functions will inline when you use them.
 *
 *
 *  Example Useage
 *  ¯¯¯¯¯¯¯¯¯¯¯¯¯¯
 *  call SaveHandle(hash, 0, 0, CreateTextTag())
 *  call SaveHandle(hash, 0, 1, TriggerAddAction(t, function thistype.onLoop))
 *
 *  call SetPlayerState(u, LoadPlayerStateHandle(hash, 0, 2), GetPlayerState(u, LoadPlayerStateHandle(hash, 0, 3)))
 *  call SetUnitState(p, LoadUnitStateHandle(hash, 0, 4), 9001)
 *
 *
 *  function SaveHandle takes hashtable table, integer parentKey, integer childKey, handle h returns boolean
 * 
 *  ->  This is basically the same thing as SaveAgentHandle, only it saves *any handle* -- it does not have to
 *      be an agent-type.  This is extremely useful for many reasons like generic saves and for saving types
 *      which could never be saved before (attacktype, damagetype, pathingtype, etc.)
 *  
 *  function SaveHandleId takes hashtable table, integer parentKey, integer childKey, handle h returns nothing
 * 
 *  ->  This is pretty much a shortcut from typing GetHandleId() each time you just want to save a handle's
 *      integer reference.
 *  
 *  function Load$NAME$Handle takes hashtable table, integer parentKey, integer childKey returns $TYPE$
 *  
 *  ->  Loads the handle of almost everything that wasn't in the hashtable API natives.
 *   
 *  function Load$NAME$HandleEx takes hashtable table, integer parentKey, integer childKey returns $TYPE$
 *   
 *  ->  If you saved the handle as an integer, this will load/typecast the desired handle from that integer.
 *      I recommend using this method instead of simple Load$NAME$Handle because it's faster to do it this way.
 *      Just keep in mind that you can't use this function for types that were already in the hashtable native
 *      API functions - they must be loaded normally or from KingKing's typecasting library.
 */
    
    function SaveHandle takes hashtable table, integer parentKey, integer childKey, handle h returns boolean
        return SaveFogStateHandle(table, parentKey, childKey, ConvertFogState(GetHandleId(h)))
    endfunction
        
    function SaveHandleId takes hashtable table, integer parentKey, integer childKey, handle h returns nothing
        call SaveInteger(table, parentKey, childKey, GetHandleId(h))
    endfunction
    
    
    //! textmacro ConvertHandleType takes NAME, TYPE
    function Load$NAME$Handle takes hashtable table, integer parentKey, integer childKey returns $TYPE$
        return Convert$NAME$(GetHandleId(LoadFogStateHandle(table, parentKey, childKey)))
    endfunction
    
    function Load$NAME$HandleEx takes hashtable table, integer parentKey, integer childKey returns $TYPE$
        return Convert$NAME$(LoadInteger(table, parentKey, childKey))
    endfunction
    //! endtextmacro
    
    //! runtextmacro ConvertHandleType("Race", "race")
    //! runtextmacro ConvertHandleType("AllianceType", "alliancetype")
    //! runtextmacro ConvertHandleType("RacePref", "racepreference")
    //! runtextmacro ConvertHandleType("IGameState", "igamestate")
    //! runtextmacro ConvertHandleType("FGameState", "fgamestate")
    //! runtextmacro ConvertHandleType("PlayerState", "playerstate")
    //! runtextmacro ConvertHandleType("PlayerScore", "playerscore")
    //! runtextmacro ConvertHandleType("PlayerGameResult", "playergameresult")
    //! runtextmacro ConvertHandleType("UnitState", "unitstate")
    //! runtextmacro ConvertHandleType("AIDifficulty", "aidifficulty")
    //! runtextmacro ConvertHandleType("GameEvent", "gameevent")
    //! runtextmacro ConvertHandleType("PlayerEvent", "playerevent")
    //! runtextmacro ConvertHandleType("PlayerUnitEvent", "playerunitevent")
    //! runtextmacro ConvertHandleType("WidgetEvent", "widgetevent")
    //! runtextmacro ConvertHandleType("DialogEvent", "dialogevent")
    //! runtextmacro ConvertHandleType("UnitEvent", "unitevent")
    //! runtextmacro ConvertHandleType("LimitOp", "limitop")
    //! runtextmacro ConvertHandleType("UnitType", "unittype")
    //! runtextmacro ConvertHandleType("GameSpeed", "gamespeed")
    //! runtextmacro ConvertHandleType("Placement", "placement")
    //! runtextmacro ConvertHandleType("StartLocPrio", "startlocprio")
    //! runtextmacro ConvertHandleType("GameDifficulty", "gamedifficulty")
    //! runtextmacro ConvertHandleType("GameType", "gametype")
    //! runtextmacro ConvertHandleType("MapFlag", "mapflag")
    //! runtextmacro ConvertHandleType("MapVisibility", "mapvisibility")
    //! runtextmacro ConvertHandleType("MapSetting", "mapsetting")
    //! runtextmacro ConvertHandleType("MapDensity", "mapdensity")
    //! runtextmacro ConvertHandleType("MapControl", "mapcontrol")
    //! runtextmacro ConvertHandleType("PlayerColor", "playercolor")
    //! runtextmacro ConvertHandleType("PlayerSlotState", "playerslotstate")
    //! runtextmacro ConvertHandleType("VolumeGroup", "volumegroup")
    //! runtextmacro ConvertHandleType("CameraField", "camerafield")
    //! runtextmacro ConvertHandleType("BlendMode", "blendmode")
    //! runtextmacro ConvertHandleType("RarityControl", "raritycontrol")
    //! runtextmacro ConvertHandleType("TexMapFlags", "texmapflags")
    //! runtextmacro ConvertHandleType("EffectType", "effecttype")
    //! runtextmacro ConvertHandleType("Version", "version")
    //! runtextmacro ConvertHandleType("ItemType", "itemtype")
    //! runtextmacro ConvertHandleType("AttackType", "attacktype")
    //! runtextmacro ConvertHandleType("DamageType", "damagetype")
    //! runtextmacro ConvertHandleType("WeaponType", "weapontype")
    //! runtextmacro ConvertHandleType("SoundType", "soundtype")
    //! runtextmacro ConvertHandleType("PathingType", "pathingtype")
/*
*   Handles that were already in the hashtable API but cannot be saved with <SaveAgentHandle>:
*
*   triggeraction   ->  LoadTriggerActionHandle
*   texttag         ->  LoadTextTagHandle
*   unitpool        ->  LoadUnitPoolHandle
*   itempool        ->  LoadItemPoolHandle
*
* **Things which still cannot be typecasted:
*
*   terraindeformation
*   weathereffect
*   camerasetup
*/
//*************************************************************************************************************
endlibrary

 

[BlackRose]

I dislike hashtables so I won't really comment, but anyways, what do these variable types do?

• raritycontrol
• texmapflags
• mapdensity

They look interesting does [ljass]widgetevent[/ljass] even have anything with it as well? I remember looking through one of the .j files and not finding anything regarding it.

 

[Bribe]

I just included everything for completeness. I didn't spend the time to look through the usefulness of each -- widgetevent is only used for EVENT_WIDGET_DEATH, apparently, which is pretty useless to save in a hashtable since there's only one option

 

[Jesus4Lyf]

It has kind of been done, yeah?
Then again, perhaps this is a nice interface...

 

[Bribe]

Thanks

I've read from some people that they wanted a SaveHandle or something able to do that very thing. This allows you to save data beyond that of SaveAgentHandle, while still not conflicting with KingKing's typecasting library because this is its own, unique API set.

 

[Jesus4Lyf]

I have to say, why would you ever use this?
(Realistic use case please, not a theoretical one like "you want to save an attack type to a timer".)

 

[Bribe]

1. Attack types -- having those indexed to a unit immediately makes for an easy assignment of a specific attack type to a unit:

UnitDamageTarget(attacker, target, 60.00, true, false, LoadAttackTypeHandle(hash, GetHandleId(attacker), 0), DAMAGE_TYPE_NORMAL, WEAPON_TYPE_WHOKNOWS)

2. Having the entire unitevent/playerunitevent API at your fingertips lets you read events in their raw form, so that you can save an eventid to your trigger handle, enabling checks like:

if LoadUnitEventHandle(hash, GetHandleId(GetTriggeringTrigger()), 0) == EVENT_UNIT_DAMAGED then
    // Actions
endif

Also, having the capability to index almost anything you want in a hashtable is very potent. I have the need for a three-dimensional array of essentially unlimited size, and the only real way to do that is through a hashtable, so now that I am able to save previously unobtainable variables (not saying I'll use them on my projects, yet), the doors are open.

I like to make abstract things work in simple ways - one of the most influential reasons I program. Before I realized there was a StringHash native, I made this.

 

[Sevion]

1) Structs?

2) Why would you ever do that?

(Realistic use case please, not a theoretical one like "you want to save an attack type to a timer".)

The main points are bolded.

 

[Jesus4Lyf]

1. Attack types -- having those indexed to a unit immediately makes for an easy assignment of a specific attack type to a unit

Easier to attach with AIDS. More efficient, too.

2. Having the entire unitevent/playerunitevent API at your fingertips lets you read events in their raw form, so that you can save an eventid to your trigger handle, enabling checks like:

For what? If you're gonna do "if" comparisons, why not just save an integer in the first place? Or some other value like a boolean? Or even a struct, or function through a function interface... I dunno, it just seems superfluous to store the event id on the trigger itself...

 

[kingkingyyk3]

Easier to attach with AIDS. More efficient, too.
Yep, the speed is same with using array.(It is array, actually. LOL)

 

[Bribe]

AIDS

The library looks worse than the disease (AutoIndex the same). Sorry, been doing JASS since February, my eyes can't read code that was written from the dark ages of WC3. The other libraries from Jesus4Lyf were short enough that I could look at everything in a single scope, but this... (what the heck is ObjectMerger? Why do AutoIndex and AIDs require a save before the library can be used?)

So, if you do use a hashtable, then you're indexing the struct to the unit, and then looking up the array from the struct to get the type, as opposed to just indexing the type. If you've already got a struct in place for this, that's definitely the more efficient approach, yeah...

But you're basically throwing out every hashtable Save/Load type except for integer by doing that. When you're just writing code, doing snippets for various spells, it's much more streamlined to index by what you're working with instead of killing a fly with a bazooka.

I have an AOE spell that uses a unit group to connect the caster to his targets. I only use a group with that caster. I'd much prefer just using a quick hashtable lookup to index the group to the unit, instead of create an entire struct for it and look it up by typecasting the struct from the integer.

It's comparable to inlining a "TriggerRegisterAnyUnitEventBJ". You can do it, but it's better to keep little things that essentially don't have a performance impact in a tight knit, and it saves you typing what amounts to nigh-pointless redundancy. Hence one of the many uses for subroutine API in the first place.

 

[kingkingyyk3]

instead of create an entire struct for it and look it up by typecasting the struct from the integer.
Use GetUnitId for array lookup, why not? o.o

 

[Bribe]

Again, you needs AIDS for that. And why, if I just want to index units, does it require a library of epic proportions? Why can't it just be a simple thing instead of all that objectmerger nonsense?

 

[kingkingyyk3]

Why can't it just be a simple thing instead of all that objectmerger nonsense?
Well, you can remove the object merger line.
You have to set the USE_PERIODIC_RECYCLER to true in this case.

 

[Sevion]

struct asdf //extends array (requires a custom allocation)
    public static method operator [] takes unit whichUnit returns thistype
        local thistype this = thistype(GetHandleId(whichUnit))

        if ( this == 0 ) then
            set this = thistype.allocate()
        endif

        return this
    endmethod
endstruct

Yes? No?

 

[saw792]

@Sevion:
1. GetHandleId() > 8191
2. Handle ids get recycled. Units do not (usually...)
3. The only situation that might be accurate and practical is for indexing dummy units that you recycle or never get destroyed. But then when you create the dummys you can just use a stack.

Let me know if I've completely missed the point of what you posted.

 

[Sevion]

@saw792:
You're right. I forgot that

We can just implement AIDS and use GetUnitIndex or w/e.

 

[Deaod]

[AIDS] looks worse than the disease (AutoIndex the same). Sorry, been doing JASS since February, my eyes can't read code that was written from the dark ages of WC3.

Actually, AutoIndex and AIDS are rather recent.

(what the heck is ObjectMerger? Why do AutoIndex and AIDs require a save before the library can be used?)

Because thats the way both libraries work. They (ab)use units with "Defend" based ability being issued "undefend" before they get removed (and on death, IIRC). And instead of requiring you to create a specific object yourself, they create the object for you through ObjectMerger.