vec3

A three-dimensional vector containing x, y, and z floating-point values. This type is used throughout the API for world positions, directions, and 3D physics.

Performance & Garbage Collection

Standard mathematical operators like + or * create a new vec3 object. In 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 create a copy of an existing one.

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

-- create a vector with specific coordinates
local v2 = vec3(10, 5, -2)

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

Methods

Efficiently update an existing vector in-place to save memory.

local pos = vec3(0, 0, 0)
local velocity = vec3(1, 0, 0)

-- add velocity to position without creating a new object
pos:add(velocity)

Operators

Use standard math syntax for non-performance-critical logic.

local combined = vec3(1, 1, 1) + vec3(2, 2, 2)

Description

The vec3 type is used extensively throughout the API to represent physical locations and orientations in the simulation.

CSP uses a right-handed coordinate system, where Y is typically the vertical (up) axis and X and Z form the ground plane. The type supports operator overloading for +, -, *, /, unary negation, and the # operator for vector length. Most methods accept an optional out parameter, allowing results to be written to an existing vector instead of allocating a new one.

Properties

Property	Type	Description
x	number	The horizontal component.
y	number	The vertical (up) component.
z	number	The depth component.

Common Methods

Method	Description
:set(x, y, z)	Updates the vector’s components in place.
:normalize(out)	Scales the vector to a length of 1.
:dot(other)	Calculates the dot product (scalar) of two vectors.
:cross(other, out)	Calculates the cross product (perpendicular vector).
:distance(other)	Returns the distance between two points in meters.
:lerp(other, mix, out)	Linearly interpolates toward another vector.

Examples

World Distance

Check the distance between the player and a specific point in the track.

local carPos = ac.getCar(0).position
local markerPos = vec3(100, 0, 200)

local dist = carPos:distance(markerPos)

if dist < 50 then
    ac.log("The car is near the marker")
end

Directional Look

Calculate a point 5 meters in front of the car based on its current heading.

local car = ac.getCar(0)
local forward = car.look -- vec3 direction

-- calculate a point in front of the car
local spawnPoint = car.position + (forward \* 5)