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.

A number of helper functions related to vectors may be found in the Vector Manipulation section of this documentation.

Loaded in Campaign Loaded in Campaign
Loaded in Battle Loaded in Battle
Loaded in Frontend Loaded in Frontend
Back to top

Creation

Call battle_vector:new to create a new vector. Preferably, use the shorthand function v provided by the script libraries.

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 157

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 221

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 235

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 249

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 263

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 277

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 293

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 335

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 351

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 367

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 383

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 409

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