Home › API Reference › Vector3

Vector3

Type	Struct (value type)
Namespace	`UnityEngine`
Related	`Vector2` (2D), `Vector3Int`

Vector3

A Vector3 is three numbers: x, y and z. Unity uses it for two different things: a position (a point in the world) and a direction with a length (like velocity: "this way, this fast").

A position is a pin on a map. A direction is an arrow drawn on the map: it points somewhere and has a length, but you can draw it anywhere. Subtracting two pins (b - a) gives you the arrow from pin a to pin b.

Constructors

Vector3 v = new Vector3(1f, 2f, 3f);

Static Properties (shortcuts)

Name	Value
`Vector3.zero`	(0, 0, 0)
`Vector3.one`	(1, 1, 1)
`Vector3.up` / `down`	(0, 1, 0) / (0, -1, 0)
`Vector3.right` / `left`	(1, 0, 0) / (-1, 0, 0)
`Vector3.forward` / `back`	(0, 0, 1) / (0, 0, -1)

These are world directions. For the direction an object is facing, use transform.forward.

Properties

Name	Type	Description
`x`, `y`, `z`	`float`	The three components.
`magnitude`	`float`	The length of the arrow. For velocity, this is the speed.
`sqrMagnitude`	`float`	Length squared. Faster (skips a square root). Good for comparing distances.
`normalized`	`Vector3`	Same direction, length 1. Use when you only care about direction.

Static Methods

Method	Returns	Description
`Distance(a, b)`	`float`	Distance between two points.
`Lerp(a, b, t)`	`Vector3`	A point part-way from `a` to `b`. `t = 0` is `a`, `0.5` is halfway, `1` is `b`.
`MoveTowards(current, target, maxDistanceDelta)`	`Vector3`	Steps from current toward target by at most that distance. Never overshoots.
`SmoothDamp(current, target, ref velocity, smoothTime)`	`Vector3`	Moves smoothly, like a spring that slows down as it arrives. Great for cameras.
`Dot(a, b)`	`float`	How much two directions agree. With normalized vectors: 1 = same way, 0 = at right angles, -1 = opposite.
`Cross(a, b)`	`Vector3`	A direction perpendicular to both.
`Angle(from, to)`	`float`	Angle between two directions in degrees (0 to 180).
`ClampMagnitude(v, maxLength)`	`Vector3`	Shortens `v` if it's longer than `maxLength`.
`ProjectOnPlane(v, planeNormal)`	`Vector3`	Flattens a vector onto a surface. E.g. make a camera direction horizontal.
`Reflect(dir, normal)`	`Vector3`	Bounces a direction off a surface.

Operators

Code	Meaning
`a + b`	Move point `a` by arrow `b`.
`b - a`	The arrow from `a` to `b`.
`v * 2f`	Twice as long, same direction.
`-v`	Opposite direction.
`a == b`	True if approximately equal (tiny floating point differences are ignored).

Code Samples

Chase the player

using UnityEngine;

public class Chaser : MonoBehaviour
{
    [SerializeField] private Transform player;
    [SerializeField] private float speed = 3f;

    void Update()
    {
        // Step toward the player. MoveTowards stops exactly on target, no jitter.
        transform.position = Vector3.MoveTowards(
            transform.position, player.position, speed * Time.deltaTime);
    }
}

Direction and distance

Vector3 toPlayer = player.position - transform.position; // arrow from me to player
float distance = toPlayer.magnitude;                     // how far
Vector3 direction = toPlayer.normalized;                 // which way (length 1)

b - a is the arrow from a to b (highlighted). Its length is the distance between them; normalizing keeps the direction but sets the length to 1, which is what you multiply by speed.

Fast range check

float range = 10f;
// Compare squared values: avoids a square root every frame.
if ((player.position - transform.position).sqrMagnitude < range * range)
{
    Debug.Log("In range");
}

Is the player in my field of view?

Vector3 toPlayer = (player.position - transform.position).normalized;
float dot = Vector3.Dot(transform.forward, toPlayer);
if (dot > 0.5f) // roughly within 60 degrees either side of forward
{
    Debug.Log("I can see you");
}

Vector3.Dot(transform.forward, toTarget.normalized) for targets around you. Checking dot > 0.5f means the target is within 60° either side of where you're facing.

Diagonal movement that isn't faster

Vector3 input = new Vector3(Input.GetAxisRaw("Horizontal"), 0f, Input.GetAxisRaw("Vertical"));
// Pressing W+D gives (1, 0, 1), which has length 1.41. That's 41% faster diagonally.
input = Vector3.ClampMagnitude(input, 1f);
transform.position += input * speed * Time.deltaTime;

What happens at runtime

Vector3 is a struct, which means it's copied whenever you assign it or pass it to a method, like an int. Changing a copy doesn't change the original:

Vector3 p = transform.position; // p is a copy
p.y = 10f;                      // changes only the copy
transform.position = p;         // now the object moves

Vector3 math is very cheap and creates no garbage, so it's fine to use freely in Update.

Common Mistakes

Lerp with a constant t in Update (Lerp(a, b, 0.1f)) moves fast at first and slows down forever without quite arriving, and speed depends on frame rate. For constant speed, use MoveTowards; for smooth easing, use SmoothDamp.
Normalizing a zero vector. Vector3.zero.normalized is (0,0,0), not an error, but it may not be what you expected.
Mixing up world and local directions. Vector3.forward is always world +Z. Use transform.forward for "where I'm facing".

Vector3

Constructors

Static Properties (shortcuts)

Properties

Static Methods

Operators

Code Samples

Chase the player

Direction and distance

Fast range check

Is the player in my field of view?

Diagonal movement that isn't faster

What happens at runtime

Common Mistakes

See also