vector3
Creates a new vector3 value.
In FiveM’s Lua runtime, vectors are real data types, just like numbers, bools and strings are.
This means that type(vector3(1, 2, 3)) will return vector3.
More about this in the Lua runtime manual.
Many existing natives such as GetEntityCoords and SetEntityCoords already have first class support for vector3
values. For example, GetEntityCoords returns a vector3, whereas SetEntityCoords accepts one, instead of using
individual x, y, z values. See the second example below for a real world use of vector3, or read more about them
in the Lua runtime manual and native functions manual.
Syntax
vector3 vector3(float x, float y, float z)
Required arguments
- x: A floating point number representing the
xvalue of your vector. - y: A floating point number representing the
yvalue of your vector. - z: A floating point number representing the
zvalue of your vector.
Examples
Basic vector3 functionality:
-- Basic vector with zero length:
vector3(0, 0, 0)
-- Vectors are a real data type:
local v = vector3(1, 2, 3)
print(type(v)) -- prints `vector3`
-- Vectors support equality operators:
local v1 = vector3(1, 2, 3)
local v2 = vector3(1, 2, 3)
local v3 = vector3(4, 5, 6)
print(v1 == v2) -- prints `true`
print(v1 == v3) -- prints `false`
print(v1 ~= v3) -- prints `true`
-- Arithmetic operations between vectors are supported:
local v = vector3(1, 2, 3)
print(v + 2) -- prints `vector3(3, 4, 5)`
print(v - 2) -- prints `vector3(-1, 0, 1)`
print(v * 2) -- prints `vector3(1, 4, 6)`
print(v / 2) -- prints `vector3(0.5, 1, 1.5)`
-- Or even with another vector:
local v1 = vector3(1, 2, 3)
local v2 = vector3(4, 5, 6)
print(v1 + v2) -- prints `vector3(5, 7, 9)`
print(v1 - v2) -- prints `vector3(-3, -3, -3)`
print(v1 * v2) -- prints `vector3(4, 10, 18)`
print(v1 / v2) -- prints `vector3(0.25, 0.4, 0.5)`
-- Vectors can be inverted:
local v = vector3(1, 2, 3)
print(-v) -- prints `vector3(-1, -2, -3)`
-- The length of the vector can be retrieved (pythagoras):
local v = vector3(1, 2, 3)
print(#v) -- prints `3.742`
-- Vectors can be normalized:
local v = vector3(1, 2, 3)
print(norm(v)) -- prints `vector3(0.27, 0.53, 0.80)`
-- Unpacking works:
local v = vector3(1, 2, 3)
local x, y, z = table.unpack(v)
-- To get the individual values from a vector:
local v = vector3(1, 2, 3)
print(v.x) -- prints `1`
print(v.y) -- prints `2`
print(v.z) -- prints `3`
-- Vectors support arbitrary swizzling:
local v = vector3(1, 2, 3)
print(v.yx) -- prints `vector2(2, 1)`
print(v.zx) -- prints `vector2(3, 1)`
print(v.xyx) -- prints `vector3(1, 2, 1)`
print(v.yxyx) -- prints `vector4(2, 1, 2, 1)`
print(v.zxxy) -- prints `vector4(3, 1, 1, 2)`
Since many native functions already return and support vectors in Lua, you can do the following to push your vehicle forward 5 meters relative to its own axis:
-- Get your vehicle's current matrix.
local vehicle = GetVehiclePedIsIn(PlayerPedId())
local _, forwardVector, _, position = GetEntityMatrix(vehicle)
-- Multiply the vector by 5, and add it to the current position.
-- Since directional vectors should usually have a length of 1, this works great.
local newPosition = (forwardVector * 5) + position
-- Update the vehicle position.
SetEntityCoords(vehicle, newPosition)