# Math

### Math

#### Vector3

`Vector3(x, y, z)`: Creates a new Vector3 with the given components.

lua

```lua
local v = Vector3(0, 10, 0)
```

`v.x` (number): The X component.

```lua
print(v.x)
```

`v.y` (number): The Y component.

```lua
print(v.y)
```

`v.z` (number): The Z component.

```lua
print(v.z)
```

`v:magnitude()`: Returns the length of the vector as a number.

```lua
local len = v:magnitude()
print(len)
```

`v:distance(other)`: Returns the distance between this vector and another `Vector3`.

```lua
local dist = v:distance(Vector3(0, 0, 0))
print(dist)
```

`v:normalize()`: Returns a unit vector pointing in the same direction with a magnitude of 1.

```lua
local dir = v:normalize()
print(dir.x, dir.y, dir.z)
```

`v:cross(other)`: Returns the cross product of this vector and another `Vector3`. The result is a vector perpendicular to both.

```lua
local c = v:cross(Vector3(1, 0, 0))
print(c.x, c.y, c.z)
```

`v:dot(other)`: Returns the dot product of this vector and another `Vector3` as a number.

```lua
local d = v:dot(Vector3(0, 1, 0))
print(d)
```

`v:lerp(other, t)`: Returns a new `Vector3` linearly interpolated between this vector and `other` by factor `t`, where `0` returns this vector and `1` returns `other`.

```lua
local result = v:lerp(Vector3(10, 10, 10), 0.5)
print(result.x, result.y, result.z)
```

Vector3 supports the standard arithmetic operators:

```lua
local a = Vector3(1, 2, 3)
local b = Vector3(4, 5, 6)

local added = a + b        -- Vector3(5, 7, 9)
local subtracted = a - b   -- Vector3(-3, -3, -3)
local scaled = a * 2       -- Vector3(2, 4, 6)
local divided = a / 2      -- Vector3(0.5, 1, 1.5)
```

***

#### Vector2

`Vector2(x, y)`: Creates a new Vector2 with the given components.

```lua
local v = Vector2(100, 200)
```

`v.x` (number): The X component.

```lua
print(v.x)
```

`v.y` (number): The Y component.

```lua
print(v.y)
```

`v:distance(other)`: Returns the distance between this vector and another `Vector2`.

```lua
local dist = v:distance(Vector2(0, 0))
print(dist)
```

Vector2 supports the standard arithmetic operators:

```lua
local a = Vector2(10, 20)
local b = Vector2(5, 10)

local added = a + b       -- Vector2(15, 30)
local subtracted = a - b  -- Vector2(5, 10)
local scaled = a * 2      -- Vector2(20, 40)
```

***

#### Color

`Color(r, g, b, a)`: Creates a new Color. All channels are in the range 0–255.

```lua
local red = Color(255, 0, 0, 255)
```

`c.r` (number): The red channel, 0–255.

```lua
print(c.r)
```

`c.g` (number): The green channel, 0–255.

```lua
print(c.g)
```

`c.b` (number): The blue channel, 0–255.

```lua
print(c.b)
```

`c.a` (number): The alpha channel, 0–255. `0` is fully transparent, `255` is fully opaque.

```lua
print(c.a)
```

Example — creating common colors:

```lua
local white   = Color(255, 255, 255, 255)
local black   = Color(0,   0,   0,   255)
local red     = Color(255, 0,   0,   255)
local green   = Color(0,   255, 0,   255)
local blue    = Color(0,   0,   255, 255)
local yellow  = Color(255, 255, 0,   255)
local cyan    = Color(0,   255, 255, 255)
local magenta = Color(255, 0,   255, 255)

-- semi-transparent red
local transparent = Color(255, 0, 0, 128)
```

***

#### Math

`Math.Clamp(value, min, max)`: Clamps `value` so it never goes below `min` or above `max`.

```lua
local clamped = Math.Clamp(150, 0, 100)
print(clamped) -- 100
```

`Math.Lerp(a, b, t)`: Linearly interpolates between `a` and `b` by factor `t`. `t = 0` returns `a`, `t = 1` returns `b`.

```lua
local result = Math.Lerp(0, 100, 0.25)
print(result) -- 25
```

`Math.Random(min, max)`: Returns a random integer between `min` and `max` inclusive.

```lua
local n = Math.Random(1, 6)
print(n)
```

`Math.RandomFloat(min, max)`: Returns a random float between `min` and `max`.

```lua
local f = Math.RandomFloat(0.0, 1.0)
print(f)
```

`Math.Distance2D(a, b)`: Returns the distance between two `Vector2` points.

```lua
local dist = Math.Distance2D(Vector2(0, 0), Vector2(100, 100))
print(dist)
```

`Math.Distance3D(a, b)`: Returns the distance between two `Vector3` points.

```lua
local dist = Math.Distance3D(Vector3(0, 0, 0), Vector3(10, 0, 0))
print(dist) -- 10
```

`Math.Sin(v)`: Returns the sine of `v` in radians.

```lua
print(Math.Sin(Math.Pi() / 2)) -- 1
```

`Math.Cos(v)`: Returns the cosine of `v` in radians.

```lua
print(Math.Cos(0)) -- 1
```

`Math.Tan(v)`: Returns the tangent of `v` in radians.

```lua
print(Math.Tan(Math.Pi() / 4)) -- ~1
```

`Math.Asin(v)`: Returns the arcsine of `v` in radians.

```lua
print(Math.Asin(1)) -- ~1.5708
```

`Math.Acos(v)`: Returns the arccosine of `v` in radians.

```lua
print(Math.Acos(1)) -- 0
```

`Math.Atan(v)`: Returns the arctangent of `v` in radians.

```lua
print(Math.Atan(1)) -- ~0.7854
```

`Math.Atan2(y, x)`: Returns the angle in radians between the positive X axis and the point `(x, y)`. More reliable than `Atan` for full 360° angles.

```lua
local angle = Math.Atan2(1, 0)
print(Math.Deg(angle)) -- 90
```

`Math.Sqrt(v)`: Returns the square root of `v`.

```lua
print(Math.Sqrt(144)) -- 12
```

`Math.Abs(v)`: Returns the absolute value of `v`.

```lua
print(Math.Abs(-42)) -- 42
```

`Math.Floor(v)`: Rounds `v` down to the nearest integer.

```lua
print(Math.Floor(4.9)) -- 4
```

`Math.Ceil(v)`: Rounds `v` up to the nearest integer.

```lua
print(Math.Ceil(4.1)) -- 5
```

`Math.Round(v)`: Rounds `v` to the nearest integer.

```lua
print(Math.Round(4.5)) -- 5
```

`Math.Pow(base, exp)`: Returns `base` raised to the power of `exp`.

```lua
print(Math.Pow(2, 10)) -- 1024
```

`Math.Log(v)`: Returns the natural logarithm (base e) of `v`.

```lua
print(Math.Log(Math.Huge())) -- inf
```

`Math.Log10(v)`: Returns the base-10 logarithm of `v`.

```lua
print(Math.Log10(1000)) -- 3
```

`Math.Log2(v)`: Returns the base-2 logarithm of `v`.

```lua
print(Math.Log2(1024)) -- 10
```

`Math.Sign(v)`: Returns `1` if `v` is positive, `-1` if negative, or `0` if zero.

```lua
print(Math.Sign(-99)) -- -1
print(Math.Sign(0))   -- 0
print(Math.Sign(42))  -- 1
```

`Math.Map(v, inMin, inMax, outMin, outMax)`: Remaps `v` from one range to another. Useful for converting values like health percentages to screen pixel lengths.

```lua
-- map health 0-100 to bar width 0-200
local barWidth = Math.Map(health, 0, 100, 0, 200)
```

`Math.Deg(radians)`: Converts a value from radians to degrees.

```lua
print(Math.Deg(Math.Pi())) -- 180
```

`Math.Rad(degrees)`: Converts a value from degrees to radians.

```lua
print(Math.Rad(180)) -- ~3.1416
```

`Math.Pi()`: Returns the constant π (approximately 3.14159).

```lua
local circumference = 2 * Math.Pi() * radius
```

`Math.Tau()`: Returns 2π (approximately 6.28318). Equal to one full revolution in radians.

```lua
local fullCircle = Math.Tau()
```

`Math.Huge()`: Returns positive infinity. Useful as an initial value when searching for a minimum.

```lua
local closest = Math.Huge()
for _, p in ipairs(players) do
    local dist = Math.Distance3D(myPos, p.HumanoidRootPart.WorldPosition)
    if dist < closest then
        closest = dist
    end
end
```

`Math.Epsilon()`: Returns the smallest representable positive float difference from 1. Useful for avoiding division by zero or floating point comparisons.

```lua
print(Math.Epsilon())
```

`Math.Min(a, b)`: Returns the smaller of two numbers.

```lua
print(Math.Min(10, 20)) -- 10
```

`Math.Max(a, b)`: Returns the larger of two numbers.

```lua
print(Math.Max(10, 20)) -- 20
```


---

# 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://yerba-1.gitbook.io/yerba-docs/api/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.