Vector Types (vec2, vec3, vec4)

2D, 3D, and 4D vector types with operators, fields, methods, and memory access functions.

vec2 - 2D Vector

Constructor

Signature: vec2(x, y)

Description: Constructs a 2D vector with the specified components.

Parameters:

• x (number): The x-component.

• y (number): The y-component.

Returns:

• vec2: A new 2D vector object.

Example:

-- Create a 2D vector
local v = vec2(10, 20)
engine.log("Vector: (" .. v.x .. ", " .. v.y .. ")", 255, 255, 255, 255)

Operators

The following operators are supported for vec2:

• Addition: vec2 + vec2 - Adds two vectors component-wise.

• Subtraction: vec2 - vec2 - Subtracts two vectors component-wise.

• Multiplication: vec2 * scalar - Multiplies each component by a scalar.

• Division: vec2 / scalar - Divides each component by a scalar.

• Negation: -vec2 - Returns the negated vector.

• Length: #vec2 - Returns the length (magnitude) of the vector.

• Equality: vec2 == vec2 - Compares two vectors for equality.

Example:

local v1 = vec2(10, 20)
local v2 = vec2(5, 8)

-- Vector operations
local sum = v1 + v2            -- (15, 28)
local difference = v1 - v2      -- (5, 12)
local scaled = v1 * 2           -- (20, 40)
local divided = v1 / 2          -- (5, 10)
local negated = -v1             -- (-10, -20)
local length = #v1              -- sqrt(10^2 + 20^2) = ~22.36
local equal = (v1 == vec2(10, 20)) -- true

engine.log("Sum: (" .. sum.x .. ", " .. sum.y .. ")", 255, 255, 255, 255)
engine.log("Difference: (" .. difference.x .. ", " .. difference.y .. ")", 255, 255, 255, 255)
engine.log("Scaled: (" .. scaled.x .. ", " .. scaled.y .. ")", 255, 255, 255, 255)
engine.log("Divided: (" .. divided.x .. ", " .. divided.y .. ")", 255, 255, 255, 255)
engine.log("Negated: (" .. negated.x .. ", " .. negated.y .. ")", 255, 255, 255, 255)
engine.log("Length: " .. length, 255, 255, 255, 255)
engine.log("Equal: " .. tostring(equal), 255, 255, 255, 255)

Fields

• vec2.x - The x-component of the vector.

• vec2.y - The y-component of the vector.

Methods

vec2:length

Signature: vec2:length()

Description: Returns the length (magnitude) of the vector.

Parameters: None

Returns:

• number: The vector's length.

Example:

local v = vec2(3, 4)
local length = v:length()  -- 5
engine.log("Vector: (" .. v.x .. ", " .. v.y .. ")", 255, 255, 255, 255)
engine.log("Length: " .. length, 255, 255, 255, 255)

vec2:length_squared

Signature: vec2:length_squared()

Description: Returns the squared length of the vector (more efficient than length() when comparing distances).

Parameters: None

Returns:

• number: The squared length of the vector.

Example:

local v = vec2(3, 4)
local length_sq = v:length_squared()  -- 25
engine.log("Vector: (" .. v.x .. ", " .. v.y .. ")", 255, 255, 255, 255)
engine.log("Length squared: " .. length_sq, 255, 255, 255, 255)

vec2:normalize

Signature: vec2:normalize()

Description: Returns a normalized copy of the vector (unit vector with the same direction but length 1).

Parameters: None

Returns:

• vec2: A normalized vector.

Example:

local v = vec2(3, 4)
local normalized = v:normalize()
engine.log("Vector: (" .. v.x .. ", " .. v.y .. ")", 255, 255, 255, 255)
engine.log("Normalized: (" .. normalized.x .. ", " .. normalized.y .. ")", 255, 255, 255, 255)
engine.log("Normalized length: " .. normalized:length(), 255, 255, 255, 255)  -- Should be close to 1

vec2:dot

Signature: vec2:dot(v)

Description: Returns the dot product with another vector.

Parameters:

• v (vec2): The vector to compute the dot product with.

Returns:

• number: The dot product.

Example:

local v1 = vec2(2, 3)
local v2 = vec2(4, 5)
local dot_product = v1:dot(v2)  -- 2*4 + 3*5 = 8 + 15 = 23
engine.log("Dot product: " .. dot_product, 255, 255, 255, 255)

vec2:distance

Signature: vec2:distance(v)

Description: Returns the distance to another vector.

Parameters:

• v (vec2): The vector to compute the distance to.

Returns:

• number: The distance between the vectors.

Example:

local v1 = vec2(1, 1)
local v2 = vec2(4, 5)
local distance = v1:distance(v2)
engine.log("Distance: " .. distance, 255, 255, 255, 255)

vec2:clone

Signature: vec2:clone()

Description: Creates a copy of the vector.

Parameters: None

Returns:

• vec2: A new vector with the same components.

Example:

local original = vec2(10, 20)
local copy = original:clone()
copy.x = 30
engine.log("Original: (" .. original.x .. ", " .. original.y .. ")", 255, 255, 255, 255)
engine.log("Copy: (" .. copy.x .. ", " .. copy.y .. ")", 255, 255, 255, 255)

vec2:perpendicular

Signature: vec2:perpendicular()

Description: Returns a vector perpendicular to this one.

Parameters: None

Returns:

• vec2: A perpendicular vector.

Example:

local v = vec2(3, 4)
local perp = v:perpendicular()
engine.log("Vector: (" .. v.x .. ", " .. v.y .. ")", 255, 255, 255, 255)
engine.log("Perpendicular: (" .. perp.x .. ", " .. perp.y .. ")", 255, 255, 255, 255)
engine.log("Dot product (should be 0): " .. v:dot(perp), 255, 255, 255, 255)

vec2:angle

Signature: vec2:angle()

Description: Returns the angle in radians from the X-axis.

Parameters: None

Returns:

• number: The angle in radians.

Example:

local v = vec2(1, 1)  -- 45 degrees
local angle = v:angle()
engine.log("Angle in radians: " .. angle, 255, 255, 255, 255)
engine.log("Angle in degrees: " .. (angle * 180 / math.pi), 255, 255, 255, 255)

vec2:rotate

Signature: vec2:rotate(radians)

Description: Rotates the vector by an angle in radians.

Parameters:

• radians (number): The angle to rotate by in radians.

Returns:

• vec2: The rotated vector.

Example:

local v = vec2(1, 0)
local rotated = v:rotate(math.pi / 2)  -- 90 degrees
engine.log("Original: (" .. v.x .. ", " .. v.y .. ")", 255, 255, 255, 255)
engine.log("Rotated 90 degrees: (" .. rotated.x .. ", " .. rotated.y .. ")", 255, 255, 255, 255)

vec2:lerp

Signature: vec2:lerp(v, t)

Description: Linearly interpolates toward another vector by a factor t.

Parameters:

• v (vec2): The target vector.

• t (number): The interpolation factor (0-1).

Returns:

• vec2: The interpolated vector.

Example:

local v1 = vec2(0, 0)
local v2 = vec2(10, 20)
local half = v1:lerp(v2, 0.5)  -- Halfway between v1 and v2
engine.log("From: (" .. v1.x .. ", " .. v1.y .. ")", 255, 255, 255, 255)
engine.log("To: (" .. v2.x .. ", " .. v2.y .. ")", 255, 255, 255, 255)
engine.log("Halfway: (" .. half.x .. ", " .. half.y .. ")", 255, 255, 255, 255)

Additional vec2 Methods

• vec2:project_onto(v) - Projects this vector onto vector v.

• vec2:clamp_length(min, max) - Clamps the vector's length between min and max.

• vec2:reflect(normal) - Reflects the vector off the given normal.

Memory Access

• vec2.read_float(address) - Reads a vec2 from memory (float precision).

• vec2.read_double(address) - Reads a vec2 from memory (double precision).

• vec2.write_float(address, v) - Writes a vec2 to memory (float precision).

• vec2.write_double(address, v) - Writes a vec2 to memory (double precision).

vec3 - 3D Vector

Constructor

Signature: vec3(x, y, z)

Description: Constructs a 3D vector with the specified components.

Parameters:

• x (number): The x-component.

• y (number): The y-component.

• z (number): The z-component.

Returns:

• vec3: A new 3D vector object.

Example:

-- Create a 3D vector
local v = vec3(10, 20, 30)
engine.log("Vector: (" .. v.x .. ", " .. v.y .. ", " .. v.z .. ")", 255, 255, 255, 255)

Operators

The vec3 supports the same operators as vec2, including:

• Addition: vec3 + vec3

• Subtraction: vec3 - vec3

• Multiplication: vec3 * scalar

• Division: vec3 / scalar

• Negation: -vec3

• Length: #vec3

• Equality: vec3 == vec3

Fields

• vec3.x - The x-component of the vector.

• vec3.y - The y-component of the vector.

• vec3.z - The z-component of the vector.

Methods

Length & Normalization

• vec3:length() - Returns the 3D vector's length.

• vec3:length_2d() - Returns the 2D (XY) length, ignoring the Z component.

• vec3:length_2d_squared() - Returns the squared 2D length.

• vec3:normalize() - Returns a normalized version of the vector.

• vec3:clamp_length(min, max) - Clamps vector length between min and max.

Math & Direction

• vec3:dot(v) - Dot product with another vector.

• vec3:cross(v) - Cross product with another vector.

• vec3:distance(v) - Distance to another vector.

• vec3:angle_between(v) - Angle in radians between vectors.

• vec3:reflect(normal) - Reflects the vector off a surface normal.

• vec3:project_onto(v) - Projects this vector onto vector v.

• vec3:rotate_axis(angle, axis) - Rotates the vector around an axis.

Utility

• vec3:clone() - Returns a copy of the vector.

• vec3:lerp(v, t) - Linear interpolation with vector v.

• vec3:slerp(v, t) - Spherical linear interpolation.

Angle & Orientation

• vec3:to_forward() - Converts angles to a forward direction vector.

• vec3:to_right() - Converts angles to a right vector.

• vec3:to_up() - Converts angles to an up vector.

• vec3:to_qangle() - Returns pitch, yaw, roll as a vector.

• vec3:normalize_angles() - Normalizes pitch/yaw.

• vec3:clamp_angles() - Clamps pitch/yaw; sets roll to 0.

• vec3.normalize_angle(angle) - Normalizes a single angle value.

• vec3.from_qangle(pitch, yaw) - Converts pitch/yaw into a direction vector.

Example:

-- Create 3D vectors
local v1 = vec3(1, 0, 0)  -- Unit vector along X axis
local v2 = vec3(0, 1, 0)  -- Unit vector along Y axis

-- Get cross product (should be unit vector along Z axis)
local cross = v1:cross(v2)
engine.log("v1 cross v2: (" .. cross.x .. ", " .. cross.y .. ", " .. cross.z .. ")", 255, 255, 255, 255)

-- Get dot product (should be 0 for perpendicular vectors)
local dot = v1:dot(v2)
engine.log("v1 dot v2: " .. dot, 255, 255, 255, 255)

-- Get angle between vectors (should be 90 degrees = π/2)
local angle = v1:angle_between(v2)
engine.log("Angle between v1 and v2 (radians): " .. angle, 255, 255, 255, 255)
engine.log("Angle between v1 and v2 (degrees): " .. (angle * 180 / math.pi), 255, 255, 255, 255)

Memory Access

• vec3.read_float(address) - Reads a vec3 from memory (float).

• vec3.read_double(address) - Reads a vec3 from memory (double).

• vec3.write_float(address, v) - Writes a vec3 to memory (float).

• vec3.write_double(address, v) - Writes a vec3 to memory (double).

vec4 - 4D Vector

Constructor

Signature: vec4(x, y, z, w)

Description: Constructs a 4D vector with the specified components.

Parameters:

• x (number): The x-component.

• y (number): The y-component.

• z (number): The z-component.

• w (number): The w-component.

Returns:

• vec4: A new 4D vector object.

Example:

-- Create a 4D vector (commonly used for RGBA colors or quaternions)
local v = vec4(255, 0, 0, 255)  -- Red color with full alpha
engine.log("Vector: (" .. v.x .. ", " .. v.y .. ", " .. v.z .. ", " .. v.w .. ")", 255, 255, 255, 255)

Operators

The vec4 supports the same operators as vec2 and vec3, including:

• Addition: vec4 + vec4

• Subtraction: vec4 - vec4

• Multiplication: vec4 * scalar

• Division: vec4 / scalar

• Negation: -vec4

• Length: #vec4

• Equality: vec4 == vec4

Fields

• vec4.x - The x-component of the vector.

• vec4.y - The y-component of the vector.

• vec4.z - The z-component of the vector.

• vec4.w - The w-component of the vector.

Methods

Length & Normalization

• vec4:length() - Returns the vector's magnitude.

• vec4:normalize() - Returns a normalized version.

Math & Utility

• vec4:dot(v) - Computes the dot product with another vec4.

• vec4:clone() - Returns a copy of the vector.

• vec4:lerp(v, t) - Linearly interpolates toward v by factor t.

• vec4:clamp_length(min, max) - Clamps the vector length.

• vec4:project_onto(v) - Projects this vector onto another.

• vec4:reflect(normal) - Reflects the vector off a surface normal.

Example:

-- Create two 4D vectors
local color1 = vec4(255, 0, 0, 255)  -- Red
local color2 = vec4(0, 0, 255, 255)  -- Blue

-- Interpolate between them (purple with 50% blend)
local purple = color1:lerp(color2, 0.5)
engine.log("Interpolated color: (" .. purple.x .. ", " .. purple.y .. ", " .. purple.z .. ", " .. purple.w .. ")", 
           purple.x, purple.y, purple.z, purple.w)

Memory Access

• vec4.read_float(address) - Reads a vec4 from memory (float precision).

• vec4.read_double(address) - Reads a vec4 from memory (double precision).

• vec4.write_float(address, v) - Writes a vec4 to memory (float precision).

• vec4.write_double(address, v) - Writes a vec4 to memory (double precision).