This is a simple library that includes a group stack for dynamic groups, a global group that can be used for enumerations, and a pair of TRUE/FALSE boolexprs for preventing the null boolexpr leak in enumerations
backwards compatibility with old maps that use them. Since the 1.24c patch, the null boolexpr leak in enumerations no longer exists. It also implements Griffen's method of GroupRefresh, which makes this a nice, all-encompassing utility set standard for group handling. Lastly, this library has means to group units in an area of effect while considering collision, something the GroupEnumUnitsInRange native does not do.
This library provides the following functions to the user.
- function NewGroup takes nothing returns group
- function ReleaseGroup takes group g returns boolean
- function GroupRefresh takes group g returns nothing
- function GroupEnumUnitsInArea takes group whichGroup, real x, real y, real radius, boolexpr filter returns nothing
- function GroupUnitsInArea takes group whichGroup, real x, real y, real radius returns nothing
This library also provides the following global variables to the user.
- group ENUM_GROUP
- boolexpr BOOLEXPR_TRUE
- boolexpr BOOLEXPR_FALSE
The reason why GroupRefresh exists is best explained by Griffen here
. It is quoted below for the readers' convenience.
Originally Posted by Captain Griffen
Units that are removed from the game or decay while part of a group remain in the hash table. They also appear to remain in the list (which can cause issues with FirstOfGroup loops).
Therefore, if units are not removed manually from the group before this happens, there is a minor leak, and the CPU cost of many group operations increases dramatically. Verification is in this thread here
NB: This only applies to where a group has units in it for longer than an instant, and where those units may decay / be removed. Most uses of groups are not vulnerable to that (most uses you should be using a static group and a boolexpr these days - those are completely unaffected).
Fortunately, GroupClear solves the problem, enabling the creation of a function that can be called on a group and flushes out all of the shadow units in it. The cost is pretty much O(n), where n is the number of real units in the group (rather than shadows).
GroupRefresh does not affect the group in a noticeable way, aside from removing the shadow references in the hash table, which speeds up most operations (see the link above for further details). The only effect it will have on outputs is on FirstOfGroup, which can return null when it comes to a shadow reference in the list, even if there are real units after it. GroupRefresh clears those out, so makes FirstOfGroup act properly again.
More frequent calls of GroupRefresh will reduce CPU costs of most operations involving groups whose usage makes them vulnerable to this, but will incur a higher CPU cost of its own. Look at the benchmarks on the link above and decide for yourself what the best balance is.
In the event that you used one of the libraries this has deprecated, the following backwards compatibility libraries have been provided for your convenience. Simply replace the old library with the respective library below and it will work fine.
Thanks guys, hopefully this helps streamline group handling!