vector

A three-dimensional vector: positions, directions and velocities in the game world. Fields x, y, z (floating-point numbers).

Common to vector, angle, vector2, color#

• Methods are called with a colon (v:length()) or through the type (vector.length(v)).
• Method arguments are checked: a wrong type gives the error bad argument '<arg>' to '<method>' (<Type> expected, got <type>).
• tostring(v) gives Vector(1.000000, 2.000000, 3.000000); v:strval() gives only the contents: 1.000000, 2.000000, 3.000000.
• == compares component-wise; a value of another type gives false.
• vector.typesafe(false) disables argument checks for the whole type, vector.typesafe(true) enables them back.

vector(x?: number, y?: number, z?: number)#

Creates a vector. Components that are not set are 0. vector(v) is a copy of the vector v. The same as vector.new(...).

Returns: vector.

local a = vector(1, 2, 3)
local b = vector(a)        -- a copy
b.z = 10
print(a, " ", b)

Operators#

local me = entity.local_pawn()
if me then
    local ahead = me:eye_position() + me:eye_angles():forward() * 100
    print(ahead)
end

v:unpack()#

Returns: number, number, number — x, y, z.

local x, y, z = vector(1, 2, 3):unpack()
print(x + y + z)   --> 6

v:init(...)#

Re-initializes the vector in place. Arguments are the same as for the constructor; without arguments — a zero vector.

Returns: nothing.

local v = vector(5, 5, 5)
v:init(1, 0, 0)
print(v)   --> Vector(1.000000, 0.000000, 0.000000)

src:copy(dst: vector)#

Copies the components of src into dst.

Returns: nothing.

local saved = vector()
local me = entity.local_pawn()
if me then me:origin():copy(saved) end

v:length(), v:lengthsqr()#

The vector length and its square. The square is faster: handy for comparing distances.

Returns: number.

local v = vector(3, 4, 0)
print(v:length(), " ", v:lengthsqr())   --> 5 25

v:length2d(), v:length2dsqr()#

The length on the X and Y axes (without height) and its square.

Returns: number.

local me = entity.local_pawn()
if me then print("Ground speed: ", math.floor(me:velocity():length2d())) end

a:dist(b: vector), a:distsqr(b: vector)#

The distance between points and its square.

Returns: number.

-- The nearest opponent
local me = entity.local_pawn()
if me then
    local best, best_d = nil, math.huge
    for _, pawn in ipairs(entity.pawns(true)) do
        local d = me:origin():distsqr(pawn:origin())
        if d < best_d then best, best_d = pawn, d end
    end
    print(best and best:name() or "nobody")
end

a:dist2d(b: vector), a:dist2dsqr(b: vector)#

The distance on the X and Y axes (without height) and its square.

Returns: number.

print(vector(0, 0, 0):dist2d(vector(3, 4, 100)))   --> 5

a:dot(b: vector)#

Dot product.

Returns: number.

-- Whether the player looks roughly towards an enemy (angle under ~25°)
local me = entity.local_pawn()
local enemy = entity.pawns(true)[1]
if me and enemy then
    local fwd = me:eye_angles():forward()
    local to  = me:eye_position():to(enemy:eye_position())
    print(fwd:dot(to) > 0.9)
end

a:cross(b: vector)#

Cross product.

Returns: vector.

print(vector(1, 0, 0):cross(vector(0, 1, 0)))   -- (0, 0, 1)

a:lerp(b: vector, t: number)#

Linear interpolation between a and b.

Returns: vector.

local mid = vector(0, 0, 0):lerp(vector(10, 20, 30), 0.5)
print(mid)   -- (5, 10, 15)

a:to(b: vector)#

A unit direction vector from a to b.

Returns: vector.

local dir = vector(0, 0, 0):to(vector(10, 0, 0))
print(dir)   -- (1, 0, 0)

v:normalize(), v:normalized()#

normalize makes the vector unit length in place and returns the previous length (0 — the vector was zero). normalized returns a unit copy without changing the original.

Returns: normalize — number; normalized — vector.

local v = vector(3, 4, 0)
local len = v:normalize()
print(len, " ", v)   -- 5 and the vector (0.6, 0.8, 0)

v:normalize_safe(fallback: vector), v:normalized_safe(fallback: vector)#

Like normalize and normalized, but with zero length the result becomes fallback.

Returns: normalize_safe — number; normalized_safe — vector.

local dir = vector(0, 0, 0):normalized_safe(vector(1, 0, 0))
print(dir)   -- (1, 0, 0)

v:scale(s: number), v:scaled(s: number)#

scale multiplies the vector by a number in place, scaled returns a multiplied copy.

Returns: scale — nothing; scaled — vector.

local v = vector(1, 2, 3)
print(v:scaled(2), " ", v)   -- a copy and the unchanged original
v:scale(10)
print(v)

v:negate()#

Flips the sign of all components in place.

Returns: nothing.

local v = vector(1, -2, 3)
v:negate()
print(v)   -- (-1, 2, -3)

fwd:angles(pseudo_up?: vector)#

The angles that give the direction fwd. With pseudo_up the roll is computed too.

Returns: angle.

-- Angles to look from the eyes at an enemy
local me = entity.local_pawn()
local enemy = entity.pawns(true)[1]
if me and enemy then
    local ang = (enemy:eye_position() - me:eye_position()):angles()
    print(ang)
end

fwd:vectors()#

The "right" and "up" vectors for the direction fwd.

Returns: vector, vector — right, up.

local right, up = vector(1, 0, 0):vectors()
print(right, " ", up)

p:closest_line_point(a: vector, b: vector)#

The point of the segment a–b closest to p.

Returns: vector.

local p = vector(5, 5, 0):closest_line_point(vector(0, 0, 0), vector(10, 0, 0))
print(p)   -- (5, 0, 0)

p:inverse_lerp(a: vector, b: vector)#

The parameter t of the projection of point p onto the line a → b (not clamped to 0–1).

Returns: number, vector — t and the vector b - a. If a and b almost coincide — 0, b - a.

local t = vector(2.5, 3, 0):inverse_lerp(vector(0, 0, 0), vector(10, 0, 0))
print(t)   --> 0.25

p:ray_dist(start: vector, dir: vector)#

The distance from point p to the ray from start in direction dir (dir must be unit length).

Returns: number.

-- How far the enemy is from the aim line
local me = entity.local_pawn()
local enemy = entity.pawns(true)[1]
if me and enemy then
    local d = enemy:eye_position():ray_dist(me:eye_position(), me:eye_angles():forward())
    print("To the aim line: ", math.floor(d))
end