# Vector functions

(Redirected from Technical:Vector 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 Y-axis 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 X-axis. 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.

## Example

Suppose you wish to place a directional light which shines from a 45-degree 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
.```