Skip to main content

Vectors

A coordinate tells you where something is. A vector tells you how to get there: a direction and a length. In game development, vector mathematics is the primary tool for placing objects relative to the player, measuring distances, and aiming weapons.

Vector3: position or movement​

In ScriptHookVDotNet, GTA.Math.Vector3 represents both points in space and displacement vectors.

// As a position
Vector3 spawnPoint = new Vector3(100f, -200f, 30f);

// As a direction or offset
Vector3 stepForward = new Vector3(0f, 2f, 0f);

Placing something in front of the player: ForwardVector​

The most common vector calculation in modding is placing an entity directly in front of the player, regardless of which way the player is facing.

Every entity has a ForwardVector: a normalized vector (length of 1 meter) pointing in the direction the entity is currently looking:

Ped player = Game.Player.Character;
Vector3 playerPos = player.Position;
Vector3 forward = player.ForwardVector;

// Place a spawn point exactly 3 meters directly ahead
Vector3 inFrontOfPlayer = playerPos + forward * 3.0f;

If you want something to spawn to the side or behind, you multiply or negate:

  • Behind: playerPos - forward * 3.0f
  • Above: playerPos + new Vector3(0f, 0f, 2.0f)

Measuring distance between two points​

To check whether the player has reached a destination or is close enough to interact with an NPC, measure the distance between their positions:

Vector3 target = new Vector3(250f, -400f, 25f);
float distance = Vector3.Distance(player.Position, target);

if (distance < 5.0f)
{
    GTA.UI.Screen.ShowSubtitle("You have arrived at the drop point.", 2000);
}

3D distance vs 2D horizontal distance​

Vector3.Distance(a, b) calculates full 3D Euclidean distance including altitude. If the target is on an overpass 20 meters above the player, 3D distance might read 22 meters even if the player is standing directly underneath it on the X/Y plane.

If you only care about horizontal proximity (ignoring bridges or vertical hills), use Vector3.Distance2D:

float horizontalDistance = Vector3.Distance2D(player.Position, target);

Direction from entity to entity: subtraction​

To find the vector pointing from entity A to entity B, subtract A from B:

// Vector pointing from player towards an enemy
Vector3 directionToEnemy = enemy.Position - player.Position;

// Normalize to get just the pure direction with length 1.0
Vector3 aimDirection = directionToEnemy.Normalized;

In the next lesson, we meet physical entities: peds, vehicles, and props, and how the game manages their handles.