> For the complete documentation index, see [llms.txt](https://valex.gitbook.io/valex/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://valex.gitbook.io/valex/external-lua-environment/color3-and-vector3-lua-environment.md).

# Color3 & Vector3 Lua Environment

### Vector3

#### `vector3.new(x, y, z)`

Constructs a new Vector3.

* **Parameters:** `x` \[float], `y` \[float], `z` \[float]
* **Returns:** `vector3`

```lua
local vec = vector3.new(10, 5, 0);
```

#### `vector3.zero()`

Returns a zero vector (0, 0, 0).

* **Returns:** `vector3`

```lua
local origin = vector3.zero();
```

#### `vector3.one()`

Returns a vector of ones (1, 1, 1).

* **Returns:** `vector3`

```lua
local scale = vector3.one();
```

#### `vector3.unit_x()`

Returns the X axis unit vector (1, 0, 0).

* **Returns:** `vector3`

```lua
local right = vector3.unit_x();
```

#### `vector3.unit_y()`

Returns the Y axis unit vector (0, 1, 0).

* **Returns:** `vector3`

```lua
local up = vector3.unit_y();
```

#### `vector3.unit_z()`

Returns the Z axis unit vector (0, 0, 1).

* **Returns:** `vector3`

```lua
local forward = vector3.unit_z();
```

#### `vec.x`, `vec.y`, `vec.z`

Read or write individual components.

```lua
local v = vector3.new(1, 2, 3);
print(v.x); -- 1
v.y = 50;
```

#### Arithmetic Operations

Supports `+`, `-`, `*`, `/`, `==`.

```lua
local a = vector3.new(1, 2, 3);
local b = vector3.new(4, 5, 6);

local sum = a + b;
local diff = b - a;
local scaled = a * 2; -- (2, 4, 6)
local divided = b / 2; -- (2, 2.5, 3)
```

#### `vec:length()` / `vec:magnitude()`

Returns the length of the vector.

* **Returns:** `float`

```lua
local len = vector3.new(0, 10, 0):length(); -- 10
```

#### `vec:squared_magnitude()`

Returns the squared length (faster than length).

* **Returns:** `float`

```lua
local sq = vector3.new(0, 10, 0):squared_magnitude(); -- 100
```

#### `vec:dot(other)`

Calculates the dot product.

* **Parameters:** `other` \[vector3]
* **Returns:** `float`

```lua
local d = vec1:dot(vec2);
```

#### `vec:cross(other)`

Calculates the cross product.

* **Parameters:** `other` \[vector3]
* **Returns:** `vector3`

```lua
local c = vec1:cross(vec2);
```

#### `vec:normalize()`

Returns the unit vector (length of 1).

* **Returns:** `vector3`

```lua
local dir = vector3.new(0, 100, 0):normalize(); -- (0, 1, 0)
```

***

### Color3

#### `color3.new(r, g, b)`

Constructs a color from 0.0 to 1.0 floats.

* **Parameters:** `r` \[float], `g` \[float], `b` \[float]
* **Returns:** `color3`

```lua
local white = color3.new(1, 1, 1);
```

#### `color3.from_rgb(r, g, b)`

Constructs a color from 0 to 255 integers.

* **Parameters:** `r` \[int], `g` \[int], `b` \[int]
* **Returns:** `color3`

```lua
local red = color3.from_rgb(255, 0, 0);
```

#### `color3.from_hex(hex)`

Constructs a color from a hex integer (0xRRGGBB).

* **Parameters:** `hex` \[uint32]
* **Returns:** `color3`

```lua
local purple = color3.from_hex(0xFF00FF);
```

#### `color3.from_hsv(h, s, v)`

Constructs a color from Hue, Saturation, Value.

* **Parameters:** `h` \[float], `s` \[float], `v` \[float]
* **Returns:** `color3`

```lua
local bright_red = color3.from_hsv(0, 1, 1);
```

#### `color3.random()`

Returns a completely random color.

* **Returns:** `color3`

```lua
local rand = color3.random();
```

#### `color3.rainbow(hue)`

Returns a color from the rainbow spectrum based on hue.

* **Parameters:** `hue` \[float]
* **Returns:** `color3`

```lua
local color = color3.rainbow(os.clock() % 1.0);
```

#### Static Presets

Common colors are available as functions.

* `color3.red()`, `color3.green()`, `color3.blue()`
* `color3.black()`, `color3.white()`, `color3.gray()`
* `color3.yellow()`, `color3.cyan()`, `color3.purple()`, `color3.orange()`

```lua
local c = color3.cyan();
```

#### `col.r`, `col.g`, `col.b`

Read or write individual components.

```lua
local c = color3.white();
c.r = 0; -- becomes cyan (0, 1, 1)
```

#### Arithmetic Operations

Supports `+`, `-`, `*`, `/`, `==`.

```lua
local c1 = color3.new(0.5, 0.5, 0.5);
local c2 = c1 * 2; -- (1.0, 1.0, 1.0)
```

#### `col:lerp(target, alpha)`

Linearly interpolates between two colors.

* **Parameters:** `target` \[color3], `alpha` \[float]
* **Returns:** `color3`

```lua
local start = color3.black();
local target = color3.white();
local mid = start:lerp(target, 0.5); -- Gray
```

#### `col:to_string()`

Returns string representation.

* **Returns:** `string`

```lua
print(color3.red():to_string());
```