> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
title: vector
description: 3D vector math and manipulation
icon: move
---

The `vector` namespace provides 3D vector math and manipulation methods on `vec_object` instances.

## angles

> Converts the angle into a forward vector, or converts the vector into its angle representation.

<Tabs>
  <Tab title="Initialize from">
    ```lua
    vec_object:angles(pitch: number, yaw: number): vector
    ```

    Converts the angle into a forward vector overwriting the vector's coordinates. Returns itself.

    <Schema title="Parameters">
      <SchemaField name="pitch" type="number" required>
        Pitch component of the angle
      </SchemaField>

      <SchemaField name="yaw" type="number" required>
        Yaw component of the angle
      </SchemaField>
    </Schema>

    <Schema title="Returns">
      <SchemaField name="vector" type="vector">
        Itself.
      </SchemaField>
    </Schema>
  </Tab>

  <Tab title="Initialize from [2]">
    ```lua
    vec_object:angles(vector: angle): vector
    ```

    Converts the angle into a forward vector overwriting the vector's coordinates. Returns itself.

    <Schema title="Parameters">
      <SchemaField name="angle" type="vector" required>
        Angle vector component
      </SchemaField>
    </Schema>

    <Schema title="Returns">
      <SchemaField name="vector" type="vector">
        Itself.
      </SchemaField>
    </Schema>
  </Tab>

  <Tab title="Convert to">
    ```lua
    vec_object:angles(): vector
    ```

    Returns the angle vector representing the normal of the vector.

    <Schema title="Returns">
      <SchemaField name="vector" type="vector">
        The angle vector representing the normal of the vector.
      </SchemaField>
    </Schema>
  </Tab>
</Tabs>

## ceil

```lua
vec_object:ceil(): vector
```

> Ceils & overwrites the x, y, and z coordinates of a vector. Returns itself.

<Schema title="Returns">
  <SchemaField name="vector" type="vector">
    Itself.
  </SchemaField>
</Schema>

## clone

```lua
vec_object:clone(): vector
```

> Creates and returns a copy of the vector.

<Schema title="Returns">
  <SchemaField name="vector" type="vector">
    A copy of the vector.
  </SchemaField>
</Schema>

## closest\_ray\_point

```lua
vec_object:closest_ray_point(ray_start: vector, ray_end: vector): vector
```

> Returns the vector of the closest point along a ray.

<Schema title="Parameters">
  <SchemaField name="ray_start" type="vector" required>
    Ray start position
  </SchemaField>

  <SchemaField name="ray_end" type="vector" required>
    Ray end position
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="vector" type="vector">
    The vector of the closest point along a ray.
  </SchemaField>
</Schema>

## cross

```lua
vec_object:cross(other: vector): vector
```

> Returns the cross product of two given vectors.

<Schema title="Parameters">
  <SchemaField name="other" type="vector" required>
    The vector to calculate the cross product with
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="vector" type="vector">
    The cross product of the two given vectors.
  </SchemaField>
</Schema>

## dist

```lua
vec_object:dist(other: vector): number
```

> Returns the Euclidean distance between the two given vectors.

<Schema title="Parameters">
  <SchemaField name="other" type="vector" required>
    The vector to get the distance to
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="distance" type="number">
    The Euclidean distance between the two given vectors.
  </SchemaField>
</Schema>

## dist2d

```lua
vec_object:dist2d(other: vector): number
```

> Returns the 2D distance to another vector.

<Schema title="Parameters">
  <SchemaField name="other" type="vector" required>
    The vector to get the distance to
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="distance" type="number">
    The 2D distance to another vector.
  </SchemaField>
</Schema>

## dist2dsqr

```lua
vec_object:dist2dsqr(other: vector): number
```

> Returns the squared 2D distance to another vector.

<Schema title="Parameters">
  <SchemaField name="other" type="vector" required>
    The vector to get the squared distance to
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="distance" type="number">
    The squared 2D distance to another vector.
  </SchemaField>
</Schema>

## distsqr

```lua
vec_object:distsqr(other: vector): number
```

> Returns the squared Euclidean distance to another vector.

<Schema title="Parameters">
  <SchemaField name="other" type="vector" required>
    The vector to get the squared distance to
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="distance" type="number">
    The squared Euclidean distance to another vector.
  </SchemaField>
</Schema>

## dist\_to\_ray

```lua
vec_object:dist_to_ray(ray_start: vector, ray_direction: vector): number
```

> Returns the distance to a ray.

<Schema title="Parameters">
  <SchemaField name="ray_start" type="vector" required>
    Ray start position
  </SchemaField>

  <SchemaField name="ray_direction" type="vector" required>
    Ray direction
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="distance" type="number">
    The distance to a ray.
  </SchemaField>
</Schema>

## dot

```lua
vec_object:dot(other: vector): number
```

> Returns the dot product of the two given vectors.

<Schema title="Parameters">
  <SchemaField name="other" type="vector" required>
    The vector to calculate the dot product with
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The dot product of the two given vectors.
  </SchemaField>
</Schema>

## floor

```lua
vec_object:floor(): vector
```

> Rounds the x, y, and z coordinates of the vector down to the largest integer that is less than or equal. Returns itself.

<Schema title="Returns">
  <SchemaField name="vector" type="vector">
    Itself.
  </SchemaField>
</Schema>

## in\_range

```lua
vec_object:in_range(other: vector, range: number): boolean
```

> Returns true if the vector is within the given distance to another vector.

<Schema title="Parameters">
  <SchemaField name="other" type="vector" required>
    The vector to calculate the distance to
  </SchemaField>

  <SchemaField name="range" type="number" required>
    The distance
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="boolean">
    `true` if the vector is within the given distance to another vector.
  </SchemaField>
</Schema>

## init

```lua
vec_object:init(x: number, y: number, z: number): vector
```

> Overwrites the vector's coordinates. Returns itself.

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    New X coordinate
  </SchemaField>

  <SchemaField name="y" type="number" required>
    New Y coordinate
  </SchemaField>

  <SchemaField name="z" type="number" required>
    New Z coordinate
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="vector" type="vector">
    Itself.
  </SchemaField>
</Schema>

## length

```lua
vec_object:length(): number
```

> Returns the Euclidean length of the vector.

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The Euclidean length of the vector.
  </SchemaField>
</Schema>

## length2d

```lua
vec_object:length2d(): number
```

> Returns the length of the vector in two dimensions, without the Z axis.

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The length of the vector in two dimensions, without the Z axis.
  </SchemaField>
</Schema>

## length2dsqr

```lua
vec_object:length2dsqr(): number
```

> Returns the squared length of the vectors x and y value.

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The squared length of the vectors x and y value.
  </SchemaField>
</Schema>

## lengthsqr

```lua
vec_object:lengthsqr(): number
```

> Returns the squared length of the vector.

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The squared length of the vector.
  </SchemaField>
</Schema>

## lerp

```lua
vec_object:lerp(other: vector, weight: number): vector
```

> Returns the linearly interpolated vector between two vectors by the specified weight.

<Schema title="Parameters">
  <SchemaField name="other" type="vector" required>
    The vector to interpolate to
  </SchemaField>

  <SchemaField name="weight" type="number" required>
    A value between 0 and 1 that indicates the weight of other
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="vector" type="vector">
    The linearly interpolated vector between two vectors by the specified weight.
  </SchemaField>
</Schema>

## normalize

```lua
vec_object:normalize(): number
```

> Normalizes the vector and returns the length of the vector.

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The length of the vector.
  </SchemaField>
</Schema>

## normalized

```lua
vec_object:normalized(): vector
```

> Returns a vector with the same direction as the specified vector, but with a length of one.

<Schema title="Returns">
  <SchemaField name="vector" type="vector">
    A vector with the same direction as the specified vector, but with a length of one.
  </SchemaField>
</Schema>

## scale

```lua
vec_object:scale(scalar: number): vector
```

> Multiplies the vector by the specified scalar.

<Schema title="Parameters">
  <SchemaField name="scalar" type="number" required>
    The scalar value
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="vector" type="vector">
    The vector multiplied by the specified scalar.
  </SchemaField>
</Schema>

## scaled

```lua
vec_object:scaled(scalar: number): vector
```

> Returns a copy of the vector multiplied by the specified scalar.

<Schema title="Parameters">
  <SchemaField name="scalar" type="number" required>
    The scalar value.
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="vector" type="vector">
    A copy of the vector multiplied by the specified scalar.
  </SchemaField>
</Schema>

## to

```lua
vec_object:to(other: vector): vector
```

> Returns the forward vector from itself to another vector.

<Schema title="Parameters">
  <SchemaField name="other" type="vector" required>
    The vector to get the direction to.
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="vector" type="vector">
    The forward vector from itself to another vector.
  </SchemaField>
</Schema>

## to\_screen

```lua
vec_object:to_screen(): vector
```

> Returns a vector containing the coordinates where the specified position vector appears on the screen.

<Schema title="Returns">
  <SchemaField name="vector" type="vector">
    A vector containing the coordinates where the specified position vector appears on the screen.
  </SchemaField>
</Schema>

## unpack

```lua
vec_object:unpack(): number, number, number
```

> Returns the x, y, and z coordinates of the vector. Note that these fields can be accessed by indexing x, y, and z.

<Schema title="Returns">
  <SchemaField name="x" type="number">
    The X coordinate of the vector.
  </SchemaField>

  <SchemaField name="y" type="number">
    The Y coordinate of the vector.
  </SchemaField>

  <SchemaField name="z" type="number">
    The Z coordinate of the vector.
  </SchemaField>
</Schema>

## vectors

```lua
vec_object:vectors(): vector, vector
```

> Returns the right and up vector of a forward vector.

<Schema title="Returns">
  <SchemaField name="right" type="vector">
    The right vector of a forward vector.
  </SchemaField>

  <SchemaField name="up" type="vector">
    The up vector of a forward vector.
  </SchemaField>
</Schema>
