GroupEnumUnitsInRange

Parameters

whichGroup	group	The group to be modified.
x	real	X map coordinate.
y	real	Y map coordinate.
radius	real	Radius in map units.
filter	boolexpr	A filter function that is run for each considered unit. If it is null (nil in Lua), all considered units will be added to the group.

comment

Clears a group and then adds units within given radius of map coordinates to it.

Does nothing if whichGroup is null.

note

Includes dead units (e.g. corpses, not yet removed from map).

Does not include:

• Hidden units
• locust units, they cannot be spatially enumerated.

note

Within the filter function, the considered unit can be accessed with GetFilterUnit.

note

The filter function must return true (a truthy value in Lua) in order to add the unit to the group.

note

The units are added consecutively to the group between filter runs, not in bulk after all filter runs were processed.

note

In terms of running the filter function, units are processed in a certain order. The playing field is divided into sectors of 256x256, i.e., {[minX=0, minY=0, maxX=256, maxY=256], [minX=256, minY=0, maxX=512, maxY=256], [minX=0, minY=256, maxX=256, maxY=512], [minX=256, minY=256, maxX=512, maxY=512], ...}. The game keeps track what units are in what sector and the order in which they were added. The filters run from bottom to top sectors as an outer loop and from left to right sectors as an inner loop. Within each sector, the units are processed in reverse order in which they were added to the sector.

note

The origin of the unit must be within the area of the circle to be considered. The collision size of the unit does not matter.

note

See: GroupEnumUnitsInRect, GroupEnumUnitsInRangeOfLoc.

patch

1.00

Source

common.j (raise an issue to discuss on Github or submit a PR)

return type

nothing

Source code

native GroupEnumUnitsInRange                takes group whichGroup, real x, real y, real radius, boolexpr filter returns nothing