vec2

A two-dimensional vector containing x and y floating-point values. This type is used for UI positioning, element dimensions, and texture coordinates (UVs).

Performance & Garbage Collection

Standard mathematical operators like + or * create a new vec2 object. In UI scripts that run every frame, it is significantly more efficient to use in-place methods like :add() or :set() to avoid putting pressure on the Lua garbage collector.

Usage Patterns

Constructors

Initialize a vector with specific values, or clone an existing one.

-- create a vector at 0,0
local v1 = vec2()

-- create a vector with specific coordinates
local v2 = vec2(100, 50)

-- create a vector from another vec2 (cloning)
local v3 = vec2(v2)

Methods

Update an existing vector in-place to save memory.

local pos = vec2(10, 10)
local offset = vec2(5, 0)

-- move the position without creating a new object
pos:add(offset)

Operators

Use standard math syntax for layout calculations.

local center = windowSize / 2
local shifted = center + vec2(10, 10)

Description

The vec2 type is the foundation of the ui and display namespaces.

In standard UI contexts, (0, 0) represents the top-left corner of the window or screen. Positive x values move to the right, and positive y values move downward. The type supports operator overloading for +, -, *, /, equality checks (==), and the # operator for vector length.

Methods such as :add(), :sub(), and :normalize() modify the vector in place and return it, allowing for method chaining (for example, v:add(v2):scale(2)).

Properties

Property	Type	Description
x	number	The horizontal component.
y	number	The vertical component.

Common Methods

Method	Description
:set(x, y)	Updates the vector’s components in place.
:normalize(out)	Scales the vector to a length of 1.
:length()	Returns the magnitude of the vector.
:distance(other)	Returns the distance between two points.
:lerp(other, mix, out)	Linearly interpolates toward another vector.
:unpack()	Returns x and y as two separate numbers.

Examples

UI Positioning

Using vec2 to define the position and size of a drawn rectangle.

function script.windowMain()
    local pos = vec2(50, 50)
    local size = vec2(200, 100)
    -- draw a rectangle using the vectors
    ui.drawRectFilled(pos, pos + size, rgbm.colors.red)
end

Intersection Check

Checking where two line segments intersect on a 2D plane.

local p1, p2 = vec2(0, 0), vec2(100, 100)
local p3, p4 = vec2(0, 100), vec2(100, 0)

local hit = vec2.intersect(p1, p2, p3, p4)

if hit then
    ac.log("Lines intersect at: " .. hit.x .. ", " .. hit.y)
end