[System] GroupUtils

[Magtheridon96]

Now that everyone's using FirstOfGroup loops, I re-evaluated GroupUtils by Rising_Dusk and found that most of the code was useless s***code now.

Here's a faster, cleaner, and 'better' version of it:

/***************************************
*
*   GroupTools
*   v1.1.2.2
*   By Magtheridon96
*
*   - Original version by Rising_Dusk
*
*   - Recycles groups, and allows the 
*   enumeration of units while taking 
*   into account collision.
*
*   API:
*   ----
*
*       - group ENUM_GROUP
*
*       - function NewGroup takes nothing returns group
*       - function ReleaseGroup takes group g returns nothing
*           - Get and release group handles
*
*       - function GroupRefresh takes group g returns nothing
*           - Refresh a group so that null units are removed
*
*       - function GroupUnitsInArea takes group whichGroup, real x, real y, real radius returns nothing
*           - Groups units while taking into account collision
*
***************************************/
library GroupTools
    
    globals
        // The highest collision size you're using in your map.
        private constant real MAX_COLLISION_SIZE = 197.
        // Data Variables
        private group array groups
        private group gT = null
        private integer gN = 0
        private boolean f = false
        // Global Group (Change it to CreateGroup() if you want)
        group ENUM_GROUP = bj_lastCreatedGroup
    endglobals
    
    static if DEBUG_MODE then
        private struct V extends array
            debug static hashtable ht = InitHashtable()
        endstruct
    endif
    
    private function AE takes nothing returns nothing
        if (f) then
            call GroupClear(gT)
            set f = false
        endif
        call GroupAddUnit(gT,GetEnumUnit())
    endfunction
    
    function GroupRefresh takes group g returns nothing
        debug if null==g then
            debug call DisplayTimedTextToPlayer(GetLocalPlayer(),0,0,60,"[GroupUtils]Error: Attempt to refresh null group!")
            debug return
        debug endif
        set f = true
        set gT = g
        call ForGroup(gT,function AE)
        if (f) then
            call GroupClear(g)
        endif
    endfunction
    
    function NewGroup takes nothing returns group
        if 0==gN then
            return CreateGroup()
        endif
        set gN = gN - 1
        debug call SaveBoolean(V.ht,GetHandleId(groups[gN]),0,false)
        return groups[gN]
    endfunction
    
    function ReleaseGroup takes group g returns nothing
        debug if null==g then
            debug call DisplayTimedTextToPlayer(GetLocalPlayer(),0,0,60,"[GroupUtils]Error: Attempt to release null group!")
            debug return
        debug endif
        debug if LoadBoolean(V.ht,GetHandleId(g),0) then
            debug call DisplayTimedTextToPlayer(GetLocalPlayer(),0,0,60,"[GroupUtils]Error: Double free!")
            debug return
        debug endif
        debug call SaveBoolean(V.ht,GetHandleId(g),0,true)
        call GroupClear(g)
        set groups[gN] = g
        set gN = gN + 1
    endfunction
    
    function GroupUnitsInArea takes group whichGroup, real x, real y, real radius returns nothing
        local unit u
        debug if null==whichGroup then
            debug call DisplayTimedTextToPlayer(GetLocalPlayer(),0,0,60,"[GroupUtils]Error: Null group passed to GroupUnitsInArea!")
            debug return
        debug endif
        call GroupEnumUnitsInRange(ENUM_GROUP,x,y,radius+MAX_COLLISION_SIZE,null)
        loop
            set u = FirstOfGroup(ENUM_GROUP)
            exitwhen null==u
            if IsUnitInRangeXY(u,x,y,radius) then
                call GroupAddUnit(whichGroup,u)
            endif
            call GroupRemoveUnit(ENUM_GROUP,u)
        endloop
    endfunction
    
endlibrary

By the way, I didn't put an empty GroupEnumUnitsInArea function so that your libraries wouldn't
compile thus notifying you of the libraries you have to fix to run off of GroupUnitsInArea

Note: The use of groups is very avoidable in Warcraft III (Thank you Bribe).
The purpose of this is to improve the code of people who use groups anyways.

Feel free to comment..

 

[noob]

Does not insult Rising_Dusk

 

[Troll-Brain]

The double free protection and group > 8190 checkings in debug mode are missing. (public stuff is so fun)

OFF-TOPIC :

Now that everyone's using FirstOfGroup loops

Define everyone.
Coz i don't think we live in the same world, most of "jasser" (not that much still alive) probably still use ForForce.

Btw is there a valid benchmark lying there (for instants groups ofc) ?

GroupEnum + null filter + FirstOfGroup/GroupRemoveUnit loop
VS
GroupEnum + all the code in the filter (return false)

 

[Magtheridon96]

Well, FoG loops are logically faster than normal group enumerations with filters for 1 reason:

Assume 100 units.

The GroupEnumUnitsInRange function with a filter will open up 100 threads (similar to 100 function calls)
The FoG loop will do nothing but loop through all the units directly.

Does not insult rising dust

?

 

[Troll-Brain]

I know, i'm just not sure that even with a null filter an enumed unit doesn't open by itself a new thread (which we have no access in case of a null filter)

 

[Magtheridon96]

Maybe the Jass interpreter checks for null code/boolexprs/filterfuncs to avoid creating and destroying threads
Let's do a benchmark ^^

 

[Troll-Brain]

Maybe the Jass interpreter checks for null code/boolexprs/filterfuncs to avoid creating and destroying threads
Let's do a benchmark ^^

Yeah, it's obvious that the jass interpreter do such optimizations ...
In fact i would bet 5 against to 1 that the FOG loop would be slower.

Btw, you are welcome for the benchmark

 

[Luorax]

Actually all the "shitcode" that was in GroupUtils had a purpose (like the filter you can pass to GroupEnumUnitsInArea). So actually replacing our old GU with this would break any map.

 

[Magtheridon96]

But GroupEnumUnitsInArea can be easily replaced with GroupUnitsInArea and a FoG loop.
If a map is using the old GU, that's fine, it doesn't have to use this one.

Oh and most of that shitcode was used to support recursion (Which I didn't find useful since FoG loops are way faster than
GroupEnumUnitsInRange with a filter, and recursion is impossible with a null filter)

edit

Silly me, I found a way to make GroupUnitsInArea faster ^^ (Will update in 24 hours)

 

[Troll-Brain]

Theories are theorical.
Until there is a valid benchmark that proves it, i won't assume FOG loop is faster.
However a FOG loop makes the code more usable, neater than coding directly inside the filter.

 

[Dirac]

Everyone should use first of group loops since they're faster than GroupEnum with filter

System for FirstOfGroup loops: http://www.hiveworkshop.com/forums/submissions-414/snippet-doublegroup-205209/

Benchmarks that prove what i'm saying: http://www.hiveworkshop.com/forums/submissions-414/system-grouptools-204534/#post2025254

 

[Magtheridon96]

I love the course of my threads :3
*Gets popcorn*

I'm going to update this tomorrow

 

[Troll-Brain]

Glad to know that i would have lost my bet, since FoG loops are way nicer than split code in a filter.

Personnaly, with 100 enumed units and a 0.1 timer and a simple action in the loop (setting an integer to the unit custom value) i get not fps lost with a FoG loop (60 fps), but have less than 30 with a GroupEnum and a filter.

I've cared to use short names and a static group instead of create/destroy a new one each time.
My benchmark was still not a concrete case but precise enough to see that FoG is the absolute winner (since when coding in jass makes sense ? )

EDIT : Omg i forgot the GroupEnum before the FoG loop ...
You see, there is a reason for sharing benchmarks test codes
Meh, will make a valid test tomorrow ...

However FoG should still be the winner, even if Dirac used dynamic groups and no action at all for filtered units (unless he enumed 0 units).

 

[Dirac]

12 units inside the group

 

[Magtheridon96]

Updated:

- Made GroupUnitsInArea faster by avoiding a filter and using an FoG loop.
- Added debug-only double-free protection.

 

[PurgeandFire]

EDIT : Omg i forgot the GroupEnum before the FoG loop ...
You see, there is a reason for sharing benchmarks test codes
Meh, will make a valid test tomorrow ...

Anitarf also made some interesting benchmarks for it, in case you want to take a look.

Anyway, the code looks good. However, you should use a global group for the GroupUnitsInArea instead of a local group.

 

[Troll-Brain]

Ok so RIP ugly code in GroupEnum filter, good to know

 

[Bribe]

GroupUtils also has the ENUM_GROUP variable.

Dynamic groups are also completely avoidable if you use UnitIndexer and LinkedList, but I don't want to burden all users with such a heavy learning curve and installation process, so this library could still serve as a middle grounds.

However this breaks backwards compatibility so it's going to suffer the same fate as my rendition of Table if you call it like this.

 

[Magtheridon96]

GroupUtils also has the ENUM_GROUP variable

No one needs that
You could use bj_lastCreatedGroup ^^

However this breaks backwards compatibility so it's going to suffer the same fate as my rendition of Table if you call it like this

So, should I change the name?
Table was fine bro
No one in their right-mind would even THINK about using Vexorian's Table nowadays ^^ (Except those veterans at wc3c.net)

If I should change the name, I guess I should go with GroupUtilities

edit
Updated.
- Now using Global group inside GroupUnitsInArea
- Changed name to GroupUtilities
- GroupUnitsInArea now even faster ^_^

 

[Bribe]

Or GroupTools, because tool is short for utility.

bj_lastCreatedGroup could mess up if there is some recursion going on, which might catch GUI users off guard and display some odd results. It is very rare such a bug could occur but having a dedicated global group just for temporary enumeration makes sense.

ENUM_GROUP, for example, would be used instead of your overkill NewGroup/ReleaseGroup calls that you do for that enumeration in GroupUnitsInArea.

Also, it makes more sense to inline IsUnitInRangeXY than let GroupUnitsInArea do it for me.

In fact dynamic groups in general are so avoidable in most cases unlike timers. This library was originally made when null filters leaked.

 

[Troll-Brain]

I think a "static" global group spelled GROUP is fine.

 

[Magtheridon96]

Or GroupTools, because tool is short for utility

That will make Dirac quite jelly

Also, it makes more sense to inline IsUnitInRangeXY than let GroupUnitsInArea do it for me.

But most people wouldn't do that (Hard to remember to do it everytime )

bj_lastCreatedGroup could mess up if there is some recursion going on, which might catch GUI users off guard and display some odd results. It is very rare such a bug could occur but having a dedicated global group just for temporary enumeration makes sense.

ENUM_GROUP, for example, would be used instead of your overkill NewGroup/ReleaseGroup calls that you do for that enumeration in GroupUnitsInArea.

Ok, I'll add it in :3

In fact dynamic groups in general are so avoidable in most cases unlike timers. This library was originally made when null filters leaked.

Sometimes, groups are unavoidable without a lot of overhead and complications. Example:

I'm updating my SubZero spell and I found that the only way to keep track of the missiles without using some other struct is either a group or an ugly Table :/ (The Table didn't really workout though)
I also found that I needed a group for storing damaged units (So I don't damage them a second time)

 

[Bribe]

You can use a hashtable to set a boolean to the handle id to say don't attack again (or a Table for this). If you need to iterate over it as well then you could use the new LinkedList to fix both problems.

 

[Dirac]

Wouldn't make me jelly at all, GroupTools has been proven to be awful.

I need ENUM_GROUP for compability

 

[Magtheridon96]

Well, if you're ok with it, I'll change the name to GroupTools and I'll use my super cool non-existent moderator/haxxor skillz to change the thread name

I'll change the name to ENUM_GROUP too so I could make this system more compatible when replacing GroupUtils

You can use a hashtable to set a boolean to the handle id to say don't attack again (or a Table for this). If you need to iterate over it as well then you could use the new LinkedList to fix both problems.

Cool
I wonder why the hashtable idea didn't occur to me

edit
Done.

edit
I made a special version for people who don't use groups (except for global ones)
and inline GroupUnitsInArea (which I just started doing):

library GroupConstants
    globals
        constant real MAX_COLLISION_SIZE = 197.0
        constant group ENUM_GROUP = CreateGroup()
    endglobals
endlibrary

rofl

 

[BBQ]

Personally, I see no point in group recycling. In a projectile system (or anything similar), you'd generally want to avoid an extra requirement and just handle it by yourself (which would also end up being more efficient than NewGroup() and ReleaseGroup()):

struct projectile
{
	group affectedUnits;
	
	static method create() -> thistype
	{
		thistype this = thistype.allocate();
		
		if (this.affectedUnits == null)
			this.affectedUnits = CreateGroup();
		
		return this;
	}
	
	method destroy()
	{
		GroupClear(this.affectedUnits);
		this.deallocate();
	}
}

 

[PurgeandFire]

Yeah, group recycling isn't really necessary for specific systems and spells, since you will usually just need one group and only need it for an instantaneous enumeration. However, in actual maps, group recycling can become pretty handy. When using this system, there is hardly any loss of performance (very light), so it does not really do any notable harm yet gives a notable benefit. =) (and in terms of systems intended for optimization, saving handles is considered notable benefit)

 

[Magtheridon96]

I totally agree with you guys.
The group handle is totally redundant in public resources unless it's static.
Then again, you won't need a global group in public resources because you'd be able to use bj_lastCreatedGroup

 

[Bribe]

The only thing I don't like about recycling handles is that there could be spikes in which an index is created but never recycled, in such a case where maybe at one part of the game you need 200 groups but for the rest of the game you only need 0-20. The surplus groups will stay recyclable but never recycled.

bj_lastCreatedGroup is good albeit you can do group ENUM_GROUP = bj_lastCreatedGroup and let the user change that to "CreateGroup()" if he so desires.

 

[Magtheridon96]

bj_lastCreatedGroup is good albeit you can do group ENUM_GROUP = bj_lastCreatedGroup and let the user change that to "CreateGroup()" if he so desires.

Done.

 

[PurgeandFire]

The only thing I don't like about recycling handles is that there could be spikes in which an index is created but never recycled, in such a case where maybe at one part of the game you need 200 groups but for the rest of the game you only need 0-20. The surplus groups will stay recyclable but never recycled.

However, recycling can still be the better of the 3 methods. If you were to use a separate group variable per use you would theoretically still end up with 200 groups. If you create and destroy, yes you will save handles, but apparently groups leak memory when they are destroyed, so there may be a net gain of memory.

So group recycling will usually be equally efficient (in terms of handles) if not better.

 

[Troll-Brain]

...but apparently groups leak memory when they are destroyed, so there may be a net gain of memory.

Tested yourself ?
Even with GroupClear called before DestroyGroup ?

 

[Bribe]

Graveyarded.

GroupUtils does group recycling already and this also breaks compatibility becuase function names are shared.

Group recycling is easy enough to inline into a library and IsUnitInRangeXY is easy enough to inline as well. For people that need to refresh a group over a duration of time it is easy enough to inline GroupRefresh or use the actual GroupUtils resource.