Vector

A battle vector is an object representing a 2D or 3D position on the battlefield. Once created, battle vectors can be passed as arguments to certain functions in order to specify movement or attack positions.

In battle vector terminology the x co-ordinate represents east to west on the battlefield, the y co-ordinate represents the height from the ground plane, and the z co-ordinate represents north to south. A 2D vector represents an x/z position, whereas a 3D vector's co-ordinates are stored x/y/z - note that the height component is in the middle. A position of 0, 0, 0 would represent the centre of the battlefield at a height of 0 above the water plane.

All battle co-ordinates and distances are specified in metres.

Loaded in Battle loaded in battle
Back to top

Creation

battle_vector:new([number x], [number y], [number z])
Creates a new battle_vector object. Initial co-ordinates may optionally be specified.

Parameters:

1

number

optional, default value=0

x

2

number

optional, default value=0

y

3

number

optional, default value=0

z

Returns:

  1. battle_vector vector

Example:

my_vector = battle_vector:new(100, 0, 100)

defined in ../../common/EmpireBattle/Source/BattleScript/BattleScriptUtilities.cpp, line 129

Back to top

Vector Arithmetic

Battle vectors can be added, subtracted, multiplied or divided. An equality test can also be performed between vectors.

Example:

vec_a = battle_vector:new(50, 50)
vec_b = battle_vector:new(100, 100)
vec_c = vec_a + vec_b         -- [150, 0, 150]
if vec_a == vec_c then
    print("Impossible!")
end
Back to top

Querying

battle_vector:get_x()
Returns the x co-ordinate stored by the vector. This is the east-west position.

Returns:

  1. number x co-ordinate

defined in ../../common/EmpireBattle/Source/BattleScript/BattleScriptUtilities.cpp, line 193

battle_vector:get_y()
Returns the y co-ordinate stored by the vector. This is the height of the vector position from the water plane.

Returns:

  1. number y co-ordinate

defined in ../../common/EmpireBattle/Source/BattleScript/BattleScriptUtilities.cpp, line 207

battle_vector:get_z()
Returns the z co-ordinate stored by the vector. This is the north-south position.

Returns:

  1. number z co-ordinate

defined in ../../common/EmpireBattle/Source/BattleScript/BattleScriptUtilities.cpp, line 221

battle_vector:length()
Returns the distance from the origin [0, 0, 0] to the position of this vector in metres.

Returns:

  1. number length

defined in ../../common/EmpireBattle/Source/BattleScript/BattleScriptUtilities.cpp, line 235

battle_vector:length_xz()
Returns the distance from the origin [0, 0] to the position of this vector in metres, disregarding any height differences.

Returns:

  1. number 2D length

defined in ../../common/EmpireBattle/Source/BattleScript/BattleScriptUtilities.cpp, line 249

battle_vector:set(obj vector or x, number y, number z)
Sets a new position for the vector. The new position may be specified as a single vector argument or as three numeric co-ordinate arguments.

Parameters:

1

obj

Either a vector specifying the new position, or a number specifying the new x co-ordinate.

2

number

A number specifying the new y co-ordinate. This is not needed if a vector was supplied as the first argument.

3

number

A number specifying the new z co-ordinate. This is not needed if a vector was supplied as the first argument.

Returns:

  1. nil

Example:

vec_a:set(vec_b)
vec_b:set(100, 0, 100)

defined in ../../common/EmpireBattle/Source/BattleScript/BattleScriptUtilities.cpp, line 265

battle_vector:set_x(number x)
Sets a new x co-ordinate for the vector.

Parameters:

1

number

x co-ordinate in metres.

Returns:

  1. nil

Example:

vec_a:set_x(100)

defined in ../../common/EmpireBattle/Source/BattleScript/BattleScriptUtilities.cpp, line 307

battle_vector:set_y(number y)
Sets a new y co-ordinate for the vector. This is the height of the position from the water plane.

Parameters:

1

number

y co-ordinate in metres.

Returns:

  1. nil

Example:

vec_a:set_y(35)

defined in ../../common/EmpireBattle/Source/BattleScript/BattleScriptUtilities.cpp, line 323

battle_vector:set_z(number z)
Sets a new z co-ordinate for the vector. This is the height of the position from the water plane.

Parameters:

1

number

z co-ordinate in metres.

Returns:

  1. nil

Example:

vec_a:set_z(-400)

defined in ../../common/EmpireBattle/Source/BattleScript/BattleScriptUtilities.cpp, line 339

battle_vector:distance(battle_vector vector)
Returns the distance from a supplied vector to the subject vector in metres.

Parameters:

1

battle_vector

vector

Returns:

  1. distance in m

Example:

vec_a = battle_vector:new(0, 100, 0)
vec_b = battle_vector:new(0, 200, 0)        -- 100m above vec_a
print(vec_a:distance(vec_b))
100

defined in ../../common/EmpireBattle/Source/BattleScript/BattleScriptUtilities.cpp, line 355

battle_vector:distance_xz(battle_vector vector)
Returns the distance from a supplied vector to the subject vector in metres, but disregarding any height difference.

Parameters:

1

battle_vector

vector

Returns:

  1. distance in m

Example:

vec_a = battle_vector:new(0, 100, 0)
vec_b = battle_vector:new(0, 200, 0)        -- 100m above vec_a
print(vec_a:distance_xz(vec_b))
0

defined in ../../common/EmpireBattle/Source/BattleScript/BattleScriptUtilities.cpp, line 381

Last updated 25/08/2021 12:07:51