Convex Areas
By creating a convex area, client scripts may define a convex hull shape on the battlefield or campaign map through a series of vectors, and then perform tests with it, such as seeing if a given position/unit is within the described shape.
Convex areas are most useful for battle scripts, but may also be used in campaign.
| Loaded in Battle |
|
| Loaded in Campaign |
|
-
convex_area:new(tablepositions) -
Creates a convex area from a supplied table of vectors. The supplied table must contain a minimum of three vector positions, and these must describe a convex hull shape. The points must declared in a clockwise orientation around the hull shape.
Parameters:
1
tableTable of vector positions
Returns:
convex_area
defined in ../working_data/script/_lib/lib_convex_area.lua, line 516
Once a convex_area object has been created with convex_area:new, functions on it may be called in the form showed below.
Example - Specification:
<convex_area_object>:<function_name>(<args>)
Example - Creation and Usage:
local test_position = v(150, 150)
local area_01 = convex_area:new({v(0, 0), v(0, 300), v(300, 300), v(300, 0)})
if area_01:is_in_area(test_position) then
out("test position is in area_01")
end
test position is in area_01
-
convex_area:item(integerindex) -
Retrieves the nth vector in the convex area. Returns false if no vector exists at this index.
Parameters:
1
integerindex
Returns:
vector
defined in ../working_data/script/_lib/lib_convex_area.lua, line 621
-
convex_area:count() -
Returns the number of vector positions that make up this convex area shape
Returns:
integernumber of positions
defined in ../working_data/script/_lib/lib_convex_area.lua, line 634
-
convex_area:is_in_area(objectcollection, [booleanstanding only]) -
Returns true if any element of the supplied object or collection is in the convex area, false otherwise.
The second boolean flag, if set to true, instructsis_in_areato disregard any routing or dead units in the collection.Parameters:
1
objectObject or collection to test. Supported object/collection types are vector, unit, scriptunit, scriptunits, units, army, armies, alliance and table.
2
booleanoptional, default value=false
Disregard routing or dead units.
Returns:
booleanany are in area
defined in ../working_data/script/_lib/lib_convex_area.lua, line 642
-
convex_area:standing_is_in_area(objectobject or collection to test) -
Alias for
is_in_area(obj, true). Returns true if any element of the supplied object or collection is in the convex area, false otherwise. Supported object/collection types are vector, unit, scriptunit, scriptunits, units, army, armies, alliance and table. Disregards routing or dead units.Parameters:
1
objectobject or collection to test
Returns:
booleanany are in area
defined in ../working_data/script/_lib/lib_convex_area.lua, line 731
-
convex_area:not_in_area(objectcollection, [booleanstanding only]) -
Returns true if any element of the supplied object or collection is NOT in the convex area, false otherwise.
The second boolean flag, if set to true, instructsnot_in_areato disregard any routing or dead units in the collection.Parameters:
1
objectObject or collection to test. Supported object/collection types are vector, unit, scriptunit, scriptunits, units, army, armies, alliance and table.
2
booleanoptional, default value=false
Disregard routing or dead units.
Returns:
booleanany are not in area
defined in ../working_data/script/_lib/lib_convex_area.lua, line 740
-
convex_area:standing_not_in_area(objectcollection) -
Alias for
not_in_area(obj, true). Returns true if any element of the supplied object or collection is NOT in the convex area, false otherwise.Parameters:
1
objectObject or collection to test. Supported object/collection types are vector, unit, scriptunit, scriptunits, units, army, armies, alliance and table. Disregards routing or dead units.
Returns:
booleanany are not in area
defined in ../working_data/script/_lib/lib_convex_area.lua, line 818
-
convex_area:number_in_area(objectcollection, [booleanstanding only]) -
Returns the number of elements in the target collection that fall in the convex area.
The second boolean flag, if set to true, instructsnumber_in_areato disregard any routing or dead units in the collection.Parameters:
1
objectObject or collection to test. Supported object types are unit, units, scriptunit, scriptunits, army, armies, alliance and table.
2
booleanoptional, default value=false
Disregard routing or dead units.
Returns:
integernumber in area
defined in ../working_data/script/_lib/lib_convex_area.lua, line 827
-
convex_area:standing_number_in_area(objectcollection) -
Alias for
standing_number_in_area(obj, true). Returns the number of elements in the target collection that fall in the convex area.Parameters:
1
objectObject or collection to test. Supported object types are unit, units, scriptunit, scriptunits, army, armies, alliance and table. isregards routing or dead units.
Returns:
integernumber in area
defined in ../working_data/script/_lib/lib_convex_area.lua, line 898