Vector functions

 See also: Math functions
Overview
There are many specialized functions to deal with a 3D game world. Variables that hold 3D coordinates are of a data type called Vector3.
In a 2D world, coordinates can be represented with X and Y coordinates. In a 3D world, the coordinates are X, Y, and Z. Imagine a character standing up with their back to you. The Yaxis is lined up with their spine. If they hold up their right arm and point straight out to their right, that's lined up with the Xaxis. And the direction of their gaze straight ahead is the Z axis.
Usually the easiest way to think about these axes is with degrees. So a point in space that was 45 degrees above the horizon might be represented with coordinates of (0, 45, 1). Though we should use floating point values for these numbers: (0.0, 45.0, 1.0). Instead of (X, Y, Z), another way of referring to these values is: (PolarAngle, Azimuth, Distance).
HeroScript, however, doesn't deal with degrees. It deals with vectors, which are normalized to a value of 1. It's beyond the scope of this database to go into the details of 3D vectors, but if you would like to learn more, it is recommended that you do some Google searches for online tutorials on 3D Graphics. For example, this page has some simple definitions: http://viz.aset.psu.edu/gho/sem_notes/3d_fundamentals/html/geometry_def.html
To convert degrees into vector3 values, the simplest method is to use one of the appropriate exposed functions.
Related functions
Convert Spherical coordinates to a Vector3
This exposed function converts X, Y, Z coordinates to a vector3 value. Client Only
Spherical2XYZ(polarAngle as float, azimuth as float, distance as float) as vector3
Convert a Vector3 to spherical coordinates
This exposed function takes a vector and converts it to XYZ coordinates. Client Only
XYZ2Spherical(polarAngle references float, azimuth references float, distance references float, currentVector as vector3)
Obtain the length of a vector
This function returns the square root of x*x + y*y + z*z
, which is the length of a vector
function VectorLength( v as vector3) as float
Note: this is the function that you use to get the distance between two points.
point1 as Vector3 = vc.character_position point2 as Vector3 = targVC.character_position dist as float = VectorLength(point1  point2)
Vector Length Square
This function returns the value of x*x + y*y + z*z
. It is a bit faster than the function which takes the square root.
function VectorLengthSq( v as vector3) as float
Obtain the dotproduct of two vectors
function DotProduct( v1 as vector3, v2 as vector3) as float
Obtain the crossproduct of two vectors
function CrossProduct( v1 as vector3, v2 as vector3) as vector3
Normalize
These functions modify the vector valueIn
so that its length (the sum of the squares of its components) becomes 1. They also scale the vector, and return the result in valueOut
.
Both of these functions do the exact same thing:
function NormalizeVector3(valueOut references Vector3, valueIn as Vector3) function Normalize(valueOut references Vector3, valueIn as Vector3)
Calculate the angle between two vectors
function AngleBetween( v1 as vector3, v2 as vector3) as vector3
This functions gives you the desired heading for an object at v2 that is in the direction of v1. Examples: the heading a character at point v2 needs to travel in order to reach point v1; the rotation of a billboard at point v1 to face toward the camera at point v2.
See also
Example
Suppose you wish to place a directional light which shines from a 45degree angle off the horizon. To set the directional light, this angle must be converted into vector3 format. This is done with the Spherical2XYZ()
exposed function:
function Spotlight(ambient, diffuse) LightDirection as vector3 Spherical2XYZ(0.0, 45.0, 1.0, LightDirection) // Convert the coordinates to the vector3 StageSetDirectionalLight("Stage", ambient, diffuse, LightDirection) // Turn on the light .