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 Campaign Loaded in Campaign
Loaded in Battle Loaded in Battle
Loaded in Frontend Loaded in Frontend
Back to top

Creation

convex_area:new(table positions)
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

table

Table of vector positions

Returns:

  1. convex_area

defined in ../../Warhammer/working_data/script/_lib/lib_convex_area.lua, line 675

Back to top

Usage

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
Back to top

Querying

convex_area:item(integer index)
Retrieves the nth vector in the convex area. Returns false if no vector exists at this index.

Parameters:

1

integer

index

Returns:

  1. vector

defined in ../../Warhammer/working_data/script/_lib/lib_convex_area.lua, line 779

convex_area:count()
Returns the number of vector positions that make up this convex area shape

Returns:

  1. integer number of positions

defined in ../../Warhammer/working_data/script/_lib/lib_convex_area.lua, line 792

convex_area:is_in_area(object collection, [boolean standing 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, instructs is_in_area to disregard any routing or dead units in the collection.

Parameters:

1

object

Object or collection to test. Supported object/collection types are vector, unit, scriptunit, scriptunits, units, army, armies, alliance and table.

2

boolean

optional, default value=false

Disregard routing or dead units.

Returns:

  1. boolean any are in area

defined in ../../Warhammer/working_data/script/_lib/lib_convex_area.lua, line 800

convex_area:standing_is_in_area(object object 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

object

object or collection to test

Returns:

  1. boolean any are in area

defined in ../../Warhammer/working_data/script/_lib/lib_convex_area.lua, line 889

convex_area:not_in_area(object collection, [boolean standing 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, instructs not_in_area to disregard any routing or dead units in the collection.

Parameters:

1

object

Object or collection to test. Supported object/collection types are vector, unit, scriptunit, scriptunits, units, army, armies, alliance and table.

2

boolean

optional, default value=false

Disregard routing or dead units.

Returns:

  1. boolean any are not in area

defined in ../../Warhammer/working_data/script/_lib/lib_convex_area.lua, line 898

convex_area:standing_not_in_area(object collection)
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

object

Object 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:

  1. boolean any are not in area

defined in ../../Warhammer/working_data/script/_lib/lib_convex_area.lua, line 976

convex_area:number_in_area(object collection, [boolean standing only])
Returns the number of elements in the target collection that fall in the convex area.
The second boolean flag, if set to true, instructs number_in_area to disregard any routing or dead units in the collection.

Parameters:

1

object

Object or collection to test. Supported object types are unit, units, scriptunit, scriptunits, army, armies, alliance and table.

2

boolean

optional, default value=false

Disregard routing or dead units.

Returns:

  1. integer number in area

defined in ../../Warhammer/working_data/script/_lib/lib_convex_area.lua, line 985

convex_area:standing_number_in_area(object collection)
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

object

Object or collection to test. Supported object types are unit, units, scriptunit, scriptunits, army, armies, alliance and table. isregards routing or dead units.

Returns:

  1. integer number in area

defined in ../../Warhammer/working_data/script/_lib/lib_convex_area.lua, line 1056

Last updated 12/08/2022 11:56:58