# math

<table data-full-width="false"><thead><tr><th width="182">Usage: math.{func}</th></tr></thead><tbody><tr><td></td></tr></tbody></table>

This table extends the existing `math` table that is a part of Lua.

## CalcAngle <a href="#calc-angle" id="calc-angle"></a>

<mark style="color:blue;">**`Function`**</mark>

Calculates angles between 2 vectors.

**Arguments**

| Name  | Type                             | Description         |
| ----- | -------------------------------- | ------------------- |
| `src` | [`Vector`](/api/types/vector.md) | Source vector.      |
| `dst` | [`Vector`](/api/types/vector.md) | Destination vector. |

**Returns**

| Type                             | Description |
| -------------------------------- | ----------- |
| [`Vector`](/api/types/vector.md) | Angles.     |

**Example**

```lua
local ang = math.CalcAngle(vec1, vec2);
```

***

## AngleNormalize <a href="#angle-normalize" id="angle-normalize"></a>

<mark style="color:blue;">**`Function`**</mark>

Normalizes an angle.

**Arguments**

| Name    | Type    | Description  |
| ------- | ------- | ------------ |
| `angle` | `float` | Input angle. |

**Returns**

| Type    | Description       |
| ------- | ----------------- |
| `float` | Normalized angle. |

**Example**

```lua
local norm = math.AngleNormalize(560);
```

***

## ApproachAngles

<mark style="color:blue;">**`Function`**</mark>

Approaches an angle over time.

**Arguments**

| Name    | Type                             | Description     |
| ------- | -------------------------------- | --------------- |
| `from`  | [`Vector`](/api/types/vector.md) | Start angle.    |
| `to`    | [`Vector`](/api/types/vector.md) | End angle.      |
| `speed` | `float`                          | Approach speed. |

**Returns**

| Type                             | Description  |
| -------------------------------- | ------------ |
| [`Vector`](/api/types/vector.md) | Delta angle. |

**Example**

```lua
local ang = math.ApproachAngles(from, to, 1.0 / game.globalVars.frame_time);
```

***

## EdgePoint

<mark style="color:blue;">**`Function`**</mark>

Returns a point on the edge of a box.

**Arguments**

| Name     | Type                             | Description              |
| -------- | -------------------------------- | ------------------------ |
| `mins`   | [`Vector`](/api/types/vector.md) | Box mins.                |
| `maxs`   | [`Vector`](/api/types/vector.md) | Box maxs.                |
| `dir`    | [`Vector`](/api/types/vector.md) | Point direction (angle). |
| `radius` | `float`                          | Area radius.             |

**Returns**

| Type                             | Description |
| -------------------------------- | ----------- |
| [`Vector`](/api/types/vector.md) | Point.      |

**Example**

```lua
local point = math.EdgePoint(mins, maxs, dir, 5);
```

***

## Lerp <a href="#lerp" id="lerp"></a>

<mark style="color:blue;">**`Function`**</mark>

Linear interpolation.

**Arguments**

| Name       | Type    | Description           |
| ---------- | ------- | --------------------- |
| `t1`       | `float` | Start value.          |
| `t2`       | `float` | End value.            |
| `progress` | `float` | Interpolation amount. |

**Returns**

| Type    | Description         |
| ------- | ------------------- |
| `float` | Interpolated value. |

**Example**

```lua
local mid = math.Lerp(0, 100, 0.5);
```

***

## VectorAngles

<mark style="color:blue;">**`Function`**</mark>

Calculates angles from a vector.

**Arguments**

| Name      | Type                             | Description                   |
| --------- | -------------------------------- | ----------------------------- |
| `forward` | [`Vector`](/api/types/vector.md) | Source vector.                |
| `up`      | [`Vector`](/api/types/vector.md) | Up vector. Defaults to `nil`. |

**Returns**

| Type                             | Description |
| -------------------------------- | ----------- |
| [`Vector`](/api/types/vector.md) | Angles.     |

**Example**

```lua
local ang = math.VectorAngles(fw);
```

***

## WorldToScreen

<mark style="color:blue;">**`Function`**</mark>

Transforms a point in the game world onto the viewport.

**Arguments**

| Name    | Type                             | Description                                          |
| ------- | -------------------------------- | ---------------------------------------------------- |
| `xyz`   | [`Vector`](/api/types/vector.md) | Point in the world.                                  |
| `round` | `bool`                           | Whether should round the output. Defaults to `true`. |

**Returns**

| Type                                        | Description            |
| ------------------------------------------- | ---------------------- |
| [`Vec2`](/api/instances/draw/types/vec2.md) | Point on the viewport. |

**Example**

```lua
local point = math.WorldToScreen(game_point);
```

***

## Clamp <a href="#clamp" id="clamp"></a>

<mark style="color:blue;">**`Function`**</mark>

Clamps a value between min and max.

**Arguments**

| Name    | Type    | Description    |
| ------- | ------- | -------------- |
| `n`     | `float` | Value.         |
| `lower` | `float` | Lowest value.  |
| `upper` | `float` | Highest value. |

**Returns**

| Type    | Description    |
| ------- | -------------- |
| `float` | Clamped value. |

**Example**

```lua
local x = math.Clamp(50, 5, 25); -- 25
```

***

## RemapVal <a href="#remap-val" id="remap-val"></a>

<mark style="color:blue;">**`Function`**</mark>

Maps the value from one range to another range.

**Arguments**

| Name  | Type    | Description                |
| ----- | ------- | -------------------------- |
| `val` | `float` | Value.                     |
| `a`   | `float` | Lowest source value.       |
| `b`   | `float` | Highest source value.      |
| `c`   | `float` | Lowest destination value.  |
| `d`   | `float` | Highest destination value. |

**Returns**

| Type    | Description   |
| ------- | ------------- |
| `float` | Mapped value. |

**Example**

```lua
local mapped = math.RemapVal(0.5, 0, 1, 0, 100); -- 50
```

***

## RemapValClamped

<mark style="color:blue;">**`Function`**</mark>

Maps the value from one range to another range. Additionally, clamps the value based on the source range.

**Arguments**

| Name  | Type    | Description                |
| ----- | ------- | -------------------------- |
| `val` | `float` | Value.                     |
| `a`   | `float` | Lowest source value.       |
| `b`   | `float` | Highest source value.      |
| `c`   | `float` | Lowest destination value.  |
| `d`   | `float` | Highest destination value. |

**Returns**

| Type    | Description   |
| ------- | ------------- |
| `float` | Mapped value. |

**Example**

```lua
local mapped = math.RemapValClamped(5, 0, 1, 0, 100); -- 100
```

***

## Vec2 <a href="#vec2" id="vec2"></a>

<mark style="color:blue;">**`Function`**</mark>

An alias to [`draw.Vec2`](#vec2).

**Example**

```lua
local vec = math.Vec2(5, 5);
```

***

## Vec3 <a href="#vec3" id="vec3"></a>

<mark style="color:blue;">**`Function`**</mark>

An alias to [`Vector`](/api/types/vector.md).

**Example**

```lua
local vec = math.Vec3(5, 12, 5);
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://lua2.fatality.win/api/instances/math.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.