> For the complete documentation index, see [llms.txt](https://lua2.fatality.win/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lua2.fatality.win/api/instances/math.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.